MobileFirst application build settings

We can use minification to reduce the size of JavaScript and CSS files in the Mobile Web or Desktop Browser application. We can also use concatenation to improve the start time of the application. To do this, we use MobileFirst build settings.

Since IBM Worklight v6.0.0, a file named build-settings.xml is created when a new MobileFirst application is created, on the same level as application-descriptor.xml. The purpose of the file is to prepare minification and concatenation configurations for each environment. These configurations are then used by the minify and concatenation engines during the build process.

The structure of the build-settings.xml file is as shown in the following example:

<buildSettings xmlns="http://www.ibm.worklight.com/build-settings">
  <common>
    <minification level="simple" includes="**" excludes="**/css/**"/>
    <concatenation includes="**" excludes="**/*.js"/>
  </common>
  <desktopBrowser>
    <minification level="simple" includes="**" excludes="**/css/**"/>
    <concatenation includes="**" excludes="**/*.txt"/>
  </desktopBrowser>
  <mobileWebApp>
    <minification level="simple" includes="**" excludes="**/css/**"/>
    <concatenation includes="**" excludes="**/*.js"/>
  </mobileWebApp>
</buildSettings>

The names of elements are aligned with names of environments. Only Mobile Web and Desktop Browser environments can be minified or concatenated, so only those individual environment elements can be configured. The <common> element contains configurations common to all environments.

All three elements – <common>, <desktopBrowser>, and <mobileWebApp> – are optional.

If any of these three elements are used, the <minification> attribute is mandatory within each one. Its level attribute specifies the compilation level of minification process and resources that can or cannot be used. Minification level options are listed in the following table.

Value	Description
none	No minification is done on the code by the MobileFirst Studio builder.
whitespaces	Removes comments from the code and also removes line breaks, unnecessary spaces, and other white space. The output JavaScript is functionally identical to the source JavaScript. (In the MobileFirst Studio Build Settings Editor, this attribute is called Remove whitespaces and comments.)
simple	Removes the same white space and comments as whitespaces, but also optimizes expressions and functions, including renaming local variables and function parameters to shorter names. Renaming variables to shorter names makes the code smaller. Because the simple setting renames only symbols that are local to functions, it does not interfere with the interaction between the compiled JavaScript and other JavaScript. Compilation with this setting always preserves the functionality of syntactically valid JavaScript, if the code does not access local variables with string names, for example, using eval() statements. (In the MobileFirst Studio Build Settings Editor, this attribute is called Google Closure Compiler Simple Optimization.)

The includes and excludes attributes must be followed by a list of file names or regular expressions as used by Ant, separated by semicolons. Only JavaScript (.js) and Cascading Style Sheet (.css) files can be listed. Wildcard characters are allowed, with the following rules:

• ** – includes or excludes all files and folders

• **/foldername/** – includes or excludes all files and folders under foldername

• **/*.css – includes or excludes all files in all folders that have an extension of .css

The includes and excludes attributes can be used in combination, such as in the following examples:

• includes="**" and excludes="**/*.css" contains all files except .css files

• includes="**" and excludes="**/css/**" contains all files except files under the css folder

• includes="**/js/**" contains only files found under the js folder

• includes="**/*.js" contains only files that have an extension of .js

• includes="**/*.js" and excludes="**/*.css" contains no files at all

For more information about minification, see Minification of JS and CSS files.

The <concatenation> element is optional. It contains no level attribute, and its includes and excludes attributes use the same syntax listed for the <minification> element.

For more information about concatenation, see Concatenation of JS and CSS files.

To turn on minification or concatenation for an environment

To instruct MobileFirst Studio to use minification, concatenation, or both when it builds the application:

1. In MobileFirst Studio, right-click the desktopbrowser or mobilewebapp element of the application (or the main application node) and choose Run As > Build Settings and Deploy Target from the menu.

   The Build Settings and Deploy Target window is displayed:

   

2. In the Build optimization area of the dialog, select the check box of the feature or features to use when you build this environment.

3. Click OK.

This action does not trigger an automatic build. To build or rebuild using these new settings, use either the Run As > Run on Worklight Development Server or the Run As > Build... menu commands.

To edit the build-settings.xml file

Similar to application-descriptor.xml, the build-settings.xml can be edited with the Eclipse DDE editor:

1. In MobileFirst Studio, double-click the build-settings.xml element of the application to display the Build Settings Editor:

   

2. To create a configuration for Concatenation:

   1. Enter the list of files to be concatenated or not concatenated in the includes and excludes fields. Use the Ant syntax that is described earlier.

3. To create a configuration for Minification:

   1. Select the wanted minification level from the Level field:

      • None (Default) specifies the none attribute in the above table.

      • Remove whitespaces and comments specifies the whitespaces attribute in the above table.

      • Google Closure Compiler Simple Optimization specifies the simple attribute in the above table.

   2. Enter the list of files to be minified or not minified in the includes and excludes fields. Use the Ant syntax that is described earlier.

The build-settings.xml can also be edited with a standard XML editor. If it is not already present, the <common> element can be added only with an XML editor. See MobileFirst application build settings for examples of the XML syntax.

Build with the build-settings.xml file

At build time, the MobileFirst Studio builder minifies or concatenates all the files that are included and not excluded, as defined in the build-settings.xml file.

During the build process, when either minification or concatenation are specified for an environment, the builder reads the build-settings.xml file and configures the compilation level and included and excluded files for that environment. Each environment is minified or concatenated according to its own configuration, and according to the following rules:

• The compilation level value of the environment overrides the compilation level specified in the <common> element.

• The includes attribute of each environment overrides an includes attribute of <common>.

• The excludes attribute of each environment is concatenated to the excludes attribute of <common>.

By editing the build-settings.xml file, we can essentially create different configurations for minification and concatenation, depending on the stage of the development cycle. For example, you might have one setting that is commonly used during development, in which the minification level is set to none and the concatenation feature is disabled. But when you move the application to production, we can edit the build settings to use a minification level of simple and to enable concatenation.

Parent topic: Optimizing MobileFirst applications