{"id":22800006,"url":"https://github.com/dadi/web-sample-engine","last_synced_at":"2025-03-30T19:17:42.183Z","repository":{"id":151392769,"uuid":"90646517","full_name":"dadi/web-sample-engine","owner":"dadi","description":"A sample interface for a DADI Web template engine","archived":false,"fork":false,"pushed_at":"2019-05-02T07:25:13.000Z","size":70,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-05T21:53:43.248Z","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/dadi.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-08T15:55:55.000Z","updated_at":"2019-05-02T07:25:12.000Z","dependencies_parsed_at":"2023-07-16T12:17:59.942Z","dependency_job_id":null,"html_url":"https://github.com/dadi/web-sample-engine","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/dadi%2Fweb-sample-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fweb-sample-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fweb-sample-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fweb-sample-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dadi","download_url":"https://codeload.github.com/dadi/web-sample-engine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246365644,"owners_count":20765549,"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-12-12T07:10:47.228Z","updated_at":"2025-03-30T19:17:41.285Z","avatar_url":"https://github.com/dadi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://dadi.cloud/assets/products/dadi-web-full.png\" alt=\"DADI Web\" height=\"65\"/\u003e\n\n## Sample engine interface\n\n[![npm (scoped)](https://img.shields.io/npm/v/@dadi/web-sample-engine.svg?maxAge=10800\u0026style=flat-square)](https://www.npmjs.com/package/@dadi/web-sample-engine)\n[![Coverage Status](https://coveralls.io/repos/github/dadi/web-sample-engine/badge.svg?branch=master)](https://coveralls.io/github/dadi/web-sample-engine?branch=master)\n[![Build Status](https://travis-ci.org/dadi/web-sample-engine.svg?branch=master)](https://travis-ci.org/dadi/web-sample-engine)\n[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](http://standardjs.com/)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/semantic-release/semantic-release)\n\nThis repository serves as a starting point to develop a new engine interface for DADI Web.\n\n# API\n\nThis section describes Web's Engine API, listing the properties and functions that engine interfaces are expected to expose.\n\n### Metadata block\n\nAll engine interfaces must have a named export called `metadata`, which gives Web a preliminary round of information about the engine before anything else is loaded. This is important because engine interfaces are initialised *on demand*, which means that a given engine will only be started when/if a template requires it.\n\nThe `metadata` export must be an object with the following properties.\n\n| Property     | Description                                                                      | Required |\n|--------------|----------------------------------------------------------------------------------|----------|\n| `extensions` | An array of file extensions supported by the engine (including the trailing dot) | **✓**    |\n| `handle`     | A string uniquely identifying the template engine                                | **✓**    |\n| `config`     | A config block to be appended to the global schema, as per [convict](https://github.com/mozilla/node-convict)'s format. If the `handle` is  `myEngine` and you add a config parameter of `myProperty`, its value in Web's configuration file should go in `engines.myEngine.myProperty`| **✗**    |\n\n### Main block\n\nThe main export must be a factory function that returns a constructor for the engine. All `require()` calls **must happen inside this function**, so that dependencies are lazy-loaded and only instantiated if/when there is a template requiring this particular engine.\n\n### Constructor\n\nThe engine constructor will be called with an `options` object, containing the following properties.\n\n| Property              | Description                                                                      |\n|-----------------------|----------------------------------------------------------------------------------|\n| `additionalTemplates` | An array of absolute paths to any templates found with an extension supported by this engine that haven't already been loaded due to not having a JSON schema file (i.e. are not pages). This is used by engines that wish to actively load/compile partial templates. |\n| `config`              | A reference to the global configuration object from core                         |\n| `pagesPath`           | The absolute path to the directory containing pages/templates                    |\n| `templates`           | A hash map containing all the templates that have been loaded                    |\n\n### Functions\n\nThe object returned from the constructor should have the following functions in its prototype.\n\n\u003e #### `.finishLoading()`\n\u003e **Arguments:** N/A\n\u003e\n\u003e **Returns:** Function\n\u003e\n\u003e **Required:** ✗\n\nThis method is fired by the core after all pages have been loaded. It can be used by engines to perform clean-up operations or to load additional templates (e.g. partials).\n\n---\n\n\u003e #### `.getCore()`\n\u003e **Arguments:** N/A\n\u003e\n\u003e **Returns:** Function\n\u003e\n\u003e **Required:** ✓\n\nMust return a reference to the core module used by the template engine.\n\n---\n\n\n\u003e #### `.getInfo()`\n\u003e **Arguments:** N/A\n\u003e\n\u003e **Returns:** Object\n\u003e\n\u003e **Required:** ✓\n\nMust return an object containing information about the template engine, such as name and version.\n\n---\n\n\u003e #### `.initialise()`\n\u003e **Arguments:** N/A\n\u003e\n\u003e **Returns:** Promise\n\u003e\n\u003e **Required:** ✓\n\nThis method is called when the core loads a page that requires this particular template engine. Because it can return a Promise, it can do any necessary asynchronous initialisation routines and resolve when finished.\n\n---\n\n\u003e #### `.register()`\n\u003e **Arguments:**\n\u003e - `name`: The name of the template to be registered\n\u003e - `data`: The content (markup) of the template\n\u003e - `path`: The absolute path to the template file\n\u003e\n\u003e **Returns:** Promise\n\u003e\n\u003e **Required:** ✓\n\nThis method is called when the core reads the content of a page template and wishes to register it with the engine. This is a good place to compile templates into functions. It can return a Promise, so the compilation can happen asynchronously.\n\n\n---\n\n\u003e #### `.render()`\n\u003e **Arguments:**\n\u003e - `name`: The name of the template to be rendered\n\u003e - `data`: The content (markup) of the template\n\u003e - `locals`: An object with data to be passed to the template\n\u003e - `options`: A list of options passed by the core. Currently, it only includes a `keepWhitespace` property, which engines may wish to implement, specifying whether or not whitespace in templates should be preserved.\n\u003e\n\u003e **Returns:** Promise\n\u003e\n\u003e **Required:** ✓\n\nThis method is called when a view wishes to render a template as HTML. Depending on how the engine interface is implemented, this could involve a compile step or simply loading a function from a cache. It returns a Promise, so asynchronous operations can be executed.\n\n# Helper functions\n\nA helpers file located in [`lib/helpers.js`](lib/helpers.js) provides a few file manipulation methods that developers might find useful when creating an engine interface. The signature and description for these functions is available in [JSDoc](http://usejsdoc.org/) format alongside the code.\n\n# Unit tests\n\nEngine adapters are responsible for testing their own functionality. This repository includes a test suite powered by [mocha](https://mochajs.org/), including [Sinon](http://sinonjs.org/) for mocking/stubbing and [html-looks-like](https://www.npmjs.com/package/html-looks-like) for easier comparison of HTML output.\n\nTo run the tests, type `npm run test`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadi%2Fweb-sample-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdadi%2Fweb-sample-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadi%2Fweb-sample-engine/lists"}