How it works (in depth)

Insight into the rules that guide how the pack Sync Table works

Note that these rules are mostly here for completeness. Although this info may help better understand of the pack, especially in explaining if its doing something unexpected, it is not necessary to understand how to use the pack.

Column type resolution

When merging tables, the columns from across the tables that are deemed equivalent will be merged together into a single column in the resulting Sync Table. The resulting type of that column is determined from the type of each of the columns in the source tables. The type chosen is the most specific type that covers the types of all the columns to be merged together. In other words, it is the type that is general enough to accommodate the values from each of the columns in the source tables (without losing any information), but is as specific as possible.

The concept of types covering others, more specific or general types is fairly involved. A brief explanation follows.

In Coda, table columns have types, such as Text, or Currency, or Slider. In the menu to set a column type, you can see that some types are under a dropdown. For example, the Slider type is under the Number dropdown. Why is that the case? Under the hood, it’s because a slider is nothing but a number, that is rendered on screen as a draggable slider. But the only information that slider actually encodes or represents is that number. As such, any Slider could be represented simply as that number instead. The Number type is said to be a more general type of the Slider type. Conversely, the Currency type encodes more information than a simple number, as it also includes the selected currency. As such, representing a value of type Currency as simply a number would necessarily lose some information. The Currency type (just like the Slider type, in fact) is said to be a more specific type of the Number type. The Number type is said to cover the Slider and Currency (and all the other Number subtypes) types.

Although there is no official Coda guidance on how each of the types relate, in this pack we build a somewhat opinionated hierarchy of all the column types, that enables resolving column types to a single common type. This hierarchy enables merging tables where their equivalent columns can be seemingly unrelated but still resolve to a sensible resulting type. For example, similar types like Slider and Currency will be resolved to the Number type, whereas more distant types like Currency and Canvas will resolve to the Text type.

Column name normalization

Normalization is the process by which the names of the columns are transformed in order to determine whether they are equivalent. From its Wikipedia article,

Text normalization⁠

is the process of transforming text into a single

canonical form⁠

that it might not have had before. This pack normalizes text by transforming it into

PascalCase⁠

, a process which allows differences in punctuation like dashes, dots, underscores, spaces, and case, to be disregarded. If the names of columns in separate tables are equal once normalized, they are considered equivalent, and the columns will be merged together.

PascalCase is chosen deliberately because that is the same

process used by Coda⁠

to normalize property names returned by packs for use as Sync Table column names. In cases where columns would be equivalent within a table but equal across the tables included to be merged, without normalization the pack would return those equivalent column names as distinct resulting columns in the Sync Table, but since they are equivalent, after the normalization performed by Coda this would result in duplicate column names. To avoid this, the pack must normalize the column names, and must use the same normalization as Coda. Once this is done, duplicates are eliminated before even being considered for the merge, see the At Most One Column section below.

The pack provides the CheckNormalizeEquivalency Formula to experiment with normalization and determine whether columns in various tables will be merged (or not) as expected. It takes in two or more strings as input and returns which of them would normalize to the same string, thus making them equivalent.

At most one column

If a table included to be merged has two or more similarly named columns that would be considered equivalent, at most one of those equivalent columns is chosen to be selected in the merge. The column selected is typically the first column encountered (i.e. the leftmost column as it appears in the doc), but no guarantees are made and you should not rely on this behaviour. For example, if a Table 1 with columns “Date 2” and “Date2” is to be merged with Table 2 with column “Date 2”, the resulting Sync Table will have a single column, “Date 2”. You can think of it as the pack first detecting any columns in the same table that are equivalent (i.e. normalize to the same value) and ignoring all but one of those duplicates in the merging process.

Row ordering

Rows appear in the resulting Merge table according to the sort ordering specified through the sortBy parameter. Note that this is not the same as the order in which tables included to be merged will have their rows appear in the Merge table. The rows from each table all appear consecutively. For example, if merging two tables, the resulting rows from the first table will be ordered with respect to each other, and likewise for the rows of the second table, with all the rows from the first table either before, or after, all the rows from the second table. The ordering is typically according to which table was specified first in the Merge table tableLink fields, but no guarantees are made and you should not rely on this behaviour.

"natural" sort ordering

"Natural" sort ordering is the order that the rows appear in the table view in the application. If the natural sort ordering of a table already included in the merge is changed, it will not change the ordering of its rows in the merge table. You will have to remove the rows from the Merge table to reflect the new sort ordering. This can be done by re-creating the Merge table entirely, or simply temporarily changing the configured table link to the link of any other table (can even be the same one as configured for the other table link!), then syncing to remove the now un-synced rows (make sure the “Keep un-synced rows” setting is turned off), then adding the table link back and syncing once more.

Column type resolution

Column name normalization

At most one column

Row ordering

"natural" sort ordering

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.