UNPKG

6.8 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 // Optional: Indicates if we should inject scripts directly into index.html, or if we should
49 // write them to separate js files that are loaded by index.html. When strict fingerprinting
50 // is required, this should be set to true, since there are scenarios where the generated
51 // amd-loading.js script will not get a unique fingerprint.
52 // default: false
53 inline: false,
54 }
55});
56```
57
58## Example using the CDN resources
59
60Your ember-cli-build.js:
61
62```javascript
63module.exports = function(defaults) {
64
65 var app = new EmberApp(defaults, {
66 amd :{
67 loader: 'https://js.arcgis.com/4.16/',
68 packages: ['esri','dojo'],
69 excludePaths: ['assets/workers']
70 }
71 });
72
73 return app.toTree();
74};
75```
76
77Your component:
78
79```javascript
80import Component from '@glimmer/component';
81import Map from 'esri/Map';
82
83class MapComponent extends Component {
84 // Do something with Map: const map = new Map({});
85}
86```
87
88Your original index.html:
89
90```html
91<!DOCTYPE html>
92<html>
93
94<head>
95 <meta charset="utf-8">
96 <meta http-equiv="X-UA-Compatible" content="IE=edge">
97 <title>My App</title>
98 <meta name="description" content="">
99 <meta name="viewport" content="width=device-width, initial-scale=1">
100
101 {{content-for "head"}}
102 <link rel="stylesheet" href="assets/vendor.css">
103 <link rel="stylesheet" href="assets/myapp.css">
104 {{content-for "head-footer"}}
105
106</head>
107
108<body>
109
110 {{content-for "body"}}
111 <script src="assets/vendor.js"></script>
112 <script src="assets/myapp.js"></script>
113 {{content-for "body-footer"}}
114</body>
115
116</html>
117```
118
119The results will be:
120- a transformed index.html in your dist directory
121- an additional script file will be created under the dist directory under assets/amd-loading.js
122
123dist/index.html:
124
125```html
126<!DOCTYPE html>
127<html>
128
129<head>
130 <meta charset="utf-8">
131 <meta http-equiv="X-UA-Compatible" content="IE=edge">
132 <title>My App</title>
133 <meta name="description" content>
134 <meta name="viewport" content="width=device-width, initial-scale=1">
135 <link rel="stylesheet" href="assets/vendor.css">
136 <link rel="stylesheet" href="assets/myapp.css">
137</head>
138
139<body>
140 <script src="https://jsdev.arcgis.com/4.15/init.js" data-amd="true"></script>
141 <script src="assets/amd-loading.js" data-amd-loading="true"></script>
142</body>
143
144</html>
145```
146
147dist/assets/amd-loading.js
148
149```javascript
150require([
151 'esri/Map'
152], function(mod0) {
153 var adoptables = [{
154 name: 'esri/Map',
155 obj: mod0
156 }];
157 var isVendor = new RegExp('vendor(.*js)');
158
159 function recursiveRequire(i, scripts) {
160 if (i >= scripts.length) {
161 return;
162 }
163 require([scripts[i]], function() {
164 if (isVendor.test(scripts[i])) {
165 adoptables.forEach(function(adoptable) {
166 enifed(adoptable.name, [], function() {
167 return adoptable.obj;
168 });
169 });
170 }
171 recursiveRequire(++i, scripts);
172 });
173 }
174 recursiveRequire(0, ["assets/vendor.js", "assets/nickel.js"]);
175});
176```
177
178## Breaking changes
179The version 3.x introduce the following breaking changes:
180- No more configPath. Use other addons to load the scripts you need in your header
181- 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
182- The loading script will be fingerprinted if you have turned on this feature in your build
183
184## Dependencies
185* Ember.js v3.12 or above
186* Ember CLI v2.13 or above
187* Node.js v10 or above
188
189## Resources
190* For more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/).
191* To learn more about the ArcGIS API for JavaScript, visit [the developers pages](https://developers.arcgis.com/javascript/).
192* To understand AST https://astexplorer.net/
193
194## Issues
195
196Find a bug or want to request a new feature? Please let us know by submitting an issue.
197
198## Contributing
199
200Esri welcomes contributions from anyone and everyone. Please see our [guidelines for contributing](https://github.com/esri/contributing).
201
202## Licensing
203Copyright 2018 Esri
204
205Licensed 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
206
207http://www.apache.org/licenses/LICENSE-2.0
208
209Unless 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.
210
211A copy of the license is available in the repository's [LICENSE](./LICENSE.md) file