diff --git a/CHANGELOG.md b/CHANGELOG.md index 92d86f3..289a900 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). ## [1.12.12] - Unreleased +### Added +- New option `autoDataVarname` to replace `useWith`. + `useWith` is keept as an alias for backward compatibility but will be removed in the future. + ### Fixed - `auto_trim` plugin: Trim comments. - `set` evaluates the expression twice. diff --git a/bench/bench.ts b/bench/bench.ts index 7520c95..09abbd7 100644 --- a/bench/bench.ts +++ b/bench/bench.ts @@ -4,7 +4,7 @@ import { Liquid } from "npm:liquidjs@10.18.0"; import { Eta } from "https://deno.land/x/eta@v3.5.0/src/index.ts"; const env = vento({ - useWith: true, + autoDataVarname: true, }); const engine = new Liquid({ cache: true, diff --git a/docs/configuration.md b/docs/configuration.md index 9ea7380..7dbf8dd 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -12,7 +12,7 @@ Pass an options object to the `vento()` function to customize Vento. // Example with the default options: const env = vento({ dataVarname: "it", - useWith: true, + autoDataVarname: true, includes: Deno.cwd(), autoescape: false, }); @@ -41,24 +41,23 @@ Now you can use the `global` variable: {{ global.title }} ``` -### useWith +### autoDataVarname -Vento can append automatically the `it.` prefix to your variables. For example, instead of -`{{ it.title }}` you can simply write `{{ title }}`. This avoid errors like _(ReferenceError: title is -not defined)_ when you're trying to print a variable that doesn't exist. +Vento can append automatically the `dataVarname` prefix (which by default is `.it`) to any variable that need it. For example, instead of +`{{ it.title }}` you can simply write `{{ title }}` and vento automatically convert it to `{{ it.title }}`. -In early versions, Vento used the [`with` statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with) to allow to use variables from the `it` object as global. But due `with` is no longer recommended and can affect to performance, starting from Vento 0.12 this has changed and now Vento transforms the code and appends the `it.` prefix to all variables that need it. - -The name of this option remains `useWith` for backward compatibility but it will be changed in the next major version. - -You can disable this behavior by setting this option to `false`: +You can disable this behavior by setting the `autoDataVarname` option to `false`: ```js const env = vento({ - useWith: false, + autoDataVarname: false, }); ``` +> [!warning] +> +> The `useWith` option is an alias for backward compatibility ([when `with` was used](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with)) but it will be removed in the future. + ### autoescape Set `true` to automatically escape printed variables: diff --git a/mod.ts b/mod.ts index bb30f1b..80be499 100644 --- a/mod.ts +++ b/mod.ts @@ -16,8 +16,9 @@ import trim from "./plugins/trim.ts"; export interface Options { includes?: string | Loader; - /** @deprecated */ + /** @deprecated Use autoDataVarname */ useWith?: boolean; + autoDataVarname?: boolean; dataVarname?: string; autoescape?: boolean; } @@ -31,7 +32,7 @@ export default function (options: Options = {}): Environment { loader, dataVarname: options.dataVarname || "it", autoescape: options.autoescape ?? false, - useWith: options.useWith ?? true, + autoDataVarname: options.autoDataVarname ?? options.useWith ?? true, }); // Register basic plugins diff --git a/src/environment.ts b/src/environment.ts index c90d65a..4adfcd0 100644 --- a/src/environment.ts +++ b/src/environment.ts @@ -49,7 +49,7 @@ export interface Options { loader: Loader; dataVarname: string; autoescape: boolean; - useWith: boolean; + autoDataVarname: boolean; } export class Environment { @@ -133,9 +133,9 @@ export class Environment { const tokens = this.tokenize(source, path); let code = this.compileTokens(tokens).join("\n"); - const { dataVarname, useWith } = this.options; + const { dataVarname, autoDataVarname } = this.options; - if (useWith) { + if (autoDataVarname) { code = transformTemplateCode(code, dataVarname); } diff --git a/test/echo.test.ts b/test/echo.test.ts index 09854be..1f040f9 100644 --- a/test/echo.test.ts +++ b/test/echo.test.ts @@ -72,7 +72,7 @@ Deno.test("Echo tag", async () => { testThrows({ options: { - useWith: false, + autoDataVarname: false, }, template: ` Hello {{ world }}