mancha 0.3.4 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +117 -21
  2. package/dist/browser.js +1 -2
  3. package/dist/mancha.js +1 -1
  4. package/package.json +2 -2
  5. package/yarn-error.log +3935 -0
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # mancha
2
2
 
3
- `mancha` is an HTML templating library. It can work as a command-line tool, imported as a Javascript
4
- function, or as a `Gulp 4+` plugin.
3
+ `mancha` is an HTML rendering library. It can work as a command-line tool, imported as a Javascript
4
+ function, or as a `Gulp` plugin.
5
5
 
6
6
  ## Examples
7
7
 
@@ -9,13 +9,16 @@ Here are some of the things you can use `mancha` for.
9
9
 
10
10
  ### Replace simple variables using `{{value}}` format
11
11
 
12
- Source:
12
+ index.html:
13
13
 
14
- ```js
15
- import * as Mancha from "mancha";
16
- const content = "<div>Hello {{user}}</div>";
17
- const output = Mancha.renderContent(content, { user: "World" });
18
- console.log(output);
14
+ ```html
15
+ <span>Hello {{name}}</span>
16
+ ```
17
+
18
+ Command:
19
+
20
+ ```bash
21
+ npx mancha --input="./index.html" --vars='{"name": "World"}'
19
22
  ```
20
23
 
21
24
  Result:
@@ -24,10 +27,7 @@ Result:
24
27
  <div>Hello World</div>
25
28
  ```
26
29
 
27
- The first argument is a string of content to preprocess, the second is a dictionary of
28
- `<key, value>` pairs such that instances of `{{key}}` in the content will be replaced with `value`.
29
-
30
- ### Include files from other local sources using the `<include>` tag
30
+ ### Include files from a relative path using the `<include>` tag
31
31
 
32
32
  hello-world.html:
33
33
 
@@ -35,33 +35,129 @@ hello-world.html:
35
35
  <span>Hello World</span>
36
36
  ```
37
37
 
38
- Source:
38
+ index.html:
39
39
 
40
40
  ```html
41
41
  <div>
42
42
  <include src="./hello-world.html"></include>
43
43
  </div>
44
- <script src="//unpkg.com/mancha" init></script>
44
+ ```
45
+
46
+ Command:
47
+
48
+ ```bash
49
+ npx mancha --input="./index.html"
45
50
  ```
46
51
 
47
52
  Result:
48
53
 
49
54
  ```html
50
- <div><span>Hello World</span></div>
55
+ <div>
56
+ <span>Hello World</span>
57
+ </div>
58
+ ```
59
+
60
+ ## Usage
61
+
62
+ ### Client Side Rendering (CSR)
63
+
64
+ To use `mancha` on the client (browser), use the `mancha.js` bundled file available via `unpkg`.
65
+
66
+ ```html
67
+ <body>
68
+ <span>Hello, {{name}}!</span>
69
+ </body>
70
+
71
+ <script src="//unpkg.com/mancha" data-vars='{"name": "John"}' target="body" init></script>
72
+ ```
73
+
74
+ Script tag attributes:
75
+
76
+ - `init`: whether to automatically render upon script load
77
+ - `data-vars`: JSON string with key-value pairs, where `{{key}}` will be replaced with `{{value}}`
78
+ - `target`: comma-separated document elements to render e.g. "body" or "head,body" (defaults to "body")
79
+
80
+ For a more complete example, see [examples/browser](./examples/browser).
81
+
82
+ ### Compile Time Server Side Rendering (SSR)
83
+
84
+ To use `mancha` on the server at compile time, you can use the `npx mancha` command. For example,
85
+ if this is your project structure:
86
+
51
87
  ```
88
+ src/
89
+ ├─ components/
90
+ | ├─ main.tpl.html
91
+ | ├─ footer.tpl.html
92
+ ├─ index.html
93
+ ├─ vars.json
94
+ ```
95
+
96
+ You can run the following command to compile the site into a `public` folder:
97
+
98
+ ```bash
99
+ npx mancha --input="./src/index.html" --vars="$(cat vars.json)" --output="./public"
100
+ ```
101
+
102
+ For a more complete example, see [examples/compiled](./examples/compiled).
52
103
 
53
- ## Use `mancha` in gulpfile scripts
104
+ ### On Demand Server Side Rendering (SSR)
54
105
 
55
- To use `mancha` in your gulpfile, you can do the following:
106
+ You can also use `mancha` as part of your server's request handling. Assuming a similar folder
107
+ structure as described in the previous section, the following `express` node server would render
108
+ the HTML code on demand for each incoming request:
56
109
 
57
110
  ```js
58
- const mancha = require('mancha');
59
- gulp.src(...).pipe(mancha({myvar: myval})).pipe(...)
111
+ import express from "express";
112
+ import { renderLocalPath } from "mancha";
113
+ import vars from "./vars.json";
114
+
115
+ const app = express();
116
+
117
+ app.get("/", async (req, res) => {
118
+ const html = await renderLocalPath("src/index.html", vars);
119
+ res.set("Content-Type", "text/html");
120
+ res.send(html);
121
+ });
122
+
123
+ app.listen(process.env.PORT || 8080);
124
+ ```
125
+
126
+ For a more complete example, see [examples/rendered](./examples/rendered).
127
+
128
+ ### Web Worker Runtime Server Side Rendering (SSR)
129
+
130
+ For servers hosted as worker runtimes, such as `Cloudflare Workers`, you will need to import a
131
+ stripped down version of `mancha` that does not have the ability to read local files. Any HTML files
132
+ will need to be separately hosted by a static server, although you can also generate strings
133
+ containing HTML on demand.
134
+
135
+ ```js
136
+ import { renderRemotePath } from "mancha/dist/web"
137
+
138
+ const VARS = {...};
139
+ const HTML_ROOT = "https://example.com/html";
140
+
141
+ self.addEventListener('fetch', async event => {
142
+ const content = await renderRemotePath(`${HTML_ROOT}/index.html`, VARS);
143
+ event.respondWith(new Response(content, { headers: {"Content-Type": "text/html"} }))
144
+ });
145
+ ```
146
+
147
+ For a more complete example, see [examples/wrangler](./examples/wrangler).
148
+
149
+ ## Compile Time `gulpfile` Scripts
150
+
151
+ To use `mancha` in your `gulpfile`, you can do the following:
152
+
153
+ ```js
154
+ import { mancha } from "mancha/dist/gulp";
155
+ gulp.src(...).pipe(mancha({"myvar": "myval"})).pipe(...)
60
156
  ```
61
157
 
62
158
  The first argument consists of a dictionary of `<key, value>` pairs of literal string replacements.
63
159
  `key` will become `{{key}}` before replacing it with `value` in the processed files. For example,
64
- if we passed `{name: "Batman"}` as the argument:
160
+ if we passed `{"name": "World"}` as the argument:
65
161
 
66
162
  Source:
67
163
 
@@ -72,5 +168,5 @@ Source:
72
168
  Result:
73
169
 
74
170
  ```html
75
- <div>Hello Batman</div>
171
+ <div>Hello World</div>
76
172
  ```
package/dist/browser.js CHANGED
@@ -12,12 +12,11 @@ var _a, _b, _c, _d;
12
12
  Object.defineProperty(exports, "__esModule", { value: true });
13
13
  const Mancha = require("./web.js");
14
14
  self["Mancha"] = Mancha;
15
- if (((_b = (_a = self.document) === null || _a === void 0 ? void 0 : _a.currentScript) === null || _b === void 0 ? void 0 : _b.getAttribute("init")) !== undefined) {
15
+ if ((_b = (_a = self.document) === null || _a === void 0 ? void 0 : _a.currentScript) === null || _b === void 0 ? void 0 : _b.hasAttribute("init")) {
16
16
  const vars = JSON.parse(self.document.currentScript.dataset["vars"] || "{}");
17
17
  const fsroot = self.location.href.split("/").slice(0, -1).join("/") + "/";
18
18
  const targets = ((_d = (_c = self.document.currentScript) === null || _c === void 0 ? void 0 : _c.getAttribute("target")) === null || _d === void 0 ? void 0 : _d.split(",")) || ["body"];
19
19
  targets.forEach((target) => __awaiter(void 0, void 0, void 0, function* () {
20
- console.log(`Replacing target ${target}.`);
21
20
  const node = self.document[target];
22
21
  node.innerHTML = yield Mancha.renderContent(node.innerHTML, vars, fsroot);
23
22
  }));