Documentation

# Darty Data Workflows

These workflows center around data-processing before the sheets are imported into the Darty-Ai Illustrator extension's user interface.

# Using Excel

Darty-Ai is able to import both .xlsx or .csv files as data-sources.
Using the .xlsx files has advantages in workflow speed and direct access to supplementary workflow assets such as connected workbooks or sub-tabs as collated data-sources for the main export tab.
While the same is possible by using Excel macros, or using another application to automatically render a .csv file, Darty's import of .xlsx directly means less obstacles between data and the document renditions.

# Excel vs CSV: Regional Differences

Importing from Excel directly also removes any issues due to possible differences among specific sub-categories of CSV based on regional location.

These are the possible kinds of .csv files:

  • Comma-Delimited CSV - uses commas (,) to separate values; the most common and traditional format.
  • Semicolon-Delimited CSV - uses semicolons (;) to separate values; often preferred in regions where commas are used as decimal separators.
  • Pipe-Delimited CSV - uses the pipe symbol (|) as the delimiter; chosen when data fields frequently include commas or semicolons.
  • Space-Delimited CSV - uses spaces to separate fields; less common due to potential ambiguity with multi-word values.
  • Custom or Multi-Character Delimiters - employs non-standard or multi-character strings as delimiters to suit specific data needs.
  • Fixed-Width Format - instead of delimiters, each field occupies a set number of characters; relies on consistent spacing for separation.

Due to the differences in these sub-categories, Darty-Ai may not be able to import them accurately if they aren't the traditional comma-delimited kind of csv.
However, importing straight from Excel bypasses these concerns altogether.

# Excel Styling & Formatting

The .xlsx is a robust file format which can store spreadsheet formulas and styles.
Coloring rows, adding borders and creating data-validation user controls can all help make the data workflow error-free and efficient.

# Using Google Sheets

Google sheets have great formula and style support like Excel, which help make data workflows efficient.
However, currently the only way to import Google Sheet data is to download the sheet as .csv or .xlsx and use the Import Data Source button of the Data tab to import the sheet.

Google sheet data could also be reloaded in Darty-Ai with the Reload button if the downloaded sheet is saved to the same locations as already loaded.

Note: Darty-Ai is planned to support Google Sheet integration in future versions.

# Key Row

The 4th row in the Darty Header is often left blank and serves as a separator between the header and the data body.
However, it can be used to add powerful advanced functionality to data operations.

# Descriptive Label

The key row cells' contents can be any text, including any encoded or included information which describes the column to another user.
For example, if the tag was "my-circ", the method was "transform" and the parameter was "deltaX", the optional descriptive key-row name for this column might be something like "circle move-x".
The name "circle move-x" sums up the general purpose of the column including:

  • The item(s) being affected: the circle.
  • The action being performed: moving an item.
  • A sub-category of the action: x-value means moving specifically in the horizontal direction.

This way of using the key row is helpful when having other team-members or non-Darty-users fill out the data.

# Identification Label

The key row cells' values could also be standard or generated unique identifiers which could couple a Darty-Ai data-sheet to external processes.
Each or any column could be outfitted with the key-row value which makes that column unique, to help map the Darty Header to a data body generated independently of the header.

# External Data Coupling

The Darty Header is a complex structure of 4 rows. This facilitates powerful control over artwork, but is not conducive to matching sheets created by other people or by automatic processes.
For example: if a separate department is responsible for adding data to a sheet, or if an automation bot writes new sheets to a filesystem folder, they both would benefit from matching data column from their data to the Darty Header columns.

# Manual User Processing

The human user may employ Google Sheet or Excel formulas to automatically splice together necessary data from various sources to form the Darty data sheet using the Darty key row and their own header row(s).
Some common techniques are:

  • Text-manipulation formulas - formulas which transform text values. Useful when needing to create Darty placeholders ( {{ replace_me }} ) inside of the source text for a follow-up replacement operation.
  • Range-splicing formulas - formulas which bring in a range of data from different tabs to a main Darty export tab.
  • Range constraining - using the range-splicing formulas to limit data records for testing.
    (Note: Darty's range input above the Export button can be used to control the export range itself at export time.)
  • Data randomization: numeric - a spreadsheet formula which produces a random number value. Helpful in creating random movements for the transform method, creating color values or setting any numeric parameter.
    • transform - moving objects around via randomized value.
    • color values - create random color values to use in CMYK/RGB/Lab color/swatch-creation.
    • effect parameters - any effects which have numeric parameters can be randomized.
    • numeric tags - items which are tagged using the name as a pure number can be randomly referenced via tagSearch parameters.
    • numeric names - similar to numeric tags, Illustrator layers and artboards could be randomly referenced by their numeric name via the layer and artboard methods. Note: the Darty Header's values including columns' default values could be randomized with such a formula as well.
  • Data-randomization: pick-list - a formula which sets a random value from a specified list of options. This is highly useful for when the template document contains an 'option list' to pick from.
    Such a list could be certain document swatches, layers, artboards, tagged items as well as any method parameter whose data type is an option-list.
    • swatches - a formula which can randomly pick from a determined list of document swatches can inject a variety into the project while still keeping it on-brand.
    • tags, layers and artboards - pre-determined names can be used to randomly reference document art items, layers or artboards for use with their respective Darty methods.
    • option-based parameters - any Darty methods' parameters which have an option-list as their data value can be randomized in a fail-safe manner.
      For example, the appearance method's strokeAlign parameter accepts the options: inside, outside, and center. The random-pick formula could apply the appropriate option, different for each record.

# External Automatic Processing

With external data automation, a scripted process would be able to match the necessary data it can access to the Darty key-row. This would create the dynamic spreadsheet with all data going to the appropriate columns.

  • API Data - external applications could obtain web data to compile into a CSV format to use in Darty.
  • Header Key-Row matching - using the key-row of a template Darty Header, an external application can match up data columns from other sources via the unique column key.
  • Output destination - the location of exported files can be managed via the external data input. The processing application could edit a data value which is used in an export configuration to set a variable segment of the output path or filename. While this works the same way in a manual spreadsheet, this underscores the fact that an intranet app could generate the spreadsheets which essentially control the output destinations of files.

←