Introduction
This concept describes the organization of new JavaScript plugins/controls inside Intershop 7.1.
These controls were introduced to the back office by new IAD sketches and were chosen in cooperation with development and interaction design.
To handle the growing number of new plugins and controls there is a need for organization and conventions.
References
Conventions: Location
There are a lot of JavaScript plugins and libraries that are used in Intershop 7.1, e.g., TinyMCE, KorJS, jQuery, jquery.scrollTo, ...
If these files are used in more places that are spread over different cartridges, they need to be consolidated and stored at a central place.
This place is the tools-Cartridge at <IS_SOURCE>/tools/staticfiles/cartridge/static/default/js, which provides different JavaScript files and includes their licenses.
Versioning
Most of the JavaScript files do not have a descriptive header comment, stating the name and, more importantly, the version of the plugin.
Saving the files only by their plugin name will make it impossible to identify the currently used version.
Add the version to the filename to make it possible to use two different versions of the same plugin for different pages, e.g., two different jQuery versions for the storefront and back office (it is still best practice to use the latest plugin version).
Naming
If the plugin consists of only 1 file, use the following naming scheme:
<pluginname>-<version>.js
<pluginname>-<version>-LICENSE.txt
package.json
If the plugin is bigger and consists of more than 1 file, move it into its own folder to group the files and prevent filename collisions:
<pluginname>-<version>/<file1>.js
<pluginname>-<version>/<file2>.js
<pluginname>-<version>/LICENSE.txt
package.json
Sort the plugins into folders, stating which framework they use, e.g.
js/jquery/plugin1/
js/jquery/plugin2/
Plugins based on other frameworks use another folder:
js/dojo/plugin1/
js/dojo/plugin2/
Dependencies
Currently there are jQuery 1.10.2 and jQueryUI 1.10.3 integrated as libraries. These versions should be used by all new jQuery-plugins (the integrated jquery-migrate plugin does a good job on backwards-compatibility).
Create the package.json file for each plugin and store information about needed libraries there.
Attached CSS files or images should be moved into the appropriate folders (if possible).
Modifications
Often there is a need to modify a specific JavaScript file (e.g., to add a smaller feature, to fix a bug or to refactor the internal naming because of collisions). Merging modified scripts with newer versions is always a hassle and cannot be simplified so weigh each merge-effort to its benefit if the edits outweigh.
Storing the original, unmodified files in a separate branch will help bug tracking and merging.
Theming
JavaScript controls are used in different places like the back office and storefront. This concept can be seen as a proposal to make different themes available:
Add the backoffice CSS class to the body element of the back office page:
<body class="backoffice"> </body>
Add ".backoffice" to each CSS rule of the back office theme
.backoffice .ui-helper-hidden { display: none; }
.backoffice .ui-helper-hidden-accessible { position: absolute !important; clip: rect(1px 1px 1px 1px); clip: rect(1px,1px,1px,1px); }
.backoffice .ui-helper-reset { margin: 0; padding: 0; border: 0; outline: 0; line-height: 1.3; text-decoration: none; font-size: 100%; list-style: none; }
Since these rules are now more specific, they will override the CSS rules of other loaded themes.
The same could be done for the storefront.