★ Templates for Beginners Part 1: Foundations

Templates are added to accounts so that users can create various documents for their events - proposals, contracts, event orders, etc. The template is a standard format that fills out the document by pulling in specific pieces of information from the event's details. We use two tools to do this:

• Froala, a rich text editor which allows you to format the document
• Handlebars, a markup language through which you'll specify the data to pull into the document

These templates are created by us; users have no access to create or edit these. Templates are specific to accounts, although you can copy/paste them from account to account without any issues.

Note: Templates create documents. Insights is for reports. We can have report templates; those are just reports that can be copied easily to an account. We try to refer to those as report templates so we don't get them confused with the document templates.

To get to an account's templates, ebaccess into the support app, open the account's slider and click Manage Templates. This will take you to the account's template page.

Each type of document has its own section. This tells you two things:

• Where the template will appear in the program. Anything built in the proposals section will be on the proposal slider, contracts are on the contracts slider, event summaries are on the documents tab, etc.
• What data set you'll be able to use to create your template. Let's discuss this more below.

Template Models

When users add event data to the application, that is all stored in the database. But just because we have the information stored in the database doesn't mean that we can pull it into a template. Each field has to be coded individually, so we got the ones we knew we needed done first and are adding others as requested with each release. We created different Template Models for different document types, each (hopefully) having the data fields or properties you need for those document types. 

The template models are:

• TemplateAgreementModel: Proposals, Contracts, Addendums, Estimates, Event Summaries
• TemplateEventOrderModel: Event Orders
• TemplateInvoiceModel: Invoices
• TemplateExhibitorOrderModel: Exhibitor Invoices, Exhibitor Service Orders

OMG WHY CAN'T THEY ALL BE THE SAME?!? Different documents have different needs, such as Event Orders and the 50,000 different ways the information can be grouped. As much as possible, we're keeping like with like but not so much that the options are overwhelming.

Once again, a template model is just a collection of data fields (or properties) that is specific to document types. The template model is tied to the document type -- you can't choose it. But it helps to know what it is, since the properties can be different from model to model. You'll also be using models within the main document template models. They are collections of properties within the template models, such as the Account model (which has account name, address, website, etc) or the Event model (event name, dates, booked spaces, etc). You'll see these smaller models in various template models as well as inside other models. I was originally going to say these are a Russian nesting doll of models, but it's more like they're a venn diagram or a mind map - these models are created and then referenced wherever it makes sense, so wherever you see the TemplateEventModel pop up, you'll know it's the same TemplateEventModel you've seen other places.

Creating a Template

To create a template - the document itself -  click the plus. Name it, click Create. Boom, you've created a template.

Editing a Template

When you create a template, the template will be opened in the Froala editor (if you'd like to edit an existing template, just click on the name and select Edit in the dropdown). We're not going to go in depth about formatting documents in this article - the rich text editor is mostly self-explanatory, and maybe we can create a tips and tricks article in the future. We're going to focus on the Handlebars side of templates, as that can be the most difficult to learn.

Handlebars is a markup language for creating templates. If you have any experience with HTML or XML, you have experience with markup languages. Or if you remember math class and how you used parenthesis to specify the order of operations, you also have an idea of how markup languages work. One difference is that there are certain expressions in Handlebars which you won't need to close -- more on that later. If you'd like to dig into the Handlebars documentation directly, their website is here.

Click on the body of the template. In the sidebar you'll see a cheat sheet for Handlebars:

At the top you'll see the template model for the document you're working on (this is a proposal). Under that, we've listed the data you have available to you in this model. The helper above is useful as you're editing your template, as it's dynamic and will react as you type.

You can also click the question mark in the upper right of the slider and select Model Docs. This shows you the same information initially, but you're able to click on each model and see what's in it. Very useful if you're trying to track down a specific bit of information.

In both helpers, each item is has purple text which tells you what type of item it is. Understanding that purple text is a key to using Handlebars. The purple text falls into two categories -- fields or collections of fields.

Fields

• String: Your basic piece of data.
• Boolean: This is a yes or no thing, such as HasScheduledPayments or IsTaxExempt. You can use these like a field and display a yes or no, but they're more often used in if  statements to hide parts of the document if certain information isn't present (such as listing the scheduled payments if there are any entered). We'll cover the fun of if in part three.
• TemplateMoneyModel: TemplateMoneyModel is just a single field, but the system has to go fetch the account currency in order to display it properly. Because of this, you'll need to add the money helper when you use these. More on how you do that and in part two. 
  • Why is this called a model? Because it has two sub-properties: the amount and the currency.
• LocalDate, LocalTime, LocalDateTime: These are all fields which display the various dates and times in the system. These will require using the date or time helpers, and you can also add information to tell the system how you would like your dates/times to be formatted (more in part 2).
  
  • OptionalDateTimeModel - be aware of this one, but it is a bit of a special snowflake. Don't use this if at all possible.
• Int32: These are numbers, no decimals, just whole numbers. Examples are the probability of close and attendance.
• Decimal: These are numbers that could have decimal places, so to get the right number of decimals you'll be using the number helper.
  
• Instant: These are point-in-time dates, such as when an event order is created. You really shouldn't see these - the devs usually convert them into one of the Date/Time fields.

Collections of Fields

We could just create one big massive list of fields, but that would get out of hand really quickly. Instead, we've created collections of fields that can then be stuck inside other collections wherever needed. There's two different kinds - a model and a model list.

• Template[Whatever]Model: This is a collection of data fields that is specific to one area of the event. So TemplateAccountModel is a collection of data fields about the event account: Name, address, zip, website, etc.
• Template[Whatever]Model List: Just like a regular model, this is a collection of data fields. But in these cases, there could be more than one of [Whatever] and so we need to list the information for each [Whatever]. So the TemplateFunctionModel List, gives you all the possible fields for a function and then will list those fields for each function on the event.

Enough background! Let's start building templates. On to part 2 -->