Support

Documentation pages for using Creodocs.


  • Manual Entry

Creating a Creodocs Template

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

This page contains a guide for how to create a new document template to appear in your Workshop, hereafter referred to as a Creodocs template, or just template. Creating a template for Creodocs requires three distinct steps:

  1. Writing the LaTeX code that creates the document layout
  2. Defining user inputs and groups in the LaTeX code
  3. Specifying how inputs should be populated by users on Creodocs

This guide will walk through the entire process of creating a basic template. The goal is to introduce you to the process and leave you equipped to create complex templates, such as the default documents available to all users of Creodocs.


Step 1. Creating a LaTeX Document

Creodocs uses LaTeX to define the structure and layout of all documents. It is the compilation (or typesetting) of LaTeX code that gives rise to the PDF documents produced by Creodocs. This makes the underlying LaTeX code the most important part of a Creodocs template. This guide assumes you are familiar with LaTeX and comfortable with using it to create documents. If not, there are a multitude of free guides available on how to use LaTeX, or you can use the Creodocs Template Creation Service to commission a LaTeX template to your specifications.

For the purpose of this guide, let's pretend we are a real estate company with multiple property managers who need to send official letters to tenants notifying them that an inspection of their rental property is due. We first need to create a LaTeX document that lays out the letter and includes company information and the letter body.

Create a file called main.tex in a new folder and add the smallest possible amount of LaTeX code required to generate a document:

\documentclass{letter}

\begin{document}

hello, world

\end{document}

Download the code above

When we compile this with pdflatex we produce the following as a PDF document:

All Creodocs templates must contain a file called main.tex. This is the file that will be compiled, but other .tex files can be present, such as when using \input{} to include LaTeX code in the main template file.

Let's now create the entire letter with everything we need to communicate to tenants. At this point, it's best to write the LaTeX code as if we are just sending one instance of this document by entering fake information throughout. This will help us in the next step when we need to determine which parts of the document will be populated by users on Creodocs. Our final letter might look something like this:

\documentclass{letter}

\usepackage{palatino}

\signature{Terrence Black \\ \textit{Property Manager} \\ Impact Real Estate}
\address{John Smith \\ Apartment 1315 \\ 126 Albert Street \\ Auckland 1010}
\date{}

\begin{document}

\begin{letter}{Impact Real Estate \\ 72 Queen Street \\ Auckland 1010}

\opening{{\Large\textbf{Notice of Inspection}} \\\\ Dear John Smith,}

This letter is to notify you that I will be conducting a routine inspection of your apartment on \textbf{March 15th, between 2pm-5pm}. The previous inspection was carried out on September 18th and as per your tenancy contract, biannual inspections must be carried out to continue your tenancy.

I will be checking for the following:

\begin{enumerate}
	\item{Damage to the property}
	\item{Functionality of smoke detectors}
	\item{Carpet cleanliness}
	\item{Any other maintenance issues}
\end{enumerate}

If you are unavailable on the date listed, please leave a key with the concierge in my name and I will carry out the inspection alone. Please note that I may need to take photographs of any damage found for documentation purposes.

Should you have any questions or concerns, please contact me directly by email at terrence@impactrealestate.nz.

\closing{Yours sincerely,}

\end{letter}
\end{document}

Download the code above

This is what this letter should look like when we compile the code with pdflatex:


Step 2. Defining User Inputs in the LaTeX Document

We made a LaTeX document for the letter we want to send tenants notifying them of upcoming inspections. We have populated it with all the information we expect to send and filled it with dummy data for a fake tenant and property manager. Our next task is to go through the LaTeX code and add special syntax where Creodocs can insert data supplied by users of this template. Each piece of information we want template users to be able to supply is called a variable.

Variables are added inline to our 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. These IDs should be succinct and descriptive of the purpose of each variable. These variable identifiers are not seen by template users.

Let's go through our letter and replace all occurrences of information we want users of the template to enter with Creodocs variable IDs. This will require carefully thinking about all potential users of the template and what their needs might be, now and in the future. The resulting code is seen below with changes in bold:

\documentclass{letter}

\usepackage{palatino}

\signature{[[[SENDERNAME]]] \\ \textit{[[[SENDERJOBTITLE]]]} \\ Impact Real Estate}
\address{[[[TENANTNAME]]] \\ [[[TENANTADDR1]]] \\ [[[TENANTADDR2]]] \\ [[[TENANTADDR3]]]}
\date{}

\begin{document}

\begin{letter}{Impact Real Estate \\ 72 Queen Street \\ Auckland 1010}

\opening{{\Large\textbf{Notice of Inspection}} \\\\ Dear [[[TENANTNAME]]],}

This letter is to notify you that I will be conducting a routine inspection of your apartment on \textbf{[[[INSPECTIONTIME]]]}. The previous inspection was carried out on [[[PREVINSPECTIONTIME]]] and as per your tenancy contract, biannual inspections must be carried out to continue your tenancy.

I will be checking for the following:

\begin{enumerate}
	\item{Damage to the property}
	\item{Functionality of smoke detectors}
	\item{Carpet cleanliness}
	\item{Any other maintenance issues}
\end{enumerate}

[[[EXTRANOTES]]] Please note that I may need to take photographs of any damage found for documentation purposes.

Should you have any questions or concerns, please contact me directly [[[SENDERCONTACTINFO]]].

\closing{Yours sincerely,}

\end{letter}
\end{document}

Download the code above

If we try to compile the new code with pdflatex, we find that it no longer compiles without errors due to the square brackets. If you need to see what it looks like, find and replace [[[ and ]]] with nothing through the template code and it will compile again. This will show you where the Creodocs variable IDs have been added:

You'll notice some information from our first draft has been kept while other information has been made into variables. This is because some information in the template will never change, while other information needs to change each time one of these letters is created. For example, the company address of Impact Real Estate won't change very often so this is safe to hard code, while the tenant's address will change every time. Often times there will be grey areas where information will usually not change, but it could, so it might be useful to make it into a variable. An example of this is the EXTRANOTES variable, where we initially mentioned leaving a key with the concierge if the tenant is not available, but what if the tenant's apartment building doesn't have a concierge? Likewise, while the sender of the letter will usually be a property manager, some property managers may have assistants and the company could have a mixture of managers with Senior Property Manager job titles, so it's best to allow the sender's job title to change.

The same Creodocs variable ID can be used within the LaTeX code multiple times. This is powerful when we need to output the same piece of information in multiple places in the resulting document. An example of this is the TENANTNAME variable which is used at the top of the letter with the tenant's address and for addressing the letter to the tenant with Dear TENANTNAME,.

Looking through our letter again, we can see that the tenant's address is split across 3 variables. What if we need to enter a suburb on a 4th line or we want to write the apartment number inline with the street number so the address only takes up 2 lines? For this, we can use variable multi-groups.

Variable multi-groups allow you to specify that some LaTeX code containing one or more variable IDs can be inserted into the document multiple times. Multi-groups are enclosed in 3 pipe characters (|||) and must contain one or more variable IDs specified as usual within square brackets, e.g. |||[[[TENANTADDR]]]|||. Groups can span multiple lines of LaTeX code and contain any other LaTeX code. If more than one set of data is submitted by a user for a multi-group, all code within the multi-group specification is duplicated one after another prior to document creation.

Let's make it so the users of our template on Creodocs can specify any number of lines for the tenant's address by replacing the 3 tenant address variables with 1 and putting it into a multi-group (change in bold):

\documentclass{letter}

\usepackage{palatino}

\signature{[[[SENDERNAME]]] \\ \textit{[[[SENDERJOBTITLE]]]} \\ Impact Real Estate}
\address{[[[TENANTNAME]]] |||\\ [[[TENANTADDR]]]|||}
\date{}

\begin{document}

\begin{letter}{Impact Real Estate \\ 72 Queen Street \\ Auckland 1010}

\opening{{\Large\textbf{Notice of Inspection}} \\\\ Dear [[[TENANTNAME]]],}

This letter is to notify you that I will be conducting a routine inspection of your apartment on \textbf{[[[INSPECTIONTIME]]]}. The previous inspection was carried out on [[[PREVINSPECTIONTIME]]] and as per your tenancy contract, biannual inspections must be carried out to continue your tenancy.

I will be checking for the following:

\begin{enumerate}
	\item{Damage to the property}
	\item{Functionality of smoke detectors}
	\item{Carpet cleanliness}
	\item{Any other maintenance issues}
\end{enumerate}

[[[EXTRANOTES]]] Please note that I may need to take photographs of any damage found for documentation purposes.

Should you have any questions or concerns, please contact me directly [[[SENDERCONTACTINFO]]].

\closing{Yours sincerely,}

\end{letter}
\end{document}

Download the code above

Notice how the multi-group contains \\ before the variable ID. This is because Creodocs duplicates all code inside the group delimiters and in this case we want each line of the address to be output on a new line, so we need to include the code that will do this inside the group. Creating groups can be tricky as it requires thinking about what will happen to the code you enclose in the group once it is duplicated. For example, in this case we could have naively specified the group as \address{[[[TENANTNAME]]] \\ |||[[[TENANTADDR]]] \\|||} and this would compile fine, but there would always be an extra newline at the end of the tenant's address block which is not what we intended with the design.


Step 3. Defining Template User Interaction on Creodocs

We have now created our LaTeX document and decided which parts of it we will expose on Creodocs for users to populate. All that remains is to describe our document to Creodocs by specifying template, variable and group information in a format that it will understand. This will allow it 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. This definition is done in a creodocs.json file that should be in the same directory as the LaTeX code.

All Creodocs templates must contain a creodocs.json file. This file specifies template information, acts as the key for variables in the LaTeX code and groups variables for display to users on Creodocs. The data within the file is in JSON format.

It's a good idea to familiarise yourself with the JSON format if you haven't come across it before. Broadly, it's a hierarchical format of keys and values that supports named and unnamed lists (or arrays) of information. The creodocs.json file is composed of 3 top-level sections. The first contains information about the whole template, the second defines each variable and the third specifies how variables should be grouped for display on Creodocs. Let's take a look at a basic creodocs.json file with 2 variables and groups:

{
	"template": {
		"name": "Template Name",
		"description": "Template Description",
		"engine": "pdflatex",
		"version": "1.0.0",
		"contact": "email@company.com"
	},
	"variables": {
		"VARNAME": {
			"name": "Variable Name",
			"description": "What does this variable do in the document?",
			"type": "string",
			"max_length": 50,
			"demo_value": "VARNAME",
			"default_value": "Testing",
			"required": true
		},
		"NUMBER": {
			"name": "Number Variable",
			"description": "What does this variable do in the document?",
			"type": "integer",
			"max_length": 4,
			"demo_value": "NUMBER",
			"default_value": "100",
			"required": false
		}
	},
	"groups": {
		"Group Name": {
			"variables": [ "VARNAME" ],
			"multi": true,
			"required": true
		},
		"Another Group": 
			"variables": [ "NUMBER" ],
			"multi": false,
			"required": true
		}
	}
}

Download the code above

Within each of the top-level sections, there are one or more levels of keys and values that define the information required to add the template to Creodocs. The first template section contains overall information about the template such as its name and description which will appear in the Workshop, but also what TeX engine should be used to compile it, the current version of the template and who users should contact for changes and support. The variables section contains a list of variables where the keys are the variable IDs used in the LaTeX code. Within each variable ID is information for how users will interact with the variable and includes how it should be displayed (name and description), what kind of data it can take (type), how much data can it take (max_length), do users have to specify it (required) and is there a default value that should be used in different situations (demo_value and default_value). Finally, the groups section combines variables into logical groups so they can be displayed together and specifies whether the variables in each group can be added by users once or many times. For a full description of the structure of this file and all the options available, please refer to the Complete Template Specifications section.

We can now follow the format of the example creodocs.json file and refer to the advanced documentation to create a creodocs.json file for our letter template:

{
	"template": {
		"name": "Notice of Inspection Letter",
		"description": "For notifying tenants of an upcoming property inspection",
		"engine": "pdflatex",
		"version": "1.0.0",
		"contact": "arthur@impactrealestate.nz"
	},
	"variables": {
		"SENDERNAME": {
			"name": "Sender Name",
			"description": "The name of the property manager or the person sending the letter on their behalf.",
			"type": "string",
			"max_length": 100,
			"demo_value": "SENDERNAME",
			"default_value": "",
			"required": true
		},
		"SENDERJOBTITLE": {
			"name": "Sender Job Title",
			"description": "The job title of the person sending the letter.",
			"type": "string",
			"max_length": 50,
			"demo_value": "SENDERJOBTITLE",
			"default_value": "Property Manager",
			"required": true
		},
		"TENANTNAME": {
			"name": "Tenant Name",
			"description": "",
			"type": "string",
			"max_length": 100,
			"demo_value": "TENANTNAME",
			"default_value": "",
			"required": true
		},
		"TENANTADDR": {
			"name": "Tenant Address",
			"description": "The mailing address of the tenant.",
			"type": "string",
			"max_length": 100,
			"demo_value": "TENANTADDR",
			"default_value": "",
			"required": true
		},
		"INSPECTIONTIME": {
			"name": "Inspection Time",
			"description": "The day/time when the inspection will take place.",
			"type": "string",
			"max_length": 100,
			"demo_value": "INSPECTIONTIME",
			"default_value": "",
			"required": true
		},
		"PREVINSPECTIONTIME": {
			"name": "Previous Inspection Date",
			"description": "The date of the last inspection of the property.",
			"type": "string",
			"max_length": 50,
			"demo_value": "PREVINSPECTIONTIME",
			"default_value": "",
			"required": true
		},
		"EXTRANOTES": {
			"name": "Extra Notes",
			"description": "Any other notes or requirements for the inspection, such as where to leave the key if the tenant isn't home.",
			"type": "string",
			"max_length": 500,
			"demo_value": "EXTRANOTES",
			"default_value": "If you are unavailable on the date listed, please leave a key with the concierge in my name and I will carry out the inspection alone.",
			"required": false
		},
		"SENDERCONTACTINFO": {
			"name": "Sender Contact Information",
			"description": "How the tenant should contact you with questions or concerns. Should start with 'by ...' or 'on ...' as the text in the letter prior to this is 'please contact me directly '.",
			"type": "string",
			"max_length": 200,
			"demo_value": "SENDERCONTACTINFO",
			"default_value": "",
			"required": true
		}
	},
	"groups": {
		"Sender Information": {
			"variables": [ "SENDERNAME", "SENDERJOBTITLE", "SENDERCONTACTINFO" ],
			"multi": false,
			"required": true
		},
		"Tenant Name": {
			"variables": [ "TENANTNAME" ],
			"multi": false,
			"required": true
		},
		"Tenant Address": {
			"variables": [ "TENANTADDR" ],
			"multi": true,
			"required": true
		},
		"Inspection Information": {
			"variables": [ "INSPECTIONTIME", "PREVINSPECTIONTIME", "EXTRANOTES" ],
			"multi": false,
			"required": true
		}
	}
}

Download the code above

Let's step through the three sections of the completed creodocs.json file as there are multiple nuances to note.

The template section contains the template name and description as they will be shown on the Workshop page. We have written our LaTeX code to be compiled with pdflatex so this is the specified engine, but if we needed to use a custom font then xelatex would be a better choice. The version of the template can be specified in any format, but it is advised to stick to the semantic X.Y.Z versioning system where X is iterated for major changes, Y for minor changes and Z for bug fixes, e.g. 1.5.12. Finally, we list a fictional Arthur at Impact Real Estate and the contact person if there are any issues with the template.

In the variables section, all of the variable IDs in the LaTeX code must be defined. The order of the variable IDs doesn't matter, that is, it doesn't need to correspond to the order they appear in the LaTeX code. For each variable, we first have a name attribute for the friendly name to be displayed to users on Creodocs. The description provides further explanation of the variable's function to users. The type of content variables can accept from users is specified in the type attribute. In our example, all variables have a value of string, which means they can hold any text content. Alternative options include integer (whole numbers), float (numbers with decimals or whole numbers) and boolean (true or false). The max_length attribute specifies the maximum number of individual letters, numbers or symbols a user can enter for the variable. This is a difficult specification to get right, since you need to set it large enough to refrain from restricting users unnecessarily, but small enough that the location of the variable in the document can accommodate the maximum number of characters. The demo_value is used for making sure the template works and these values are used in the preview image for the template. A few of the variables have a default_value, which is automatically populated in the manual entry form. Users still have the option to modify these, but the idea is that the default value represents the most common value the variable will contain. Finally, whether variables are required is also an important attribute. Optional variables can be left blank by users and the document will be produced without them, but variables marked as required must have content entered. In our case, most of our variables are required because they represent pieces of information that are needed in the letter for it to make sense.

In the groups section, group names each contain a number of key-value pairs with variable IDs specified as a list under a variables attribute. Each variable ID must be present in only one group. The group names will be displayed to users, so they should be clear and concise. The order in which they appear will be their order on Creodocs. The idea is to group variables in a logical fashion so like is with like. For example, in our letter, we have 3 variables related to the person sending the letter: sender name, sender job title and sender contact information. These are logically grouped into the Sender Information group to be displayed together. The multi attribute specifies whether the variables in the group can be added multiple times by template users. If multi is true, all variables in the group must be in the same variable multi-group in the LaTeX code (i.e. enclosed in |||). In our letter, only the TENANTADDR variable ID can be entered multiple times for each line of the tenant's address, so it must be in its own group in the groups specification. Finally, the required attribute allows overriding the required attribute of individual variables in the group. If required is false for the group, all variables can have no content submitted for them by the template user, even if they are required individually. However, if any variable does have content submitted for it, then the normal per-variable required values will apply.


Closing Remarks

We have finished making our template! All that remains is to package the two files we have created into a zip file so they can be uploaded to Creodocs together. For convenience, you can download this file here:

Download Template

All Creodocs templates must be uploaded as zip files containing at minimum a main.tex file and a creodocs.json file. Other files can be included if needed, such as additional .tex files, images or fonts.

Hopefully you are now equipped to create your own templates. When doing so, it is recommended that you refer to the Complete Template Specifications section for additional information and options, as this guide intentionally glossed over details in favour of simplicity.

The next step is to add our template to Creodocs which is covered in the Adding a Template section.