Enumeration
Enumerations are a powerful feature that lets you create multiple variations of a design from a single row of data. Instead of manually creating dozens of similar rows, you can use enumerations to automatically generate all possible combinations.
What Are Enumerations?
Think of enumerations as a way to multiply your data. When you mark columns as "enumeration columns" and put comma-separated values in those cells, Component.Studio automatically generates every possible combination.
Imagine you're making a deck of playing cards. Instead of creating 52 separate rows (one for each card), you can create just ONE row:
| name | suit | rank |
|---|---|---|
| Card | Hearts,Diamonds,Clubs,Spades | A,2,3,4,5,6,7,8,9,10,J,Q,K |
If you mark suit and rank as enumeration columns, Component.Studio will automatically generate all 52 combinations (4 suits × 13 ranks = 52 cards)!
How to Set Up Enumerations
Add columns to your dataset for each attribute that will vary. These must be string columns (not number columns).
In the dataset toolbar, you'll see an "Enumerations" dropdown. Click it and select which columns should be used for enumeration. You can select multiple columns.
In your enumeration columns, enter values separated by commas. For example: Red,Blue,Green
Component.Studio automatically generates all combinations. Your design will iterate through every combination when you export or print.
How Combinations Work (Cartesian Product)
When you have multiple enumeration columns, Component.Studio creates every possible combination by multiplying them together. This is called a cartesian product.
Let's say you have two enumeration columns:
- color: Red,Blue
- size: Small,Large
This generates 4 combinations (2 colors × 2 sizes):
| Combination | color | size | Enumeration Name |
|---|---|---|---|
| 1 | Red | Small | Card - Red - Small |
| 2 | Red | Large | Card - Red - Large |
| 3 | Blue | Small | Card - Blue - Small |
| 4 | Blue | Large | Card - Blue - Large |
Combinations multiply quickly! If you have 3 columns with 4 values each, you'll get 4 × 4 × 4 = 64 combinations. Make sure you actually need that many variations.
Special Enumeration Variables
When working with enumerated rows, Component.Studio provides special variables you can use in your templates:
If this is the 2nd row in your dataset: 1
For the 5th combination of this row: 4
The 25th card overall: 24
- row.$index - Use when you need to know which original dataset row this came from. Useful for grouping or organizing by source row.
- row.$enumerationIndex - Use when you want to number variations within a single row. Great for creating "variant 1 of 4" type labels.
- row.$globalIndex - Use when you need a unique sequential number across all generated items. Perfect for card numbering (e.g., "Card 1 of 52").
Practical Examples
Example 1: Character Variations
You're making character cards with different outfits and weapons:
| name | outfit (enum) | weapon (enum) | quantity |
|---|---|---|---|
| Warrior | Leather,Plate,Mage Robe | Sword,Axe | 2 |
This generates 6 unique cards (3 outfits × 2 weapons), and each variation will be printed 2 times (quantity = 2), for a total of 12 cards.
In your design, you could use:
Example 2: Multi-Language Cards
Create the same card in multiple languages:
| name | language (enum) | title_en | title_es | title_fr |
|---|---|---|---|---|
| Fireball | en,es,fr | Fire Blast | Explosión de Fuego | Boule de Feu |
In your design, use conditional logic:
Example 3: Difficulty Variants
Create easy, medium, and hard versions of the same card:
| name | difficulty (enum) | points_easy | points_medium | points_hard |
|---|---|---|---|---|
| Dragon | Easy,Medium,Hard | 3 | 5 | 8 |
Use the difficulty value to select the right point value:
Tips and Best Practices
Keep Enumeration Values Simple
Use short, clear values in your enumeration columns. Avoid spaces if possible (use underscores or hyphens instead):
- Good: Red,Blue,Green
- Good: Small,Medium,Large
- Works but less ideal: Light Blue,Dark Blue,Royal Blue
Quantity Works Per Enumeration
The quantity column applies to each enumeration, not the original row. If a row generates 10 enumerations and quantity is 5, you'll get 50 total items (10 × 5).
Use Descriptive Column Names
Name your enumeration columns clearly so you remember what they do. color, suit, size, difficulty are all great choices.
Preview Before Printing
Always preview your enumerated designs before exporting. It's easy to accidentally create more combinations than you intended!
Combine with Dataset Variables
You can use enumeration columns alongside regular columns. Not every column needs to be an enumeration - use them only where you need variations.
Enumerations are recalculated automatically when you change data. For very large datasets (hundreds of rows with many enumerations), you might notice a brief delay while combinations regenerate. This is normal!
Common Questions
Can I use number columns for enumeration?
No. Only string (text) columns can be marked as enumeration columns. If you need to enumerate numbers, create a string column with values like 1,2,3,4,5 and use {{number(row.columnName)}} to convert them to numbers in your templates.
What happens if I leave an enumeration cell empty?
If a cell in an enumeration column is empty, that row will generate just one enumeration (itself), with an empty value for that enumeration column. The empty value will be used in the enumeration name.
Can I have different enumerations for different rows?
Yes! Each row can have different values in the enumeration columns. One row might enumerate colors, while another row enumerates sizes. The enumeration columns apply to all rows, but each row's actual values determine what gets generated.
How do I see all my enumerations?
The dataset editor shows your original rows. To see all generated enumerations, open your design - each enumeration will appear as you page through the cards/components.
Can I change which columns are enumeration columns?
Yes! Just use the Enumerations dropdown in the dataset toolbar to select different columns. All enumerations will automatically regenerate based on your new selection.
Troubleshooting
| Problem | Solution |
|---|---|
| I selected a column but it doesn't show in the Enumerations dropdown | Only string columns can be enumeration columns. Check that your column type is set to "string" not "number". |
| I'm getting way more combinations than expected | Remember: combinations multiply! Check how many values you have in each enumeration column and multiply them together. Reduce values or columns if needed. |
| My enumeration values have leading/trailing spaces | Component.Studio automatically trims spaces from comma-separated values. Red, Blue, Green becomes Red, Blue, Green. |
| Changes to enumeration columns aren't showing up | Enumerations update automatically but there's a short delay (debouncing). Wait a moment and refresh your design view. |
| I want to use a comma in an enumeration value | Currently, commas are always treated as separators. Consider using a different separator in your value (like semicolon or dash). |
Summary
Enumerations are a powerful way to automatically generate variations of your designs. They're perfect for:
- Playing cards (suits, ranks)
- Character variations (outfits, weapons, abilities)
- Multi-language versions
- Difficulty levels
- Color/size combinations
- Any situation where you need multiple similar items
By marking string columns as enumeration columns and entering comma-separated values, you can turn one row into dozens or even hundreds of unique combinations - saving you tons of time and keeping your data clean and organized!