HTML Templates

https://z.explo.org/documents/html_templates

HTML Templates are like the familiar "merge email" concept, but for any kind of document. Think of them as "reusable" documents, for all of the situations where you keep making the same printout or PDF, but changing a few tiny things.

The resulting documents can be used as standalone web pages, attached as PDFs to batch emails, or used for reporting or other purposes.

Overview

Our HTML Templates system uses HTML and CSS, the language of document definition on the web, to define any document we'd like to use elsewhere in the system. If you know HTML/CSS, you can make document templates. If you don't know HTML/CSS, this is as good a time as any to learn!

Inside of the HTML/CSS, you can use the Elixir programming language's EEx templating language to make powerful, dynamic templates. See "Making Your Own Template" below for more information about that.

Here are some example ways that HTML templates can be used:

• Create a permalink URL for a billing statement
• Send out "certificate of completion" emails to all enrolled students, with a PDF certificate attached
• Print out ID badges for students or staff
• Design a "universal" reporting format that can receive data from arbitrary systems or spreadsheets and print them out in the same format.

Making Your Own Template

To make a template, start here. Type or paste your HTML and CSS design into the relevant fields, and double-check in the "live preview" that things are looking like they should.

To reference variable data or perform calculations, you can use any Elixir syntax in your templates. You "wrap" the Elixir code in EEx template tags, like so:

# in Elixir...
iex> 1 + 1
2

# in an HTML template...
<%= 1 + 1 %>
2

Example / Starter Templates

We've created some sample templates to help give a better idea of what's possible. Click each link below to be brought into an HTML template editor with the example pre-loaded:

• Regular HTML and CSS with no variables
• Using variables in HTML
• Using variables in CSS
• Using Elixir conditionals
• Using Elixir String functions
• Using Elixir Date functions
• A more complicated example: Student Photo ID

Resources

We've put together some further reading that may prove helpful.

General Resources

• Learn HTML
• Learn CSS
• For a more classroom-based approach to learning HTML and CSS, you might try Code Academy's Courses.
• More about the Elixir programming language (which you're using right now :)
  • Elixir language syntax reference
  • In addition to plain old Elixir syntax, HTML templates can use the String and Date module functions.
  • The Elixir source documentation is very comprehensive.
• Learn more about EEx templates:
  • The Phoenix Framework template docs
  • The Phoenix Framework view module docs, which uses EEx.

Z System

Here in Z, these are the modules that contain HTML template code and documentation.

• Z.Documents - Information about handling template data.
• Z.Documents.HtmlTemplates - "Business logic" for handling HTML template data and rendering HTML templates.
• ZWeb.Documents.HtmlTemplatesLive - The "human" interface to HTML templates. This is where you see, edit, and preview templates.
• ZSchemas.Documents.HtmlTemplate - The data definition of an HTML template
• Utility.EExSafeEngine - The place where we make sure nobody's trying to inject malicious code into our templates.