/dist
/js_template-*.tgz
/node_modules
+/package-lock.json
/yarn.lock
/yarn-error.log
SPDX-License-Identifier: MIT
Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
## Overview
-The `js_template` package, consisting of the function `js_template()`, parses a
-superset of JavaScript (ES6) which can contain HTML-like constructs, and
-generates plain JavaScript code which in turn, can generate the desired HTML.
+The `js_template` package exports a single function `js_template(root, dirname,
+pathname)`, which loads the given file from disk, parses it for a superset of
+JavaScript (ES6) which can contain HTML-like constructs, and then generates
+equivalent plain JavaScript code which in turn, can generate the desired HTML.
The system is inspired by Pug (formerly Jade) templates, but emphasizing the
JavaScript, for instance you do not need a `-` sign at the start of each line,
the output HTML. However, the empty `{ }` must still be given in the template.
This is partly for the parser's convenience, since it depends on recognizing
the `{ }` to distinguish between an HTML template and ordinary JavaScript code.
-It is also more uniform: there is no need to remember which tags are special.
+It is also more uniform: there is no need to remember which tags are special.
### Regular text in templates
If the text is multi-line, backquoted (template) strings are be used, to allow
embedded newlines. When the entire text is held in a variable, e.g. `myvar`, a
-template string such as `\`${myvar}\`` should be used, to convert it into a
-standalone statement consisting of only a string contant, and hence into HTML.
+template string such as ```${myvar}``` should be used, to convert it into a
+standalone statement consisting of only a string constant, and hence into HTML.
In the future, we may extend the parser to do this automatically for statements
that consist of only a variable name, which would have no effect in JavaScript.
### HTML class and id shorthand
-The tag name can be followed by `#name` for as shorthand for the HTML attribute
+The tag name can be followed by `#name` as shorthand for the HTML attribute
`id="name"`
or by `.name` as shorthand for the HTML attribute
`class="name"`
essential, unlike in regular JavaScript, so that `p {...}` occurs in statement
rather than expression context. As an expression it would return a string which
would be ignored, since the page template is expecting output to be in `_out`.
-
+
## File management
The `js_template()` function gives a "point and shoot" interface which makes it
Before using either a disk-cached or a memory-cached template, the modification
times are checked and the template is recompiled if it is stale. Thus you can
edit your website while it is live, and each page will be recompiled as needed
-each time it is served. Templates deleted on disk are also hidden in the cache.
+just before serving. Templates deleted on disk are not returned from the cache.
+
+Note: If the document root is not writeable, a simple expedient is to make sure
+that all `.*.jst.js` files are up to date, so no write is attempted. You can do
+this by firing up a development instance of the server in a writeable directory
+and then indexing the whole site, for example by a recursive `wget` invocation.
+
+## To be implemented
+
+It is intended that we will shortly add a timer function (or possibly just a
+function that the user should call periodically) to flush built templates from
+the cache after a stale time, on the assumption that the template might not be
+accessible or wanted anymore. For example, if the templates are HTML pages, the
+link structure of the site may have changed to make some pages inaccessible.
+
+As mentioned throughout the above text, we will also improve the JST parser and
+translator to remove the need for some quoting or backticking workarounds, and
+to improve support for some HTML constructs such as stylesheets via a dedicated
+CSS parser, and similarly we may add various preprocessors such as TypeScript.
+
+We may also simplify the API to take only the root directory and the pathname.
+With the current interface, the working directory name and the pathname are
+resolved before doing anything, so the caller should really do this. It evolved
+that way because of the implementation details of the `_require(...)` pathway.
+
+We're also working on a "JSTizer" which can take ordinary HTML code and spit
+out sample JST code, which is handy during development when inserting things
+like Bootstrap templates into your page. The primary interface to the JSTizer
+would probably be a webapp, although source code would also be made available.
+
+## GIT repository
+
+The development version can be cloned, downloaded, or browsed with `gitweb` at:
+https://git.ndcode.org/public/js_template.git
+
+## License
+
+All of our NPM packages are MIT licensed, please see LICENSE in the repository.
+We also gratefully acknowledge the `acorn` team for the original MIT license of
+their JavaScript parser, which we've heavily modified to produce the JST parser.
-Note: deletion of rarely or never accessed pages from the memory cache is not
-yet implemented (it will use a long timeout, e.g. one week), so the webserver
-should be restarted occasionally. This will be fixed if it becomes an issue in
-practice. Also, if the document root is not writeable, a simple expedient is to
-make sure that all `.*.jst.js` files are up to date, so no write is attempted.
+## Contributions
-## Conclusions
+We would greatly welcome your feedback and contributions. The `js_template` is
+under active development (and is part of a larger project that is also under
+development) and thus the API is considered tentative and subject to change. If
+this is undesirable, you could possibly pin the version in your `package.json`.
-Further detailed documentation and tutorials will be added to the project in
-due course. For the present, the software is in active development, so it would
-be premature to document everything exactly as it is now. Please do contact the
-author Nick Downing <nick@ndcode.org>, should you have questions or feedback.
+Contact: Nick Downing <nick@ndcode.org>
* SPDX-License-Identifier: MIT
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
*/
-let BuildCache = require('BuildCache')
+let BuildCache = require('build_cache')
let acorn = require('./dist/acorn')
let astring = require('astring')
let fs = require('fs')
{
"name": "js_template",
- "description": "JavaScript template engine",
- "homepage": "https://www.ndcode.org",
- "main": "js_template.js",
- "version": "6.0.2",
- "engines": {
- "node": ">=0.4.0"
- },
- "maintainers": [
- {
- "name": "Nick Downing",
- "email": "nick@ndcode.org",
- "web": "https://www.ndcode.org"
- }
+ "version": "0.1.0",
+ "description": "JavaScript HTML template engine",
+ "keywords": [
+ "template",
+ "HTML",
+ "webpage",
+ "dynamic",
+ "server-side",
+ "render"
],
+ "homepage": "https://www.ndcode.org",
"repository": {
"type": "git",
"url": "https://git.ndcode.org/public/js_template.git"
},
- "license": "MIT",
- "scripts": {
- "prepare": "rollup -c rollup.config.js"
+ "bugs": {
+ "email": "nick@ndcode.org"
},
+ "main": "js_template.js",
+ "engines": {
+ "node": ">=0.4.0"
+ },
+ "directories": {},
"dependencies": {
"astring": "^1.3.1",
+ "build_cache": "^0.1.0",
"html-escape": "^2.0.0",
"rollup": "^0.45.0",
"rollup-plugin-buble": "^0.16.0"
- }
+ },
+ "devDependencies": {},
+ "scripts": {
+ "prepare": "rollup -c rollup.config.js"
+ },
+ "maintainers": "Nick Downing <nick@ndcode.org>",
+ "license": "MIT"
}
* SPDX-License-Identifier: MIT
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
*/
let transform = (visitors, node, state) => {
* SPDX-License-Identifier: MIT
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
*/
let assert = require('assert')
public / jst.git / commitdiff