Using e107's built-in classes and methods.

Javascript

Basics

Including javascript in your plugin or theme may be achieved by using the following function:

		e107::js(type, value, dependency, zone);

Example: Load a script in the 'faqs' plugin directory and auto-load jquery if not already loaded.

		e107::js('faqs','js/faqs.js', 'jquery')

Example: Load a theme script in the footer

		e107::js("theme", "js/scripts.js", 'jquery');  // no 'zone' value, loaded in the footer by default. 

Example: Load a theme script in the header

		e107::js("theme", "js/scripts.js", 'jquery', 2); // including a 'zone' value loads it in the header 
Type Value Description
core path relative to the core folder Include a core js file in the header of the page
url full url to javascript filel Include a remote js file in the header of the page
inline javascript code Include raw javascript code in the header of the page
theme path to js file, relative to the current theme's folder Include a theme js file
(any plugin folder name) path to js file, relative to the plugin's folder Include a plugin js file
settings ‡ array (PHP) Adds settings to e107's global storage of JavaScript settings.

settings: An associative array with configuration options. The array is merged directly into e107.settings. All plugins should wrap their actual configuration settings in another variable to prevent conflicts in the e107.settings namespace. Items added with a string key will replace existing settings with that key; items with numeric array keys will be added to the existing settings array.

JavaScript Behaviors

Behaviors are event-triggered actions that attach to page elements, enhancing default non-JavaScript UIs. Behaviors are registered in the e107.behaviors object using the method 'attach' and optionally also 'detach' as follows:

		
var e107 = e107 || {'settings': {}, 'behaviors': {}};

(function ($)
{
  e107.behaviors.myBehavior = {
    attach: function (context, settings)
    {

    },
    detach: function (context, settings, trigger)
    {

    }
  };
})(jQuery);

e107.attachBehaviors is added to the jQuery ready event and so runs on initial page load. Developers implementing Ajax in their solutions should also call this function after new page content has been loaded, feeding in an element to be processed, in order to attach all behaviors to the new content.

See the e107_web/js/core/all.jquery.js file for more information.

Using jQuery

jQuery is now namespaced to avoid conflicts with other Javascript libraries such as Prototype. All your code that expects to use jQuery as $ should be wrapped in an outer context like so.

		(function ($) {
  // All your code here.
})(jQuery);

If you don't, you may see the error Uncaught TypeError: Property '$' of object [object DOMWindow] is not a function or similar.

jQuery Once

e107.behaviors will often be called multiple times on a page. For example, core/custom plugin performs some Ajax operation, all e107 behaviors will be executed again after page load, in order to attach any relevant JavaScript to the newly loaded elements. This can have the undesired affect of applying JavaScript to elements each time e107 behaviors are executed, resulting in the same code being applied multiple times. To ensure that the JavaScript is applied only once, we can use the jQuery $.once() function. This function will ensure that the code inside the function is not executed if it has already been executed for the given element.

Using jQuery $.once() (integrated into e107 core), the developer experience of applying these effects is improved. Note that there is also the $.removeOnce() method that will only take effect on elements that have already applied the behaviors.

		
var e107 = e107 || {'settings': {}, 'behaviors': {}};

(function ($)
{

  e107.behaviors.myBehavior = {
    attach: function (context, settings)
    {
      $(context).find(".some-element").once('my-behavior').each(function ()
      {
        // All your code here.
      });
    }
  };

})(jQuery);

Settings passed locally to JavaScript Behaviors

		e107.behaviors.myBehavior = {
  attach: function(context, settings) {
    $('#example', context).html(settings.myvar);
  }
};

How to override a JavaScript Behavior

If you want to override a bit of core (or third party) e107 JavaScript Behavior, just copy the behavior to your javascript file (e.g in your plugin or theme), then load it after the original code using "zones".


Thursday 09 November 2017 - 14:11:33 admin,

Social Links