Variable Importer Dev

# General Description

WARNING

👉 This is a draft! 👈

We need to document:

  1. The format of an entire JSON, XML and CSV document.
  2. The format of the JSON (XML) Manifest
    • The format of the user inputted record cell, i.e. the input the user would type in a single excel cell and the JSON and XML equivalents.
    • The format of the JSON that is to be generate by the extension (AKA Tom) to send to the plugin (AKA Ten) interpreted from the user inputted record cell
    • The format of the JSON response the plugin should send to the extension after performing an action. {"error": null, "Hi you're cute"}
  4. The above formats need to documenting for each variable type including all the valid options of each type, min / max and valid entries.
    swatch: [name, rgb(), cmyk(), lab(), swatch()]

Thought 🧐

We could in theory allow an input json that would in the format of the json commands to be sent to the plugin in such a case we would not need the manifest. Just a thought!

# Document Format

# An Entire JSON document containing 3 records and 2 variables

# JSON

/**
* The input json will be one big blob like a csv file
* It will be an array where each member of the array is a record that would generate a new document.
* Each row should contain and array of cell containing the info for each variable type
* Each cell should state the variable name and value
**/
[ // Record 1
  [
    { // Record 1 Variable 1 each "Cell" must contain one name and one value
      "name": "dog_stroke", // this is the variable name
      "value": {
        "width": "11px",
        "color": "rgb(0,0,0)"
      }
    }, // End of Variable 1
    {  // Record 1 Variable 2
      "name": "dog_fill",
      "value": {
        "color": "#f00"
      }
    } // End of Variable 2
  ],  // End of record 1
  [   // Record 2
    { // Record 2 Variable 1
      "name": "dog_stroke", // this is the variable name
      "value": {
        "width": ".5mm",
        "color": "cmyk(100, 50, 25, 0)"
      }
    }, // End of Variable 1
    {  // Record 2 Variable 2
      "name": "dog_fill",
      "value": {
        "swatch": {
          "name": "bright green",
          "color": "lab(100,-127,127)",
          "global": true
        }
      }
    } // End of Variable 2
  ],   // End of record 2
  [   // Record 3
    { // Record 3 Variable 1
      "name": "dog_stroke", // this is the variable name
      "value": {
        "swatch": "red" // note no stroke width here
      }
    }, // End of Variable 1
    {  // Record 3 Variable 2
      "name": "dog_fill",
      "value": {
        "swatch": "'bright green copy (2)'" 
        /* this swatch name must be quoted so that it is not interpreted as a function
        * we could have a fullback that if the function name is not recognized and the swatch name is
        * then it is to be considered as the swatch name.
        * so "bright green copy (2)" without the quotes would be good but a swatch named "rgb(4,5,6)" would 
        * need to be quoted "'rgb(4,5,6)'"
        * same for 3 6 and 8 digit # numbers "'#c0ffee'" swatch called #c0ffee "#c0ffee" rgb hex value
        */
      }
    } // End of Variable 2
  ],   // End of record 3
]     // End of file

# CSV

dog_stroke dog_fill
11px | rgb(0,0,0) #f00
.5px | cmyk(100, 50, 25, 0) swatch("bright green", lab(100,-127,127), true)
red 'bright green copy (2)'

# Manifest Format

Coming some time

# Cell Values

For each variable type we want to write up 4 formats in the documentation.

  1. User inputted JSON we should be able to directly convert the JSON to csv if we use the correct method
  2. User inputted XML (this can be directly generated from the JSON
  3. User inputted csv (excel is exactly the same format) we should be able to directly convert the csv to JSON if we use the correct method
  4. Extension generated JSON to parse with scriptMessage call to c++

We need to document the following workflow:

  • User inputted CSV / JSON / XML
  • Extension parsed JSON to be sent to the plugin using something like scriptMessage
  • Message response from plugin

Tip 👇

The User inputted JSON / CSV should be bi-directionally convertible. I.e. We will want to be able to read a cell from a csv file and combined with the cells header and manifest convert to a json object.
Likewise given a JSON object we should be able to generate the equivalent csv cell.

# To be continued

← Variable Types →