Document Properties
KbidF23288
Last Modified04-Feb-2020
Added to KB18-Jun-2012
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - JavaScript Controls

Product Version

7.1

Product To Version

 

Status

final

1 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.

2 References

3 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.

4 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).

4.1 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/

4.2 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).

4.3 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.

4.4 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.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets