CYOA Studio template creation

CYOA Studio uses HTML and CSS packaged into a template to create the final document. This document describes the process of making your own template.

You’ll need:

• HTML/CSS knowledge. This document does not teach the technical know how required, but there are more than enough tutorials on this topic on the internet already.
• CYOA Studio. For testing your template (and of course for using it).
• A zip tool. The final .cyoatemplate file is simply a renamed .zip file. Most modern operating systems ship with the ability to zip files.

Template structure

A template consists of these files:

• page.html.mustache contains the document structure that the sections and options are placed into. If a template doesn’t provide its own page file, a default is provided that should work for most templates.
• style.css.mustache contains the style sheet. This file is mandatory.
• style_option.json describes the customization options and their default values.
• Any number of image files used in the template.

Both the page and style sheet are mustache templates. The page will be provided with the content that should be displayed, and the style sheet with the customization options the user chooses. The values are accessed by a curly brace syntax like ``. For more information see the mustache manual.

You can access the default files in the repository for reference. Feel free to use them as a basis for your template.

page.html.mustache

This template provides the base structure for the document. The default should work for most use cases, but you can provide your own. The following values are provided to the template:

• style contains the content of style.css.mustache after it’s been templated.
• customCss contains the custom CSS provided by the user.
• title.
• section contains a list of all the sections. The sections have the following values:
  • id contains an automatically generated id, which is used to jump to the section. It should be used in an id field of the first element that represents this section.
  • title.
  • description.
  • options contains a list of all the options in the section. The sections have the following values:
    • id contains an automatically generated id, just like the one for sections.
    • title.
    • cost.
    • rollRange.
    • description.
    • image contains the image of the option, to be used as the src attribute of an img tag.

Note that the titles and descriptions contains HTML strings, and as such should be included using the non-escaping triple bracket syntax. The same goes for style and customCss.

All fields of options and sections can be empty. The corresponding parts in the document should not be displayed when these values are empty.

style_options.json

This JSON file describes the options available to the user. It should contain a simple JSON object. Depending on the name of the fields, different values are assumed:

• Ends in Image: An image. The default value has to be the name of an image file included in the template.
• Ends in Color: A color. The default value has to be a valid CSS color.
• Ends in Font: A font-family. The default value has to be the name of the font family.

In the template, images are provided as strings to be used in an url() expression. Colors and fonts are provided as strings to be used in color attributes and font-family, respectively.

If no such file is provided, no options are presented to the user.

style.css.mustache

This file can contain arbitrary CSS to style the document. The options described in the style_options.json file are provided. Use the triple bracket syntax to avoid escaping of control characters.

Sadly, the document is displayed with the slightly outdated version of webkit that JavaFX uses. It supports a lot of modern CSS3 features, but not all of them. CSS grids are not supported, neither are blend modes.

This tool still supports users changing the color of the background image. If a style option ending in Image and one with the same name but ending in ImageColor exist, additionally to the two values the style sheet can also use a value ending in ImageBlended, containing the original image, multiplied with the color. For example, if two options called backgroundImage and backgroundImageColor exist, backgroundImageBlended will contain the background image with the color applied. If you use this option, provide a light, black and white image for best results.

Testing

If you put all the files required for the template, you can load it through the Import template->From folder... option. For development, it might be useful to export the file to HTML and edit that exported file.

Packaging up

Once your template is done, you can zip it together and change the file ending to .cyoastudio. You can then distribute that file if you want.