Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Useful core Javascript modules: Difference between revisions

From MoodleDocs
m (Add core/tree)
(Give examples)
(21 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{Moodle 2.9}}
{{Moodle 2.9}}
The source code for all these modules (and a number of others) can be found in lib/amd/src.


== Configuration settings (core/config) ==
== Configuration settings (core/config) ==
Line 6: Line 8:
<code javascript>
<code javascript>
require(['core/config’], function(mdlcfg) {
require(['core/config’], function(mdlcfg) {
     cosole.log(mdlcfg.wwwroot); // outputs the wwwroot of moodle to console
     console.log(mdlcfg.wwwroot); // outputs the wwwroot of moodle to console
});
});
</code>
</code>
Line 15: Line 17:
<code javascript>
<code javascript>
require([‘core/str’], function(str) {
require([‘core/str’], function(str) {
     str.get_string('edita', 'core', stringargument).done(function(s) {
     // start retrieving the localized string; store the promise that some time in the future the string will be there.
      console.log(s);
    var editaPresent = str.get_string('edita', 'core', stringargument);
     }).fail(console.log(e));
    // as soon as the string is retrieved, i.e. the promise has been fulfilled,
    // edit the text of a UI element so that it then is the localized string
    // Note: $.when can be used with an arbitrary number of promised things
    $.when(editaPresent).done(function(localizedEditString) {
        $("someUIElementSelector").text = localizedEditString;
     });
});
});
</code>
You can also convert multiple strings and add parameters in a single call
<code javascript>
    // Real example from user/amd/src/status_field.js
    var strings = [
        {
            key: 'unenrol',
            component: 'enrol'
        },
        {
            key: 'unenrolconfirm',
            component: 'enrol',
            param: {
                user: parentContainer.data('fullname'),
                course: parentContainer.data('coursename'),
                enrolinstancename: parentContainer.data('enrolinstancename')
            }
        }
    ];
    str.get_strings(strings).then(function (results) {
        console.log(results);
    });
</code>
</code>


Line 60: Line 90:


== URL module (core/url) ==
== URL module (core/url) ==
Useful Functions:
<code javascript>
// Generate an absolute URL by using the relative path to a file and optionally slash arguments
url.fileUrl(relativeScript, slashArgs)
// Generate an absolute URL from the given relative path, include the URL parameters and possibly the current session key
url.relativeUrl(relativePath, params, includeSessionKey)
// Generates an image url using the filename of the image and the Moodle component (core, plugin, etc.) where it can be found
url.imageUrl(imagename, component)
</code>
Example:


<code javascript>
<code javascript>
// Prerequisites:
// - A Javascript file is present under $CFG->wwwroot."/path/to/file.js"
require(['core/url'], function(url) {
require(['core/url'], function(url) {
     url.fileUrl(relativeScript, slashArg);
     url.fileUrl("/path/to/file.js", "");
     url.relativeUrl(relativePath);
     console.log("Generated URL: " + url);
    url.imageUrl(imagename, component);
});
});
</code>
</code>
== Ajax Module (core/ajax) ==
The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions. This saves having to worry about security in ajax functionality because it's all done for you.
For the full story, see [[AJAX]]


== Tree (core/tree) ==
== Tree (core/tree) ==
 
{{Moodle 3.1}}
If you want to add a hierarchical interface, you should use the tree module. It will handle user interaction and accessibility for you.
If you want to add a hierarchical interface, you should use the tree module. It will handle user interaction and accessibility for you.


Line 77: Line 126:
     return {
     return {
         init: function() {
         init: function() {
        new Tree("css/jquery selector of the tree container");
            new Tree("css/jquery selector of the tree container");
    }
        }
     };
     };
});
</code>
Read more about the [[Tree]] module
== Modal (core/modal) ==
{{Moodle 3.2}}
If you'd like to add a modal to your page the modal modules will handle all of the magic for you, all you need to bring is your content!
<code javascript>
require(['jquery', 'core/modal_factory'], function($, ModalFactory) {
  var trigger = $('#create-modal');
  ModalFactory.create({
    title: 'test title',
    body: '<p>test body content</p>',
    footer: 'test footer content',
  }, trigger)
  .done(function(modal) {
    // Do what you want with your new modal.
    // Maybe... add a class to the modal dialog, to be able to style it.
    modal.getRoot().addClass('mydialog');
  });
});
</code>
Read more about the [[AMD_Modal]] module
== Paged content (core/paged_content_factory) ==
{{Moodle 3.6}}
If you need to create a paged content region to asynchronously load the pages as the user requests them then you can use the paged content modules.
Read more about the [[AMD_paged_content]] module
== PubSub (core/pubsub) ==
{{Moodle 3.6}}
A simple module to do event subscription and publishing in JavaScript without the need for jQuery.
Read more about the [[AMD_pubsub]] module
== Loading icons (core/loadingicon) ==
{{Moodle 3.7}}
A simple module to add a loading icon which is easily removable, either via resolving a Promise, or removes itself automatically when another Promise is resolved.
<code javascript>
define(['jquery', 'core/ajax', 'core/loadingicon'], function($, Ajax, LoadingIcon) {
  return {
    demo1: function() {
      // Add a loading icon which can be removed by the caller.
      var exampleElement = $('.example');
      var loadingIcon = LoadingIcon.addIconToContainerWithPromise(exampleElement);
      // To remove:
      loadingIcon.resolve();
    },
    demo2: function() {
      // Add a loading icon which would be removed when the AJAX request completes.
      var exampleElement = $('.example');
      var requests = Ajax.call([{
          methodname: 'some_method',
      }]);
      LoadingIcon.addIconToContainerRemoveOnCompletion(exampleElement, requests);
      requests[0].then(function(request) {
          // Do something.
      })
      .catch;
    },
  };
});
});
</code>
</code>
Line 85: Line 209:
==See also==
==See also==
* [[Javascript Modules]]
* [[Javascript Modules]]
* [[Fragment]]




[[Category:AJAX]]
[[Category:AJAX]]
[[Category:Javascript]]
[[Category:Javascript]]

Revision as of 05:57, 6 May 2019

Moodle 2.9


The source code for all these modules (and a number of others) can be found in lib/amd/src.

Configuration settings (core/config)

Example of using config module: require(['core/config’], function(mdlcfg) {

   console.log(mdlcfg.wwwroot); // outputs the wwwroot of moodle to console

});

Language strings (core/str)

Example of using language strings module (retrieved via ajax, if the string is not yet loaded) require([‘core/str’], function(str) {

   // start retrieving the localized string; store the promise that some time in the future the string will be there.
   var editaPresent = str.get_string('edita', 'core', stringargument);
   // as soon as the string is retrieved, i.e. the promise has been fulfilled,
   // edit the text of a UI element so that it then is the localized string
   // Note: $.when can be used with an arbitrary number of promised things
   $.when(editaPresent).done(function(localizedEditString) {
        $("someUIElementSelector").text = localizedEditString;
   });

});

You can also convert multiple strings and add parameters in a single call

   // Real example from user/amd/src/status_field.js
   var strings = [
       {
           key: 'unenrol',
           component: 'enrol'
       },
       {
           key: 'unenrolconfirm',
           component: 'enrol',
           param: {
               user: parentContainer.data('fullname'),
               course: parentContainer.data('coursename'),
               enrolinstancename: parentContainer.data('enrolinstancename')
           }
       }
   ];
   str.get_strings(strings).then(function (results) {
       console.log(results);
   });

The string will be retrieved via AJAX request on the first use and cached in browser local storage until purge caches or site upgrade

IT IS NOT RECOMMENDED to call: $PAGE->requires->string_for_js('edita', 'core'); // You do not need this!

Because:

  • The list of strings used now needs to be maintained in 2 places
  • The strings are always sent, and bloat the page size even if they are not used
  • All strings fetched via the AJAX method above are cached in browser local storage anyway, so these strings will never be used 99% of the time

Notifications (core/notification)

Examples: require(['core/notification’], function(notification) {

   notification.alert('Hello', 'Welcome to my site!', 'Continue');

});

Strings and notifications: require(['core/str', 'core/notification’], function(str, notification) {

               str.get_strings([
                       {'key' : 'delete'},
                       {'key' : 'confirmdeletetag', component : 'tag'},
                       {'key' : 'yes'},
                       {'key' : 'no'},
                   ]).done(function(s) {
                       notification.confirm(s[0], s[1], s[2], s[3], function() {
                           window.location.href = href;
                       });
                   }
               ).fail(notification.exception);

});

URL module (core/url)

Useful Functions: // Generate an absolute URL by using the relative path to a file and optionally slash arguments url.fileUrl(relativeScript, slashArgs) // Generate an absolute URL from the given relative path, include the URL parameters and possibly the current session key url.relativeUrl(relativePath, params, includeSessionKey) // Generates an image url using the filename of the image and the Moodle component (core, plugin, etc.) where it can be found url.imageUrl(imagename, component)

Example:

// Prerequisites: // - A Javascript file is present under $CFG->wwwroot."/path/to/file.js" require(['core/url'], function(url) {

   url.fileUrl("/path/to/file.js", "");
   console.log("Generated URL: " + url);

});

Ajax Module (core/ajax)

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions. This saves having to worry about security in ajax functionality because it's all done for you.

For the full story, see AJAX

Tree (core/tree)

Moodle 3.1

If you want to add a hierarchical interface, you should use the tree module. It will handle user interaction and accessibility for you.

define(['jquery', 'core/tree'], function($, Tree) {

   return {
       init: function() {
           new Tree("css/jquery selector of the tree container");
       }
   };

});

Read more about the Tree module

Modal (core/modal)

Moodle 3.2


If you'd like to add a modal to your page the modal modules will handle all of the magic for you, all you need to bring is your content! require(['jquery', 'core/modal_factory'], function($, ModalFactory) {

 var trigger = $('#create-modal');
 ModalFactory.create({
   title: 'test title',

body: '

test body content

',

   footer: 'test footer content',
 }, trigger)
 .done(function(modal) {
   // Do what you want with your new modal.
   // Maybe... add a class to the modal dialog, to be able to style it.
   modal.getRoot().addClass('mydialog');
 });

});

Read more about the AMD_Modal module

Paged content (core/paged_content_factory)

Moodle 3.6


If you need to create a paged content region to asynchronously load the pages as the user requests them then you can use the paged content modules.

Read more about the AMD_paged_content module

PubSub (core/pubsub)

Moodle 3.6


A simple module to do event subscription and publishing in JavaScript without the need for jQuery.

Read more about the AMD_pubsub module

Loading icons (core/loadingicon)

Moodle 3.7


A simple module to add a loading icon which is easily removable, either via resolving a Promise, or removes itself automatically when another Promise is resolved.

define(['jquery', 'core/ajax', 'core/loadingicon'], function($, Ajax, LoadingIcon) {

 return {
   demo1: function() {
     // Add a loading icon which can be removed by the caller.
     var exampleElement = $('.example');
     var loadingIcon = LoadingIcon.addIconToContainerWithPromise(exampleElement);
     // To remove:
     loadingIcon.resolve();
   },
   demo2: function() {
     // Add a loading icon which would be removed when the AJAX request completes.
     var exampleElement = $('.example');
     var requests = Ajax.call([{
         methodname: 'some_method',
     }]);
     LoadingIcon.addIconToContainerRemoveOnCompletion(exampleElement, requests);
     requests[0].then(function(request) {
         // Do something.
     })
     .catch;
   },
 };

});

See also