1 | ## What's all this here
|
2 |
|
3 | ### Dust in parts
|
4 | The Dust project consists of 3 parts:
|
5 |
|
6 | * **dust.js** - the core (runtime) file responsible for providing:
|
7 | * a `dust` namespace
|
8 | * all public end user API methods (such as `dust.render`, `dust.makebase`)
|
9 | * all publically overridable methods (such as `dust.onError`, `dust.log`) and overridable objects (`dust.helper`)
|
10 | * shared utility methods used internally (such as `dust.isArray`)
|
11 | * definitions for all internal objects (such as `Context`, `Stub`, `Stream`, etc.)
|
12 | * ... which include all internal methods called from the templates (such as `context.get`, `chunk.section`, `chunk.partial`, etc.)
|
13 | * **parser.js** - responsible for providing a parse methods which things that look like Dust and turning it into a Dust AST
|
14 | * **compiler.js** - responsible for taking Dust AST and turning it into Javscript functions that can be `dust.render`'ed
|
15 |
|
16 |
|
17 | ### dust-core pre-compiling files and keeping a slim runtime
|
18 | For browser performance, we recommend providing only the **dust-core.js** file to the browser and compiling templates on the server.
|
19 |
|
20 | You can think of **dust-core.js** as the runtime file. Currently, core only include **dust.js** which provides enough to render basic templates in the browser(without helpers; for templates with helpers see the dustjs-helpers repo).
|
21 |
|
22 | ### dust-full when you need to compile
|
23 | When you need to compile templates, that is take files written in Dust syntax and converting them to things that can be `dust.render`'ed, you'll need **dust-full.js**. The **compiler.js** and **parser.js** file are included with **dust.js** in **dust-full.js** in order to provide the compile functionality.
|
24 |
|
25 | You should provide **dust-full.js** to the browser if you are compiling templates on demand or if simply just don't want to pre-compile on the server and perf does not matter.
|
26 |
|
27 | If you are using Node and using `require('dustjs-linkedin')` you are getting dust-full.
|
28 |
|
29 | ### Server vs Browser - the server file
|
30 | Dust is written to run on both the server and the browser. In truth, it is written to work first on the browser and modified to work on the server.
|
31 |
|
32 | A few things are added to make it work on the server:
|
33 |
|
34 | * A UMD style wrapper is added to all the files so that, for example, `dust` is returned to `module.exports` in Node whereas it would have returned as `window.dust` in the browser
|
35 | * Servers that use npm (Node) need a single main entry point. For us, this is **index.js** which sets up `dust-full` by pulling in the necessary lib modules, modifies some methods to work in Node, and exports it as a module.
|
36 | * Browsers don't need to be a single file but to make it easier a build script is setup so that the necessary lib files are combined into **dist/dust-full.js** and **dist/dust-core.js**.
|