feat: promiscuous templates handling

fiadone · Jul 30, 2022 · f0a4659 · f0a4659
1 parent b4c29cb
commit f0a4659
Show file tree

Hide file tree

Showing 26 changed files with 2,383 additions and 153 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -0,0 +1,3 @@
+{
+  "extends": "@fiad"
+}
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,5 @@
 .DS_Store
-node_modules
+.idea
+dist
+node_modules
+playground/*.lock
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,103 @@
+# Migration guide
+
+## From *v1.x* to *v2.x*
+
+### 1. [Breaking change] __The template path has been moved to the *script* tag's `data-template` attribute.__
+
+Replace this:
+```html
+<script type="application/json">
+  {
+    "template": "path/to/template.twig",
+    "data": {
+      "foo": "bar"
+    }
+  }
+</script>
+```
+
+with this:
+```html
+<script type="application/json" data-template="path/to/template.twig">
+  {
+    "foo": "bar"
+  }
+</script>
+```
+
+> ℹ️ The *data* property is no longer required in the *JSON* schema.
+
+
+### 2. [Breaking change] __Plain text content is no longer supported within *.html* files.__
+
+Replace this:
+```json
+{
+  "template": "path/to/template.twig",
+  "data": {
+    "foo": "bar"
+  }
+}
+```
+
+with this:
+```html
+<script type="application/json" data-template="path/to/template.twig">
+  {
+    "foo": "bar"
+  }
+</script>
+```
+
+
+### 3. [New feature] __Multiple *script* tags are now supported within the same *.html* file and can live together with standard *HTML* code.__
+
+```html
+<html>
+  <body>
+
+    <!-- other html contents -->
+
+    <script type="application/json" data-template="path/to/fragment-a.twig">
+      {
+        "foo": "bar"
+      }
+    </script>
+
+    <!-- other html contents -->
+
+    <script type="application/json" data-template="path/to/fragment-b.twig"></script>
+
+    <!-- other html contents -->
+
+  </body>
+</html>
+```
+
+
+### 4. [New option] __*Twig*'s internal template caching is now configurable.__
+
+```js
+/* vite.config.js */
+import { defineConfig } from 'vite'
+import twig from 'vite-plugin-twig'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    twig({
+      // ...
+      cache: true
+    })
+  ]
+})
+
+```
+or
+```js
+/* twig.config.js */
+module.exports = {
+  // ...
+  cache: true
+}
+```
diff --git a/README-v1.md b/README-v1.md
@@ -0,0 +1,85 @@
+# vite-plugin-twig
+
+[Vite](https://github.com/vitejs/vite) plugin for [Twig](https://github.com/twigjs/twig.js/).
+
+---
+
+## ⚠️ Notice
+This documentation refers to the version *1.x* of the plugin. Take a look [here](./README.md) for latest releases.
+
+
+## Installation
+```
+npm i -D vite-plugin-twig
+```
+
+
+## Usage
+
+```js
+/* vite.config.js */
+import { defineConfig } from 'vite'
+import twig from 'vite-plugin-twig'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    twig()
+  ]
+})
+```
+
+### Options
+The plugin can be configured both via the *twig.config.js* file from the project root or by passing a configuration object directly as argument to the function above (in this last case, the configuration file will be ignored).
+
+Here below the list of the supported options.
+
+#### `filters`
+__type__ `{ [key: string]: (...args: any[]) => any }`
+
+__default__ `{}`
+
+A collection of custom filters to extend *Twig*. Look at [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/Extending-twig.js) to learn more.
+
+#### `functions`
+__type__ `{ [key: string]: (...args: any[]) => any }`
+
+__default__ `{}`
+
+A collection of custom functions to extend *Twig*. Look at [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/Extending-twig.js) to learn more.
+
+#### `globals`
+__type__ `{ [key: string]: any }`
+
+__default__ `{}`
+
+The global variables to be injected in each template.
+
+#### `settings`
+__type__ `{ [key: string]: any }`
+
+__default__ `{}`
+
+The *Twig* settings. Please refer to [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/) to learn more.
+
+
+### Templates
+The *html* files located by default in the *Vite* project root are not intented to be replaced directly by the *twig* ones as the normal page files resolution/linking on the *Vite*'s dev server is wanted to be preserved along with the build logic. However, those files are supposed to contain a json definition instead of the traditional markup, which should be moved on the *twig* side.
+
+More in details, a *html* file should look like this:
+
+```html
+<!-- index.html -->
+<script type="application/json">
+  {
+    "template": "path/to/template.twig",
+    "data": {
+      "title": "Homepage"
+    }
+  }
+</script>
+```
+
+where `template` is the path of the *twig* template to be rendered (relative to the *cwd*), and `data` is the local context for that page (eventually merged with the *globals* provided via plugin options).
+
+> ℹ️ The *script* tag is not mandatory, since a plain text representation of the *json* will be correctly parsed too. However, it is recommended for readability and syntax highlighting purposes.
diff --git a/README.md b/README.md
@@ -4,6 +4,10 @@
 
 ---
 
+## ⚠️ Notice
+This documentation refers to the version *2.x* of the plugin. Take a look [here](./README-v1.md) for older releases or check out the [migration guide](./MIGRATION.md).
+
+
 ## Installation
 ```
 npm i -D vite-plugin-twig
@@ -14,66 +18,106 @@ npm i -D vite-plugin-twig
 
 ```js
 /* vite.config.js */
+import { defineConfig } from 'vite'
 import twig from 'vite-plugin-twig'
 
-export default {
+export default defineConfig({
+  // ...
   plugins: [
     twig()
   ]
-}
+})
 ```
 
 ### Options
 The plugin can be configured both via the *twig.config.js* file from the project root or by passing a configuration object directly as argument to the function above (in this last case, the configuration file will be ignored).
 
 Here below the list of the supported options.
 
+#### `cache`
+__type__ `Boolean`
+
+__default__ `false`
+
+If *true*, it enables internal *Twig*'s template caching.
+
 #### `filters`
-__type__ `{ [key: string]: (...args: any[]) => any }`
+__type__ `{ [key: String]: (...args: Any[]) => Any }`
 
 __default__ `{}`
 
 A collection of custom filters to extend *Twig*. Look at [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/Extending-twig.js) to learn more.
 
 #### `functions`
-__type__ `{ [key: string]: (...args: any[]) => any }`
+__type__ `{ [key: String]: (...args: Any[]) => Any }`
 
 __default__ `{}`
 
 A collection of custom functions to extend *Twig*. Look at [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/Extending-twig.js) to learn more.
 
 #### `globals`
-__type__ `{ [key: string]: any }`
+__type__ `{ [key: String]: Any }`
 
 __default__ `{}`
 
 The global variables to be injected in each template.
 
 #### `settings`
-__type__ `{ [key: string]: any }`
+__type__ `{ [key: String]: Any }`
 
 __default__ `{}`
 
 The *Twig* settings. Please refer to [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/) to learn more.
 
 
 ### Templates
-The *html* files located by default in the *Vite* project root are not intented to be replaced directly by the *twig* ones as the normal page files resolution/linking on the *Vite*'s dev server is wanted to be preserved along with the build logic. However, those files are supposed to contain a json definition instead of the traditional markup, which should be moved on the *twig* side.
+The *.html* files located by default in the *Vite* project root are not intented to be replaced directly by the *.twig* ones since the normal page files resolution/linking on the *Vite*'s dev server is wanted to be preserved along with the build logic. However, those files are enabled to contain special *script* tags which will be treated as placeholders for contents you want to delegate to *Twig*.
 
-More in details, a *html* file should look like this:
+More in details, a *.html* file could look like this:
 
 ```html
 <!-- index.html -->
-<script type="application/json">
+<script type="application/json" data-template="path/to/template.twig">
   {
-    "template": "path/to/template.twig",
-    "data": {
-      "title": "Homepage"
-    }
+    "foo": "bar"
   }
 </script>
 ```
 
-where `template` is the path of the *twig* template to be rendered (relative to the *cwd*), and `data` is the local context for that page (eventually merged with the *globals* provided via plugin options).
+where the `data-template` attribute defines the path (relative to the *cwd*) of the *.twig* file to be rendered in place of the *script* tag, whose content (optional) represents instead a *JSON* definition of the local context to be injected in the template (possibly merged with the *globals* provided via plugin options).
+
+Take a look [here](./playground/index.html) for a clearer example.
+
+> ℹ️ The *application/json* type is not mandatory, but it is recommended for syntax highlighting and linting purposes.
+
+The plugin also supports a promiscuous templates handling, allowing you:
+- to have *.html* files with both standard and *Twig* based code
+- to render (multiple) *Twig* fragments within a standard *.html* page
+
+This could be useful, for instance, when you want to use *Twig* for new implementations without having to refactor an existing code base.
+
+With that in mind, a *.html* file could look as follows:
+
+```html
+<html>
+  <body>
+
+    <!-- existing contents -->
+
+    <script type="application/json" data-template="path/to/fragment-a.twig">
+      {
+        "foo": "bar"
+      }
+    </script>
+
+    <!-- existing contents -->
+
+    <script type="application/json" data-template="path/to/fragment-b.twig"></script>
+
+    <!-- existing contents -->
+
+  </body>
+</html>
+```
 
-> ℹ️ The *script* tag is not mandatory, since a plain text representation of the *json* will be correctly parsed too. However, it is recommended for readability and syntax highlighting purposes.
+Take a look [here](./playground/fragments.html) for a clearer example.
diff --git a/build.config.js b/build.config.js
@@ -0,0 +1,16 @@
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  entries: [
+    'src/index'
+  ],
+  declaration: true,
+  clean: true,
+  rollup: {
+    emitCJS: true
+  },
+  externals: [
+    'twig',
+    'vite'
+  ]
+})
diff --git a/index.d.ts b/index.d.ts