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.
Property | Value |
Extension Scope | Application |
Sugar Variable | $js_groupings |
Extension Directory | ./custom/Extension/application/Ext/JSGroupings/ |
Compiled Extension File | ./custom/application/Ext/JSGroupings/jsgroups.ext.php |
Manifest Installdef | $installdefs['jsgroups'] |
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
Name | Type | Description |
from | String | The basepath of the file to be installed |
to_module | String | The key for the module where the file will be installed |
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.