Skip to content

Commit

Permalink
feat: files and fragments filtering helpers + config refactoring
Browse files Browse the repository at this point in the history
  • Loading branch information
fiadone committed Aug 6, 2022
1 parent f0a4659 commit 4f5c377
Show file tree
Hide file tree
Showing 9 changed files with 260 additions and 106 deletions.
131 changes: 109 additions & 22 deletions MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,28 +50,52 @@ with this:
```


### 3. [New feature] __Multiple *script* tags are now supported within the same *.html* file and can live together with standard *HTML* code.__
### 3. [Breaking change] __*Twig*'s extensions are now wrapped in the *extensions* property within the configuration.__

```html
<html>
<body>

<!-- other html contents -->
Replace this:
```js
/* vite.config.js */
import { defineConfig } from 'vite'
import twig from 'vite-plugin-twig'

<script type="application/json" data-template="path/to/fragment-a.twig">
{
"foo": "bar"
export default defineConfig({
// ...
plugins: [
twig({
// ...
filters: {
// ...
},
functions: {
// ...
}
</script>

<!-- other html contents -->
})
]
})
```

<script type="application/json" data-template="path/to/fragment-b.twig"></script>
with this:
```js
/* vite.config.js */
import { defineConfig } from 'vite'
import twig from 'vite-plugin-twig'

<!-- other html contents -->

</body>
</html>
export default defineConfig({
// ...
plugins: [
twig({
// ...
extensions: {
filters: {
// ...
},
functions: {
// ...
}
}
})
]
})
```


Expand All @@ -93,11 +117,74 @@ export default defineConfig({
})

```
or


### 5. [New option] __Via the *fileFilter* option, now the plugin provides a custom way to determine if the current transforming .html file should be processed/ignored or not__

```js
/* twig.config.js */
module.exports = {
/* vite.config.js */
import { defineConfig } from 'vite'
import twig from 'vite-plugin-twig'

export default defineConfig({
// ...
cache: true
}
plugins: [
twig({
// ...
fileFilter: filename => {
// your custom logic
return true // or false
}
})
]
})

```


### 6. [New option] __Via the *fragmentFilter* option, now the plugin provides a custom way to determine if a matched fragment should be processed/ignored or not__

```js
/* vite.config.js */
import { defineConfig } from 'vite'
import twig from 'vite-plugin-twig'

export default defineConfig({
// ...
plugins: [
twig({
// ...
fragmentFilter: (fragment, template, data) => {
// your custom logic
return true // or false
}
})
]
})

```


### 7. [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>
```
78 changes: 61 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,50 +24,94 @@ import twig from 'vite-plugin-twig'
export default defineConfig({
// ...
plugins: [
twig()
twig({ /* ...options */ })
]
})
```

### 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).
The plugin can be configured both directly with the options parameter shown above or via the dedicated *twig.config.(js|ts)* file, like following:

```js
/* twig.config.js */
import { defineConfig } from 'vite-plugin-twig'

export default defineConfig({
// ...
})
```

> ℹ️ *defineConfig* is a bypass function with type hints, which means you can also omit it if you don't need the autocompletion/typecheck.
Here below the list of the supported options.

#### `cache`
__type__ `Boolean`
__type:__ `boolean`

__default__ `false`
__default:__ `false`

If *true*, it enables internal *Twig*'s template caching.

#### `filters`
__type__ `{ [key: String]: (...args: Any[]) => Any }`
#### `extensions`
__type:__ `{ filters: TwigExtensions, functions: TwigExtensions }`

__default:__ `undefined`

A collection of custom filters and functions to extend *Twig*. Look at [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/Extending-twig.js) to learn more.

#### `fileFilter`
__type:__ `(filename: string) => boolean`

__default:__ `undefined`

A custom filter to determine if the current transforming *.html* file should be processed/ignored or not (useful for improving compatibility with other plugins).

__default__ `{}`
Example:
```js
/* twig.config.js */
import { defineConfig } from 'vite-plugin-twig'

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.
export default defineConfig({
// ...
fileFilter: filename => filename.endsWith('.twig.html')
})
```

#### `fragmentFilter`
__type:__ `TwigFragmentFilter`

#### `functions`
__type__ `{ [key: String]: (...args: Any[]) => Any }`
__default:__ `undefined`

__default__ `{}`
A custom filter to determine if the current matched fragment should be processed/ignored or not (useful for improving compatibility with other plugins).

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.
Example:
```js
/* twig.config.js */
import { defineConfig } from 'vite-plugin-twig'

export default defineConfig({
// ...
fragmentFilter: (fragment, template, data) => {
return fragment.indexOf('data-engine="twig"') > -1
// or template.endsWith('.twig')
// or data.engine === 'twig'
}
})
```

#### `globals`
__type__ `{ [key: String]: Any }`
__type:__ `{ [key: string]: any }`

__default__ `{}`
__default:__ `undefined`

The global variables to be injected in each template.

#### `settings`
__type__ `{ [key: String]: Any }`
__type:__ `{ views: any, 'twig options': any }`

__default__ `{}`
__default:__ `undefined`

The *Twig* settings. Please refer to [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/) to learn more.
The *Twig* settings. Please refer to *twig.js* [documentation](https://github.com/twigjs/twig.js/wiki/) and [types](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/twig/index.d.ts) to learn more.


### Templates
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "vite-plugin-twig",
"version": "2.0.0",
"version": "2.1.0",
"license": "MIT",
"keywords": [
"vite-plugin",
Expand Down
2 changes: 1 addition & 1 deletion playground/vite.config.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { defineConfig } from 'vite'
import twig from '../src'
import twig from 'vite-plugin-twig'

export default defineConfig({
plugins: [
Expand Down
5 changes: 5 additions & 0 deletions src/config.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import type { PluginOptions } from '../types'

export function defineConfig(options: PluginOptions) {
return options
}
4 changes: 2 additions & 2 deletions src/index.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
import { viteTwigPlugin } from './plugin'
export { defineConfig } from './config'
export { viteTwigPlugin as default } from './plugin'

export default viteTwigPlugin
17 changes: 10 additions & 7 deletions src/plugin.ts
Original file line number Diff line number Diff line change
@@ -1,18 +1,21 @@
import path from 'path'
import path from 'node:path'
import type { Plugin } from 'vite'
import type { TwigOptions } from '../types'
import { retrieveOptionsFromConfigFile, configureTwig, parseHTML } from './tasks'
import type { PluginOptions } from '../types'
import { configureTwig, parseHTML, retrieveConfigFromFile } from './tasks'

export function viteTwigPlugin(options: TwigOptions): Plugin {
const { cache, filters, functions, globals, settings } = options || retrieveOptionsFromConfigFile()
export async function viteTwigPlugin(options: PluginOptions): Promise<Plugin> {

configureTwig({ cache, filters, functions })
const config = options || await retrieveConfigFromFile()

configureTwig(config)

return {
name: 'vite-plugin-twig',
transformIndexHtml: {
enforce: 'pre',
transform: html => parseHTML(html, { globals, settings })
transform: async (html, ctx) => {
return await parseHTML(html, ctx, config)
}
},
handleHotUpdate({ file, server }) {
if (path.extname(file) === '.twig') {
Expand Down
Loading

0 comments on commit 4f5c377

Please sign in to comment.