Skip to content

Commit 8f379f1

Browse files
izaeraizaera
committed
Update README
Fixes #185
1 parent 0f8ccd9 commit 8f379f1

File tree

1 file changed

+17
-290
lines changed

1 file changed

+17
-290
lines changed

‎README.md‎

Lines changed: 17 additions & 290 deletions
Original file line numberDiff line numberDiff line change
@@ -2,303 +2,30 @@
22

33
[![Build Status](https://travis-ci.org/liferay/liferay-amd-loader.svg)](https://travis-ci.org/liferay/liferay-amd-loader)
44

5-
Supports loading modules via combo URL. Modules can be loaded automatically when some other module is being triggered, but only if some condition is met.
5+
This repository holds the AMD Loader packed with Liferay DXP.
66

7-
**_Note:_** Loading anonymous modules via combo URL is not possible. If some of the modules is anonymous and `combine` is set to `true`, the module should be registered and `anonymous` property to be set as `true`. In this way this module will be excluded from the combo URL and a separate `script` element will be created for it. If `combine` is set to `false`, describing the module is not needed.
7+
Note that, though it may be used outside of Liferay, it's very unprobable that
8+
it can be useful without the extensive support it gets from the server (for
9+
module resolution and load).
810

9-
## How to build it?
11+
## Setup
1012

11-
1. Clone or fork the repository on your machine.
12-
2. Install NodeJS.
13-
3. Run `npm install` in the cloned/forked repository.
14-
4. Run `npm run build` to build it.
13+
1. Clone this repository
14+
2. Install NodeJS >= [v6.11.0](http://nodejs.org/dist/v6.11.0/), if you don't have it yet
15+
3. Run `npm install` to install dependencies
16+
4. Run `npm run build` to build it
17+
5. Run `npm test` to run tests
1518

1619
This will build the loader in 'build/loader' directory. There will be three versions:
1720

18-
* loader.js - release version (no traces)
19-
* loader-min.js - same as loader.js but minified
20-
* loader-debug.js - debug version with console traces (quite verbose)
21-
22-
Both versions have minified versions too.
21+
- loader.js: release version
22+
- loader-min.js: minified release version
23+
- loader-debug.js: debug version
2324

2425
## How to run the demo?
2526

26-
1. The default configuration and the demo require a combo loader that is automatically started and listens to port 3000.
27-
2. Run demo script:
28-
`npm run demo`.
29-
3. Open a browser, for example Chrome and load `http://localhost:8080/`. Open the console and look for the messages. You will see that resouces are being loaded.
30-
31-
# Loader features
32-
33-
1. Supports combo loading of the resources.
34-
2. Supports conditional loading.
35-
3. The configuration can be auto generated.
36-
37-
# Registering modules
38-
39-
Use `define` function:
40-
41-
```javascript
42-
define('aui-dialog', ['aui-node', 'aui-plugin-base'], function(
43-
node,
44-
pluginBase
45-
) {
46-
return {
47-
log: function(text) {
48-
console.log('module aui-dialog: ' + text);
49-
},
50-
};
51-
});
52-
```
53-
54-
You may specify that the module should be loaded on triggering some other module and only of some condition is being met:
55-
56-
```javascript
57-
define(
58-
'aui-dialog',
59-
['aui-node', 'aui-plugin-base'],
60-
function(node, pluginBase) {
61-
return {
62-
log: function(text) {
63-
console.log('module aui-dialog: ' + text);
64-
},
65-
};
66-
},
67-
{
68-
condition: {
69-
trigger: 'aui-test',
70-
test: function() {
71-
var el = document.createElement('input');
72-
73-
return 'placeholder' in el;
74-
},
75-
},
76-
path: 'aui-dialog.js',
77-
}
78-
);
79-
```
80-
81-
Here it is specified, that this module should be loaded automatically if developer requests 'aui-test' module, but only if some condition is being met.
82-
83-
# Using ES6 syntax in your modules
84-
85-
```javascript
86-
'use strict';
87-
88-
import { log as logBase } from 'aui-base';
89-
import { log as logCore } from 'aui-core';
90-
import { log as logEvent } from 'aui-event';
91-
92-
function log(text) {
93-
logEvent('module aui-dialog says via aui-event: ' + text);
94-
logBase('in module aui-dialog logBase is available: ' + text);
95-
logCore('in module aui-dialog logCore is available: ' + text);
96-
}
97-
98-
export { log };
99-
100-
/**
101-
* The code below is meta configuration, in this case it includes module condition only.
102-
* You may delete the whole function statement if you don't need it.
103-
*/
104-
(function META() {
105-
return {
106-
condition: {
107-
test: function() {
108-
return true;
109-
},
110-
trigger: 'nate',
111-
},
112-
path: 'nate.js',
113-
};
114-
});
115-
116-
/**
117-
* There is another way to define META. Liferay Config Generator recognizes both.
118-
* It is up to you to choose one.
119-
*/
120-
META: ({
121-
condition: {
122-
test: function() {
123-
return true;
124-
},
125-
trigger: 'nate',
126-
},
127-
path: 'nate.js',
128-
});
129-
```
130-
131-
Transpile the above using [Babel](https://babeljs.io/) to AMD syntax. If you transpile using Babel, be sure you added the option for generating module IDs, or you use [Liferay AMD modules config generator](https://www.npmjs.com/package/liferay-module-config-generator), which will generate the module name in "define" function, if not already available.
132-
133-
# Loading modules
134-
135-
Use `require` method:
136-
137-
```javascript
138-
require('aui-base', 'aui-test', function(base, test) {
139-
// your code here
140-
}, function(error) {
141-
console.error(error);
142-
});
143-
```
144-
145-
# Mapping paths
146-
147-
You can map parts of module's path with another value and the path will be replaced accordingly. Example:
148-
149-
```
150-
__CONFIG__.paths = {
151-
'jquery': 'http://code.jquery.com/jquery-2.1.3.min.js',
152-
'aui': 'html/js'
153-
};
154-
```
155-
156-
In this case a module, specified as "jquery" will be loaded from "http://code.jquery.com/jquery-2.1.3.min.js" and a module, specified as "aui/loader.js" will be loaded from:<br>
157-
URL + basePath + "html/js/loader.js" where URL and basePath will be retrieved from config.js. Here is an exaple:<br>
158-
If the URL is "http://localhost:3000/modules" and basePath is "/base", the final path will look like this:
159-
"http://localhost:3000/modules/base/html/js/loader.js"
160-
161-
The Loader also supports an `*` as key in the `paths` configuration. The value should be a function, which will receive the module as an argument and the returned value will be used as a path for this module. The `*` has lower precedence than a specific key for a given module. Example:
162-
163-
```javascript
164-
__CONFIG__ = {
165-
paths: {
166-
'*': function(module) {
167-
return 'https://rawgit.com/bkardell/gaps/master/' + module + '.js';
168-
},
169-
},
170-
};
171-
```
172-
173-
# Mapping module names
174-
175-
You can map module names. Example:
176-
177-
```
178-
__CONFIG__.maps = {
179-
'liferay': 'liferay@1.0.0',
180-
'liferay2': 'liferay@1.0.0'
181-
};
182-
```
183-
184-
Mapping a module will change its name in order to match the value, specified in the map. Examples:
185-
186-
```
187-
require('liferay/html/js/autocomplete'...)
188-
```
189-
190-
Under the hood, it will be the same as if the user specified:
191-
192-
```
193-
require('liferay@1.0.0y/html/js/autocomplete'...)
194-
```
195-
196-
Module mapping works in module dependencies too:
197-
198-
```
199-
define('liferay@2.0.0', ['exports', 'liferay/test.js'], function (__exports__, liferay) {
200-
'use strict';
201-
202-
function log(text) {
203-
console.log('liferay@2.0.0 says', text);
204-
}
205-
206-
__exports__.log = log;
207-
});
208-
```
209-
210-
The module 'liferay/test.js' in the dependencies will be transparently changed to:
211-
212-
```
213-
'liferay@1.0.0/test.js'
214-
```
215-
216-
The Loader also supports an `*` as key in the `maps` configuration. The value should be a function, which will receive the module as an argument and the returned value will be used as the new module name. The `*` has lower precedence than a specific key for a given module. Example:
217-
218-
```javascript
219-
__CONFIG__ = {
220-
maps: {
221-
'*': function(module) {
222-
if (module.indexOf('@') === -1) {
223-
module += '@1.0';
224-
}
225-
226-
return module;
227-
},
228-
},
229-
};
230-
```
231-
232-
# Passing default URL parameters
233-
234-
Arbitrary URL parameters might be added to each module request. The parameter will be added to all kind of requests - for modules with external or absolute path, anonymous and in case of combined modules.
235-
To achieve that, you may specify the parameters in `defaultURLParams` configuration property:
236-
237-
```javascript
238-
{
239-
'url': 'http://localhost:3000/modules?',
240-
'defaultURLParams': {
241-
'languageId': 'en_US'
242-
}
243-
}
244-
```
245-
246-
In this case, `languageId` with value 'en_US' will be added to each module request and the result might look like this:
247-
`http://localhost:3000/modules?/base/foo.js&/base/bar.js&languageId=en_US`
248-
249-
# Loading modules via combo URL
250-
251-
In order to load the modules via combo URL, a special config file have to be created first. You can do that manually or using a special tool, which comes together with the loader. It is called `config-generator`. See the next section for more details:
252-
253-
# Automatically generating the configuration
254-
255-
In order to generate the configuration, there is a separate project, called [Liferay AMD modules config generator](https://www.npmjs.com/package/liferay-module-config-generator). You may use it to generate the configuration file automatically.
256-
257-
Here is an example usage:
258-
259-
```bash
260-
$ lfr-cfgen -b src/config/config-base.js -o src/config/config.js src/modules
261-
```
262-
263-
A preferable way to work with the loader would be to generate a separate, base config file and pass it to the config generator as in the code above. In the base file you may define the URLs, combine flags, etc. and then leave config generator to add the modules.
264-
Look on the example modules and the demo for more information. Then, just load the generated configuration to the browser and the Loader will do the rest.
265-
266-
# Reporting errors caused mismatched anonymous modules
267-
268-
By default mismatched anonymous modules will be reported by throwing an exception. This is configurable and there is a property:
269-
270-
```javascript
271-
// By default, `reportMismatchedAnonymousModules` is not set and
272-
// in this case the loader will throw an exception
273-
274-
// Throw an exception
275-
__CONFIG__.reportMismatchedAnonymousModules = 'exception';
276-
277-
// Log the error using console.log
278-
__CONFIG__.reportMismatchedAnonymousModules = 'log';
279-
280-
// Log the error using console.info
281-
__CONFIG__.reportMismatchedAnonymousModules = 'info';
282-
283-
// Log the error using console.warn
284-
__CONFIG__.reportMismatchedAnonymousModules = 'warn';
285-
286-
// Log the error using console.error
287-
__CONFIG__.reportMismatchedAnonymousModules = 'error';
288-
289-
// Ignore the error
290-
__CONFIG__.reportMismatchedAnonymousModules = 'off';
291-
```
292-
293-
# Namespacing the Loader
294-
295-
Setting `namespace` property of the config to a value as a string will expose the Loader to this variable, instead directly to window. For example, if `namespace` is set to "VM", the Loader will be available as `window.VM.Loader`.
296-
297-
# Exposing Loader globally
298-
299-
Setting `exposeGlobal` property of the config will expose the Loader to the window, among with the `define` and `require` functions. By default the value of this property is true. For example, there will be `window.Loader`, `window.require` and `window.define` methods in case `exposeGlobal` is unset or set to true. Otherwise, these will be undefined.
300-
301-
# Ignoring module versions
27+
The default configuration and the demo require a combo loader that is automatically started and listens to port 3000.
30228

303-
Setting `ignoreModuleVersion` property of the config will ignore the `@major.minor.path` version qualifier in a module name to allow for a more lenient module name match in scenarios where undisclosed security vulnerabilities can lead to a security leak if versions are exposed to the
304-
loader configuration.
29+
1. Run demo script with `npm run demo`
30+
2. Open a browser and load [http://localhost:8080](http://localhost:8080)
31+
3. Open the browser console and look for the messages

0 commit comments

Comments
 (0)