{"_id":"584b3fccb1578425007a4c49","user":"55a6caa022cfa321008e01d6","project":"55a6e72e8cc73e0d00096635","version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":0,"category":{"_id":"584b3de7e5f3a42300df6ef7","project":"55a6e72e8cc73e0d00096635","__v":0,"version":"55a6e72f8cc73e0d00096638","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-12-09T23:27:35.491Z","from_sync":false,"order":16,"slug":"javascript-api","title":"JavaScript Customization"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-12-09T23:35:40.162Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"This example show how to add a third-party JavaScript legacy library – one _not_ distributed via npm – into a theme, by using the hooks in `<theme-name>/assets/js/app.js`. This entry includes: \n\n* [What We're Building](#what)\n* [Install the Dependencies](#install)\n* [Configure the webpack Loaders in webpack.conf.js](#loaders)\n* [Import the Dependencies](#import)\n* [Configure the loaded() Method](#configure)\n* [Update the blog.html Template](#blog)\n* [Update the post.html Template](#post)\n* [Adjust the Styling in _socialLinks.scss](#css)\n* [Generalizing This Example](#shims)\n## <span id=\"what\"> What We're Building </span>\n\nWe'll use <a href=\"https://jqueryui.com/download/all/#1-5a\">jQuery UI 1.5a</a> to implement an accordion that wraps each blog on the Blogs page:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1393cdd-final1.png\",\n        \"final1.png\",\n        1160,\n        517,\n        \"#84e072\"\n      ],\n      \"caption\": \"Screenshot of final product, with top post open\",\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f8499df-final2.png\",\n        \"final2.png\",\n        1167,\n        423,\n        \"#98e991\"\n      ],\n      \"caption\": \"Screenshot of final product, with bottom post open\",\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nThis is a contrived example, to demonstrate how to pull in and use a legacy library. Please imagine that this legacy accordion plug-in is required for some particular use case.\n\n## <span id=\"install\"> Install the Dependencies </span>\n\nThis example requires jQueryUI 1.5a, which you can download <a href=\"https://jqueryui.com/resources/download/jquery-ui-1.5a.zip\" target =\"_blank\">here</a>. We'll unzip it to `<theme-name>/assets/vendor`, but feel free to use a different target location.\n\nWe must also install a few webpack loaders, as follows:\n\n`npm install --save-dev css-loader script-loader style-loader url-loader`\n\n## <span id=\"loaders\"> Configure the webpack Loaders in webpack.conf.js </span>\n\nThe <a href=\"https://github.com/webpack/script-loader>\">script</a> loader is used to load the legacy scripts in the global context.  \n\nThe <a href=\"https://github.com/webpack/css-loader\">css</a> and <a href=\"https://github.com/webpack/style-loader\">style</a> loaders are used to import the legacy CSS and to inject it into the DOM, respectively.  \n\nThe <a href=\"https://github.com/webpack/url-loader\">url</a> loader is used to import the .PNG's in the legacy CSS files:\n\n```javascript\n{\n    test: /\\.js$/,\n    loader: 'script',\n    include: /assets\\/vendor/\n},\n{\n    test: /\\.css$/,\n    loader: 'style-loader!css-loader',\n    include: /assets\\/vendor/,\n},\n{\n    test: /\\.png$/,\n    loader: 'url-loader',\n    include: /assets\\/vendor/,\n}\n```\n\nHere is how the config should look:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/af04839-webpack-non.png\",\n        \"webpack-non.png\",\n        2216,\n        1336,\n        \"#1c1c1c\"\n      ],\n      \"sizing\": \"full\",\n      \"caption\": \"Screenshot of webpack config\"\n    }\n  ]\n}\n[/block]\n## <span id=\"import\"> Import the Dependencies </span>\n\nImport these new dependencies in `<theme-name>/assets/js/theme/blog.js`.\n\nNotice that, in `<theme-name>/assets/js/app.js`, there is a mapping between the `blog` and `blog-post` and the `blog.js` script:\n\n```javascript\nconst PageClasses = {\n    mapping: {\n        ...\n        'pages/blog': blog,\n        'pages/blog-post': blog,\n```\n\nThat is, when navigating to the blog or blog-post page the `blog.js` script is run.  First it's constructor will be run, followed by the methods `before`, `loaded` and `after`, in that order. \n\n## <span id=\"configure\"> Configure the loaded() Method </span>\n\nWe'll use the `loaded` method to initialize our accordion widget:\n\n```javascript\nimport PageManager from '../page-manager';\nimport $ from 'jquery';\nimport '../../vendor/jquery.ui-1.5a/themes/flora/flora.accordion.css';\nimport '../../vendor/jquery.ui-1.5a/jquery.js';\nimport '../../vendor/jquery.ui-1.5a/jquery.dimensions.js';\nimport '../../vendor/jquery.ui-1.5a/ui.accordion.js';\nlet jQueryLegacy = window.$;\nwindow.$ = $;\n\nexport default class Blog extends PageManager {\n    loaded(next) {\n        jQueryLegacy('#blogAccordion').accordion(\n            {\n                header: \".ui-accordion-link\"\n            }\n        );\n        next();\n    }\n}\n```\n\nNote that `jquery.ui-1.5a/jquery.js` will set `window.$`. So, after the jQuery UI imports, we copy a reference from `window.$` to `jQueryLegacy`, and then reset `window.$` to `$` (which is imported above). An alternative would be to use the <a href=\"https://github.com/webpack/imports-loader\">imports</a> and <a href=\"https://github.com/webpack/exports-loader\">exports</a> loaders to wire up the dependencies that jQuery UI requires.\n\n## <span id=\"blog\"> Update the blog.html Template </span>\n\nUpdate the `<theme-name>/templates/pages/blog.html` Template with the Accordion HTML:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/febf035-blog.png\",\n        \"blog.png\",\n        1266,\n        1222,\n        \"#1c1c1c\"\n      ],\n      \"sizing\": \"80\",\n      \"caption\": \"Screenshot of blog.html\"\n    }\n  ]\n}\n[/block]\n## <span id=\"post\"> Update the post.html Template </span>\n\nUpdate the `<theme-name>/templates/components/blog/post.html` template to remove the title (as it's now included in `blog.html`):\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4fc6ac7-post.png\",\n        \"post.png\",\n        983,\n        308,\n        \"#f3edef\"\n      ],\n      \"caption\": \"Screenshot of post.html\"\n    }\n  ]\n}\n[/block]\n## <span id=\"css\"> Adjust the Styling in _socialLinks.scss </span>\n\nFinally, to fix some of the styling, we need to add a bit of CSS to \n`<theme-name>/assets/scss/components/stencil/socialLinks/_socialLinks.scss`:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/29ac7f0-css.png\",\n        \"css.png\",\n        983,\n        250,\n        \"#eff3f4\"\n      ],\n      \"caption\": \"Screenshot of _socialLinks.scss\"\n    }\n  ]\n}\n[/block]\n## <span id=\"shims\"> Generalizing This Example </span>\n\nYou would follow a similar setup to work with any legacy JavaScript library. You can read more about shimming legacy code <a href=\"https://webpack.github.io/docs/shimming-modules.html\">here</a>.","excerpt":"Third-party JavaScript","slug":"js-non-npm","type":"basic","title":"Advanced Non-npm Example"}

Advanced Non-npm Example

Third-party JavaScript

This example show how to add a third-party JavaScript legacy library – one _not_ distributed via npm – into a theme, by using the hooks in `<theme-name>/assets/js/app.js`. This entry includes: * [What We're Building](#what) * [Install the Dependencies](#install) * [Configure the webpack Loaders in webpack.conf.js](#loaders) * [Import the Dependencies](#import) * [Configure the loaded() Method](#configure) * [Update the blog.html Template](#blog) * [Update the post.html Template](#post) * [Adjust the Styling in _socialLinks.scss](#css) * [Generalizing This Example](#shims) ## <span id="what"> What We're Building </span> We'll use <a href="https://jqueryui.com/download/all/#1-5a">jQuery UI 1.5a</a> to implement an accordion that wraps each blog on the Blogs page: [block:image] { "images": [ { "image": [ "https://files.readme.io/1393cdd-final1.png", "final1.png", 1160, 517, "#84e072" ], "caption": "Screenshot of final product, with top post open", "sizing": "80" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/f8499df-final2.png", "final2.png", 1167, 423, "#98e991" ], "caption": "Screenshot of final product, with bottom post open", "sizing": "80" } ] } [/block] This is a contrived example, to demonstrate how to pull in and use a legacy library. Please imagine that this legacy accordion plug-in is required for some particular use case. ## <span id="install"> Install the Dependencies </span> This example requires jQueryUI 1.5a, which you can download <a href="https://jqueryui.com/resources/download/jquery-ui-1.5a.zip" target ="_blank">here</a>. We'll unzip it to `<theme-name>/assets/vendor`, but feel free to use a different target location. We must also install a few webpack loaders, as follows: `npm install --save-dev css-loader script-loader style-loader url-loader` ## <span id="loaders"> Configure the webpack Loaders in webpack.conf.js </span> The <a href="https://github.com/webpack/script-loader>">script</a> loader is used to load the legacy scripts in the global context. The <a href="https://github.com/webpack/css-loader">css</a> and <a href="https://github.com/webpack/style-loader">style</a> loaders are used to import the legacy CSS and to inject it into the DOM, respectively. The <a href="https://github.com/webpack/url-loader">url</a> loader is used to import the .PNG's in the legacy CSS files: ```javascript { test: /\.js$/, loader: 'script', include: /assets\/vendor/ }, { test: /\.css$/, loader: 'style-loader!css-loader', include: /assets\/vendor/, }, { test: /\.png$/, loader: 'url-loader', include: /assets\/vendor/, } ``` Here is how the config should look: [block:image] { "images": [ { "image": [ "https://files.readme.io/af04839-webpack-non.png", "webpack-non.png", 2216, 1336, "#1c1c1c" ], "sizing": "full", "caption": "Screenshot of webpack config" } ] } [/block] ## <span id="import"> Import the Dependencies </span> Import these new dependencies in `<theme-name>/assets/js/theme/blog.js`. Notice that, in `<theme-name>/assets/js/app.js`, there is a mapping between the `blog` and `blog-post` and the `blog.js` script: ```javascript const PageClasses = { mapping: { ... 'pages/blog': blog, 'pages/blog-post': blog, ``` That is, when navigating to the blog or blog-post page the `blog.js` script is run. First it's constructor will be run, followed by the methods `before`, `loaded` and `after`, in that order. ## <span id="configure"> Configure the loaded() Method </span> We'll use the `loaded` method to initialize our accordion widget: ```javascript import PageManager from '../page-manager'; import $ from 'jquery'; import '../../vendor/jquery.ui-1.5a/themes/flora/flora.accordion.css'; import '../../vendor/jquery.ui-1.5a/jquery.js'; import '../../vendor/jquery.ui-1.5a/jquery.dimensions.js'; import '../../vendor/jquery.ui-1.5a/ui.accordion.js'; let jQueryLegacy = window.$; window.$ = $; export default class Blog extends PageManager { loaded(next) { jQueryLegacy('#blogAccordion').accordion( { header: ".ui-accordion-link" } ); next(); } } ``` Note that `jquery.ui-1.5a/jquery.js` will set `window.$`. So, after the jQuery UI imports, we copy a reference from `window.$` to `jQueryLegacy`, and then reset `window.$` to `$` (which is imported above). An alternative would be to use the <a href="https://github.com/webpack/imports-loader">imports</a> and <a href="https://github.com/webpack/exports-loader">exports</a> loaders to wire up the dependencies that jQuery UI requires. ## <span id="blog"> Update the blog.html Template </span> Update the `<theme-name>/templates/pages/blog.html` Template with the Accordion HTML: [block:image] { "images": [ { "image": [ "https://files.readme.io/febf035-blog.png", "blog.png", 1266, 1222, "#1c1c1c" ], "sizing": "80", "caption": "Screenshot of blog.html" } ] } [/block] ## <span id="post"> Update the post.html Template </span> Update the `<theme-name>/templates/components/blog/post.html` template to remove the title (as it's now included in `blog.html`): [block:image] { "images": [ { "image": [ "https://files.readme.io/4fc6ac7-post.png", "post.png", 983, 308, "#f3edef" ], "caption": "Screenshot of post.html" } ] } [/block] ## <span id="css"> Adjust the Styling in _socialLinks.scss </span> Finally, to fix some of the styling, we need to add a bit of CSS to `<theme-name>/assets/scss/components/stencil/socialLinks/_socialLinks.scss`: [block:image] { "images": [ { "image": [ "https://files.readme.io/29ac7f0-css.png", "css.png", 983, 250, "#eff3f4" ], "caption": "Screenshot of _socialLinks.scss" } ] } [/block] ## <span id="shims"> Generalizing This Example </span> You would follow a similar setup to work with any legacy JavaScript library. You can read more about shimming legacy code <a href="https://webpack.github.io/docs/shimming-modules.html">here</a>.