1 | # Ember CLI HTMLBars
|
2 |
|
3 | <a href="https://github.com/ember-cli/ember-cli-htmlbars/actions"><img alt="Build Status" src="https://github.com/ember-cli/ember-cli-htmlbars/workflows/ci/badge.svg"></a>
|
4 |
|
5 | ### Registering a Plugin
|
6 |
|
7 | ```javascript
|
8 | var SomeTransform = require('./some-path/transform');
|
9 |
|
10 | module.exports = {
|
11 | name: 'my-addon-name',
|
12 |
|
13 | included: function() {
|
14 | // we have to wrap these in an object so the ember-cli
|
15 | // registry doesn't try to call `new` on them (new is actually
|
16 | // called within htmlbars when compiling a given template).
|
17 | this.app.registry.add('htmlbars-ast-plugin', {
|
18 | name: 'some-transform',
|
19 | plugin: SomeTransform
|
20 | });
|
21 | }
|
22 | };
|
23 | ```
|
24 |
|
25 | #### Options for registering a `htmlbars-ast-plugin`
|
26 |
|
27 | * `name` - String. The name of the AST transform for debugging purposes.
|
28 | * `plugin` - A function of type [`ASTPluginBuilder`](https://github.com/glimmerjs/glimmer-vm/blob/master/packages/%40glimmer/syntax/lib/parser/tokenizer-event-handlers.ts#L329-L341).
|
29 | * `dependencyInvalidation` - Boolean. A flag that indicates the AST Plugin may, on a per-template basis, depend on other files that affect its output.
|
30 | * `cacheKey` - function that returns any JSON-compatible value - The value returned is used to invalidate the persistent cache across restarts, usually in the case of a dependency or configuration change.
|
31 | * `baseDir` - `() => string`. A function that returns the directory on disk of the npm module for the plugin. If provided, a basic cache invalidation is performed if any of the dependencies change (e.g. due to a npm install/upgrade).
|
32 |
|
33 | #### Implementing Dependency Invalidation in an AST Plugin
|
34 |
|
35 | Plugins that set the `dependencyInvalidation` option to `true` can provide function for the `plugin` of type `ASTDependencyPlugin` as given below.
|
36 |
|
37 | Note: the `plugin` function is invoked without a value for `this` in context.
|
38 |
|
39 | ```ts
|
40 | import {ASTPluginBuilder, ASTPlugin} from "@glimmer/syntax/dist/types/lib/parser/tokenizer-event-handlers";
|
41 |
|
42 | export type ASTDependencyPlugin = ASTPluginWithDepsBuilder | ASTPluginBuilderWithDeps;
|
43 |
|
44 | export interface ASTPluginWithDepsBuilder {
|
45 | (env: ASTPluginEnvironment): ASTPluginWithDeps;
|
46 | }
|
47 |
|
48 | export interface ASTPluginBuilderWithDeps extends ASTPluginBuilder {
|
49 | /**
|
50 | * @see {ASTPluginWithDeps.dependencies} below.
|
51 | **/
|
52 | dependencies(relativePath): string[];
|
53 | }
|
54 |
|
55 | export interface ASTPluginWithDeps extends ASTPlugin {
|
56 | /**
|
57 | * If this method exists, it is called with the relative path to the current
|
58 | * file just before processing starts. Use this method to reset the
|
59 | * dependency tracking state associated with the file.
|
60 | */
|
61 | resetDependencies?(relativePath: string): void;
|
62 | /**
|
63 | * This method is called just as the template finishes being processed.
|
64 | *
|
65 | * @param relativePath {string} A relative path to the file that may have dependencies.
|
66 | * @return {string[]} paths to files that are a dependency for the given
|
67 | * file. Any relative paths returned by this method are taken to be relative
|
68 | * to the file that was processed.
|
69 | */
|
70 | dependencies(relativePath: string): string[];
|
71 | }
|
72 | ```
|
73 |
|
74 | ### Precompile HTMLBars template strings within other addons
|
75 |
|
76 | ```javascript
|
77 | module.exports = {
|
78 | name: 'my-addon-name',
|
79 |
|
80 | setupPreprocessorRegistry: function(type, registry) {
|
81 | var htmlbarsPlugin = registry.load('template').find(function(plugin) {
|
82 | return plugin.name === 'ember-cli-htmlbars';
|
83 | });
|
84 |
|
85 | // precompile any htmlbars template string via the precompile method on the
|
86 | // ember-cli-htmlbars plugin wrapper; `precompiled` will be a string of the
|
87 | // form:
|
88 | //
|
89 | // Ember.HTMLBars.template(function() {...})
|
90 | //
|
91 | var precompiled = htmlbarsPlugin.precompile("{{my-component}}");
|
92 | }
|
93 | };
|
94 | ```
|
95 |
|
96 | ### Tagged Template Usage / Migrating from `htmlbars-inline-precompile`
|
97 |
|
98 | Starting with version 4.0, this addon now includes the testing helper from [ember-cli-htmlbars-inline-precompile](https://github.com/ember-cli/ember-cli-htmlbars-inline-precompile)
|
99 |
|
100 | This will require an update to the imports of the `hbs` helper in your tests:
|
101 |
|
102 | Prior syntax:
|
103 |
|
104 | ```
|
105 | import hbs from 'htmlbars-inline-precompile';
|
106 |
|
107 | ...
|
108 |
|
109 | await render(hbs`
|
110 | <MyComponent />
|
111 | `);
|
112 | ```
|
113 |
|
114 | New syntax:
|
115 |
|
116 | ```
|
117 | import { hbs } from 'ember-cli-htmlbars';
|
118 |
|
119 | ...
|
120 |
|
121 | await render(hbs`
|
122 | <MyComponent />
|
123 | `);
|
124 | ```
|
125 |
|
126 | There is a [codemod](https://github.com/ember-codemods/ember-cli-htmlbars-inline-precompile-codemod) available to automate this change.
|
127 |
|
128 | ### Handlebars 2.0 Support (Ember < 1.10)
|
129 |
|
130 | Handlebars 2.0 support has been removed. If you are using ember-cli-htmlbars with a 1.9.x project please continue
|
131 | to use ember-cli-htmlbars@0.6.x.
|
132 |
|
133 | ### Using as a Broccoli Plugin
|
134 |
|
135 | ```javascript
|
136 | var HtmlbarsCompiler = require('ember-cli-htmlbars');
|
137 |
|
138 | var templateTree = new HtmlbarsCompiler('app/templates', {
|
139 | isHTMLBars: true,
|
140 |
|
141 | // provide the templateCompiler that is paired with your Ember version
|
142 | templateCompiler: require('./bower_components/ember/ember-template-compiler')
|
143 | });
|
144 | ```
|