{"id":22061714,"url":"https://github.com/floofies/cdatemplate","last_synced_at":"2025-03-23T17:27:52.891Z","repository":{"id":135350317,"uuid":"83913546","full_name":"Floofies/cdaTemplate","owner":"Floofies","description":"A JavaScript template engine which uses custom W3C-valid data attributes instead of template syntax.","archived":false,"fork":false,"pushed_at":"2017-10-27T18:50:35.000Z","size":87,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-28T23:28:40.203Z","etag":null,"topics":["data-attribute-html","dom-manipulation","formatter","html-template","inject-data","insert-data","javascript","template-engine","templating-engine"],"latest_commit_sha":null,"homepage":"","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/Floofies.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-04T18:01:15.000Z","updated_at":"2024-04-03T22:34:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"57f5a74e-769c-4480-b3f4-f7b0f5d6b70c","html_url":"https://github.com/Floofies/cdaTemplate","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/Floofies%2FcdaTemplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Floofies%2FcdaTemplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Floofies%2FcdaTemplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Floofies%2FcdaTemplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Floofies","download_url":"https://codeload.github.com/Floofies/cdaTemplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245139180,"owners_count":20567121,"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":["data-attribute-html","dom-manipulation","formatter","html-template","inject-data","insert-data","javascript","template-engine","templating-engine"],"created_at":"2024-11-30T18:14:09.750Z","updated_at":"2025-03-23T17:27:52.862Z","avatar_url":"https://github.com/Floofies.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cdaTemplate\n###### Custom Data Attribute Templating Engine\nThis template engine borrows several concepts from [jquery-template](https://github.com/codepb/jquery-template), and is very functionally similar.\n\n# :books: Documentation\nA template consists of HTML elements with [custom `data` attributes](#paperclip-data-insertion-attributes). The attribute __name__ specifies how the data should be inserted, while the attribute __value__ specifies the object property to track; like so:\n```HTML\n\u003c!-- Inserts a Text Node --\u003e\n\u003cdiv data-content-text=\"myTag\"\u003e\u003c/div\u003e\n\n\u003c!-- Inserts an href attribute --\u003e\n\u003ca data-href=\"myTag\"\u003eThis is a link!\u003c/a\u003e\n```\nYou may load templates from any of the following sources:\n- `\u003cscript\u003e` Nodes.\n- `\u003ctemplate\u003e` Nodes.\n- A \"live\" Node.\n- A remote HTML file.\n\nTemplates are stored in an internal cache for fast re-use. If you make a change to a template and would like to overwrite the cached version, you can use the `overwriteCache` option.\n\n## :clipboard: Examples\n\u003cdetails\u003e\u003csummary\u003eBasic Example 1: In-DOM Template\u003c/summary\u003e\n\nThis example shows usage of an in-document template in a `\u003cscript\u003e` tag.\n##### HTML Document:\n```HTML\n\u003c!-- Template Container Element --\u003e\n\u003cscript id=\"myTemplate\"\u003e\n  \u003cdiv class=\"helloWorld\" data-content-text=\"myTag\"\u003e\u003c/div\u003e\n\u003c/script\u003e\n\n\u003c!-- Destination Element --\u003e\n\u003cdiv id=\"myContainer\"\u003e\u003c/div\u003e\n```\n##### Your Script:\n```JavaScript\n// Initialize an instance of cdaTemplate.\nvar templateLoader = new cdaTemplate();\n\n// Set up the data source.\nvar dataSource = {\n  myTag: \"Hello World!\"\n};\n\n// Load the template.\ntemplateLoader.loadTemplate(\"#myTemplate\", \"#myContainer\", {\n  data: dataSource\n});\n```\n##### The Resulting Destination Element:\n```HTML\n\u003cdiv id=\"myContainer\"\u003e\n  \u003cdiv class=\"helloWorld\"\u003e\n    Hello World!\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eBasic Example 2: Remote File Template with XHR\u003c/summary\u003e\n\nThis example shows usage of a remote template retreived via AJAX.\n##### Remote HTML File Template - myTemplate.html:\n```HTML\n\u003cdiv data-content-text=\"myTag\"\u003e\u003c/div\u003e\n```\n##### HTML Document:\n```HTML\n\u003c!-- Destination Element --\u003e\n\u003cdiv id=\"myContainer\"\u003e\u003c/div\u003e\n```\n##### Your Script:\n```JavaScript\n// Initialize an instance of cdaTemplate.\nvar templateLoader = new cdaTemplate();\n\n// Set up the data source.\nvar dataSource = {\n  myTag: \"Hello World!\"\n};\n\n// Load the template.\ntemplateLoader.loadTemplateXhr(\"myTemplate.html\", \"#myContainer\", {\n  data: dataSource\n});\n```\n##### The Resulting Destination Element:\n```HTML\n\u003cdiv id=\"myContainer\"\u003e\n  \u003cdiv class=\"helloWorld\"\u003e\n    Hello World!\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eBasic Example 3: Custom Data Injector\u003c/summary\u003e\n\nThis example shows a custom data injector which appends a Text Node to an Element's children 5 times.\n##### HTML Document:\n```HTML\n\u003c!-- Template Container Element --\u003e\n\u003cscript id=\"myTemplate\"\u003e\n  \u003cdiv data-append-five-text=\"myTag\"\u003e\u003c/div\u003e\n\u003c/script\u003e\n\n\u003c!-- Destination Element --\u003e\n\u003cdiv id=\"myContainer\"\u003e\u003c/div\u003e\n```\n##### Your Script:\n```JavaScript\n// Initialize an instance of cdaTemplate.\nvar loader = new cdaTemplate();\n\n// Set up the data source.\nvar dataSource = {\n  myTag: \"Hello World!\"\n};\n\n// Add a custom data injector.\n// This one appends `input` into `target` 5 times.\nloader.addInjector(\"append-five-text\", function (input, target) {\n  for (var i = 1; i \u003c= 5; i++) {\n    target.insertAdjacentText(\"beforeend\", input);\n  }\n});\n\n// Load the template.\nloader.loadTemplate(\"#myTemplate\", \"#myContainer\", {\n  data: dataSource\n});\n```\n##### The Resulting Destination Element:\n```HTML\n\u003cdiv id=\"myContainer\"\u003e\n  \u003cdiv\u003e\n    Hello World!\n    Hello World!\n    Hello World!\n    Hello World!\n    Hello World!\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eBasic Example 4: Custom Data Formatter\u003c/summary\u003e\n\nThis example shows a custom data formatter which pre-formats input data prior to it being injected into a template.\n##### HTML Document:\n```HTML\n\u003c!-- Template Container Element --\u003e\n\u003cscript id=\"myTemplate\"\u003e\n  \u003cdiv data-content-text=\"myTag\" data-content-text-format=\"myFormatter\"\u003e\u003c/div\u003e\n\u003c/script\u003e\n\n\u003c!-- Destination Element --\u003e\n\u003cdiv id=\"myContainer\"\u003e\u003c/div\u003e\n```\n##### Your Script:\n```JavaScript\n// Initialize an instance of cdaTemplate.\nvar loader = new cdaTemplate();\n\n// Add a custom data formatter.\n// This one returns `input` with all uppercase letters.\nloader.addFormatter(\"myFormatter\", input =\u003e input.toUpperCase());\n\n// Set up the data source.\nvar dataSource = {\n  myTag: \"Hello World!\"\n};\n\n// Load the template.\nloader.loadTemplate(\"#myTemplate\", \"#myContainer\", {\n  data: dataSource\n});\n```\n##### The Resulting Destination Element:\n```HTML\n\u003cdiv id=\"myContainer\"\u003e\n  \u003cdiv\u003e\n    HELLO WORLD!\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\u003c/details\u003e\n\n## :bulb: Methods\nYou are provided with three interfaces for loading templates: `loadTemplate`, `loadTemplateAsync`, and `loadTemplateXhr`. They can be accessed via the `cdaTemplate` namespace.\n___\n\n### `loadTemplate`\n###### Function\n```JavaScript\ncdaTemplate.loadTemplate( templateSelector , destinationSelector , options );\n```\nClones the contents of the element targeted by `templateSelector`, injects data into the clone, and inserts the clone into any elements targeted by `destinationSelector`. The two parameters must be valid CSS Selectors.\n\nIf multiple elements match `destinationSelector`, you can enable insertion into multiple destinations via the `multiDest` option; otherwise, only the first element matching the Selector will receive the template.\n\n##### Parameters\n\n- **`templateSelector`** String\n\n  A valid CSS Selector or URL targeting the template.\n\n- **`destinationSelector`** String\n\n  A valid CSS Selector targeting one or more destinations.\n\n- **`options`** Object\n\n  Accepts a range of configuration options. See [Options Documentation](#wrench-options)\n\n##### Return Value\n\n- Array\n\n  An Array containing the inserted template(s).\n\n___\n\n### `loadTemplateAsync`\n###### Async Function\n```JavaScript\ncdaTemplate.loadTemplateAsync( templateSelector , destinationSelector , options );\n```\nWraps `loadTemplate` in a Promise.\n\nThis is the same as `async` to `true` in the configuration object.\n\n##### Parameters\n\n- **`templateSelector`** String\n\n  A valid CSS Selector or URL targeting the template.\n\n- **`destinationSelector`** String\n\n  A valid CSS Selector targeting one or more destinations.\n\n- **`options`** Object\n\n  Accepts a range of configuration options. See [Options Documentation](#wrench-options)\n\n##### Return Value\n\n- Promise\n\n  The Promise resolves with an Array containing the inserted template(s).\n___\n\n### `loadTemplateXhr`\n###### Async Function\n```JavaScript\ncdaTemplate.loadTemplateXhr( templateURL , destinationSelector , options );\n```\nRetrieves a clone of the HTML file at `templateURL` via XHR, injects data into it, and inserts the clone into any element(s) targeted by `destinationSelector`; which must be a valid CSS Selector.\n\nThis is the same as setting `isFile` to `true` in the configuration object.\n\n##### Parameters\n\n- **`templateURL`** String\n\n  The URL/URI of the template HTML file.\n\n- **`destinationSelector`** String\n\n  A valid CSS Selector targeting one or more destinations.\n\n- **`options`** Object\n\n  Accepts a range of configuration options. See [Options Documentation](#wrench-options)\n\n##### Return Value\n\n- Promise\n\n  The Promise resolves with an Array containing the inserted template(s).\n\n___\n\n### `addInjector`\n###### Function\n```JavaScript\ncdaTemplate.addInjector( name, callback );\n```\nAdds a custom injector function to the loader.\n\n`name` will match to the name of a Custom Data attribute in the HTML of your template; `callback` will run when that attribute is encountered. The callback must mutate the DOM Node, `target`, directly.\n\n##### Parameters\n\n- **`name`** String\n\n  The name of the injector attribute. (EX: `data-inject-thing` or `inject-thing`). The `data` prefix will be added automatically if it is missing.\n\n- **`callback`** String\n\n  The injector callback. Can mutate `target` directly via the DOM API.\n\n##### Callback Parameters\n\n- **`input`** Mixed\n\n  Data to be injected into `target`.\n\n- **`target`** Node\n\n  The target Node to inject `input` into.\n\n___\n\n### `addFormatter`\n###### Function\n```JavaScript\ncdaTemplate.addFormatter( name, callback );\n```\nAdds a custom formatter function to the loader.\n\n`name` will match to the value of a `data- * -format` attribute in the HTML of your template; `callback` will run, formatting any associated data, when that value is encountered. The callback must return the formatted data, but should not attempt to mutate `value` directly.\n\nFor instance, if you have an injector attribute like `data-content-text` on your template element, and would like to format it, you should add `data-content-text-format` to the element as well, with the value being equal to the `name` of your formatter;\n\nExample Template:\n```HTML\n\u003cdiv data-content-text=\"myTag\" data-content-text-format=\"myFormatter\"\u003e\n```\n\nThis example shows the property `myTag`, associated with `data-content-text`, being run through the formatter `myFormatter` prior to being injected.\n\n##### Parameters\n\n- **`name`** String\n\n  The value of the formatter attribute. (EX: `myFormatter`).\n\n- **`callback`** Function\n\n  The formatter callback. Must return formatted data.\n\n##### Callback Parameters\n\n- **`value`** Mixed\n\n  A value to base new formatted data from. Do not mutate!\n\n___\n## :wrench: Options\nSeveral options are available for use in the `options` object.\n\nOption|DataType|Default|Description\n---|---|---|---\n`async`|Boolean|`false`|If `true`, `loadTemplate` will return a Promise. (Same as running `loadTemplateAsync`)\n`ajax`|Function|Built-In|The XHR function to retrieve remote templates. Must accept a URL as a paremeter, and return a Promise which resolves with the template DOMString.\n`append`|Boolean|`false`|Appends the children of the destination element with the template.\n`afterInsert`|Function|No-Op|The Callback to execute after inserting the template.\n`beforeInsert`|Function|No-Op|The Callback to execute before inserting the template.\n`complete`|Function|No-Op|The Callback to execute after finishing execution. (Non-conditional)\n`data`|Object/Array|`false`|An Object or Array with named properties matching tags in a template.\n`elemPerPage`|Number|`10`|The number of elements to include per-page.\n`error`|Function|No-Op|The Callback to execute if template loading was not successful. Errors output into the destination element if not set.\n`errorMessage`|String|`There was an error loading the template.`|The error message to output into the destination element. (Not used if `error` is set)\n`isFile`|Boolean|`false`|Treats the first parameter of `loadTemplate` as a remote file URI/URL. (Same as running `loadTemplateXhr`)\n`multiDest`|Boolean|`false`|Inserts the templates into multiple elements matching the `destinationSelector`. (Only the first match is used otherwise)\n`overwriteCache`|Boolean|`false`|Forces the template to load from it's original location instead of the cache. (Slower)\n`paged`|Boolean|`false`|Enables pagination of the `data` property if `data` is an Array.\n`pageNo`|Number|`1`|The page number to start at.\n`prepend`|Boolean|`false`|Prepends the children of the destination element with the template.\n`removeAttrs`|Boolean|`true`|Removes `data` attributes from loaded templates.\n`success`|Function|No-Op|The Callback to execute if template loading was successful.\n\n## :paperclip: Data Insertion Attributes\nSeveral one-way data insertion attributes are available for use in templates.\n\nAttribute|Description\n---|---\n`data-alt`|Sets the `alt` attribute of the element.\n`data-class`|Sets the `class` attribute of the element.\n`data-content`|Inserts the data into the element as document nodes.\n`data-content-append`|Appends the data to the element's children as document nodes.\n`data-content-prepend`|Prepends the data to the element's children as document nodes.\n`data-content-text`| Inserts data into the element as a text node.\n`data-content-text-append`| Appends the data to the element's children as a text node.\n`data-content-text-prepend`| Prepends the data to the element's children as a text node.\n`data-for`|Sets the `for` attribute of the element.\n`data-href`|Sets the `href` attribute of the element.\n`data-id`|Sets the `id` attribute of the element.\n`data-link`|Wraps the element's contents an `\u003ca\u003e` tag and sets it's `href` attribute.\n`data-link-wrap`|Wraps the entire element in an `\u003ca\u003e` tag and sets it's `href` attribute.\n`data-style`|Sets the `style` attribute of the element.\n`data-value`|Sets the `value` attribute of the element.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloofies%2Fcdatemplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloofies%2Fcdatemplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloofies%2Fcdatemplate/lists"}