JavaScript and Cantemo

It is important if you are planning on developing any Apps that interface with the user that you understand JavaScript and how Cantemo utilises JavaScript to enhance and bring about behaviour on the pages of the site.

The JavaScript libraries that we use are updated on major versions for performance, enhanced functionality and better APIS. If there is a potential security risk the libraries will be updated on a minor version.

Standard modules used

• JQuery

• JQuery UI

• LoDash

• Backbone.js

• LAB.js

• Datatables

JQuery

JQuery is used both for animation and for bringing about behaviour in the page.

http://jquery.com/

JQuery UI

Please see the JQuery UI documentation available from the JQuery UI website for more information on the capabilities of JQuery UI.

http://jqueryui.com/

Backbone.js and LoDash

We use LoDash instead of Underscore.js because of the better native features that Lodash provides over Underscore.js

http://lodash.com/

http://backbonejs.org/

Translation

Strings that should be able to be translated can be wrapped in the gettext function, for example this will create an alert, but with a translatable string:

alert(gettext('This string will be available for translation'));

Please refer to the Translation and also the Django documentation on how to properly work with translation.

Creating modal dialogs

Many places in the interface we use modal dialogs (often referred to as pop-ups) to prompt users for more information on tasks that they wish to carry out. Examples are:

• Export

• Add to Collection

• New Saved Search.

All of these contain menus which the user needs to fill out.

We use JQuery UI Dialog widget to provide this modal dialog. In the past a widget called $.facebox was used, but this is being phased out as of version 1.6. and at a later date will be removed altogether.

Standard Example

Example of creating modal from a HTML page that can be served from Cantemo:

var standardOptions = {
    width: 600,
    modal: true,
    resizable: false,
    dialogClass: 'myDialogClass',
    title: gettext('Export'),
    show: { effect: "fade", duration: 300 },
    hide: { effect: "fade",  duration: 300 }
    };
$dialogEl = $('<div></div>');
$dialogEl.load('/url/to/my/plugin/').dialog(standardOptions);

This will create a div element, then load ‘/url/to/my/plugin/’ page from Cantemo, and put that in to the div element, and then call dialog on it. One of the side effects of doing this is that any script tag in the page from Cantemo will be executed.

Extended Example

Example without script tags in the called page, that would call the export view, setup buttons, and then display it self with handlers for submitting:

export: function(event) {
    event.preventDefault();
    var self=this, buttons;
    $.get('{% url "vs_items_export" %}?selected_objects={{ item.getId }}', \
                                                      function(data){
        buttons = [{
          text: gettext('Close'),
          click: function() { $(this).dialog('close')},
          class: 'close-export-button ui-dialog-button-cancel'
        }];
        self.$dialogEl = $('<div></div>');
        self.$dialogEl.html(data).dialog(standardOptions);
        if (self.$dialogEl.find('form#export_ajax_form').length == 1){
            buttons = [{
              text: gettext('Export'),
              click: function() { $('form#export_ajax_form').ajaxSubmit({
                beforeSubmit: function(arr, $form, options) {
                  $("#vscollectionexport").empty().end().html\
                   ('<center><img src="{{STATIC_URL}}img/core/\
                   loading-small.gif" /></center>');
                  return true;
                },
                success: function(responseText, statusText, xhr, $form) {
                  if (statusText == "success"){
                      $.growl(responseText, 'success');
                      $(".ui-dialog-content").dialog("close");
                  }
                },
                error: function(responseText, statusText, xhr, $form) {
                  $.growl(responseText.responseText, 'error');
                  $("#vscollectionexport").empty().end();
                  $(".ui-dialog-content").dialog("close");
                }
                });
              },
              class: 'send-export-button ui-dialog-button-confirm'
            }].concat(buttons);
            self.$dialogEl.dialog('option', 'buttons', buttons);
        } else {
            self.$dialogEl.dialog('option', 'buttons', buttons);
        }
      });
},

This example is shown in how it could be implemented as a handler, for a click event in a Backbone.js view.