Series: Auto-generate Lists of Cards
What is a Series?
Ordinarily, one row in your content generates exactly one card. If you use the #count feature, one row can generate any number of cards, but they will all be perfect copies of each other.Learn more about the #count feature.
Sometimes the cards in a deck are all different, yet follow a regular pattern. For example, in a regular poker deck there are four suits, and within each suit there are 13 ranks, from A to K.
The Series feature allows you to create lists of different cards by listing the differences. A simple 52-card poker deck can be specified with a single row of content and use of the Series syntax, like this:
| Suit | Rank |
| |Heart|Spade|Diamond|Club| | |A|2~10|J|Q|K| |
The rest of this page describes the Series feature in detail.
On This Page
A Series is Multiple Values in One FieldHow to Write a Simple Series
Using Ranges
Multiple Ranges in One Row
Using #count with a Series
Embedding a Series in Another Field
Things You Can't Do with a Simple Series
Escapes
A Series is Multiple Values in One Field
Normally, a single field in your content specifies the value for one item on one card. But if the value is in Series format, it is treated as a list of several values. In the poker deck example above, the value of the Suit column is:
|Heart|Spade|Diamond|Club|
That value specifies four different elements: these are Heart, Spade, Diamond, and Club. If that were the only series in the row, the row would generate four cards: one each for Heart, Spade, Diamond, and Club.
How to Write a Simple Series
A series always goes into a single field on a single row.The value of a field is recognized as a series only if the value both begins and ends with a vertical bar character '|' (which we will call a pipe character). If that's not true, the value will not be interpreted as a series.
Within the value, pipe characters separate elements. When the deck is printed, previewed, or exported, Multideck will expand the row into multiple rows, one for each element in the series, and the value for that field in a row will be that element.
Example: Multideck will treat the row
|Heart|Spade|Diamond|Club| something
...as if it were four rows:
Heart something
Spade something
Diamond something
Club something
An element may be empty, in which case it is treated the same as a normal empty field. In this example, the third element is empty:
Using Ranges
If the elements of a series are a simple progression, you can shorten your series specification by using a range. Here's an example of the Rank field for a standard poker deck, using the range syntax:
|A|2~10|J|Q|K|
The letters for Ace, Jack, Queen, and King don't form a progression, so they have to be listed individually. But the ranks 2 through 10 do form a simple progression. They are specified by putting a ~ (tilde) character between the values for the first and last elements of the progression. So 2~10 is treated as 2|3|4|5|6|7|8|9|10.
A range element currently can't be any more complex than start~end. Use only one tilde, and make sure the start and end values are simple.
The progression can be increasing or decreasing. The expression 10~2 will count down from 10 to 2, instead of counting up from 2 to 10.
The increment is always 1: you can't use a range to specify only odd numbers, for example.
Currently, ranges support decimal integers, and roman numerals in either upper- or lower-case. So for example, the range I~IX expands to I|II|III|IV|V|VI|VII|VIII|IX.
Multiple Series in One Row
A row can contain series in more than one field. In the poker deck example above, there is a series of suits in the Suit column, and a series of ranks in the Rank column.Multideck handles this by expanding the row of the first series (in this case, the Suit) into a row for each element of the Suit series. Next, it expands each of those rows (one each for Heart, Spade, Diamond, and Club) by generating a row for each element of the Rank series. Since there are 4 suits and 13 ranks, the deck generated by this row will have 4 * 13 = 52 cards: a full poker deck from one row.
Using #count with a Series
Normally, the #count column will create the specified number of copies of the row. If you use it in a row with one or more series, it will produce that many copies of the entire series.In the following example, the one-line poker deck has been given a count of 2. The result will be 104 cards: two complete 52-card poker decks.
| Suit | Rank | #count |
| |Heart|Spade|Diamond|Club| | |A|2~10|J|Q|K| | 2 |
Embedding a Series in Another Field
A series won't be recognized by Multideck unless it's the entire value of its field. That means you can't include a series as just part of a field's value. For example, you can't have a field whose value is:Gain one |Wheat|Brick|Stone|. <== This won't work!
But remember that it's possible to include the value of one field in the value of another, by using markup to refer to the other field. Here's a spreadsheet excerpt that will work:
| Goods | Effect |
| |Wheat|Brick|Stone| | Gain one {..Goods}. |
In the above example, the value of the Effect field (which must be a rich text field) refers to the value of the Goods field by including a reference to it: that's the {..Goods} part. The series in the Goods field expands this row to three rows: the first row has only Wheat in its Goods field, the second has Brick, and the third has Stone. In the Effect field, the markup {..Goods} is replaced by the value of the Goods field. So the whole thing expands to:
| Goods | Effect |
| Wheat | Gain one Wheat. |
| Brick | Gain one Brick. |
| Stone | Gain one Stone. |
Learn more about Embedded References to Other Fields in Rich Text Markup.
Another Example The poker deck example we've been using is overly simple. It will work if all you want to show on a card is the rank and suit. But the cards in a real poker deck also have images in the center, and each of those images is unique.
But we can still do it with a bit of cleverness, by using an Image With Markup item and a row like this:
| Suit | Rank | Image |
| |Heart|Spade|Diamond|Club| | |A|2~10|J|Q|K| | {..Rank}-{..Suit}.png |
The new Image field creates an image file name by joining the values of the Rank and Suit fields. For example, the value of the Image field when Rank is "3" and Suit is "Spade" will be:
3-Spade.png
Of course, it's up to you to provide the 52 appropriately-named image files!
Things You Can't Do with a Simple Series
One difficulty with the poker deck example is that a proper poker deck uses colors: red for Hearts and Diamonds, black for Spades and Clubs. The color should apply to the numbers and letters of the rank, in addition to the suit icons. There's no simple way to that with just the Series feature. But it can be done by combining a series with some Styles. This was discussed in a previous page about the Styles feature.Another thing you can't do with just a series is to create a series of cards that differ in more ways than just the series. This can be done by adding in the Rotor feature. You can read more about Rotors in a later page in this section of Help. We recommend reading this section's pages in order, but if you want to jump ahead anyway:
Escapes
In the rare case that you need to use literal pipe or tilde characters in your value, you can do so by preceding them with a backslash character. The value \|1|3|5| will not be treated as a series, because it does not start with a simple pipe character; but the backslash will be removed and will not be part of the value.Similarly, the value |1|3\~5|7| will product the series
1
3~5
7
because the \~ combination will be treated as a literal ~ character, and will not be interpreted as a range.