Javascript

Please note: This page is under construction and has not been finished yet.

Introduction

....

Basic Javascript methods

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

e107::js($type, $data, $parm = null, $zone = null, $pre = '', $post = '')

Parameter	Value	Description	Mandatory?
type	See type & data		Yes
data	See type & data		Yes
parm	jquery | array	Specifies dependencies or other parameters	No
zone		Specifies the zone in which the javascript is loaded	No
pre			No
post			No

type & data

Type	Data	Description
core	path relative to the core folder	Include a core js file
url	full URL to javascript file	Include a remote js file
inline	javascript code	Include raw javascript code
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	Adds settings to e107's global storage of JavaScript settings.

Examples

Example #1

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

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

Example #2

Load a theme script in the footer

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

Example #3

Load a theme script in the header

e107::js("theme", "js/scripts.js", 'jquery', 2); // including a 'zone' value loads it in the header 

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.

Remember that loading from URL may take more time than local resources. Use dependency if needed!

JavaScript Behaviors

Behaviors are event-triggered actions that attach to page elements, enhancing default non-JavaScript UI's.

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 following 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".