JSGroupings

Overview

The JSGroupings extension allows for additional JavaScript grouping files to be created or added to existing groupings within the system.

JSGroupings are file packages containing one or more minified JavaScript libraries. The groupings enhance system performance by reducing the number of JavaScript files that need to be downloaded for a given page. Some examples of JSGroupings in Sugar are sugar_sidecar.min.js, which contains the Sidecar JavaScript files, and sugar_grp1.js, which contains the base JavaScript files.

You can find all of the groups listed in ./jssource/JSGroupings.php. Each group is loaded only when needed by a direct call (e.g., from a TPL file). For example, sugar_grp1.js is loaded for almost all Sugar functions, while sugar_grp_yui_widgets.js will usually be loaded for just record views.

To load a JSGroupings file for a custom module, simply add a new JSGrouping and then include the JavaScript file for your custom handlebars template. You can also append to an existing grouping, such as ./include/javascript/sugar_grp7.min.js, to include the code globally.

Properties

The following extension properties are available. For more information, please refer to the Extension Property documentation.

Implementation

The following sections illustrate the various ways to implement a customization to a Sugar instance.

File System

Creating New JSGroupings

When working directly with the filesystem, you can create a file in ./custom/Extension/application/Ext/JSGroupings/ to add or append Javascript to JSGroupings in the system. The following example will add a new JSGrouping file to the system:

./custom/Extension/application/Ext/JSGroupings/<file>.php

<?php

//creates the file cache/include/javascript/newGrouping.js
$js_groupings[] = $newGrouping = array(
    'custom/file1.js' => 'include/javascript/newGrouping.js',
    'custom/file2.js' => 'include/javascript/newGrouping.js',
);

Next, create the Javascript files that will be grouped as specified in the JSGrouping definition above:

./custom/file1.js

function one(){
    //logic
}

./custom/file2.js

function two(){
    //logic
}

Next, navigate to Admin > Repair > Quick Repair and Rebuild. The system will then rebuild the extensions and compile your customization into ./custom/application/Ext/JSGroupings/jsgroups.ext.php.

Finally, navigate to Admin > Repair > Rebuild JS Grouping Files. This will create the grouping file in the cache directory as specified:

./cache/include/javascript/newGrouping.js

function one(){}/* End of File custom/file1.js */function two(){}/* End of File custom/file2.js */

Appending to Existing JSGroupings

In some situations, you may find that you need to append your own JavaScript to a core Sugar JSGrouping. Similarly to creating a new JSGrouping, to append to a core JSGrouping you can create a new PHP file in ./custom/Extension/application/Ext/JSGroupings/. The example below demonstrates how to add the file ./custom/file1.js to ./cache/include/javascript/sugar_grp7.min.js.

./custom/Extension/application/Ext/JSGroupings/<file>.php

<?php

//Loop through the groupings to find grouping file you want to append to

foreach ($js_groupings as $key => $groupings)
{
    foreach  ($groupings as $file => $target)
    {
    	//if the target grouping is found
        if ($target == 'include/javascript/sugar_grp7.min.js')
        {
            //append the custom JavaScript file
            $js_groupings[$key]['custom/file1.js'] = 'include/javascript/sugar_grp7.min.js';
        }
        break;
    }
}

Next, navigate to Admin > Repair > Quick Repair and Rebuild. The system will then rebuild the extensions and compile your customization into ./custom/application/Ext/JSGroupings/jsgroups.ext.php.

Module Loadable Package

When building a module loadable package, you can use the $installdefs['jsgroups'] index to install the extension file.

Installdef Properties

The example below demonstrates the proper install definition that should be used in the ./manifest.php file to add the JSGrouping Extension file to the system. When using this approach, you still need to use the $installdefs['copy'] index for the custom JavaScript files you are adding to JSGroupings. Sugar will automatically execute Rebuild Extensions to reflect the new JSGrouping, however, you will still need to navigate to Admin > Repair > Rebuild JS Grouping Files, to create the grouping file in the cache directory.

./manifest.php

<?php

$manifest = array(
    ...
);

$installdefs = array(
    'id' => 'jsGroupings_Example',
    'jsgroups' => array(
        array(
            'from' => '<basepath>/Files/custom/Extension/application/Ext/JSGroupings/<file>.php',
            'to_module' => 'application',
        )
    ),
    'copy' => array(
        array(
            'from' => '<basepath>/Files/custom/file1.js',
            'to' => 'custom/file1.js'
        ),
        array( 
            'from' => '<basepath>/Files/custom/file2.js',
            'to' => 'custom/file2.js' 
        )
    )
);

Alternatively, you may use the $installdefs['copy'] index for the JSGrouping Extension file. When using this approach, you may need to manually run repair actions such as a Quick Repair and Rebuild. For more information on the $installdefs['copy'] index and module-loadable packages, please refer to the Introduction to the Manifest page.

Considerations

• The grouping path you specify will be created in the cache directory.
• If you wish to add a grouping that contains a file that is part of another group already, add a '.' after <file>.js to make the element key unique.