View source for Twig2

{{WIP}}
{{TracCloudGuideTabs}}
<div class="tcWidgetPage">
<div class="categoryDynamic">
{{TracCloudGuideProfileTOC}}
</div>
<div class="pageTitle">TracCloud Twig Guide</div>

Many text fields throughout TracCloud support Twig and HTML, giving you greater control in determining what data is displayed to your students, staff, and faculty based on the context of appointments, visits, and more, as well as formatting that data to be as clear as possible.<br><br>

<b>Twig</b> will be the primary focus of this article. Twig is a template engine that serves two primary purposes in TracCloud:

* <b>1. Print variables in text</b>
::Personalize your emails and messages. Greet the student by name, let them know what subject they selected in their appointment, what time their appointment takes place, the location, and more. These same variables are also used for purpose #2.<br>

* <b>2. Add logic to your text</b>
::Modify the email or message based on why it was sent. Add an extra paragraph if Reason X was selected, send a follow-up email after a visit if the student chose Y, prevent an email from being sent on a SAGE referral if Z recommendation was checked, and much more. Rather than creating a generic email for any context, create a dynamic email that changes to match your needs.<br><br>

Twig (and HTML) are supported in [[TracCloudGuideProfilePrefsEmails|profile emails]], [[TracCloud:_Welcome_Messages|welcome messages]], [[TracCloud:_Email_Templates|email templates]], [[TracCloudGuideProfilePrefsScheduleDisplay|appointment display]], and more. Most of the examples listed in this article are for appointment emails or SAGE referrals, but the same concepts apply in all other supported fields. It's also worth keeping in mind that Twig exists outside of TracCloud, and there are many resources online for how you can utilize it that will also work here (such as [https://twig.symfony.com/doc/3.x/ Symfony]). This guide likely covers everything you will need, but it doesn't cover everything that Twig is capable of.<br><br>

<b>HTML</b> will also be used sparingly throughout this article, but without much explanation as it's more ubiquitous than Twig. There are many excellent resources online explaining how to use this markup language, such as [https://www.w3schools.com/html/html_styles.asp W3Schools]. HTML is used to adjust font sizes and colors, embed images and videos, and more.

==Part 1. Syntax, Terminology, and Essential Knowledge==
When reading the wiki or talking to support, you will often see fields like <i>Student.First_Name</i> or <i>Courses.Subject</i> referred to as "Twig tags." To use another term, these are <b>variables</b>. They contain data, it's up to you what you do with that data through Twig. If you're at all familiar with any programming languages, then you likely already know the concepts. This article will provide you with the necessary knowledge to use Twig in TracCloud, regardless of your current knowledge level.

<span style="color:red; font-weight: bold;">Important:</span> [[TracCloud:_Rosetta|A complete list of Twig tags can be found here.]] Not all tags can be used in all places, but you can almost always predict what will and won't work in a given location. For example, in the [[TracCloud:_Emails|Appointment Confirmation Email]], you can expect to use Student, Reason, Subject, Staff tags, etc. Whereas in the [[TracCloud:_Log_Listing_Message,_KIOSK_Notices,_and_Custom_KIOSKs|Notices on KIOSK]], you can only use Center tags. This is because when that message is displayed at the top of an idle kiosk, nothing ties that message to any one Student or Staff record, let alone Registrations, Reasons, etc.

Whenever you're using Twig, you'll see different delimiters being used.

::<b><nowiki>{{ something }}</nowiki></b> - You would use this to <b>display</b> (i.e., print or echo) the contents of "something."

::<b><nowiki>{% something %}</nowiki></b> - You would use this to <b>execute</b> something, typically to create conditions (e.g., <i>if</i> statements).

::<b><nowiki>{# something #}</nowiki></b> - This is a comment. Whatever you write between the hashes will not be displayed. These are handy to make notes for yourself or other admins inside emails and messages.

Here's how those would work in practice. If we sent this to a student named "John," they would receive the message on the right. Notice how the conditional text was handled, and that the comment wasn't shown.

<hr style='margin-bottom: 0px;'>
<div style='width: 49%; float: left;'>
<syntaxhighlight lang="twig">
Hi {{Student.First_Name}}!

{% if Student.First_Name == 'Jane' %} 
    Your name is Jane.
{% else %}
    Your name is not Jane.
{% endif %}

{# I never said this example would be realistic #}
    </syntaxhighlight>
</div>
<div style='width: 49%; float: right;'>
    <blockquote style="margin-top: 15px;">
    Hi John!

    Your name is not Jane.
    </blockquote>
</div>
<hr>

Now here's a more realistic example.

<hr style='margin-bottom: 0px;'>
<div style='width: 49%; float: left;'>
<syntaxhighlight lang="twig">
Hi {{Student.First_Name}},

Your appointment has been scheduled for {{Appointment.StartTime}} on {{Appointment.Day}}, {{Appointment.StartDate}} with {{Consultant.FirstLast}}.

{% if Appointment.Online == 1 %}
    Click here to join your appointment: {{Appointment.OnlineLink}}.</a>
{% endif %}
</syntaxhighlight>
</div>
<div style='width: 49%; float: right;'>
    <blockquote style="margin-top: 15px;">
    Hi John,

    Your appointment has been scheduled for 04:00pm on Thursday, 04/02/26 with Dave Smith.
    </blockquote>
</div>
<hr>

==Part 2. <i>if</i> Statements==

The vast majority of the logic you're likely to build with Twig will be <i>if</i> statements. Simply, "if A, do X." You could also do "if A, do X. Otherwise if B, do Y. Otherwise if C, [...]" and so on. For a realistic example, "if the student selected the reason 'Exam Help,' then include the following paragraph" or "if the appointment is online, include the online meeting link."

An <i>if</i> statement always begins with <nowiki>{% if [...] %}</nowiki> and ends with <nowiki>{% endif %}</nowiki>. When building emails and messages, you will be working with Twig tags (variables) in these statements. So the following... 

<syntaxhighlight lang="twig">
{% if 2 > 1 %}
    two is greater than one!
{% endif %}

{% if 1 == 1 %}
    1 is the same as 1!
{% endif %}

{% if "foo" != "bar" %}
    "foo" is a different word than "bar"!
{% endif %}
</syntaxhighlight>

...functions just like this. [[TracCloud:_Rosetta|Once again, a list of these tags and definitions are available here.]]

<syntaxhighlight lang="twig">
{% if Appointment.Online == 1 %}
    This is an online appointment, click the following to join....
{% endif %}

{% if Reason.ReasonName == "Writing Support" %}
    Please remember to upload your paper to your appointment. Here's how...
{% endif %}
</syntaxhighlight>

You can add <i>else</i> and <i>elseif</i> statements before the <i>endif</i> too, to handle alternate cases easily (rather than multiple separate <i>if...endif</i> statements for every condition).

<syntaxhighlight lang="twig">
{% if Appointment.Online == 1 %}
    Join Virtually: {{Appointment.OnlineLink}}
{% elseif Appointment.Online == 2 %}
    Accessing your Appointment: Login to TracCloud to view your asynchronous appointment.
{% elseif Appointment.Online == 3 %}
    We will call for your phone appointment at your chosen time.
{% else %}
    In-person location: {{Appointment.Location}}
{% else %}
</syntaxhighlight>

To check multiple conditions, <i>and</i> and <i>or</i> statements can be used.

<syntaxhighlight lang="twig">
{% if Reason.ReasonName == "Academic Coaching" and Student.WatchLists.wl_14 == 'true' %}
    Please remember to bring XYZ to this appointment.
{% endif %}

{% if Reason.ReasonName == "Peer Tutoring" or Consultant.CustomData.cf_123 == 'true' %}
    You have booked an appointment with a Peer Tutor!
{% endif %}
</syntaxhighlight>

A list of operators can be found in part 4.

==Part 3. Working with Arrays==

>95% of Twig tags you will work with in TracCloud contain single values, but a very small number of fields are <b>arrays</b> containing multiple values. Most notably, [[TracCloud:_SAGE|SAGE]] reasons & recommendations and Multiple Checkbox [[TracCloud:_Custom_Fields|custom fields]].

As an example, take Student.First_Name. This field can only contain one value at any given time. <i>Student.First_Name</i> = Jane, so <nowiki>{{Student.First_Name}}</nowiki> outputs Jane. But how about the <i>Reasons</i> field in SAGE referrals? This is an array that contains "Poor Grades" and "Acceptable Attendance" and "Lack of Focus." If we try to use <nowiki>{{Reasons}}</nowiki>, we'll get an error. That's where we have to take a slightly different approach, using the <i>for</i> tag.

Here's how this works, with an example variable so you can see what it's working with. For each item in the "exampleField" array, it prints the item (and adds a <nowiki><br></nowiki> tag to insert a line break).

<hr style='margin-bottom: 0px;'>
<div style='width: 49%; float: left;'>
<syntaxhighlight lang="twig">
{% set exampleField = ['a','b','c'] %}
    
{% for item in exampleField %}
    {{item}}<br>
{% endfor %}
</syntaxhighlight>
</div>
<div style='width: 49%; float: right;'>
    <blockquote style="margin-top: 15px;">
    a<br>
    b<br>
    c<br>
    </blockquote>
</div>
<hr>

Now back to our SAGE example. Remember, Reasons is an array that contains ['Poor Grades','Acceptable Attendance','Lack of Focus'].

<hr style='margin-bottom: 0px;'>
<div style='width: 49%; float: left;'>
<syntaxhighlight lang="twig">    
{% for item in Reasons %}
    {{item}}<br>
{% endfor %}
</syntaxhighlight><br>
</div>
<div style='width: 49%; float: right;'>
    <blockquote style="margin-top: 15px;">
    Poor Grades<br>
    Acceptable Attendance<br>
    Lack of Focus<br>
    </blockquote>
</div>
<hr>

You can also check if a value is in an array as an <i>if</i> statement like this. Inversely, you can do <i>not in</i> instead of <i>in</i> to check if a value is not in an array.

<syntaxhighlight lang="twig">
{% if 'Poor Grades' in Reasons %}
    Here are some great resources to improve your study habits...
{% endif %}

{% if "Meet with Advisor" in Recommendations %}
    We recommended that you meet with your advisor, here's how to schedule...
{% endif %}
</syntaxhighlight>

More Twig examples and tag definitions for SAGE emails can be found [[TracCloud:_SAGE|here.]]

==Part 4. Tips and Tricks==

The remainder of this article covers some extra tips and tricks, as well as unique functions that may be of use.

===4.1. Special Tags===

TracCloud has a few special functions listed below that can be used to prevent an email from sending, CC additional recipients, automatically get special values, and more. More of these functions are available specifically for certain modules, such as [[TracCloud:_SAGE|SAGE Early Alerts]], [[TracCloud:_Success_Plans|Success Plans]], and [[TracCloud:_Work_Plans|Work Plans]]. Visit the emails/Twig sections of those articles to learn more. The ones listed below are available throughout TracCloud.

{| class="wikitable"
|-
| <nowiki>{{CalcMissedAppointments(Student.Sequence, Center.ProfileID)}}</nowiki> || The student's total number of missed appointments since the date specified in your profile Scheduling Prefs. Uses System Pref date if Profile date is blank.
|-
| <nowiki>{{CalcMissedDate(Center.ProfileID)}}</nowiki> || Your profile “Calc Missed Appointments Since” date. If this field is blank, this will use your global Calc Missed date instead.
|-
| <nowiki>{{setAdditionalCC('address@domain.edu,address2@domain.edu')}}</nowiki> || CC additional email addresses, can be used with 'if' statements to make the CC conditional.
|-
| <nowiki>{{ GetActiveTermFrom() }}</nowiki> || Can be used to get the start date of your current active term(s).
|-
| <nowiki>{{ GetActiveTermTo() }}</nowiki> || Can be used to get the end date of your current active term(s).
|-
| <nowiki>{{ setResultActions('SendEmail', '0') }}</nowiki> || Can be used to prevent an email from sending, similar to "#ACTION:DO NOT SEND#" in SAGE emails.
|-
| <nowiki>{{ GetDatePlusDays(5) }}</nowiki> || Get the current date plus the number of days specified in parentheses
|-
| <nowiki>{{ GetDateTimePlusDays(5) }}</nowiki> || Get the current date AND time plus the number of days specified in parentheses
|}

===4.2. List of Operators===

Beyond the basics like == (equals) and != (not equals), there are plenty more operators available depending on what you want to accomplish. 

{| class="wikitable"
|-
! Operator !! Description !! True Example
|-
| == || Equals || <nowiki>{% if 1 == 1 %}</nowiki>
|-
| != || Does not equal || <nowiki>{% if 'a' != 'b' %}</nowiki>
|-
| > || Greater than || <nowiki>{% if 2 > 1 %}</nowiki>
|-
| < || Less than || <nowiki>{% if 1 < 2 %}</nowiki>
|-
| in || Is contained by (for arrays) || <nowiki>{% if 'z' in ['a','b','c'] %}</nowiki>
|-
| not in || Is not contained by (for arrays) || <nowiki>{% if 'z' not in ['a','b','c'] %}</nowiki>
|-
| starts with || Begins with || <nowiki>{% if 'abc' starts with 'a' %}</nowiki>
|-
| ends with || Concludes with || <nowiki>{% if 'abc' ends with 'c' %}</nowiki>
|-
|}

===4.3. Filters===

Filters can be used to modify or change the data stored in variables. One of the most common examples is using the 'date' filter to modify the format of dates in emails. For example, <nowiki>{{Appointment.StartDT}}</nowiki> would return 2026-01-31 14:00:00, while <nowiki>{{Appointment.StartDT|date("D, F j, h:ia")}}</nowiki> would return "Sat, January 31, 02:00pm." ([https://www.php.net/manual/en/datetime.format.php click here for a list of datetime format codes]). A list of some of the supported filters and functions in TracCloud can be found below.

{| class="wikitable"
|-
! Filter !! Description !! Example !! Output
|-
| date || Change the format of a date field || <nowiki>{{Appointment.StartDT|date("Y-m-d")}}</nowiki> || 2026-01-31
|-
| lower || Changes contents to lowercase || <nowiki>{{Student.First_Name|lower}}</nowiki> || jane
|-
| upper || Changes contents to uppercase || <nowiki>{{Student.First_Name|lower}}</nowiki> || JANE
|-
| trim || Trim spaces or text from the start and end of a string || <nowiki>{{Student.Cell_Phone|trim(' ')}}</nowiki> || 555-555-5555
|}

===4.4. Indentation===

Twig is not indentation sensitive. Most of the examples in this article use indentation to improve readability, but it will function regardless of it. All three of the examples below will function identically.

<syntaxhighlight lang="twig">    
{% if Appointment.Online == 1 %}
    This is an online appointment!
{% endif %}

{% if Appointment.Online == 1 %}
This is an online appointment!
{% endif %}

{% if Appointment.Online == 1 %}This is an online appointment!{% endif %}
</syntaxhighlight>

===4.5. Streamlining Twig Statements===

If you find yourself writing something like this:

<syntaxhighlight lang="twig">
{% if Reason.ReasonName == 'X' or Reason.ReasonName == 'Y' or Reason.ReasonName == 'Z' %}
</syntaxhighlight>

Try using an array instead. Both will work, but the latter is cleaner and easier to update later.

<syntaxhighlight lang="twig">
{% if Reason.ReasonName in ['X','Y','Z'] %}
</syntaxhighlight>

<hr>

If you're repeatedly checking the same condition, like this:

<syntaxhighlight lang="twig">
Your {% if Appointment.Online == '1' or Appointment.CustomData.cf_123 == 'Hybrid Appt' %} online {% endif %} appointment has been scheduled for... 
Location: {% if Appointment.Online == '1' or Appointment.CustomData.cf_123 == 'Hybrid Appt' %} To join, please click... {% endif %}... 
Appointment policies: {% if Appointment.Online == '1' or Appointment.CustomData.cf_123 == 'Hybrid Appt' %} Please remember to... {% endif %}...
</syntaxhighlight>

Consider setting a variable once and using that instead:

<syntaxhighlight lang="twig">
{% if Appointment.Online == '1' or Appointment.CustomData.cf_123 == 'Hybrid Appt' %}
    {% set online = true %}
{% else %}
    {% set online = false %}
{% endif %}

Your {% if online %} online {% endif %} appointment has been scheduled for... 
Location: {% if online %} To join, please click... {% endif %}... 
Appointment policies: {% if online %} Please remember to... {% endif %}...
</syntaxhighlight>

<hr>

This one is more minor, but in most cases instead of writing this:

<syntaxhighlight lang="twig">
{% if Appointment.Location != '' %}
</syntaxhighlight>

You can write the following. This will return true if that field is not false, blank, or 0.

<syntaxhighlight lang="twig">
{% if Appointment.Location %}
</syntaxhighlight>

==Part 5. Getting Help==

If you're a primary SysAdmin for your TracCloud instance and you need some help with Twig or HTML, feel free to reach out to us. Scroll all the way to the top of this page and click the "Support" tab to visit our helpdesk.

[[Category:TracCloud Manual]]
</div>