JavaScript Resource Handler Serve JavaScript Resources from the Server - RickStrahl/Westwind.Globalization GitHub Wiki

If you're building applications that include JavaScript logic it's likely that you also need to access localized resources on the client. This library provides a JavaScript Resource HttpHandler that can serve resources in the proper localized locale to your client application.

The resource handler allows you to specify which resources to serve and which locale - or auto-detected locale - to serve the data to your JavaScript client application.

To configure the Resource Handler it has to be registered in web.config as follows:

<configuration>
<system.webServer>
<handlers>
    <add name="JavaScriptResourceHandler"
        verb="GET"
        path="JavascriptResourceHandler.axd"
        type="Westwind.Globalization.JavaScriptResourceHandler,Westwind.Globalization.Web" />
</handlers>
</system.webServer>
</configuration>

Note this entry is automatically made for you when you install the NuGet package.

The resource handler is then accessed as a script resource in your code by calling the static JavaScriptResourceHandler.GetJavaScriptResourcesUrl() method:

<script src="@JavaScriptResourceHandler.GetJavaScriptResourcesUrl("resources","Resources")"></script>
<script>
    document.querySelector("#JavaScriptHelloWorld").innerText = resources.HelloWorld;
</script>

or if you're using a plain HTML page:

<script src="JavaScriptResourceHandler.axd?ResourceSet=Resources&LocaleId=auto&VarName=resources&ResourceType=resdb&ResourceMode=1"></script>
<script>
    document.querySelector("#JavaScriptHelloWorld").innerText = resources.HelloWorld;
</script>

Either of the above generate the following script code (shown here localized in German):

resources = {
	"HelloWorld": "Hallo schn\u00F6de Welt",
	"Ready": "Los",
	"Today": "Heute",
	"Yesterday": "Gestern",
    "dbRes": function dbRes(resId) { return resources[resId] || resId; }    
};

A full JavaScript resource handler URL looks like this:

JavaScriptResourceHandler.axd?ResourceSet=Resources&LocaleId=auto&VarName=resources&ResourceType=resdb&ResourceMode=1

The QueryString parameters on the URL are used as follows:

The ResourceSet name as defined in the database or the name of the ResX file relative to the ResxBaseFolder defined in the configuration.

This can be either a specific localeId like de, or de-de. Or it can be auto in which ASP.NET will use its default locale, which you can override to match the browser's locale as described in Auto-detecting browser locale. The recommendation is to use auto and have IIS detect the browser locale and switch the thread UiCulture.

You can specify what type of resources are loaded with this Resource handler. The options are resdb, which uses the dbResourceProvider/Manager or resx which uses Resx resources. Again in order for Resx resources to work the ResxBaseFolder must be set.

Determines how Resx Resources are loaded using either project (1) or WebForms (0) style resources. If project (0) resources are used make sure the ResxBaseFolder points to the path where your Resx resources like. If you use WebForms mode, resources are located using App_GlobalResources and App_LocalResources folders.

The localization by default uses the active locale of the current request, so if you switch the locale using WebUtils.SetUserLocale() as shown earlier, the resources are localized to that locale as well. You can also explicitly provide the LocaleId as a parameter in the first call, or in the LocaleId query parameter in the raw script call.

Note that the variable name is generated in global scope by default, so resources is generated in global scope. However, you can pass in any variable name. For example, if you have a previously declared object that you want to attach the resources to you can use that name. For example:

<script>
    global = {};  //  declare your own global object on the page
</script>
<!-- generated resources to global.resources -->
<script src="@JavaScriptResourceHandler.GetJavaScriptResourcesUrl("global.resources","Resources")"></script>
<script>
    // use global.resources object to access resource values
    document.querySelector("#JavaScriptHelloWorld").innerText = global.resources.HelloWorld;
</script>

Note also that there's a dbRes() function included in the class that allows safe, string based access to properties like this:

var strReady1 = resources.Ready; // error if not found or can be blank  
var strReady2 = resources.dbRes('Ready'); // no error, output 'Ready' if not found or empty

That is if you try to access resources that don't exist or are null//empty the resourceKey is returned. This allows for resource names that act as 'default' values or at least will act as fail-safe that returns the key which is better than no text at all. The behavior of this function is similar to to the DbRes.T() function on the server.