Localizing your Ext JS packages

In our projects we use home brewed packages in our Ext JS applications. The advantage of packages (also your theme is a package) is that they can easily be used to share sources between different applications. That will increase the possibility of reusing of your own component development.

For example you have your own designed search toolbar at the top of your grids. Well such a toolbar would be a great candidate to put in your own package. That would make it easy to just add the package to your application requirements and start using the components without the hassle of copying and editing sources in your application source tree.

In this article I will show you how you can localize (i18n) a component in your package, the Sencha way. It is important to notice that we use Sencha CMD.

Difference between common shares and a package

There is more than one way to share code between applications. If you have a workspace with more than one application you can share code using a "common" folder. If you want to share code between different applications for different customers you can use the "common" folder as well, but it is more likely to use a package.

In a package we share components that we use in most of our applications. One of our packages we have called "Factory". But you can give it almost any name you like. You can even have more packages.

"common" or package

To decide when to use the "common" folder for sharing or when to use a package is totally up to you. We use the "Factory" package only for those things that are completely independent to the specific functionality of an application. We want to keep the package lightweight and avoid having a lot of code in it that we will not use in our applications. In our package we have for example some singletons, some generic toolbars for a grid and form panel. We also have some overrides in our package.

A form field override with localization

I will show you how we have managed localization in our package by the use of a Ext.form.field.VTypes override.

As I said our package is called "Factory". This has been created in our workspace "packages" folder with the command:

sencha generate package Factory

After this is done it will create in the "local" folder of your packages the folder "Factory". Your package is ready to use.

I will skip some steps here and show you the structure of the package folder "Factory" that are relevant to this sample.

Locale

First thing to notice is that the "locale" folder is not coming when creating the package. So you have to create this folder manually. In this folder you put the folders with the languages you want to support like:

As you can see it follows the same structure as you would use for SASS or other overrides.

The source code in the "de" or German VTypes.js looks like this:

Ext.define('Factory.de.form.field.VTypes', {
    override: 'Ext.form.field.VTypes',
    urlOnlyText: 'Soll eine gültigen Webseiten URL sein'
});

As you can see the "locale" itself is not in the path of the Ext.define. This is correct.

The original override in our package

In the "overrides" folder of our package we have:

In this VTypes.js we have the following code:

Ext.define('Factory.overrides.form.field.VTypes', {
    override: 'Ext.form.field.VTypes',
    urlOnly: function (v) {
        return /https?:\/\/([-\w\.]+)+(:\d+)?(\/([\w/_\.]*(\?\S+)?)?)?/.test(v);
    },
    urlOnlyText: 'Must be a valid web URL'
});

As you can see the Ext.define path has the "overrides" in it's path. Most important thing to notice is that the override in the "locale" folder is not overriding "Factory.overrides.form.field.VTypes", but "Ext.form.field.VTypes". If you don't do this, it will result in the error: "Cannot read property '$isClass' of undefined".

Package.json

We need to make a small modification to the package.json of our "Factory" package.

"overrides": "${package.dir}/overrides,${package.dir}/${toolkit.name}/overrides,${package.dir}/locale/${package.locale}",

We put the "${package.dir}/locale/${package.locale}" at the end of the "overrides" tag. I have taken this from the "ext-locale" package that comes with Ext JS. Don't ask me why it works, but it works.

How to use the package in your application

To use the package in your application you have to modify the app.json file in your application root folder. You have to change the requires attribute the following way

"requires": [
    "font-awesome",
    "jarvus-hotfixes",
    "Factory"
]

or you modify the the requires according to the specific toolkit used

"classic": {
    "js": [
      {
        "path": "${framework.dir}/build/ext-all-rtl-debug.js"
      }
    ],
    "requires": [
      "ext-locale",
      "Factory"
    ],
    "locale": "de"
},

Next step with Sencha CMD

After these modifications you execute one of the following commands in Sencha CMD rooted to the application folder:

Refresh the app

sencha app refresh

Watch the app folder and continue development

sencha app watch

Build the app for production

sencha app build

How it looks

Reuse of the Ext JS package

To use your package in another application you can simply copy the /packages/local/Factory folder and place this in the /packages/local folder of the other application/workspace.

After modifying the requirements in the app.json and do execute a

sencha app refresh

it can also contribute the other application(s).

Links

Official documentation on packages from Sencha