{"id":21540961,"url":"https://github.com/reshape/expressions","last_synced_at":"2025-06-17T04:39:30.858Z","repository":{"id":57354538,"uuid":"65311080","full_name":"reshape/expressions","owner":"reshape","description":"plugin that adds the ability to use expressions, conditionals, and loops","archived":false,"fork":false,"pushed_at":"2019-02-05T12:37:31.000Z","size":446,"stargazers_count":8,"open_issues_count":13,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-10T18:01:36.376Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reshape.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-09T16:33:40.000Z","updated_at":"2018-12-03T11:00:00.000Z","dependencies_parsed_at":"2022-09-12T04:10:16.825Z","dependency_job_id":null,"html_url":"https://github.com/reshape/expressions","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/reshape/expressions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fexpressions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fexpressions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fexpressions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fexpressions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reshape","download_url":"https://codeload.github.com/reshape/expressions/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reshape%2Fexpressions/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260294188,"owners_count":22987600,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T05:00:41.188Z","updated_at":"2025-06-17T04:39:30.835Z","avatar_url":"https://github.com/reshape.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reshape Expressions\n\n[![npm](https://img.shields.io/npm/v/reshape-expressions.svg?style=flat-square)](https://npmjs.com/package/reshape-expressions)\n[![tests](https://img.shields.io/travis/reshape/expressions.svg?style=flat-square)](https://travis-ci.org/reshape/expressions?branch=master)\n[![dependencies](https://img.shields.io/david/reshape/expressions.svg?style=flat-square)](https://david-dm.org/reshape/expressions)\n[![coverage](https://img.shields.io/coveralls/reshape/expressions.svg?style=flat-square)](https://coveralls.io/r/reshape/expressions?branch=master)\n\nLocal variables, expressions, loops, and conditionals in your html.\n\n## Installation\n\nFirst, install from npm with `npm i reshape-exp --save`, then add it as a plugin to your reshape pipeline:\n\n```js\nconst reshape = require('reshape')\nconst exp = require('reshape-expressions')\nconst {readFileSync} = require('fs')\n\nreshape({ plugins: exp() })\n  .process(readFileSync('exampleFile.html', 'utf8'))\n  .then((res) =\u003e {\n    return res.output({ foo: 'bar' }) // =\u003e your html\n  })\n```\n\n## Usage\n\nThis plugin provides a syntax for including local variables and expressions in your templates, and also extends custom tags to act as helpers for conditionals and looping.\n\nYou have full control over the delimiters used for injecting locals, as well as the tag names for the conditional and loop helpers, if you need them. All options that can be passed to the `expressions` plugin are shown below:\n\n| Option | Description | Default |\n| ------ | ----------- | ------- |\n| **delimiters** | Array containing beginning and ending delimiters for escaped locals. | `['{{', '}}']` |\n| **unescapeDelimiters** | Array containing beginning and ending delimiters for inserting unescaped locals. | `['{{{', '}}}']` |\n| **conditionalTags** | Array containing names for tags used for standard `if`/`else if`/`else` logic | `['if', 'elseif', 'else']` |\n| **loopTags** | Array containing names for standard `for` loop logic | `['each']` |\n\n### Locals\n\nYou can inject locals into any piece of content in your html templates, other than overwriting tag names. For example, if you had the following template:\n\n```html\n\u003cdiv class=\"{{ myClassName }}\"\u003e\n  My name is {{ myName }}\n\u003c/div\u003e\n```\n\nAnd passed it through reshape like this:\n\n```js\nreshape({ plugins: exp() })\n  .process(template)\n  .then((res) =\u003e res.output({ myClassName: 'introduction', myName: 'Marlo' })))\n```\n\nYou would get this as your output:\n\n```html\n\u003cdiv class=\"introduction\"\u003eMy name is Marlo\u003c/div\u003e\n```\n\n### Unescaped Locals\n\nBy default, special characters will be escaped so that they show up as text, rather than html code. For example, the following template:\n\n```html\n\u003cp\u003eThe fox said, {{ strongStatement }}\u003c/p\u003e\n```\n\nCalled as such:\n\n```js\nreshape({ plugins: exp() })\n  .process(template)\n  .then((res) =\u003e res.output({ strongStatement: 'wow!' }))\n```\n\nYou would see the following output:\n\n```html\n\u003cp\u003eThe fox said, \u0026lt;strong\u0026gt;wow!\u0026lt;strong\u0026gt;\u003c/p\u003e\n```\n\nIn your browser, you would see the angle brackets, and it would appear as intended. However, if you wanted it instead to be parsed as html, you would need to use the `unescapeDelimiters`, which by default are three curly brackets, like this:\n\n```html\n\u003cp\u003eThe fox said, {{{ strongStatement }}}\u003c/p\u003e\n```\n\nIn this case, your code would render as html:\n\n```html\n\u003cp\u003eThe fox said, \u003cstrong\u003ewow!\u003cstrong\u003e\u003c/p\u003e\n```\n\n### Expressions\n\nYou are not limited to just directly rendering local variables either, you can include any type of javascript expression and it will be evaluated, with the result rendered. For example:\n\n```html\n\u003cp class=\"{{ env === 'production' ? 'active' : 'hidden' }}\"\u003ein production!\u003c/p\u003e\n```\n\nWith this in mind, it is strongly recommended to limit the number and complexity of expressions that are run directly in your template. You can always move the logic back to your config file and provide a function to the locals object for a smoother and easier result. For example:\n\n```html\n\u003cp class=\"{{ isProduction(env) }}\"\u003ein production!\u003c/p\u003e\n```\n\n```js\nreshape({ plugins: exp() })\n  .process(template)\n  .then((res) =\u003e {\n    return res.output({\n      production: true\n      isProduction: (env) =\u003e {\n        return env === 'production' ? 'active' : 'hidden'\n      }\n    })\n  })\n```\n\n```html\n\u003cp class=\"active\"\u003ein production!\u003c/p\u003e\n```\n\n### Conditional Logic\n\nConditional logic uses normal html tags, and modifies/replaces them with the results of the logic. If there is any chance of a conflict with other custom tag names, you are welcome to change the tag names this plugin looks for in the options. For example, given the following template:\n\n```html\n\u003cif condition=\"foo === 'bar'\"\u003e\n  \u003cp\u003eFoo really is bar! Revolutionary!\u003c/p\u003e\n\u003c/if\u003e\n\u003celseif condition=\"foo === 'wow'\"\u003e\n  \u003cp\u003eFoo is wow, oh man.\u003c/p\u003e\n\u003c/elseif\u003e\n\u003celse\u003e\n  \u003cp\u003eFoo is probably just foo in the end.\u003c/p\u003e\n\u003c/else\u003e\n```\n\nAnd the following config:\n\n```js\nreshape({ plugins: exp() })\n  .process(template)\n  .then((res) =\u003e res.output({ foo: 'foo' }))\n```\n\nYour result would be only this:\n\n```html\n\u003cp\u003eFoo is probably just foo in the end.\u003c/p\u003e\n```\n\nAnything in the `condition` attribute is evaluated directly as an expression.\n\nIt should be noted that this is slightly cleaner-looking if you are using the [SugarML parser](https://github.com/reshape/sugarml). But then again so is every other part of html.\n\n```sml\nif(condition=\"foo === 'bar'\")\n  p Foo really is bar! Revolutionary!\nelseif(condition=\"foo === 'wow'\")\n  p Foo is wow, oh man.\nelse\n  p Foo is probably just foo in the end.\n```\n\n### Loops\n\nYou can use the `each` tag to build loops. It works with both arrays and objects. For example:\n\nInput:\n\n```html\n\u003ceach loop=\"item, index of anArray\"\u003e\n  \u003cp\u003e{{ index }}: {{ item }}\u003c/p\u003e\n\u003c/each\u003e\n```\n\nConfig:\n\n```js\nreshape({ plugins: exp() })\n  .process(template)\n  .then((res) =\u003e {\n    return res.output({\n      anArray: ['foo', 'bar'],\n      anObject: { foo: 'bar' }\n    })\n  })\n```\n\nOutput:\n\n```html\n\u003cp\u003e1: foo\u003c/p\u003e\n\u003cp\u003e2: bar\u003c/p\u003e\n```\n\nAnd an example using an object (note that it uses \"in\" rather than \"of\", in the same way that this would be handled with javascript natively):\n\n```html\n\u003ceach loop=\"value, key in anObject\"\u003e\n  \u003cp\u003e{{ key }}: {{ value }}\u003c/p\u003e\n\u003c/each\u003e\n```\n\nOutput:\n\n```html\n\u003cp\u003efoo: bar\u003c/p\u003e\n```\n\nThe value of the `loop` attribute is not a pure expression evaluation, and it does have a tiny and simple custom parser. Essentially, it starts with one or more variable declarations, comma-separated, followed by the word `in`, followed by an expression.\n\nSo this would also be fine:\n\n```html\n\u003ceach loop=\"item in [1,2,3]\"\u003e\n  \u003cp\u003e{{ item }}\u003c/p\u003e\n\u003c/each\u003e\n```\n\nSo you don't need to declare all the available variables (in this case, the index is skipped), and the expression after `in` doesn't need to be a local variable, it can be any expression.\n\n### License \u0026 Contributing\n\n- Licensed under [MIT](LICENSE)\n- See [guidelines for contribution](CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freshape%2Fexpressions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freshape%2Fexpressions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freshape%2Fexpressions/lists"}