Note:

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

jQuery: Difference between revisions

From MoodleDocs
m (Protected "jQuery": Developer Docs Migration ([Edit=Allow only administrators] (indefinite)))
 
(74 intermediate revisions by 14 users not shown)
Line 1: Line 1:
{{Moodle 2.5}}
{{Template:Migrated|newDocId=/docs/guides/javascript/jquery/}}
{{Deprecated|version=3.8}}
The use of jQuery in new code is strongly discouraged and is not generally accepted in new code. Specific exceptions to this rule are made on a case-by-case basis, generally when interfacing with legacy code which expects to be passed a jQuery object.


'''WORK IN PROGRESS'''
Moodle supports the use of native ES6-style modules and constructs since Moodle 3.8. These are transpiled into supported code.


YUI is the recommended library for development of Moodle plugins or customisations. However due to significant demand it will be possible to use also jQuery in Moodle 2.5 and later.
{{Moodle 2.9}}


Before Moodle 2.9 we used [[YUI]] to write javascript in Moodle. As of Moodle 2.9 we are transitioning to jQuery and [[Javascript Modules]] because Yahoo has ceased all new development on YUI (http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui). 


==Examples==
This page explains the recommended way to use jQuery in core and plugins, although other [[jQuery pre2.9|older]] methods of including jQuery will still work.


===Basic jQuery in add-on theme===
== Why do we need JQuery? ==
'''We do not need jQuery and its use is discouraged'''. The following is legacy documentation and no longer current advice.


# create /theme/sometheme/lib.php file if it does not exist yet
JQuery is useful for handling browser inconsistencies, and for utility functions that would otherwise be duplicated all over the code. Some particular things that JQuery is good at are:
# add new function theme_sometheme_page_init to the lib.php file (replace 'sometheme' with real name of your theme)
* DOM Manipulations
# use jQuery JavaScript in theme layout files
* Promises ($.Deferred)
* Ajax


<code php>
== How to use JQuery ==
<?php
As of Moodle 2.9, the recommended way to write javascript is in AMD Modules. For more information on writing AMD modules in Moodle see [[ Javascript Modules ]].  
// file: /theme/sometheme/lib.php
function theme_sometheme_page_init(moodle_page $page) {
    $page->requires->jquery();
}
</code>


<code html4strict>
JQuery has been added as an AMD Module and is available to all AMD javascript.  
// near the end of file: /theme/sometheme/layout/general.php
<script>
  $('.headermain').mouseover(function() {
    alert('grrr');
  });
</script>
</code>


===jQuery UI in add-on activity module===
To make use of JQuery, either list it as a dependency of your module, or use a require call to load it.


<code php>
=== As a dependency of a module ===
<syntaxhighlight lang="php">
    define(['jquery'], function($) {
        // Private functions.
        var privateFunc = function(a) {
            // JQuery is available via $ if I want it
            return a + 1;
        };
   
        // Public functions.
        return {
            publicFunc: function(b) {
                // JQuery is available via $ if I want it
                return privateFunc(b) + 1;
            }
        }
    });
</syntaxhighlight>


<?php
=== With a require call ===
require('../../config.php');
<syntaxhighlight lang="php">
 
    require(['jquery'], function($) {
// ... normal PAGE and access control
        // JQuery is available via $
 
    });
$PAGE->requires->jquery();
    // JQuery is not in scope and cannot be used.
$PAGE->requires->jquery_plugin('ui');
</syntaxhighlight>
$PAGE->requires->jquery_plugin('ui-css');


echo $OUTPUT->header();
== What about JQuery UI ? ==
?>
JQuery UI is a separate project containing a library of reusable widgets that relies on JQuery. JQuery UI is available for plugins to use, but it should not be used in core code.
    <button>A button element</button>


<div id="dialog" title="Basic dialog">
The problems with JQuery UI are:
  <p>This is the default dialog which is useful for displaying information. The dialog window can be moved, resized and closed with the 'x' icon.</p>
* It uses an entirely different themeing system for CSS that does not work well with Moodle themes
</div>
* It introduces CSS conflicts with bootstrap
    <script>
* The widgets have some accessibility features - but only if used in a very specific way which is not well documented
        $(function() {
            $( "#dialog" ).dialog();
        });
    </script>
<?php
echo $OUTPUT->footer();
</code>


===jQuery UI in add-on block===
Over time we will build up a library of widgets in core either by wrapping a suitable library or implementing from scratch.


<code php>
If you STILL want to use JQuery UI in your plugin, it is available as an AMD module named 'jqueryui'.


 
<syntaxhighlight lang="php">
class block_html extends block_base {
     require(['jquery', 'jqueryui'], function($, jqui) {
 
         // JQuery is available via $
     function get_required_javascript() {
         // JQuery UI is available via $.ui
        parent::get_required_javascript();
 
        $this->page->requires->jquery();
        $this->page->requires->jquery_plugin('ui');
        $this->page->requires->jquery_plugin('ui-css');
    }
 
    function get_content() {
 
         // ....
 
         $this->content->text .= '
<div id="progressbar"></div>
<script>
  $(function() {
    $( "#progressbar" ).progressbar({
      value: 37
     });
     });
  });
     // JQuery is not in scope and cannot be used.
  </script>';
     // JQuery UI is not in scope and cannot be used.
 
</syntaxhighlight>
 
        // ....
     }
</code>
 
===Override base jQuery UI theme===
# download new jQuery UI theme and extract it into theme/sometheme/jquery/
# create new jQuery theme ui css plugin in your theme
# overrider core 'ui-css' with 'yourtheme-ui-css'
 
<code php>
<?php
// file: theme/sometheme/jquery/plugins.php
$plugins = array(
     'some-ui-css'  => array('files' => array('custom-1.0/jquery-ui-1.10.2.custom.min.css')),
);
</code>
 
<code php>
<?php
// file: /theme/sometheme/lib.php
function theme_sometheme_page_init(moodle_page $page) {
    // There is no need to $page->requires->jquery() ff the theme does not use jQuery.
    $page->requires->jquery_plugin('sometheme-ui-css', 'theme_sometheme');
    $page->requires->jquery_override_plugin('ui-css', 'sometheme-ui-css');
}
</code>
 
===Backwards compatibility for scripts written for older jQuery scripts===
 
See [https://github.com/jquery/jquery-migrate/ jQuery Migrate plugin]
 
<code php>
$PAGE->requires->jquery_plugin('migrate');
</code>
 
==More information==
 
===mymobile theme===
 
See mymobile theme for more information including custom jQuery plugins, integration with jQuery Mobile.
 
===jQuery plugin collisions===


The loading order of plugins is defined by order of $PAGE->requires. If there are plugins with the same name the first $PAGE->require wins.
{{Moodle 3.2}}
In Moodle 3.2 we upgraded jQuery to 3.1 and removed the jQuery migrate plugin. You should not have to change your code unless you have been ignoring jQuery deprecation notices for many many years (but it's recommended to test it in 3.2).


It is recommended to use plugin overrides only in themes because multiple overrides of the same plugin result in undefined behaviour. In general themes should have more freedom to add extra jQuery plugins, other Moodle plugins should ideally use only basic jQuery or jQuery UI.
==See also==
* [[Javascript Modules]]
* [[Useful core Javascript modules]]
* [[jQuery pre2.9]]
* [http://jquery.com jQuery]
* [http://jqueryui.com jQuery User Interface]


===See also===
[[Category:Javascript]]
* [http://jquery.com]
* [http://jqueryui.com]

Latest revision as of 14:05, 24 June 2022

Important:

This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date.

Why not view this page on the new site and help us to migrate more content to the new site!

This feature has been marked as deprecated since Moodle 3.8

The use of jQuery in new code is strongly discouraged and is not generally accepted in new code. Specific exceptions to this rule are made on a case-by-case basis, generally when interfacing with legacy code which expects to be passed a jQuery object.

Moodle supports the use of native ES6-style modules and constructs since Moodle 3.8. These are transpiled into supported code.

Moodle 2.9


Before Moodle 2.9 we used YUI to write javascript in Moodle. As of Moodle 2.9 we are transitioning to jQuery and Javascript Modules because Yahoo has ceased all new development on YUI (http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui).

This page explains the recommended way to use jQuery in core and plugins, although other older methods of including jQuery will still work.

Why do we need JQuery?

We do not need jQuery and its use is discouraged. The following is legacy documentation and no longer current advice.

JQuery is useful for handling browser inconsistencies, and for utility functions that would otherwise be duplicated all over the code. Some particular things that JQuery is good at are:

  • DOM Manipulations
  • Promises ($.Deferred)
  • Ajax

How to use JQuery

As of Moodle 2.9, the recommended way to write javascript is in AMD Modules. For more information on writing AMD modules in Moodle see Javascript Modules .

JQuery has been added as an AMD Module and is available to all AMD javascript.

To make use of JQuery, either list it as a dependency of your module, or use a require call to load it.

As a dependency of a module

    define(['jquery'], function($) {
        // Private functions.
        var privateFunc = function(a) {
            // JQuery is available via $ if I want it
            return a + 1;
        };
    
        // Public functions.
        return {
            publicFunc: function(b) {
                // JQuery is available via $ if I want it
                return privateFunc(b) + 1;
            }
        }
    });

With a require call

    require(['jquery'], function($) {
        // JQuery is available via $
    });
    // JQuery is not in scope and cannot be used.

What about JQuery UI ?

JQuery UI is a separate project containing a library of reusable widgets that relies on JQuery. JQuery UI is available for plugins to use, but it should not be used in core code.

The problems with JQuery UI are:

  • It uses an entirely different themeing system for CSS that does not work well with Moodle themes
  • It introduces CSS conflicts with bootstrap
  • The widgets have some accessibility features - but only if used in a very specific way which is not well documented

Over time we will build up a library of widgets in core either by wrapping a suitable library or implementing from scratch.

If you STILL want to use JQuery UI in your plugin, it is available as an AMD module named 'jqueryui'. 

    require(['jquery', 'jqueryui'], function($, jqui) {
        // JQuery is available via $
        // JQuery UI is available via $.ui
    });
    // JQuery is not in scope and cannot be used.
    // JQuery UI is not in scope and cannot be used.

Moodle 3.2

In Moodle 3.2 we upgraded jQuery to 3.1 and removed the jQuery migrate plugin. You should not have to change your code unless you have been ignoring jQuery deprecation notices for many many years (but it's recommended to test it in 3.2).

See also

Retrieved from "https://docs.moodle.org/dev/index.php?title=jQuery&oldid=63444"
Powered by MediaWiki