Data Sources

Data sources are used to provide values for variables and styles from a collection of tabular data. With data sources it is possible to set up a document where styles and variables are sources from the columns of a table, with each row presenting an alternate variable value set.

Data sources are also known as data merge, and can be used to automatically generate variations of artworks for exporting. Data sources are managed from the Data Sources panel (Panels -> Styles).

The table containing style and variable values can be imported from a CSV (command separated values), XML or JSON files, or can be created and edited in the Data Sources panel.

When using an external file to store the variable values, the file can be linked so that when the values in the file change, the document is automatically updated. This also allows the creation of different canvas and artboard instances of the same design based on different rows from the data source.

For complex style values (shape or image effects, object styles) it is recommended to use the Data Sources panel to create and edit the variables and styles, export into an XML data file (VectorStyler specific) and then link to this file to source the variable values.

Any attribute that supports styling can also be stored as an entry in a data source table. This allows the sourcing from data files not just for numbers and conditions, but also effect or object styles, shapes, colors or gradients.

Using Data Sources

Data sources can be used to link style and variable definitions to the rows of a table stored in a file, and create multiple artwork versions using alternate variable values in the data rows.

Data source files can store both complex style definitions like effects or shapes, or basic variable types like numbers, conditions or colors. When using data sources for complex style definition, it is recommended to use a VectorStyler specific file format to allow the hierarchical storage of these attributes. When using basic variable types like numbers or colors, both the CSV and VectorStyle formats can be used.

Variable definition

To use data sources for basic variable definition from a CSV file, setup a CSV file as shown here.

[number] width1, [color] color1, [color] color2, [text] text1
12.0, #B6CC66, #FF3939, Green
20.0, #A21E50, #A21E90, Red
16.0, #451EA2, #1E7AA2, Blue

In this example, we have a number variable, 2 color styles and a text variable, defining 3 possible sets of values for these variables.

Import this CSV using the Import Data button in the Data Sources panel. The list of variable definition is shown, with the values taken from the first row.

Apply the color styles from the Data Sources panel to some objects, and use the width variable as a stroke width on objects. Changing the active row of the data source will activate different variable values, updating the content of the document.

To inspect how various types of styles and variables are stored in a CSV file, create the variables (columns) in the Data Source panel and export the data source to a CSV Table

Data Sources in Repeaters

Variables and styles defined by data sources and used in repeated objects can be altered by iterating the rows of the data sources over the repeated objects.

The Repeater panel menu contains two menu items used to specify which data source rows is iterated and in what order the rows are applied to the repeated objects.

• The Data Source menu item opens to a list of data sources imported into the document. Select one of these data sources to apply different rows of it on the repeated objects.
• The Data Menu menu item contains the various row selection modes for the repeated object style overrides.

Canvas Data Grid

The Canvas -> Canvas Data Grid menu can be used to repeat the artboard and first layer of a canvas using variations from the rows of a data source. The canvas grid creates one artboard per data row, from the data source, and automatically updates these if the data source changes.

The content of the first layer and first artboard can be edited to modify the layout of the repeated artwork. Use Refresh (Command+R) to refresh the artboard copies of canvas grid once the modifications are done.

To use the canvas grid feature, setup a data source with variables and styles, and multiple data rows. Create the content on a single artboard and keep all artwork inside a layer (use sub-layers of the layer to structure design).

From the Data Source panel apply styles and variables to the objects in the artwork.

Once the artwork is ready on the artboard, select a data source in the Canvas -> Canvas Data Grid menu to repeat the artboard once for each data row. To update the design, make changes on the first artboard and the press Command+R to refresh all artboards.

Changing the variables and styles in the Data Source panel, or replacing the data source with an other file (with the same column names) will automatically update the content of the artboard grid.

The canvas grid repetition options can be selected using the Canvas -> Canvas Data Grid -> Options menu:

• Content - Select an alternate symbol to be repeated. Layers or symbols created on a Reference canvas can be used for repetition of the current canvas contains no content. Selecting Default will repeat the first layer of the current canvas.
• Data Source - Select a data source to use as style override in the repeated layers.
• Horizontal - Set the horizontal spacing between the artboards.
• Vertical - Set the vertical spacing between the artboards.
• Vertical First - Set the artboard repetition direction.
• Locked Copies - Lock the repeated copies of the artwork, to allow editing only on the first artboard.
• Preview - preview the canvas grid options.

Exporting

When exporting artwork to a file format, the export operation can be repeated automatically with different rows of a data source selected as variable and style override.

When data sources are included in a document, the Export options view will show a Data Source drop down with the data source files defined by the document. Select one of the data sources.

Confirming the export options will export multiple copies of the artwork, one for each data row, using the variable and style values from that row.

The Data Sources Panel

The Data Sources panel can be opened from the Panels - Styles menu, and it is part of the style and variable management module of VectorStyer. By default, the Data Sources panel contains a Import Data button, that can be used to import existing data source files.

A VectorStyler document can link to and use multiple data source files, each with its own column set (providing variable and style names) and rows providing alternate values of those variables. These data sources are listed and managed as collections in the data source panel.

A new data source collection can be created by importing an existing data source file, or by creating an empty data source using the Create New Collection command of the panel menu. The top row of a data source file (in CSV format) should specify the columns names (variable and style names) while subsequent rows specify alternate values for variables.

The variables and styles stored in a data source collection (file) are listed in the Data Sources panel under the collection name. Since the panel may contain multiple collections (multiple data source files linked to the document), each collection can be opened or closed in the list.

The data sources panel is organized as follows:

• The list of data source collections, each containing a list of variable and style definitions, is shown in the panel.
• The panel menu contains commands to import, export and manage data sources.
• The panel icons can be used to create, remove or edit the styles and variables of the data source.
• Commands for individual data sources can be accessed using the icons in the title row of a data sources (with the Row label).
• The active row is used to set the variable and style values from that row of the data source.

The following commands are accessible from the bottom icon row of the panel:

• - Apply the selected style to the selected objects.
• - Open a modal editor view to edit the attributes of the selected style.
• - Edit the selected style name. This will edit the column name of the data source table.
• - Update the selected style from the selected object.
• - Create a new style from the selected objects, or with a default value, and create a new column in the data source.
• - Update the data sources from the linked file.
• - Remove the selected variable.

The content of a data source is listed under the data source name. The content is managed with commands next to the Row label:

• The Row drop down of a data source contains the list of names of the rows of the data source. Select a row to activate the styles and variables in that row.
• - Link or unlink the data source with an external file.
• - Lock or unlock the data source.
• - Duplicate the current row in the data source.
• - Remove the current row from the data source.
• - Load the data source content from a file.
• - Link the data row to the selected object. The styles in the selected object will have an override from the linked data row.
• - Select the previous data row.
• - Select the next data row.

The following commands are accessible from the data source panel menu:

• Style Location - Select the storage location of the edited styles. This can be Document, Canvas or the selected Object.
• Import Collection - Import a new data source. Same as the Import Data button.
• Export Collection - Export the selected data source. The data source can be exported to CSV, XML, JSON and VectorStyler specific files. Depending on the content of the data source (complex styles or just variables), some formats may be better suited than others.
• Relink Data File - Relink the data source to another data file and update its content.
• Create New Collection - Creates a new empty data source.
• Remove Collection - Removes the selected data source from the document.
• Edit Variable - Edit the attributes of the selected style or variable.
• Create New Style - Creates a new style or variable with a default value, also creating a new column in the current data source.
• Create File Link - Creates a new variable containing a link to a graphics file. The variable can be used as a content for objects, and can be drag and dropped onto the document to create instances of the linked file.
• Create Color Scheme - Creates a color generator variable. Color generators are variables that generate a new color from an other color using a color scheme. Color generators can be used to link to existing color variables and create alternate tones of those colors, updating the color as the original color changes.
• Create Number Variable - Creates a new number variable.
• Create Measurement - Creates a new measurement number variable.
• Create Condition - Creates a new condition variable.
• Create From Selection - Creates a new style from the selected objects.
• Edit Style Name - Edit the selected style or variable name. Also changes the column name associated with the selected variable.
• Duplicate Data Row - Duplicates the current data row.
• Remove Data Row - Removes the current data row.
• Apply to Selection - Applies the selected styles on the selected objects.
• Assign from Selection - Updates the value of the selected styles from the selected objects.
• Detach Selected - Detach the selected variables from their instance in the document.
• Replace Style - Replace the selected style with an other style in the document.
• Remove Selected Style - Deletes the selected style.
• Previous Data Row - Activates the previous data row.
• Next Data Row - Activate the next data row.
• Copy - Copy the selected styles and variables to the clipboard.
• Cut - Copy the selected styles and variables to the clipboard, and remove them from the data source.
• Paste - Paste variables and styles from the clipboard, creating new data source columns.
• Update Variables - Updates the data source content from the linked files.
• Files - Import and export variables and styles.