template-guidelines.md

Template guidelines

Content

1. Description
2. Custom templates
3. .json files

1. Description

OS2Display contains templates for screens and slides. These are used to create content for the screens.

Templates should be placed in a bundle that is required by composer. As an example see DefaultTemplateBundle. The bundles should extend Os2DisplayBaseExtension in DependencyInjection/[BUNDLE_NAME]Extension.php, the same as:

class Os2DisplayDefaultTemplateExtension extends Os2DisplayBaseExtension
{
    /**
     * {@inheritdoc}
     */
    public function load(array $configs, ContainerBuilder $container)
    {
        $this->dir = __DIR__;

        parent::load($configs, $container);
    }
}

Templates are located in the Resources/public/templates folder.

To load new templates into OS2Display, run the following command:

bin/console os2display:core:templates:load

2. Custom templates

A template should consist of

1. a .json file that supplies metadata for the template. This contains the path to all the other files the template consists of.
2. an .html file for the live representation of the template (angular).
3. (if necessary) an .html files for preview and editing of the template. These will often be the same file (angular).
4. a .css file for the template.
5. an .png icon for template representation in the administration.
6. a .js file for running the slide in screen (not for screen templates) if special code is necessary.

Naming

It is important that the id in the .json file is unique. Therefore, it should be prefixed with [organization]- . Unique naming is important is in the class names in the templates and css. These should be prefixed with the id of the template.

3. .json files

The .json files are the most important files of the templates since they contain all the metadata for the template. These are the files the os2display:core:templates:load command looks for when adding templates to the system.

See the .json files in the DefaultTemplateBundle folder for examples.

JSON configuration file for Slide templates

The JSON file should contain

{
  "id": "[organization]-[template name]",
  "type": "screen",
  "name": "[display name]",
  "icon": "[relative path to icon.png]",
  "paths": {
    "live": "[relative path to live-template.html]",
    "edit": "[relative path to edit-template.html]",
    "css": "[relative path to live-template.css]"
  },
  "orientation": "[landscape or portrait]",
  "tools": {
    "[tool id]": "[relative path to tool]"
  }
}

JSON configuration file for Screen templates

The .json file should contain

{
  "id": "[organization]-[template name]",
  "type": "slide",
  "name": "[display name]",
  "icon": "[relative path to icon.png]",
  "paths": {
    "live": "[relative path to live-template.html]",
    "edit": "[relative path to edit-template.html]",
    "preview": "[relative path to preview-template.html]",
    "css": "[relative path to live-template.css]"
    "js": "[relative path to the slide script.js]"
  },
  "orientation": "[landscape or portrait]",
  "slide_type": "[type of the slide: base, video, rss, iframe, calendar]",
  "media_type": "[image or video]",
  "script_id": "[the id for the js script]",
  "ideal_dimensions": {
    "width": "1920",
    "height": "1080"
  },
  "empty_options": {
    [default variables for the slide]
  },
  "tools": [
    {
      "name": "[display name for tool]",
      "id": "[tool id]",
      "path": "[relative path to tool]"
    },
    {
      "name": "[display name for tool]",
      "id": "[tool id]",
      "path": "[relative path to tool]"
    }
  ]
}