From cfb3ab7fc8d733c34052bb7624ca3aedc313a7db Mon Sep 17 00:00:00 2001 From: Dmytro Poperechnyy Date: Mon, 4 Nov 2019 14:31:28 -0600 Subject: [PATCH 1/4] Replace jquery/ui usages with individual jQuery UI components --- .../javascript/custom_js.md | 178 +++++++++++++++++- .../javascript/js_practice.md | 143 +++++++++++++- 2 files changed, 319 insertions(+), 2 deletions(-) mode change 120000 => 100644 guides/v2.3/javascript-dev-guide/javascript/custom_js.md mode change 120000 => 100644 guides/v2.3/javascript-dev-guide/javascript/js_practice.md diff --git a/guides/v2.3/javascript-dev-guide/javascript/custom_js.md b/guides/v2.3/javascript-dev-guide/javascript/custom_js.md deleted file mode 120000 index 984c5f13063..00000000000 --- a/guides/v2.3/javascript-dev-guide/javascript/custom_js.md +++ /dev/null @@ -1 +0,0 @@ -../../../../guides/v2.2/javascript-dev-guide/javascript/custom_js.md \ No newline at end of file diff --git a/guides/v2.3/javascript-dev-guide/javascript/custom_js.md b/guides/v2.3/javascript-dev-guide/javascript/custom_js.md new file mode 100644 index 00000000000..6a8e290d9be --- /dev/null +++ b/guides/v2.3/javascript-dev-guide/javascript/custom_js.md @@ -0,0 +1,177 @@ +--- +group: javascript-developer-guide +subgroup: 1_Javascript +title: Use custom JavaScript +--- + +## Overview {#custom_js_overview} + +This topic discusses how to use custom [JavaScript](https://glossary.magento.com/javascript) components with the components provided by Magento or having replaced them with custom implementations. + +We strongly recommend not changing the source code of default Magento components and widgets. All customizations must be implemented in custom modules or themes. + +## Add a custom JS component + +To add a custom JS component (module), take the following steps: + +1. Place the custom component source file in one of the following locations: + - Your theme JS files: `/web/js` or `/_/web/js`. In this case the component is available in your theme and its [child themes]({{ page.baseurl }}/frontend-dev-guide/themes/theme-inherit.html). + - Your module view JS files: `/view/frontend/web/js`. In this case the component is available in all modules and themes (if your module is enabled). + +1. Optionally, in the corresponding [module](https://glossary.magento.com/module) or theme, create a `requirejs-config.js` configuration file, if it does not yet exist there and set path for your resource. The RequireJS configuration file can be placed in one of the following locations: + + - Your theme: `` + - Module within your theme: `/` + - Your module (depending on the needed area - **base**, **frontend**, **adminhtml**): `/view/` + +## Replace a default JS component {#js_replace} + +To use a custom implementation of an existing Magento JS component: +Place the custom component source file in one of the following +locations: + +- Your theme JS files: `/web/js` +- Your module view JS files: `/view/frontend/web/js` + +Create a RequireJS configuration file `requirejs-config.js`, having +specified the following: + +```javascript +var config = { + "map": { + "*": { + "": "" + } + } +}; +``` + +- ``: the name of the default component you replace +- ``: the name of the custom component + +For example, if you want to use custom `navigation-menu.js` script instead of the default menu widgets, your `requirejs-config.js` should contain the following: + +```javascript +var config = { + "map": { + "*": { + "menu": "js/navigation-menu", + "mage/backend/menu": "js/navigation-menu" + } + } +}; +``` + +Place your `requirejs-config.js` file in one of the following +directories (according to the location of your custom script, see step 1 +of this procedure): + +- Your [theme](https://glossary.magento.com/theme) files: `` +- Your module view files: `/view/frontend` + +This way your custom JS component is used instead of the [Magento component](https://glossary.magento.com/magento-component) in all entries all over the [frontend](https://glossary.magento.com/frontend) area. + +## Extend a default JS component {#extend_js} + +You can add a custom JS component/widget, which will extend a default Magento component/widget. + +### Extend Magento widget {#extend_js_widget} + +To extend a default Magento [jQuery](https://glossary.magento.com/jquery) widget, create `.js` with the following contents: + +```javascript +define([ + 'jquery', + 'jquery-ui-modules/widget', // use individual jQuery UI component if your widget is for frontend or base areas + // 'jquery/ui', // use all 'jquery/ui' library if your widget is for adminhtml area + 'mage/' // usually widget can be found in /lib/web/mage dir +], function($){ + + $.widget('.', $.mage., { ... }); + + return $..; +}); +``` + +Where the following notation is used: + +- `.` - the name of your custom [widget](https://glossary.magento.com/widget). According to the jQuery widgets naming + convention, must contain a [namespace](https://glossary.magento.com/namespace) and name. +- `mage.` - the name of the Magento widget that you + extend. + +{:.bs-callout .bs-callout-tip} +All jQuery UI components for frontend and base areas are located in `lib/web/jquery/ui-modules` dir. They can be used in JS widgets by `jquery-ui-modules` path mapping like `jquery-ui-modules/widget`, `jquery-ui-modules/slider` etc. +Usage of individual jQuery UI components instead of monolith jQuery UI library improves storefront performance. + +For information about how to initialize your custom widget in a `.phtml` template, see the [JavaScript initialization]({{ page.baseurl }}/javascript-dev-guide/javascript/js_init.html){:target="_blank"} topic. + +### Extend a default Ui component {#extend_js_component} + +To extend a default JS Ui component, your custom script must contain the following: + +```javascript +define([ + '' +], function(){ + + return .extend({ + + defaults: { ... }, // properties with default values + ... // methods of your component + }); +}); +``` + +Where the following notation is used: + +- ``: path to the default component that you extend +- ``: variable containing the default component that you extend + +For example, `Filters.js` script extends the default `filters.js`: + +```javascript +define([ + 'Magento_Ui/js/grid/filters/filters' +], function(Filters){ + + return Filters.extend({ + + defaults: { ... }, // properties with default values + ... // methods of your component + }); +}); +``` + +For information about how to initialize your custom JS component in a `.phtml` template, see the [JavaScript initialization] topic. + +## Disable default Magento JS {#disable_default_js} + +To disable the auto-loading of default Magento JS components and widget initialization: + +1. Create a `requirejs-config.js` file with the following content: + + ```javascript + var config = { deps: [ ] }; + ``` + +1. Put the `requirejs-config.js` file in one of the following + locations: + + - Your custom theme files: `` + - Your custom module files: `/view/frontend` + +If you need to enable the loading of default Magento JS components and widget initialization on a certain stage, add the following code in your JS script: + +```javascript +$(mage.apply); +``` + +{:.ref-header} +Related topic + +- [JavaScript resources in Magento]({{ page.baseurl }}/javascript-dev-guide/javascript/js-resources.html) +- [About AMD modules and RequireJS]({{ page.baseurl }}/javascript-dev-guide/javascript/js-resources.html) + +[JavaScript initialization]: {{page.baseurl}}/javascript-dev-guide/javascript/js_init.html +v2.3/performance-best-practices/advanced-js-bundling.html diff --git a/guides/v2.3/javascript-dev-guide/javascript/js_practice.md b/guides/v2.3/javascript-dev-guide/javascript/js_practice.md deleted file mode 120000 index af297b5e7e2..00000000000 --- a/guides/v2.3/javascript-dev-guide/javascript/js_practice.md +++ /dev/null @@ -1 +0,0 @@ -../../../../guides/v2.2/javascript-dev-guide/javascript/js_practice.md \ No newline at end of file diff --git a/guides/v2.3/javascript-dev-guide/javascript/js_practice.md b/guides/v2.3/javascript-dev-guide/javascript/js_practice.md new file mode 100644 index 00000000000..8824f2a1962 --- /dev/null +++ b/guides/v2.3/javascript-dev-guide/javascript/js_practice.md @@ -0,0 +1,142 @@ +--- +group: javascript-developer-guide +subgroup: 1_Javascript +title: Customizing JavaScript illustration +--- + +## Overview {#practice_overview} + +This topic features a step-by-step illustration of how to customize a [jQuery](https://glossary.magento.com/jquery) [widget](https://glossary.magento.com/widget) and how to use a custom widget instead the default Magento one. + +## Customize a default Magento jQuery widget + +In their Orange theme, OrangeCo wants to remove the "Click on image to view it full sized" message displayed on the product page. + +The high-level steps for this task are the following: + +1. Define how the message is output. +1. Add the custom script extending the default one. +1. Update RequireJS configuration to use the custom script instead of the default one. + +Let's look at each step in more detail. + +### Step 1: Define how the message is output {#define_script1} + +OrangeCo needs to define how the message is output. To do this, they take the following steps: + +1. Open a product page. +1. Select to view the page source. +1. Search for the "Click on image to view it full sized" string. The illustration of the search result follows: ![Page source search result] +1. View that it is output by [`gallery.js`]. + +We see that the script which OrangeCo needs to alter is `gallery.js`. + +To be able to extend `gallery.js`, OrangeCo needs to know the path to it. To get this info, they refer to `requirejs-config.js`, which [can be reached from the page source view or from the file system]. According to the configuration, the path for `gallery` is `mage/gallery`. The illustration follows: + +![RequireJS config file] + +### Step 2: Add the custom widget extending the gallery widget {#add_code1} + +In the `app/design/frontend/OrangeCo/orange/web/js` OrangeCo adds `orange-gallery.js` with the following content: + +```javascript +define([ + 'jquery', + 'jquery-ui-modules/widget', + 'mage/gallery' +], function($){ + + $.widget('orange.gallery', $.mage.gallery, { + _create: function() { // special method of jQuery UI Widgets + this._setOption('controls', {'notice': {}}); + } + }); + + return $.orange.gallery; +}); +``` + +### Step 3: Update the RequireJS configuration {#config1} + +OrangeCo adds the custom `app/design/OrangeCo/orange/requirejs-config.js` with the following content: + +```javascript +var config = { + "map": { + "*": { + "gallery": "js/orange-gallery" + } + } +}; +``` + +The new behavior is applied once the store pages are reloaded. + +## Add and use a custom widget (jCarousel) {#use_custom_widget} + +OrangeCo wants to use the [jCarousel widget] to display product images on product pages. The high level steps for this task are the following: + +1. Define how product images are displayed by default. +1. Add the custom script to the file system. +1. Update RequireJS configuration to use the custom script instead of the default one. + +Let's look at each step in more detail. + +### Step 1: Define what is the default implementation + +Using the approach described in the previous section, OrangeCo defines that the product images are displayed by [`gallery.js`], and the configuration path for it is `mage/gallery`. + +### Step 2: Add the custom script to the file system + +For the jCarousel widget to be able to use the configuration passed to the gallery widget, +OrangeCo needs to add a "wrapper" script. + +To do this, OrangeCo adds the following files in the `app/design/frontend/OrangeCo/orange/web/js` directory: + +- The jCarousel widget source file: `jquery.jcarousel.js` +- A \"wrapper\" `orange-carousel.js` with the following content: + + ```javascript + define([ + 'jquery', + 'js/jquery.jcarousel' + ], function($){ + + return function (config, element) { + var jCarouselConfig = { + list: '.items.thumbs', + items: '.item.thumb' + }; + $(element).jcarousel(jCarouselConfig); + } + }); + ``` + +### Step 3: Update RequireJS configuration + +In the `app/design/OrangeCo/orange` directory OrangeCo adds `requirejs-config.js` with the following content: + +```javascript +var config = { + "map": { + "*": { + "gallery": "js/orange-gallery" + } + }, + "shim": { + "js/jquery.jcarousel": ["jquery"] // as jquery.jcarousel isn't an AMD module + } +}; +``` + +## Recommended reading + +[Use custom JavaScript] + +[Page source search result]: {{site.baseurl}}/common/images/fdg_js_pr1.png +[`gallery.js`]: {{ site.mage2bloburl }}/{{ page.guide_version }}/lib/web/mage/gallery/gallery.js +[can be reached from the page source view or from the file system]: {{page.baseurl}}/javascript-dev-guide/javascript/custom_js.html#extend_js +[RequireJS config file]: {{site.baseurl}}/common/images/fdg_pr_2.png +[jCarousel widget]: http://sorgalla.com/jcarousel/ +[`gallery.js`]: {{ site.mage2bloburl }}/{{ page.guide_version }}/lib/web/mage/gallery/gallery.js +[Use custom JavaScript]: {{page.baseurl}}/javascript-dev-guide/javascript/custom_js.html From 5e45ec52ae53e3c4298dfbfd38903c30bb497b4f Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Mon, 4 Nov 2019 16:40:58 -0600 Subject: [PATCH 2/4] Update custom_js.md --- .../javascript/custom_js.md | 42 ++++++++----------- 1 file changed, 17 insertions(+), 25 deletions(-) diff --git a/guides/v2.3/javascript-dev-guide/javascript/custom_js.md b/guides/v2.3/javascript-dev-guide/javascript/custom_js.md index 6a8e290d9be..6ffde055f33 100644 --- a/guides/v2.3/javascript-dev-guide/javascript/custom_js.md +++ b/guides/v2.3/javascript-dev-guide/javascript/custom_js.md @@ -1,22 +1,19 @@ --- group: javascript-developer-guide -subgroup: 1_Javascript title: Use custom JavaScript --- -## Overview {#custom_js_overview} +This topic discusses how to use custom [JavaScript](https://glossary.magento.com/javascript) components with the components provided by Magento or custom replacement implementations. -This topic discusses how to use custom [JavaScript](https://glossary.magento.com/javascript) components with the components provided by Magento or having replaced them with custom implementations. +We strongly recommend that you do not change the source code of default Magento components and widgets. All customizations must be implemented in custom modules or themes. -We strongly recommend not changing the source code of default Magento components and widgets. All customizations must be implemented in custom modules or themes. - -## Add a custom JS component +## Add a custom JS component {#custom_js_overview} To add a custom JS component (module), take the following steps: 1. Place the custom component source file in one of the following locations: - Your theme JS files: `/web/js` or `/_/web/js`. In this case the component is available in your theme and its [child themes]({{ page.baseurl }}/frontend-dev-guide/themes/theme-inherit.html). - - Your module view JS files: `/view/frontend/web/js`. In this case the component is available in all modules and themes (if your module is enabled). + - Your module view JS files: `/view/frontend/web/js`. In this case, the component is available in all modules and themes (if your module is enabled). 1. Optionally, in the corresponding [module](https://glossary.magento.com/module) or theme, create a `requirejs-config.js` configuration file, if it does not yet exist there and set path for your resource. The RequireJS configuration file can be placed in one of the following locations: @@ -27,14 +24,13 @@ To add a custom JS component (module), take the following steps: ## Replace a default JS component {#js_replace} To use a custom implementation of an existing Magento JS component: -Place the custom component source file in one of the following -locations: + +Place the custom component source file in one of the following locations: - Your theme JS files: `/web/js` - Your module view JS files: `/view/frontend/web/js` -Create a RequireJS configuration file `requirejs-config.js`, having -specified the following: +Create a RequireJS configuration file `requirejs-config.js`, having specified the following: ```javascript var config = { @@ -49,7 +45,7 @@ var config = { - ``: the name of the default component you replace - ``: the name of the custom component -For example, if you want to use custom `navigation-menu.js` script instead of the default menu widgets, your `requirejs-config.js` should contain the following: +For example, if you want to use a custom `navigation-menu.js` script instead of the default menu widgets, your `requirejs-config.js` should contain the following: ```javascript var config = { @@ -62,14 +58,12 @@ var config = { }; ``` -Place your `requirejs-config.js` file in one of the following -directories (according to the location of your custom script, see step 1 -of this procedure): +Place your `requirejs-config.js` file in one of the following directories (according to the location of your custom script, see step 1 of this procedure): - Your [theme](https://glossary.magento.com/theme) files: `` - Your module view files: `/view/frontend` -This way your custom JS component is used instead of the [Magento component](https://glossary.magento.com/magento-component) in all entries all over the [frontend](https://glossary.magento.com/frontend) area. +This way, your custom JS component is used instead of the [Magento component](https://glossary.magento.com/magento-component) in all entries all over the [frontend](https://glossary.magento.com/frontend) area. ## Extend a default JS component {#extend_js} @@ -77,7 +71,7 @@ You can add a custom JS component/widget, which will extend a default Magento co ### Extend Magento widget {#extend_js_widget} -To extend a default Magento [jQuery](https://glossary.magento.com/jquery) widget, create `.js` with the following contents: +To extend a default Magento [jQuery](https://glossary.magento.com/jquery) widget, create `.js` with contents similar to the following: ```javascript define([ @@ -95,16 +89,14 @@ define([ Where the following notation is used: -- `.` - the name of your custom [widget](https://glossary.magento.com/widget). According to the jQuery widgets naming - convention, must contain a [namespace](https://glossary.magento.com/namespace) and name. -- `mage.` - the name of the Magento widget that you - extend. +- `.` - the name of your custom [widget](https://glossary.magento.com/widget). According to the jQuery widgets naming convention, this value must contain a [namespace](https://glossary.magento.com/namespace) and name. +- `mage.` - the name of the Magento widget that you extend. {:.bs-callout .bs-callout-tip} -All jQuery UI components for frontend and base areas are located in `lib/web/jquery/ui-modules` dir. They can be used in JS widgets by `jquery-ui-modules` path mapping like `jquery-ui-modules/widget`, `jquery-ui-modules/slider` etc. -Usage of individual jQuery UI components instead of monolith jQuery UI library improves storefront performance. +All jQuery UI components for frontend and base areas are located in `lib/web/jquery/ui-modules` dir. They can be used in JS widgets by `jquery-ui-modules` path mapping like `jquery-ui-modules/widget` and `jquery-ui-modules/slider`. +Using individual jQuery UI components instead of the monolithic jQuery UI library improves storefront performance. -For information about how to initialize your custom widget in a `.phtml` template, see the [JavaScript initialization]({{ page.baseurl }}/javascript-dev-guide/javascript/js_init.html){:target="_blank"} topic. +For information about initializing your custom widget in a `.phtml` template, see the [JavaScript initialization]({{ page.baseurl }}/javascript-dev-guide/javascript/js_init.html) topic. ### Extend a default Ui component {#extend_js_component} @@ -143,7 +135,7 @@ define([ }); ``` -For information about how to initialize your custom JS component in a `.phtml` template, see the [JavaScript initialization] topic. +For information about initializing your custom JS component in a `.phtml` template, see the [JavaScript initialization] topic. ## Disable default Magento JS {#disable_default_js} From af9b43dec040beb5f6fd68c812d9c517a7978e4d Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Mon, 4 Nov 2019 16:47:03 -0600 Subject: [PATCH 3/4] Update js_practice.md --- guides/v2.3/javascript-dev-guide/javascript/js_practice.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/guides/v2.3/javascript-dev-guide/javascript/js_practice.md b/guides/v2.3/javascript-dev-guide/javascript/js_practice.md index 8824f2a1962..3644f9e6a2b 100644 --- a/guides/v2.3/javascript-dev-guide/javascript/js_practice.md +++ b/guides/v2.3/javascript-dev-guide/javascript/js_practice.md @@ -1,11 +1,8 @@ --- group: javascript-developer-guide -subgroup: 1_Javascript title: Customizing JavaScript illustration --- -## Overview {#practice_overview} - This topic features a step-by-step illustration of how to customize a [jQuery](https://glossary.magento.com/jquery) [widget](https://glossary.magento.com/widget) and how to use a custom widget instead the default Magento one. ## Customize a default Magento jQuery widget @@ -129,7 +126,8 @@ var config = { }; ``` -## Recommended reading +{:.ref-header} +Recommended reading [Use custom JavaScript] From 672a857ec4a1e5e9a32460660f471e6142d98b8c Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Mon, 4 Nov 2019 16:50:18 -0600 Subject: [PATCH 4/4] Update custom_js.md Correcting linting error --- guides/v2.3/javascript-dev-guide/javascript/custom_js.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/v2.3/javascript-dev-guide/javascript/custom_js.md b/guides/v2.3/javascript-dev-guide/javascript/custom_js.md index 6ffde055f33..b750f304e1f 100644 --- a/guides/v2.3/javascript-dev-guide/javascript/custom_js.md +++ b/guides/v2.3/javascript-dev-guide/javascript/custom_js.md @@ -91,7 +91,7 @@ Where the following notation is used: - `.` - the name of your custom [widget](https://glossary.magento.com/widget). According to the jQuery widgets naming convention, this value must contain a [namespace](https://glossary.magento.com/namespace) and name. - `mage.` - the name of the Magento widget that you extend. - + {:.bs-callout .bs-callout-tip} All jQuery UI components for frontend and base areas are located in `lib/web/jquery/ui-modules` dir. They can be used in JS widgets by `jquery-ui-modules` path mapping like `jquery-ui-modules/widget` and `jquery-ui-modules/slider`. Using individual jQuery UI components instead of the monolithic jQuery UI library improves storefront performance.