Symphony.

With the upcoming release of version 2.2, Symphony will ship with an updated JavaScript implementation. There are a few changes developers should be aware of when they revise and update their extensions.

Changes

A major effort has been made to clean up and streamline Symphony’s JavaScript. Among the important changes developers need to be aware of are:

• The constant Symphony.Website is deprecated and should be replaced by Symphony.Context.get('root').
• The constant Symphony.Lang is deprecated and should be replaced by Symphony.Context.get('lang').
• The translation function Symphony.Language.add() now needs to be called after the DOM ready. If it’s called before, the Symphony object is not initialised yet and the function won’t have any effect.
• The old duplicator has been removed in favour of the new one which is provided as jQuery plugin since Symphony 2.0.5. Extension developers still using the old code will have to update their markup accordingly. The duplicator used in the section editor is a good example how to implement a new duplicator. Furthermore, the duplicator now accepts an option collapsible (either set to true or false) that enabled an accordion-like interface.
• Events triggered by the core plugins are now properly namespaced, e. g. click.tags. Extension developers should do the same with their events to make it easier for other developers to change the system behaviour.

Symphony Context

Symphony 2.2 offers a new context object. Symphony.Context contains information about the backend environment, like page, entry id, mode (create, edit), and so on. Here are some usage examples:

• Add context: Symphony.Context.add('group', {name: value});
• Get context: Symphony.Context.get('group');
• Get full context: Symphony.Context.get();
• Get environment information: Symphony.Context.get('env');

Available Plugins

Symphony 2.2 offers the following core plugins that are available for extension developers:

• symphony.collapsible.js for accordion-like effects.
• symphony.duplicator.js for repeatable interface components.
• symphony.orderable.js for element sorting.
• symphony.pickable.js for toggling elements based on a select box value.
• symphony.selectable.js for element selection.
• symphony.tags.js for creating single, multiple or inline tag lists.

Conventions

Symphony 2.2 introduces a number of JavaScript coding conventions that developers should follow. This will help reduce conflicts among scripts and keep code readable and consistent throughout Symphony and its ecosystem of extensions.

Naming Conventions for Files

• Scripts in the publish area: extensionname.publish.js
• Scripts in the section settings: extensionname.settings.js
• Scripts in the preferences: extensionname.preferences.js
• Scripts in other backend areas: extensionname.areaname.js, e. g. extensionname.pages.js

Avoiding Conflicts

It is good practice to wrap the code in a self invoking anonymous function like so:

(function($) {
    $(document).ready(function() {
        // Your code here
    });
})(jQuery.noConflict());

Documentation

Scripts should be well commented so that other developers can easily follow their logic. Symphony adopted the JsDoc Toolkit conventions for code documentation. It might also be helpful to add inline comments:

// Comment explaining if condition:
if() {
    // Your code here
}

// Optional comment explaining else.
else {
    // Your code here
}

Indentation

Script should be indented using tabs.

Variable Declarations

Variables should be declared in a single statement:

var x,
    y;

Naming Conventions for Variables and Functions

• variable_with_long_names
• objectFunction