Support

Documentation pages for using Creodocs.


  • Manual Entry

Complete Template Specifications

  Creodocs offers a paid service called LaTeX Typesetting to create and modify templates for use on Creodocs.

This page contains a complete reference of all requirements and options for creating Creodocs templates. The creation of a template requires you to first implement your document in LaTeX, then to define your document in a creodocs.json file in a way that allows Creodocs to display it and accept user inputs. As such, this page is divided into the following sections:

  1. LaTeX Code Specifications
  2. creodocs.json Specifications
  3. Example Template Downloads

LaTeX Code Specifications

Creodocs uses TeX Live for typesetting templates and the two typesetting engines available are pdflatex and xelatex. There are no restrictions on what you can do in your LaTeX code; in general, if it compiles using TeX Live, it will compile on Creodocs. This means you are free to use packages that are part of TeX Live without including them as files with your template, unless you need a specific version of a package or it is not included with TeX Live. Other inclusions such as images, fonts and additional .tex files are allowed and can be housed in separate directories or alongside the template code.

The template you upload to Creodocs must be packaged as a zip file and must contain a main.tex file at the top (root) level. This is the file that will be compiled by Creodocs but you can include additional LaTeX files from within it using the standard LaTeX \input{} command.

Each location in the LaTeX code where Creodocs users can supply information is called a variable. Variables are added inline to the LaTeX code and have the syntax of [[[VARNAME]]]. The text within the square brackets is the variable identifier (ID) and can only contain upper case letters and numbers with a length of 1 to 30 characters. This is an example of using a variable inside a LaTeX document: Hello world, my name is \textbf{[[[NAME]]]}!. Variables can be used any number of times in the LaTeX code.

By default, variables accept one value from users, but it is sometimes useful to allow one or more variables to accept multiple sets of content, this is called a multi-group. For example, in an invoice document, each invoiced item works well as a multi-group of several variables, one for the date, description, count and rate. Multi-groups are enclosed in 3 pipe characters (|||) in the LaTeX code and must contain one or more variable IDs specified as usual within square brackets, e.g. |||[[[VARNAME]]]|||. Groups can span multiple lines of LaTeX code and contain any other LaTeX code, but they cannot contain other groups. If more than one set of data is submitted by a user for a multi-group, all code and text within the multi-group specification is duplicated for each set prior to typesetting.


creodocs.json Specifications

A creodocs.json file must be included with every template at the top (root) level of the packaged template, alongside the LaTeX code. It is formatted using JSON syntax and describes the template to Creodocs in a standard format. This enables Creodocs to display the template and variables to users in a clean and helpful way, and restrict the types and amounts of information that can be submitted for each variable.

The creodocs.json file must contain template, variables and groups top level sections. You will find each of these described under their corresponding titles below. Please take careful note of the attributes required within each section and the allowed values. The order of attributes within each top level section does not matter in your creodocs.json file. Attributes that are listed as not required in the specifications must be present, but their values can be left blank as empty strings (e.g. "name:" "").

template Specification

This top level section contains information that applies to the entire template.

Attribute Description Required Allowed Values
name The name of the template as it will be displayed to users Yes 1-50 letters, numbers, spaces or any of _-:,./'"
engine The TeX engine to be used for typesetting the template Yes pdflatex or xelatex
version The version of the template, used for keeping track of updates to templates; the recommended syntax is semantic versioning (X.Y.Z; e.g. 1.4.12) Yes 1-10 letters, numbers, spaces or any of _-:.,/()
description A description of the template displayed in the Workshop to provide additional information about the template's purpose to users No 0-250 letters, numbers, spaces or any of _-:,./'"
contact Contact details of the person responsible for the template, typically an email address No 0-50 letters, numbers, spaces or any of @_-:.,/()

Example:

"template": {
	"name": "Company Design Invoice",
	"description": "Use for invoicing clients for design work",
	"engine": "pdflatex",
	"version": "1.0.0",
	"contact": "rob@company.com"
}

variables Specification

This top level section defines each variable ID used in the LaTeX code for display to users of the template and restricts the type and amount of content each variable can take.

Variable IDs

Under the variables top level section should be a list of all variable IDs used in the LaTeX code. Their order does not need to correspond to the order in which they are used in the code. Variable IDs must be 1-30 characters in length and contain only uppercase letters and numbers.

For Each Variable ID

Attribute Description Required Allowed Values
name The name of the variable as it will be displayed to users Yes 1-40 letters, numbers, spaces or any of _-:.,/'
type The type of content the variable can accept from users Yes string, integer, float or boolean
required Whether users must enter content for the variable or if it can be empty Yes true or false
max_length Maximum number of characters that can be submitted for the variable Yes Whole number between 1-5000

A value of >300 will show multi-line input fields in the manual data submission form
demo_value A value to be used for testing the template works and in the image preview of the template Yes (if variable required) Must adhere to type and max_length of the variable

Can be an array of values if variable is in a multi-group (all other variables in the group must have the same number of array elements)
default_value Pre-filled value for the variable, useful when there is an obvious default value No Must adhere to type and max_length of the variable
description Additional information about the variable or usage instructions, displayed in a tooltip to users No 0-50 letters, numbers, spaces or any of _-:.,?/()'";

Example

"variables": {
	"INVITEE": {
		"name": "Invitee Name",
		"description": "",
		"type": "string",
		"demo_value": "John Smith",
		"default_value": "",
		"max_length": 100,
		"required": true
	},
	"GUESTS": {
		"name": "Additional Guests",
		"description": "The number of additional guests the invitee can bring.",
		"type": "integer",
		"demo_value": "1",
		"default_value": "1",
		"max_length": 2,
		"required": false
	}
}

groups Specification

This top level section groups variable IDs in logical categories for display to users. A variable ID cannot be in multiple groups and all variable IDs must be grouped.

Group Names

Under the groups top level section should be a list of all group names to display to users of the template. Their order corresponds to the order in which they will be displayed. Group names must be 1-50 characters in length and contain only letters, numbers, spaces and any of _-:,./'().

For Each Group Name

Attribute Description Required Allowed Values
variables A list of variable IDs that belong in the group Yes One or more variable IDs in a list, each variable ID must be identical to one of the variable IDs present in the variables top level specification; variables will appear in the order they are listed
multi Whether users can submit multiple sets of data for the group's variables Yes true or false
required false if all variables can be submitted empty, even if they are required individually Yes true or false

Example

"groups": {
	"Invitees": {
		"variables": [ "INVITEENAME", "INVITEEPARTNERNAME" ],
		"multi": false,
		"required": true
	},
	"Invitee Address": 
		"variables": [ "ADDRESSLINE" ],
		"multi": true,
		"required": true
	}
}

Example Template Downloads

Download Example creodocs.json

Download Example LaTeX Code

Download Example Complete Creodocs Template