UNPKG

6.41 kBMarkdownView Raw
1# ember-cli-amd
2
3If your project needs to use an AMD based library, the Ember loader will conflict with the AMD loader.
4
5The issue is that the Ember Loader defines the same globals `require` and `define` but are not AMD compatible.
6
7The solution is to make the Ember Loader not conflicting anymore with the AMD Loader and to load the Ember App as an AMD module.
8
9This addon will:
10* Allow you to import AMD modules from you Ember code. Example: `import Map from 'esri/Map';`
11* Update the code generated by Ember to avoid conflicts with the AMD loader
12* Update the index.html to use the AMD Loader:
13 * load any pure AMD modules found in the code first using the AMD loader.
14 * load the Ember code as AMD modules (app and vendor)
15 * reference the AMD modules inside the Ember loader
16
17[View it live](http://esri.github.io/ember-cli-amd/) using the [ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/).
18
19## Usage
20
21`ember install ember-cli-amd`
22
23Update your ember-cli-build file. See configuration below as an example:
24
25```javascript
26var app = new EmberApp({
27 amd : {
28 // Specify the loader path. Can be a CDN path or a relative path in the dist folder
29 // - CDN: loader: 'https://js.arcgis.com/4.14/'
30 // - Local: loader: 'assets/jsapi/init.js'
31 loader: 'https://js.arcgis.com/4.16/',
32
33 // AMD packages from which modules are imported from in your application.
34 // Used to parse the import statements and discover the AMD modules from the other modules.
35 packages: ['esri','dojo'],
36
37 // Optional: a list of relative paths from the build directory that should not be parsed by ember-cli-amd.
38 // This is useful for:
39 // - when using an AMD api locally and copied under public folder. The files will be copied under the build folder. These files are pure AMD
40 // modules and should not be converted.
41 // - when copying from public to build directory files that are pure JS or pure AMD
42 excludePaths: ['assets/jsapi', 'assets/myLibThatDontUseEmberDefineOrRequire'],
43
44 // Optional: the path to javascript file that will be created for loading the AMD modules
45 // default: assets
46 loadingFilePath: 'assets'
47 }
48});
49```
50
51## Example using the CDN resources
52
53Your ember-cli-build.js:
54
55```javascript
56module.exports = function(defaults) {
57
58 var app = new EmberApp(defaults, {
59 amd :{
60 loader: 'https://js.arcgis.com/4.16/',
61 packages: ['esri','dojo'],
62 excludePaths: ['assets/workers']
63 }
64 });
65
66 return app.toTree();
67};
68```
69
70Your component:
71
72```javascript
73import Component from '@glimmer/component';
74import Map from 'esri/Map';
75
76class MapComponent extends Component {
77 // Do something with Map: const map = new Map({});
78}
79```
80
81Your original index.html:
82
83```html
84<!DOCTYPE html>
85<html>
86
87<head>
88 <meta charset="utf-8">
89 <meta http-equiv="X-UA-Compatible" content="IE=edge">
90 <title>My App</title>
91 <meta name="description" content="">
92 <meta name="viewport" content="width=device-width, initial-scale=1">
93
94 {{content-for "head"}}
95 <link rel="stylesheet" href="assets/vendor.css">
96 <link rel="stylesheet" href="assets/myapp.css">
97 {{content-for "head-footer"}}
98
99</head>
100
101<body>
102
103 {{content-for "body"}}
104 <script src="assets/vendor.js"></script>
105 <script src="assets/myapp.js"></script>
106 {{content-for "body-footer"}}
107</body>
108
109</html>
110```
111
112The results will be:
113- a transformed index.html in your dist directory
114- an additional script file will be created under the dist directory under assets/amd-loading.js
115
116dist/index.html:
117
118```html
119<!DOCTYPE html>
120<html>
121
122<head>
123 <meta charset="utf-8">
124 <meta http-equiv="X-UA-Compatible" content="IE=edge">
125 <title>My App</title>
126 <meta name="description" content>
127 <meta name="viewport" content="width=device-width, initial-scale=1">
128 <link rel="stylesheet" href="assets/vendor.css">
129 <link rel="stylesheet" href="assets/myapp.css">
130</head>
131
132<body>
133 <script src="https://jsdev.arcgis.com/4.15/init.js" data-amd="true"></script>
134 <script src="assets/amd-loading.js" data-amd-loading="true"></script>
135</body>
136
137</html>
138```
139
140dist/assets/amd-loading.js
141
142```javascript
143require([
144 'esri/Map'
145], function(mod0) {
146 var adoptables = [{
147 name: 'esri/Map',
148 obj: mod0
149 }];
150 var isVendor = new RegExp('vendor(.*js)');
151
152 function recursiveRequire(i, scripts) {
153 if (i >= scripts.length) {
154 return;
155 }
156 require([scripts[i]], function() {
157 if (isVendor.test(scripts[i])) {
158 adoptables.forEach(function(adoptable) {
159 enifed(adoptable.name, [], function() {
160 return adoptable.obj;
161 });
162 });
163 }
164 recursiveRequire(++i, scripts);
165 });
166 }
167 recursiveRequire(0, ["assets/vendor.js", "assets/nickel.js"]);
168});
169```
170
171## Breaking changes
172The version 3.x introduce the following breaking changes:
173- No more configPath. Use other addons to load the scripts you need in your header
174- The AMD module loading will be done in a separate javascript file. This is to keep the index.html as small as possible and optimized for caching
175- The loading script will be fingerprinted if you have turned on this feature in your build
176
177## Dependencies
178* Ember.js v3.12 or above
179* Ember CLI v2.13 or above
180* Node.js v10 or above
181
182## Resources
183* For more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/).
184* To learn more about the ArcGIS API for JavaScript, visit [the developers pages](https://developers.arcgis.com/javascript/).
185* To understand AST https://astexplorer.net/
186
187## Issues
188
189Find a bug or want to request a new feature? Please let us know by submitting an issue.
190
191## Contributing
192
193Esri welcomes contributions from anyone and everyone. Please see our [guidelines for contributing](https://github.com/esri/contributing).
194
195## Licensing
196Copyright 2018 Esri
197
198Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
199
200http://www.apache.org/licenses/LICENSE-2.0
201
202Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
203
204A copy of the license is available in the repository's [LICENSE](./LICENSE.md) file