You can drive an After Effects expression with Templater data, and the safest way is to point it at the Source Text of a dynamic text layer. That method works in Templater 2.8.0 and later. The second method, reading values from Templater’s JSON footage layer, is friendlier to write and less reliable to run in a batch.
The reason this matters is that a template is only as flexible as its properties. Text, images and colors change from row to row without any help from expressions. A bar that grows with a number, a counter, a scale or a position that responds to a value in your spreadsheet needs an expression, and an expression needs to read your data. Our documentation gives two routes for that. This article explains both, shows how to choose between them, and spends most of its time on the one detail that trips people up: every value Templater hands you is a String.
Everything arrives as text, so cast it
Templater interprets all of its data as Strings. That includes values that look like numbers. A cell holding 42 reaches your expression as the characters 4 and 2, not as the number forty-two. If you try to do arithmetic on it without converting it first, you will get the wrong result or none. The fix is to cast the String to the type your code needs.
Our documentation names the types you are likely to want: Integer, Float, Array, Boolean and JSON Object. It also lists the functions that do the casting.
- parseInt() casts a String as an Integer.
- parseFloat() casts a String as a Float.
- parseNumber() casts a String as either an Integer or a Float. This method determines which type is needed.
- eval() casts a String as an Object or an Array.
If your expression needs a String, skip the cast and reference the value directly. A caption that just displays someone’s name needs nothing converted.
The choice among those functions comes down to what your data holds. A whole count, such as the number of items, belongs with parseInt(). A decimal, such as a percentage with a fraction in it, belongs with parseFloat(). When a column might hold either, and you would rather not decide row by row, parseNumber() makes that call for you. The eval() function covers structured values, where a cell holds something that should become an Array or an Object. In our view it is the one that deserves the most care, so use it on data you control.
Booleans are on the list of types too, though the documentation’s examples do not include a dedicated function for them. If your expression needs a true or false value, you will be writing a small comparison in your own code, for instance testing whether the String equals a word your data uses for yes. Because the data is text, the comparison is against text.
A scenario: a progress bar driven by a column
Say you are building a video that shows a customer how far they have come toward a goal, and your spreadsheet has a column called progress. Each row is a customer, and the cell holds their number. You want a bar to grow to match it.
The documented steps are short. Map the progress column to a text layer, following the instructions in Mapping Templater Data to Layers. That text layer is now dynamic, and its Source Text changes from row to row. You can leave the layer visible if the number belongs on screen, or design around it. Then reveal the Source Text property of that layer. On the bar you want to animate, open the property you plan to control, add an expression, and use the pickwhip to point at the progress layer’s Source Text. Finally, wrap that reference in parseFloat() or parseNumber(), so the bar sees a number instead of a String.
Now preview. As Templater moves through rows, the text layer updates, the expression reads the new value, casts it and moves the bar. No row-by-row editing happens in After Effects, and the expression never needs to know which row is current. That is the pattern in miniature. Data lands in a layer, an expression reads the layer, and the cast turns text into something you can calculate with.
Why the text layer is the stable choice
The text layer route has a plain advantage: it is built from things After Effects does natively. A dynamic text layer is a text layer. Its Source Text is a standard property. A pickwhip reference to it is the most ordinary expression link there is. Templater maps data into that layer on every job, and your expression reads whatever the layer holds at that moment.
For that reason, as of After Effects 15.1.1 we recommend referencing the Source Text property of dynamic text layers in expression code as the more stable solution. When a batch is running unattended, stable is the quality you want most.
The cost is a little clutter. You need a text layer for every value an expression will read. In a template with a dozen driven properties, that can mean a dozen helper layers. You could keep these layers in a dedicated nested composition or hide them from view, since they only exist to carry data. That housekeeping is cheap compared with a batch that stops to wait for a dialog.
The JSON footage route, and what it costs you
The second method reads values from Templater’s JSON footage layer. In expression code, our documentation describes referencing JSON footage as more user-friendly and more intuitive. Instead of creating helper text layers, you point at a named key, and the keys match your column names. For a template with many values, that is a real saving in effort.
It comes with warnings that deserve to be read in full before you commit to it.
First, this method relies on an After Effects feature that may require manual interaction during batch processes. Our documentation describes mapping data to expressions this way as an experimental feature, supported as such until a future release of After Effects. As of After Effects 15.1.1, a modal dialog requires someone to respond when the source of an imported JSON footage item changes structure. That dialog can interfere with Templater’s batch processes. A batch that stops for a dialog is not a hands-off batch.
Second, previews using this experimental feature do not automatically update within After Effects. The documentation attributes that to a bug in ExtendScript, where After Effects does not detect the file changes to reload the file. Rendering should still work with the correct data imported. In other words, the preview may lag behind what the render will produce. If you are designing by eye against the preview, you may be looking at stale values.
Our documentation points to Adobe’s Uservoice forums for the status of both bugs. That is the honest summary. If your batch runs unattended, the text layer method is the better bet. If you are building something exploratory and sitting at the machine, the JSON route may save you effort.
Setting up the JSON method
If you decide to use it anyway, the steps run like this. In the Templater Preferences dialog, in the Data Source section, enable the Import Templater data as JSON footage preference. With that setting on, Templater automatically creates a JSON file containing the data from a single job and imports it into your project.
Link your data source to your After Effects project, if you have not already. Then use the Transport control buttons in the main Templater panel, in the Transport section, to advance the preview. A file named templater-data.json appears in the project panel. For each job Templater processes, it overwrites templater-data.json with that job’s data.
Two properties of that file shape how you write expressions. The file only ever has one object in its root JSON array, because it holds one job at a time. And every property value in it is a String, because of how After Effects handles changes in imported JSON footage items. So the casting rules from the first section apply here in exactly the same way.
Next, drag templater-data.json from the project panel to the timeline of your target composition to add it as a layer. You can instead add it to a composition nested within your target composition. If you plan to use Templater’s replication feature, apply the Templater Settings effect to the JSON footage layer by going to Effect, then Dataclay, then Templater Settings.
Now reveal the JSON layer’s Data property group, and inside it the dataOutline 0 group. The property keys you see there correspond to the column names in your spreadsheet, or to the property keys in your JSON feed. Edit the expression on the property you want to drive, and use the pickwhip to reference the specific key from the dataOutline 0 group. Add a cast if your code needs a number, an array or an object, and finish the expression.
One practical consequence follows from the key names. Because the keys mirror your column names, renaming a column in the spreadsheet changes the key an expression is looking for. If an expression suddenly stops reading a value after someone tidied up the sheet, check the names first. Our post on what happens when a data column name matches a reserved Templater name covers a related naming trap.
Choosing a method, and knowing when to skip expressions
Put the two methods side by side and the decision is not hard. Use Source Text references when the batch will run on its own, when it will run on a render machine nobody watches, or when you want the preview to stay in step with the data. Use the JSON footage route when you are experimenting, when you have many values to read and the helper layers would be a burden, and when you are prepared to babysit a run. Whichever you choose, cast your values.
Before reaching for either, ask whether an expression is the right tool. Templater does a great deal on its own: it maps data to text, images and colors without any expression. Its dynamic text styling, for example, allows font face and text direction to change based on data. Expressions add power, and they also add something that has to be maintained by a person who understands the code. Two of our own posts look at that trade-off from different sides. Text style expressions in After Effects shows what expressions can do for type. When an After Effects expression is too fragile to maintain says when to stop. If the effect you want can be reached through dynamic Essential Properties, that may be a cleaner path than hand-written code, though you should read that post to see how it fits your template.
Finally, test with a small range of rows that includes awkward cases. A blank cell is worth testing, because an empty value will not cast to a number you meant to use. A value with a stray character will cast badly. Try the longest value, the shortest value, a blank, and a value with a decimal. Previewing a few rows catches these before a full batch does. For checking merged output at specific frames, generating spot checks with Templater is the quickest route. The Templater overview shows how all of these features sit together.
One more habit helps with either method. Keep a short note beside the template that says which layers carry data for expressions and which cast each value. Our documentation tells you to cast a String as a Float, Integer or Array “if necessary”, and the note lets the next person see where that was necessary. Whoever opens the project later will know which text layers or JSON keys feed which expressions, and they will not delete a helper layer that looks unused.
The bottom line
Every Templater value is a String, so cast it before you calculate with it. Prefer referencing the Source Text of a dynamic text layer, because it is the more stable method in a batch. Treat the JSON footage route as experimental, since it can stop a batch for a dialog and its preview may not refresh. And ask first whether Templater can do the job without an expression at all.
Below are the questions we get most often about this topic.
Frequently Asked Questions
Which Templater version do I need to use data in expressions?
Templater 2.8.0 or later. From that version you can use data in expressions by referencing the Source Text property of a dynamic text layer, or any data parameter from Templater’s JSON footage layer. Our documentation recommends the Source Text approach as the more stable one as of After Effects 15.1.1, so start there unless you have a reason to read the JSON footage instead.
Why does my number behave like text in an expression?
All Templater data are interpreted as Strings, including values that look like numbers. A cell holding 42 reaches the expression as text. Cast it first. Use parseInt() for a whole number, parseFloat() for a decimal, or parseNumber() when the value could be either and you want the function to decide. Use eval() to turn a String into an Object or Array.
Which method is better for an unattended batch?
Referencing the Source Text of a dynamic text layer. The JSON footage method relies on an After Effects feature that may need manual interaction during batch processes. As of After Effects 15.1.1, a dialog appears when the imported JSON footage changes structure, and it can interfere with Templater’s batch processing. The text layer route avoids that, which is why we recommend it for stability.
Why does my preview not update when I use the JSON footage method?
Our documentation attributes it to a bug in ExtendScript, where After Effects does not detect the file changes and reload the file. Previews that use this experimental feature do not update automatically. Rendering should still work with the correct data imported, so judge the final output from a render or spot check and not only from the preview.
How do I turn on the JSON footage method?
Open Templater Preferences and, in the Data Source section, enable Import Templater data as JSON footage. Templater then creates a JSON file with the data from a single job and imports it. Advance the preview with the Transport buttons and a file named templater-data.json appears in the project panel. Drag it to your target composition and pickwhip the keys inside its dataOutline 0 group.
What is in templater-data.json?
One job’s data. The file’s root JSON array only ever holds one object, and Templater overwrites it with each processed job. The property keys correspond to your spreadsheet column names or to the keys in your JSON feed. Every value in the file is a String, so the same casting rules apply as with a text layer’s Source Text.
Do I need the Templater Settings effect on the JSON layer?
Only if you plan to use Templater’s replication feature. In that case apply the Templater Settings effect to the JSON footage layer, found under Effect, then Dataclay, then Templater Settings. Our documentation ties that step to replication only.
