Imposium-template-engine NPM

Imposium Template Engine

Using the Template Engine

Basic Flow

The flow of a template sequence is as follows. Please see the /example/index.html file for an example of this in action.

If running locally - the template configuration is pulled in via TemplateEngine.setDevConfig. If running on the server, this configuration is passed from the server at runtime.
All fonts specified in the TemplateEngine.webFontConfig object are loaded.
TemplateEngine.initTemplate is called. This is where you should perform all custom logic for this template.
Once all custom logic / functionality triggered by initTemplate is complete, TemplateEngine.render() must be called. This will trigger the render sequence.
Before every frame is rendered, two things happen. if the template is animated, we seek the main GSAP timeline to the proper time, and then TemplateEngine.update() is called. If the template needs to execute any custom functionality on a frame-by-frame basis, it needs to be executed here, inside of a returned Promise() which resolves when the custom functionality is complete.
All frames are rendered in sequence, and once all frames have been rendered - the template exits.

Setting Development Configuration

To configure the template for local development, we use the setDevConfig() method. This can be pre-configured if you downloaded the template as a "Sample Template" from the Imposium Story Editor, in the template layer options.

Below are two examples of this in use. One for configuring the template to run as a single "image" output, and another to run it as an "image_sequence" (animated) template.

Note: This configuration is ONLY used locally - all configuration used during a render is passed in from the server, at runtime.

    TemplateEngine.setDevConfig({
        "type": "image_sequence",
        "frames": 24,
        "frame": 12,
        "fps": 24,
        "width": 600,
        "height": 200,
        "background_color":null,
        "inventory": {
            "first_name": "Fred",
            "last_name": "Peters"
        },
    });


    TemplateEngine.setDevConfig({
        "type": "image",
        "width": 600,
        "height": 200,
        "background_color":null,
        "inventory": {
            "first_name": "Fred",
            "last_name": "Peters"
        },
    });

Loading Fonts

To ensure custom fonts are fully loaded before the template is initialized, pass in their font family names using the syntax below:

    TemplateEngine.webFontConfig = {
        custom: {
            families: ['Font-Family-1', 'Font-Family-2']
        }
    };

Adding Animation

Every animated template includes a main Greensock GSAP timeline. If the template includes any animation, it needs to be added to this main timeline, using the syntax below:

    TemplateEngine.timeline.add(YOUR_GSAP_ANIMATION_HERE);

You can add as many animations as you want, as long as they are all included in the main timeline.

Accessing files from the Asset Library

The Template Engine includes two methods which can be used to pull in assets from the Imposium asset library.

Get asset by ID: TemplateEngine.getAssetById(assetId:string) Using getAssetById() you can pass in any asset ID which is associated with the project the template will be running on. If the asset is found, this function will return the full asset JSON. If no asset is found it will return null.
Get assets from tags: TemplateEngine.getAssetsFromTags(tags:string | string[], type:string (optional)) Using getAssetsFromTags() you can query the asset library using the same tagging mechanism used to pull in assets to layers. Pass in a single tag, or an array of tags, and an array of assets will be returned which match those tags. You can optionally pass in a type such as "video" or "image" to further filter these results. If no assets are found, it will return an empty array.