{"id":17087854,"url":"https://github.com/geraintluff/jstl","last_synced_at":"2025-09-10T20:42:58.952Z","repository":{"id":8192768,"uuid":"9622001","full_name":"geraintluff/jstl","owner":"geraintluff","description":"JavaScript templating","archived":false,"fork":false,"pushed_at":"2013-04-28T21:39:58.000Z","size":130,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-20T11:49:28.703Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geraintluff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-23T11:56:34.000Z","updated_at":"2024-01-04T03:22:19.000Z","dependencies_parsed_at":"2022-08-06T21:15:40.948Z","dependency_job_id":null,"html_url":"https://github.com/geraintluff/jstl","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geraintluff%2Fjstl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geraintluff%2Fjstl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geraintluff%2Fjstl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geraintluff%2Fjstl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geraintluff","download_url":"https://codeload.github.com/geraintluff/jstl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227351573,"owners_count":17768419,"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-10-14T13:35:10.320Z","updated_at":"2024-11-30T14:21:24.828Z","avatar_url":"https://github.com/geraintluff.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jstl - JavaScript as a Templating Language\n\n`jstl` is a templating library for JavaScript, *using* JavaScript.\n\nRather than trying to design a new language, `jstl` allows you to write JavaScript code for the control logic of your templates, while also providing a customisable \"short form\" for variable substitution.\n\n`jstl` takes in a template, and produces a function.  This function **includes JavaScript code from the template**, so it is basically equivalent to `eval()` - **DO NOT RUN TEMPLATES YOU DO NOT TRUST**.\n\nExample code:\n```html\n\u003cdiv class=\"this-user\"\u003e\n    \u003cdiv class=\"name\"\u003e\u003c?jsfullname?\u003e\u003c/div\u003e\n    \u003cdiv class=\"security-status\"\u003e\n        \u003c?js if (window.location.substring(0, 5) == \"https\") { ?\u003e\n        \u003cdiv class=\"security-status-encrypted\"\u003eEncrypted\u003c/div\u003e\n        \u003c?js } else { ?\u003e\n        \u003cdiv class=\"security-status-unencrypted\"\u003eUnencrypted\u003c/div\u003e\n        \u003c?js } ?\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n```\n\nEverywhere `\u003c?js` is used, `\u003c%` can be used instead (and `%\u003e` can be used in place of `?\u003e`).\n\n## *Another* templating library?\n\nYeah, I know there are already quite a few.  But they generally suffer from the following problems:\n\n* **New syntax** - the more complex ones define their own syntax for `if`/`foreach`/etc.\n* **Not customisable** - they give you a set of pre-defined output filters (HTML entities, URI encoding, etc).\n\n`jstl` tries to avoid these, by piggybacking on the JavaScript language while providing a simple base for extending behaviour.\n\n## Writing templates\n\nThere are two different ways to use the special tags in a template.\n\n### 1) Simple substitution:`\u003c?jsvariable?\u003e` or `\u003c%variable%\u003e`\n\nIf there is no space following the `\u003c?js` the block is substituted with a value.  By default, this is taken as a property of the first function argument (HTML-escaped).\n\nExample template:\n```html\n\u003cdiv\u003e\n    \u003c%name%\u003e likes \u003c%food%\u003e.\n\u003c/div\u003e\n```\n\nCalling the function:\n```javascript\nvar obj = {name: \"Everybody\", food: \"chocolate\"};\nvar html = myTemplate(obj);\n```\n\nResult:\n```html\n\u003cdiv\u003e\n    Everybody likes chocolate.\n\u003c/div\u003e\n```\n\n### 2) JavaScript code: `\u003c?js ... ?\u003e` or `\u003c% ... %\u003e`\n\nIf there is whitespace following the opening `\u003c?js`/`\u003c%`, the block is run as JS code.\n\nThe special function `echo()` is defined, which contribues to the output of the function.\n\nExample template:\n```html\n\u003cdiv\u003e\n    Current URI: \u003c?js\n        echo(window.location.toString());\n    ?\u003e\n\u003c/div\u003e\n```\n\nResult:\n```html\n\u003cdiv\u003e\n    Current URI: http://example.com/\n\u003c/div\u003e\n```\n\n## Loading templates\n\nTemplates can be loaded either as strings (`jstl.create(str)`) or they can be loaded from C-style comments in your JS file, assuming that file is accessible via AJAX.\n\nThe syntax for loading from comments is to start your comment `/* Template: \u003cidentifier\u003e` followed by a newline.  To load all templates in a file, call `jstl.loadTemplates()` from that file.\n\nExample:\n```javascript\ntemplate = jstl.create('\u003cdiv\u003e\u003c?jstitle?\u003e\u003c/div\u003e').compile();\n\n/* Template: example-template\n\u003cdiv\u003e\n    \u003c?jstitle?\u003e\n\u003c/div\u003e\n*/\ntemplate2 = jstl.getTemplate('example-template').compile();\n```\n\n## Customising\n\nBehaviour can be modified either by passing arguments into `template.compile()`, or by changing properties in the `jstl` object.\n\n### The \"no spaces\" behaviour\n\nYou can completely customise the behaviour of the \"no spaces\" form.\n\nThe way you do this is by passing in a function to `t.compile()` of the following form:\n```javascript\nt.compile(function (variableName) {\n    return function (arg0, arg1, ...) {\n        ...\n    }\n});\n```\n\nYou might need to look at that twice - you supply a compile-time function which returns a function that is called at render time.\n\nFor example, a simple example might be:\n```javascript\nvar t = jstl.create('Name: \u003c%name%\u003e');\nvar f = t.compile(function (variableName) {\n    return function (value) {\n        return value[variableName].toString();\n    }\n});\n\nvar value = {name: \"Mary\"};\nvar result = f(value); // returns: \"Name: Mary\"\n```\n\nThe default function (that `t.compile()` uses if you don't supply your own) is available at `jstl.defaultFunction`.  It looks very much like the above, except it HTML entity-encodes the output.\n\nYou can change this default by altering `jstl.defaultFunction`.\n\n### \"Header code\"\n\nYou can also provide some JavaScript code to sit at the top of the compiled template.  It's completely equivalent to adding the same code to the top of the template.\n\n```javascript\nvar f = t.compile(null, \"var value = arguments[0];\");\n```\n\nA good use for this might be to alias function arguments (as in the example) - that makes the `value` variable available for use within your templates, so you don't have to pepper your code with `arguments[N]`.\n\nThe default \"header code\" is actually the one from above example - however, you can change this by altering `jstl.defaultHeaderCode`.\n\n## Wait - how does it get the templates from JavaScript comments?\n\n### In-browser\n\nThe secret is that when `jstl.getTemplate()` is called, it calls through to `jstl.loadTemplates()`.  This function figures out what source file is running (it should be the last `\u003cscript\u003e` in the document), fetches it via AJAX and inspects it for comments.\n\nIf for some reason you aren't calling `jstl.getTemplate()` when the script loads (I can't think why you would), then you should call `jstl.loadTemplates()` manually, optionally including the URI of the source file containing templates.\n\n### Using Node\n\nSince the above AJAX trick doesn't work when running server-side, every script containing templates should call `jstl.loadTemplates(__filename)`, so the library can read the file and parse all templates from it.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeraintluff%2Fjstl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeraintluff%2Fjstl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeraintluff%2Fjstl/lists"}