Document Template Basics

A Document Template is simply a text document which contains placeholders for data. When a user generates a document for a Draft or Project using the Document Template the data from that particular Draft or Project is injected into the template.

For example, to insert the name of the Draft into a template we might have a template:

Draft Name : {{ draft.DraftName }}

When this Template is run against a Draft called "Draft 1" we will get the content:

Draft Name : Draft 1

The {{ and }} denote the start and end of placeholders and the draft.DraftName within tells the system that we want the value of the DraftName attribute of the draft object.

The draft object has many more attributes than DraftName (see the Object Model Reference). As an example we might want to list all the Forms in the Draft.

Draft Name : {{ draft.DraftName }}

Forms
=====
{% for form in draft.als_forms_set.all() %}
{{ form.OID }}
{% endfor %}

In this example we loop through all the forms defined in the Draft and insert their OIDs into the generated document. If Draft1 contained 3 Forms "FORMA","FORMB" and "FORMC" we would see:

Draft Name : Draft1

Forms
=====
FORMA
FORMB
FORMC

TrialGrid uses the Jinja2 template system. The Document Template examples show usage of the Jinaj2 template system but do not provide a tutorial on the syntax itself. The Jinja2 website offers excellent reference material to learn the syntax.

TrialGrid also uses the Django Query system which allows collections of objects in the Draft to be queried. In our example we showed the collection of Forms being listed but it is also possible to filter collections (e.g. to just active Forms) and to order them by some attribute (e.g. by OID or by Ordinal). A tutorial on the Django Query system is also beyond the scope of the TrialGrid documentation.

The Django project maintains a reference on Querying.

Template Scope

Document templates have a Scope which determines where the document template can be accessed and what data it receives.

Templates with a Draft Home scope can be accessed from the Draft Home Page. They receive a draft object which represents the Draft the template is being generated for.

Draft Name : {{ draft.DraftName }}

Forms
=====
{% for form in draft.als_forms_set.all() %}
{{ form.OID }}
{% endfor %}

Templates with a Project Home scope can be accessed from the Project Home Page. They receive a project object which represents the Project the template is being generated for.

Example:

Project Name : {{ project.ProjectName }}

Drafts
======
{% for draft in project.als_crfdraft_set.all() %}
{{ draft.DraftName }}
{% endfor %}

Templates with a Project Tickets scope can be accessed from the Project Tickets Page. They receive a project object which represents the Project the template is being generated for as well as the page of the tickets listing they are being run on (open, closed, all) and any filters or search active:

Example:

Project Name : {{ project.ProjectName }}

Ticket Page: {{ ticket_page.title() }}

Active Search: {{ search_text or 'None' }}
Label Filter : {{ " ,".join(filter_labels) or 'None' }}
Assignments Filter : {{ filter_assignments }} {# All, Unassigned, Assigned to me #}

Tickets
=======
{% for ticket in project.ticket_set.filter(id__in=filtered_ids).order_by('iid') %}
{{ticket.iid}} : {{ ticket.title }}
{% endfor %}

Turning Text Content into other Formats (Word, PDF, Excel etc)

Templates that are set to be of type "Word" must have content that conforms to the TrialGrid Ltd DocXMarkup format. The template text is generated and the resulting expanded text is then processed again by DocXMarkup into a Word format document which can be downloaded by the user. See the section on Generating Word Documents for more information.

Templates that are set to be of type "PDF" must have content that conforms to the ReportLab Markup (RML) format. Similarly to the Word process, generating of PDF output is a two-step process that first expands the text template and then takes the expanded template and processes it to produce PDF output. See the section on Generating PDF Documents for more information.

Templates that are set to be of type "Excel 2003/2004" must have content that conforms to the Microsoft Excel 2003/2004 format. See the section on Generating Excel Documents for more information.

Plain text templates can be useful for generating output for system integration. Text format templates can be used to generate tab-delimited or Comma-separated values files and XML files.

Security and Performance

The draft object is the entrypoint into the TrialGrid object model. From a Draft you can move up the hierarchy into the Project and from the Project up to the URL. However, you cannot use this system to investigate other Projects or URL's.

In addition, generating documents may cause a lot of database queries. In order to limit the performance impact of users running very large document generation tasks (hundreds or thousands of pages) a time limit is enforced on how long a report can run.

Setting the name of the generated file

By default the name of the file generated is the same as the name of the Document Template with spaces and characters that are not allowed in file names replaced with underscores (_). It is sometimes convenient to change the name of the generated document to include the name of the Draft or some other value. This can be achieved by setting the name inside the template with {% do SET_FILE_NAME(..) %} The value of the file name can also be retrieved using {{ GET_FILE_NAME() }}

For example, if the name of the Draft is "Draft 1" then:

{% do SET_FILE_NAME(draft.DraftName + ' Test') %}
{{ GET_FILE_NAME() }}

returns:

Draft_1_Test