Conditional Logic & Transforms
Overview
Conditional visibility and text transforms let you create smart cards that show different content based on your spreadsheet data. Instead of building a separate design for every card variant, you design once and let expressions do the work: showing a fire icon only on fire-type cards, displaying a "RARE" badge only on high-rarity cards, or auto-formatting all card names consistently.
There are two complementary systems covered in this guide:
- Conditional Visibility: control whether an element appears on a given card based on a rule evaluated against the current spreadsheet row.
- Text Transforms (Pipes): modify how text values are displayed using pipe syntax inside
{{Column}}templates, without altering the underlying data.
Text transforms use the same {{Column Name}} reference syntax as the rest of Chitmunk's spreadsheet links, and the expressions below use it to name a column. If you haven't linked a spreadsheet yet, read the CSV Data Merge guide first.
Conditional Visibility
Every element in Chitmunk has a Condition section in the inspector, with a rule builder. Leave it empty and the element always appears. Add a rule and the element is shown only when it is true for the current spreadsheet row, and hidden otherwise. Under the hood each rule is an expression such as {{Type}} == 'Spell'; the sections below use that form because it is the exact syntax the engine reads.
To set a condition:
- Select an element on the card.
- In the inspector, open the Condition section and click + Add condition.
- Choose a column, choose a comparison (equals, not equals, greater than, less than, at least, at most, contains, doesn't contain, starts with, ends with, is empty, is not empty), and type the value. Add more rules and choose All of these must match (AND) or Any one of these can match (OR).
- Step through your cards with the Previous card and Next card buttons in the bottom bar. The element will appear and disappear as Chitmunk evaluates your rule against each row's data.
Tip: Elements with Show on every card checked (at the bottom of the Condition section) are never affected by conditions; they always render. Use it for elements that should appear on every card regardless of data, such as the card frame or border.
Comparison Operators
Use these operators to compare a column value against a literal value. String literals should be wrapped in single quotes. Numeric comparisons work without quotes.
| Expression | Meaning |
|---|---|
{{col}} == 'value' |
Equals (string or number) |
{{col}} != 'value' |
Not equals |
{{col}} > 5 |
Greater than (numeric) |
{{col}} < 10 |
Less than (numeric) |
{{col}} >= 5 |
Greater than or equal (numeric) |
{{col}} <= 10 |
Less than or equal (numeric) |
Equals and not equals are case-sensitive, while contains, starts with and ends with ignore capitalization. {{Type}} == 'Spell' does not match a row where the Type column contains spell or SPELL.
String Operators
These operators check for patterns within string values rather than exact matches.
| Expression | Meaning |
|---|---|
{{col}} contains 'fire' |
Column value includes the substring |
{{col}} !contains 'poison' |
Column value does not include the substring |
{{col}} startsWith 'The' |
Column value begins with the string |
{{col}} endsWith 'ing' |
Column value ends with the string |
{{col}} isEmpty |
Column is blank or missing from the row |
{{col}} isNotEmpty |
Column has any non-blank value |
Tip: isEmpty and isNotEmpty are particularly useful for optional columns. If your spreadsheet has a Subtitle column that only some cards use, you can show the subtitle element only when {{Subtitle}} isNotEmpty.
Range Operator
The between operator checks whether a numeric column value falls within an inclusive range. It is a clean alternative to combining two comparison operators.
{{col}} between 5 and 10
This is equivalent to {{col}} >= 5 AND {{col}} <= 10, but easier to read. It is well suited to tier-based styling, for example, showing a gold border only on cards with a Rarity between 4 and 6:
{{Rarity}} between 4 and 6
Boolean Logic
Combine multiple conditions using AND, OR, and NOT. Keywords are case-insensitive (and and AND both work).
| Operator | Example |
|---|---|
| AND | {{Type}} == 'Spell' AND {{Level}} > 3 |
| OR | {{Faction}} == 'Red' OR {{Faction}} == 'Blue' |
| NOT | NOT {{Status}} == 'Banned' |
Use parentheses to control evaluation order when mixing AND and OR:
({{Type}} == 'Spell' OR {{Type}} == 'Trap') AND {{Level}} > 3
Without parentheses, AND binds more tightly than OR, the same precedence rules as most programming languages. When in doubt, add parentheses to make your intent explicit.
Tip: Keep conditions as simple as possible. A boolean chain longer than two or three clauses is hard to debug, especially when you are browsing rows and trying to figure out why an element is or isn't appearing. Consider splitting complex logic across multiple elements with simpler individual conditions.
Text Transforms (Pipes)
Text transforms modify how a column value is displayed without changing your spreadsheet data. Use the pipe character | inside a {{Column}} template to apply a transform:
| Syntax | Output |
|---|---|
{{Name|upper}} |
UPPERCASE |
{{Name|lower}} |
lowercase |
{{Name|capitalize}} |
First letter capitalized ("fire drake" becomes "Fire drake") |
{{Name|trim}} |
Leading and trailing whitespace removed |
{{Name|truncate:20}} |
Cut to 20 characters, with an ellipsis appended if truncated |
Transforms work anywhere you write a {{Column}} reference in text: inside a text box's content or in an AI art prompt.
Transform Chaining
Combine multiple transforms by chaining them with additional pipe characters. Transforms execute left to right, each receiving the output of the previous transform as its input.
{{Name|trim|upper|truncate:15}}
This expression first trims whitespace from the Name value, then converts it to uppercase, then cuts it to 15 characters (adding an ellipsis if it was longer). Order matters when a transform changes what the next one sees: truncating before trimming would count the extra spaces.
Tip: A common pattern is {{Name|trim|capitalize}}; it cleans up inconsistent spacing or capitalization in your spreadsheet without requiring you to re-edit the source data.
Fallback Values
Use the || (double pipe) operator to specify a fallback value that is displayed when a column is empty or missing from a row:
{{Description || 'No description available'}}
If the Description column for the current row is blank, the text No description available is rendered instead. If Description has a value, that value is used normally.
Fallbacks work alongside transforms. The transform is applied to the resolved value, whether that value came from the column or the fallback:
{{Name || 'Unknown'|upper}}
This renders the Name value in uppercase, or UNKNOWN if Name is empty. The |upper transform applies after the fallback is resolved.
Tip: Fallback values are especially useful for optional spreadsheet columns. If some rows have a Subtype column and others don't, use {{Subtype || ''}} to silently output nothing instead of displaying a literal {{Subtype}} placeholder on cards where the column is missing.
Practical Examples
Here are common patterns you can adapt for your own card designs.
Show a fire icon only on fire-type cards:
Set the condition on your fire icon element to: {{Element}} == 'Fire'
Show a "RARE" badge on high-rarity cards:
Set the condition to: {{Rarity}} > 3
Show different art frames by faction:
Create a separate image element for each faction's frame art. Set the condition on the Red frame to {{Faction}} == 'Red', the Blue frame to {{Faction}} == 'Blue', and so on. Only one frame will render per card.
Auto-uppercase all card names:
In your card name text element, use {{Name|upper}} as the text content instead of plain {{Name}}.
Truncate long descriptions to fit a fixed text area:
Use {{Description|truncate:80}} to cap descriptions at 80 characters. You can also turn on Shrink to fit in the text settings to automatically reduce font size instead of truncating, choose whichever fits your design.
Show a special badge only on cards of specific types:
({{Type}} == 'Spell' OR {{Type}} == 'Trap') AND {{Level}} >= 5
Hide an element when an optional column is blank:
{{FlavorText}} isNotEmpty
Tips & Best Practices
- Test as you go. Use the Previous card and Next card buttons in the bottom bar (or PageUp and PageDown) to browse through cards while editing. You will immediately see which rows cause an element to appear or disappear, making it easy to catch mistakes in your expressions.
- Use Show on every card for always-visible content. Decorative borders, the card frame, and any element that should never be hidden should have it checked. Those elements are never evaluated against conditions.
- Keep conditions simple. Complex boolean chains are hard to debug, especially with large spreadsheets. If you find yourself writing a four-clause AND/OR expression, consider whether you can restructure your CSV data (for example, adding a computed column in your spreadsheet) to make the condition simpler.
- Use fallback values for optional columns. If your spreadsheet has columns that only some rows fill in, use
{{Column || ''}}or{{Column || 'default text'}}to prevent placeholder text from appearing on cards where the column is absent. - Transforms do not affect visibility expressions. Conditional visibility uses raw column values for comparisons; pipe transforms are not supported there. Use transforms only inside text content templates.
- Duplicate, don't rebuild. When creating per-faction or per-type variants, duplicate an existing element and change only the condition and the image source. This keeps your element stack organized and avoids re-entering position, size, and style settings.