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 bySymphony.Context.get('root')
. - The constant
Symphony.Lang
is deprecated and should be replaced bySymphony.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 totrue
orfalse
) 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
Comments
Good stuff Nils!
What’s the naming convention for files that are being used on every backend page?
extensionname.js
,extensionname.all.js
,extensionname.general.js
?We haven’t thought of that but it makes sense to use the first one in my opinion.
Create an account or sign in to comment.