Fill your Sketch designs with live data from Google Spreadsheets and Microsoft Excel
JavaScript
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
images
src
.babelrc
.gitignore
LICENSE
README.md
demo.sketch
gulpfile.js
package.json

README.md

Cloudstitch Framer Module

The Cloudstitch Sketch Plugin is an open source extention of the Sketch Data Populator that lets you also use Google Spreadsheet and Microsoft Excel data in your Sketch designs.

Download, unzip, and double-click Cloudstitch.sketchplugin to install.

Why this is Awesome

Designers should work with meaningful and realistic data as early as possible in the design process for the following reasons:

  1. Content informs design decisions (and helps you convey your purpose)
  2. Data are relentless (so UI components must be designed for robustness)
  3. It's fun (seeing your design evolve with meaningful data is motivating and rewarding)

Read more about designing with meaningful data.

The original Sketch Data Populator not only makes you more productive (probably around 60x faster), it changes the way you design user interfaces (at least that's what happened to us). And this Cloudstitch extension makes you even more productive by letting you manage your data in shared spreadsheets instead of cumbersome JSON files.

How to install

Download the latest version from the releases page, unzip it and double-click the Cloudstitch.sketchplugin file to install it in Sketch.

Testing & Credits

Please report bugs, observations, ideas & feature requests as issues or get in touch.

This plugin is an extension of the Sketch Data Populator plugin. We've submitted our additions back as a pull request but decided to also release our own branded fork as space to experiment with tools for the design community. Sketch Data Populator was created by precious design studio in collaboration with Lukas Ondrej.

Please get in touch if you have questions or comments via @cloudstitch or our website.

How to use

The Cloudstitch Sketch Plugin plugin creates a grid from a selected Layer, Layer Group or Artboard and replaces text and image {placeholders} with data from a JSON source:

Sketch Data Populator

How it works

  1. Create a Layer Group that contains at least one Text Layer. In the Text Layer content, use placeholders for you data fields in curly brackets – such as {firstname} or {lastname}. You can do arbitrary string concatenation such as {lastname}, {firstname}. The plugin's "Populate with …" command will replace all these placeholders with respective data. Please note that if your Text Layer is called {name} (in the Layer List), the content of the Layer will always be overwritten with the data contained in {name}. So if you use multiple {placeholders} in a Text Layer, you should rename your Layer to something without curly brackets.

  2. In the same Layer Group, create a Shape Layer (this is your image placeholder). Give the Shape Layer a placeholder name in curly brackets – such as {image}. The plugin's "Populate with …" command will replace this placeholder with respective image data (PNG or JPG, local file or URL).

Available Commands

Create Spreadsheet

will take you to a page on Cloudstitch.com that will generate a cloud-hosted spreadsheet (Google or Microsoft) that you can access from inside Sketch. If you don't have an account, you'll be asked to create a free one.

Cloudstitch Framer Module

Populate with Spreadsheet

will display a dialog that asks you for the username and appname of the Cloudstitch project you just created, as well as the worksheet name inside the spreadsheet that you'd like to load.

You can find the username and appname for your project by looking at its URL:

Cloudstitch Framer Module

The worksheet name is the name of the tab that you see inside Google Sheets or Excel (for example, Sheet1 or People or Products)

Cloudstitch Framer Module

Populate with Preset

will display a dialog that allows you to select one of your Presets as well as configure Data and Layout options:

Populate with Preset

Populate with JSON

will ask you to choose a JSON file that can sit anywhere on your Computer. After picking a JSON file, you can configure Data and Layout options:

Populate with JSON

Populate Table

allows to use .csv files (eg. exported from a Google Sheet) to populate complex data structures to complex layer structures. The documentation for this feature is still work in progress.

Populate again (⌘⇧X)

re-populates all selections with the last used Preset/JSON and options configuration. Great for "shuffling" through different data sets.

Clear Layers

restores populated Layers to their initial {placeholders}. An example: you used the placeholders "{firstname} {lastname}" in a Text Layer, they became "John Doe" after populating. "Clear Layers" will restore to "{firstname} {lastname}".

This is useful because populating a Text Layer means the initially used {placeholders} will be persisted – so without restoring, it would always try to populate the initial {placeholders}, no matter what you type into the field.

Reveal Presets

will point you into the plugin's location for its Presets. Presets are simply JSON files and folders with image assets that live inside the plugin bundle. In there, you can use any desired folder structure.

To find the "Preset" folder inside the plugin bundle, right click Sketch Data Populator.sketchplugin and select Show Package Contents.

Data & Layout Options for 'Populate with…' commands

Data options

Randomize data order

instead of going through the JSON top down row by row, it will pick a random data set.

Trim overflowing text

a Text Layer that has been set with a fixed width will trim overflowing text.

Insert ellipsis after trimmed text

will insert a "…" after the trimmed text.

Default substitute (see below)

Handling missing data

Text Substitutes

{placeholder}
inserts an empty string if no data are available for placeholder

{placeholder?}
uses the Default substitute

{placeholder?substitute}
uses the custom substitute you append after the "?"

Image Substitutes

If there's no image available, it will turn off the fill of the placeholder shape and turn it on again once there's data available when re-populating. So for images, it's recommended to put a substitute image or pictogram behind the actual image. So this will be visible if there's no actual image data (see "demo.sketch" for examples).

Layout options

If "Create grid" is checked, the plugin will create a grid from selected elements (Layer Groups or Artboards) and populate them in one go. Set the amount of rows and columns and the respective margins. This option works very similar to Sketch's "Make Grid" tool (you can use negative margins, too).

Populating Iconfonts

If you're into using Iconfonts for Icons in Sketch as described in this article, that's a great fit with Data Populator. It is possible because Iconfonts use custom ligatures to trigger certain icons: for example, the string 'heart' is being replaced with a ♥ icon.

To make this happen, simply create an Auto Width Text Layer, choose an appropriate Iconfont and call the Layer {iconname} (according to your available Ligatures) in the Layer List.

The Layer's content will always be replaced with the {iconname} representing a ligature, triggering the respective icon.

Multiline Text Layers

Usually, populating Text Layers is limited to single lines of text. If you populate an Auto Width Text Layer, it will always expand the width of the Layer and keep it single line.

If you populate a Fixed Width Text Layer without the trimming (see above), it will keep that fixed width but always expand the number of lines to fit the available data. If you populate a Fixed Width Text Layer with trimming turned on, it will always truncate the data to a single line – meaning the default max. number of lines is 1.

However, if you want Data Populator to truncate after another defined number of lines, that's also possible. Do this by appending the following to the Layer Name of a Fixed Width Text Layer in Sketch's Layer List:

| -l n
where 'n' is your desired number of max. lines

Filters

By appending your {placeholder} with one of the following available filters, separated by a |, you can use certain operations on your populated strings. We will add more filters in the future and you can add filters yourself, too.

1. UPPERCASE

You can force your data to be UPPERCASE after populating by appending your {placeholder} with | upper.

{name | upper}
→ PETER

2. lowercase

You can force your data to be lowercase after populating by appending your {placeholder} with | lower.

{name | lower}
→ peter

3. Maximum characters

You can set the maximum number of characters of your {placeholder} by appending it with | max n, 'n' representing the desired number of characters.

{name | max 3}
→ Pet

4. Join

Imagine you want to concatenate the keys name, price, date and time seperated by a · (interpunct/middle dot). Usually, you would create a string in a Text Layer like this:
{name} · {price} · {date} · {time}

This works great as long as you have data for each key – like:
CursusId.jpeg · $1993.33 · 3.12.2014 · 2:29 PM

But now imagine there's no data (or substitute) for price and time. Which would lead to:
CursusId.jpeg · · 3.12.2014 ·

That's why there's now a "join" function with the following syntax to be used inside a {placeholder}:
{name,price,date,time|& · }

  1. comma separated list of keys
  2. |
  3. & followed by a delimiter, eg. · or , (put spaces where you need them!)

So in our above mentioned example, without data (or substitutes) for price and time, it renders like this:
CursusId.jpeg · 3.12.2014

Here's an animated example: join-enumeration

Combining Filters

Filters can also be combined or grouped with parentheses within {placeholders}. Here are some examples:

{firstname | upper | max 3}
→ PET
assuming firstname = Peter

{(lastname, firstname | &, ), DateOfBirth | & born on }
→ Miller, Peter born on 14.07.1970
assuming firstname = Peter, lastname = Miller

{(firstname | upper | max 3), (lastname | max 1) | & · }
→ PET · M

Conditional Actions

A data-driven "if this than that" for Sketch Data Populator: triggers in the data lead to actions in Sketch.

A Conditional Action performs a certain action on a Layer Group or Symbol based on data and a conditional expression. The Conditional Action is controlled by the name of the Layer Group (or Symbol Instance).

We will add more Conditional Actions in the future and you can add some yourself, too.

1. #show[condition]

shows layer if true and hides otherwise

2. #hide[condition]

hides layer if true and shows otherwise

3. #lock[condition]

locks layer if true and unlocks otherwise

4. #unlock[condition]

unlocks layer if true and locks otherwise

5. #delete[condition]

deletes the layer if the condition is true

6. #plugin[condition, command path]

runs the specified plugin command if condition is true.
Use the command path like this: 'Plugin > Command'

7. #swapSymbol[condition, symbol name]

swaps the affected symbol to the via symbol name specified symbol.

Examples

#show["{firstname}".length > 3]
shows layer if {firstname} has more than 3 characters and hides otherwise

#show["{firstname}" == "Peter"]
shows layer if {firstname} is 'Peter' and hides otherwise

#show["{firstname}".includes('e')]
shows layer if {firstname} includes 'e' and hides otherwise

#show["{firstname}".startsWith('Pe')]
shows layer if {firstname} starts with 'Pe' and hides otherwise

#show["{firstname}".endsWith('r')]
shows layer if {firstname} ends with 'r' and hides otherwise

#swapSymbol[true, bg/{color}]
swaps the affected symbol to 'bg/red' (assuming {color} delivers 'red' from the data). 'true' can be replaced with any conditional expression.

You can combine several conditions:

#show["{firstname}".includes('e') || "{firstname}".length > 3]
shows layer if {firstname} includes 'e' and has more than 3 characters, hides otherwise

Or several Conditional Actions:

#swapSymbol["{status}" == "regular", bg/white] #swapSymbol["{status}" == "VIP", bg/yellow]

Pure JavaScript syntax is being used for Conditional Actions, so you can basically use anything available in JavaScript.

Demo

Check out the demo.sketch file to get an idea. The demo makes use of the Google Material Design Iconfont – please get it here before opening the document.

Plugin Development

Cloudstitch Sketch Plugin is based on Sketch Fusion by Andrey Shakhmin, @turbobabr, as presented at #SketcHHackday 2016.

Development

npm install
gulp watch

To release a new version as GitHub release, run:

export GITHUB_TOKEN=yoursecrettoken
gulp release