Introduction

This document is VIDA.IO web app User Guide.

Home

After login, the app home shows a document explorer

• Top section: header
• Left section: document, user navigator
• Right section: document list

Top Menu

The top menu contains the following options:

• Home url
• Explore
• Products & Services
• Notification dropdown
• User name with logout drop down option

Notifications

The notification button shows the unread messages. A dropdown panel of notifications will be shown upon click. The panel will show the latest 20 notifications.

Sidebar Menu

This section contains menu options to access all of our supported documents (d3 document, dashboard, gist) and user profile page.

Document List

Once a document type is selected on the sidebar, a document list displays all of user’s owned/shared/starred documents.

Shared and starred documents are d3 sub-category documents that are displayed under D3 documents.

This section comes with a header bar action on top that includes a button to create a new document, sorting buttons, and total number of documents.

For D3 document, a document in this list contains extra information including:

• Template/child document icon (mark with a solid/blank circle)
• Sharing icon (individual or team)
• Privacy icon (a lock for private, open lock for unlisted, no icon for public )
• Created date
• Check box for batch action such as delete

Profile Settings

This section contains user or company information and some profile settings.

• User or company name (editable)
• Username (editable) - a public profile page with all users’ visualizations through the URL ‘vida.io/username’
• Email (non-editable)
• Joined date and time
• Created-by URL (PRO subscription only) - this allows a custom signature URL for users when embedding visualizations.
• Created-by image - this follows the above feature to replace text with a custom image (i.e. company’s logo)
• Google analytics tracking ID - this setup analytics callback for all users’ owned visualizations.
• Subscription information

D3 Document

This section is entirely for D3 documents only. Other types of documents may or many not have similar features.

When creating or viewing a document, this window will show. It contains 2 parts:

• Left pane: canvas
• Right pane: editors

Create New

To create a new d3 document, on home screen after login go to: D3 Documents > New Document

This new doucment list includes two separate set of templates:

• Basic built in templates
• User-set templates

When creating a new document from built-in templates, a new and complete document will be created. The last option in this list is the ‘Import Github’. This feature is used to import VIDA compatible documents from GitHub. For VIDA compatible structure, please visit Vida GitHub Template.

When creating a new document from user-set templates, a template child document will be created.

Notes: user-set templates are regular documents and must have 'No-clone’ disabled in order to show up in the list.

Top Menu

This is designed to have similar user experience with a desktop app. It contains the following options (left to right):

• Vida logo - go back home
• D3 text - d3 document editor indicator
• File menu with additional dropdown options:
  • Get Embed Code - gets embed URLs for current document
  • Delete - removes current document
  • Exit - exits current edit document to go back home
• Save - comes with a shortcut as 'Ctrl+Return’
• Clone - clones current document. When cloning a template, the newly cloned document will become a child document.
• More option (horizontal ellipsis)- allows custom view window arrangement

Canvas

This section contains the visual presentation of the document where it combines the code, data, properties and styles together. It has three(3) different sections:

• Title: editable when selected
• Description: editable when selected
• SVG rendering space: the vector drawing from current document. This will be re-drawn upon the following triggers:
  • Save - when there’s a code change and the document is being saved
  • Property change - a property change will immediately render a new SVG

Notes: Saving a document with no change will not trigger the re-rendering.

Editors

This sections contains the most important data for a document including settings. It contains the following tabs:

Settings (Ctrl+1)

This tab shows all the possible settings for a regular document

• Template switch (regular doucment) or Template detach (child document)
• Sharing - share with individuals or teams
• Privacy - allow document to be public/unlisted/private.
  • Public - can be seen and searched by any user
  • Unlisted - cannot be searched, but can be seen to whoever has the document URL
  • Private - can only be seen by owner and shared individuals/teams
• Resource - import external javascript and stylesheet libraries. This also provides a list with some preloaded and suggested resources.
• Tags - allows documents to be searched and indexed properly
• Embed Custom Signature (PRO subscription only) when embed
  • Text
  • URL (redirect URL)
• Embed Widget switch - show/hide embed widget
• General info
• No clone - enable/disable cloning
• Thumbnail - public image for the current document

Data

This tab contains a data editor. Users can choose to import data from a file. There’re three (3) supported data type:

• CSV
• TSV
• JSON

This data tab has the editor shown as default. A grid can be viewed (non-editable) once data is saved first.

Internal

By default, each document will have one (1) internal dataset. A new dataset can be added using the Data > Datasets > Add new option. It has a default name as dataN with N is the number of datasets. Naming a dataset is similarly as naming a file.
The currently viewing dataset can be removed using the Data > Datasets > Remove current option. This option is unavailable if the document has only 1 dataset.

External

Each document can be configured to link external datasets as its own data. This option can be accessed under Data > Datasets > Link external. When linking external datasets, all current document datasets will be removed upon selecting the first external dataset. When unlinking external datasets, all the current external datasets will be copied to the current document.

Using datasets’ data

When a document is saved, the parsed data from this data tab will be available to use within the javascript code through data variable. To better understand, one may print the structure in debug console.

The data structure is different in case of a single and multiple datasets.

• Multiple datasets - each dataset’s data can be accessed using data['datasetName’].
  • Example: datasets Weather 2014, Weather 2015, Weather 2016; Weather 2014 data is available using data['Weather 2014’].
• Single dataset - instead of using data['datasetName’], data will be available directly under 'data’ variable
  • Example: dataset VC Industry 2015, all data will be available using data variable instead of data['VC Industry 2015’].

Notes:

• A document can only have a maximum of 10 datasets.
• Auto properties data column detection will only apply for the first dataset in multiple datasets.

Properties

Properties feature is one of the important feature that makes d3 documents versatile. By defining a document properties, the owner allow document customization and any other user can quickly clone and turn it into his needs.

There are five (5) supported types based on javascript types:

• Data Column - string type for column name parsed from data
• Number - number type
• String - string type
• Boolean - boolean type
• Color - hex string (ex: ’#0C5175’)

Notes:

• Properties can be changed only by document owner and shared users with edit access.
• A template child cannot change its properties. They’re only available for the template document.
• When a property changes, the document will be saved and re-rendering will be triggered automatically .
• Data column properties will be automatically detected when there’s any change from the data column from Data tab.

Javascript

Javascript code is at heart of a d3 document. This code block will be wrapped inside an anonymous function before execution. 'data’ variable contains the parsed JSON from Data tab. 'config’ variable contains the properties set in Properties tab. To use properties, use config[“propertyName”] or config.propertyName within the code.

A div with id 'canvas-svg’ is dedicated for d3 svg rendering. Rendering outside this div may result unexpected behavior and UI misalignment.

When saving a document with javascript/html/stylesheet/data changes, a re-rendering will be trigger. Saving a document without any change will not trigger re-rendering.

Notes: * Defining any 'data’ and 'config’ variable internally within the code will overwrite the passing through ones. * When cut and paste external code, the pseudo code 'select(“body”)’ will automatically be replaced by 'select(“canvas-svg”)’.

Stylesheet

This editor contains the normal basic stylesheet code.

Notes: * Use class or id specific to style elements related the visualization only * Avoid using styling that alters this webapp (Example: html, body, h1, a, etc.). Your documents may get flagged if doing so.

HTML

This editor contains the normal basic stylesheet code. This code block will be within inserted inside ’#canvas’ div. The d3 svg will be rendered within ’#canvas-svg’ which can be placed anywhere within this HTML code block.

Notes: 3. Do not define an html page here, i.e. including html, head, body tags.

Readme

This editor contains markdown content for the document. This content is shown right below the document svg for its public page.

For how to write a markdown document, please visit Daring Fireball

Shortcuts

These tabs have some shortcuts that may be useful for frequent use.

• Ctrl + number (1,2,3,4,5,6) - change editor tabs
• Ctrl + Enter - save document
• Ctrl + ’/’ - enable/disable canvas full view

Templates

A document can be set as a template using the Template switch in Settings tab. By setting this, any further documents that are cloned from this template will be the children.

Parent

A parent template or template is a regular document. When updating a template, its javascript, html and css code will be synchronized across its children. Data and properties’ values are unchanged within its children. Settings, data and properties are not synced across its children.

If the template mode is switched off, all of its children will be disconnected from then and any update will not change its previously children.

Notes:

• After the parent template is switched off, children documents are still in children mode. Users need to 'detach’ them to make them fully independent.

Child

A child document can only apply its own settings, data set and properties. The underlying code are mirrored from its parent template.

When the template document has changes, javascript/html/stylesheet code will be synchronized across its children. Thus, there’re only three (3) tabs shown in a child:

• Settings
• Data
• Properties

Users may detach a child from its parent and turn it into a regular document through 'Detach’ button in Settings tab. By detaching from its parent, it will no longer receive any code update from the parent. This action is not reversible.

Notes:

• Properties cannot be changed through a child.
• Updating data and properties doesn’t change its parent and siblings’ data or properties.

Embed & Share

Embed feature is used to present the current visual part of the document on an external site. This option is available under through

File > Get Embed Code

The dimensions of the embed document is automatically built into the URL if the document has width and height properties set up.

There are two (2) different URL for embedding a document:

• HTTP - HyperText Transfer Protocol (faster)
• HTTPS - Secure HTTP (slower)

The Share option is also availble within this dialog window. If the document is public or unlisted, anybody with the share URL will be able to see the public page of the document. If the document is private, only owner and shared users can access the document public or edit page.

Notes:

• While editing a document, owner can test and view the public page through menu More Options (ellipsis icon) > View public page.
• The 'Test Embed’ button shows a visual part of the document on a separate page.

Import

There are two (2) ways to import a visualization to Vida.

Vida document format

Please visit Vida Document Template for more details.

Manually

Users need to follow Vida document format to enture proper imports. Please visit section D3 Docuemnt / Editors.

Debug

How to

Debugging a Vida d3 document is similar to debuging any javacript code. Chrome debugging console is recommended for this task.

The document code is inserted at the bottom of the each page. To set a break point any where within the code, developers can insert a 'debugger;’ statement right before the wanted break point and then save the document. By doing this, the Chrome console will automatically break when the re-execution happens.

Safe Mode

Developers often find their code takes too long or even got stuck and unable to load or reload. This is due to the javascript execution could not be completed. One common mistake is having the code running an infinite loop or a very long process.

Turning on the safe mode will help developers to fix these cases. This mode doesn’t execute the javascript unless disabled again.

To turn on safe mode, go to Home / D3 Documents and from the document list select the bug icon on the target document. Once the bug is lit up, loading the document again will not execute the javascript code.

To turn off this mode, document owner can click on the bug icon within the top menu bar to disable it. This option can be done similarly as turning on in the document list with the bug icon.

Notes: * Canvas svg rendering will not run unless this mode is disabled. * Enabling this will stop embed rendering.

Gist

This tool is used port and publish back GitHub gist to and from Vida system. It helps developer of any level experiment any gist and see the changes in action. The edit view is designed to have similar user experience with a d3 document one.

Notes:

• This is incompatible with Vida d3 document format.
• This doesn’t include most features supported for a d3 document. To fully utilize these feature, consider porting a gist to a Vida-d3 document format.

Import New

To import a gist, go to Home / Gist, select Import Gist (Block) from the document list top left menu. Once successfully imported, the gist edit view will show up with top menu bar, ’#canvas-svg’ div on the left, the settings and editors on the right.

Save and Publish to GitHub

When a gist has any changes, the re-rendering will trigger once the document is saved (using ‘Save’ button or 'Ctrl+Return’ shortcut). This action only saves the document within Vida internal system. To replicate these changes on GitHub, developers need to publish them back. To publish, follow the following steps:

• Select Connect to GitHub button in Settings tab, and allow GitHub authentication.
• When connected, click Select a Gist dropdown menu option, and select the target gist.
• Click Push to complete publishing.

Dashboard

Important: This feature is in beta.

Vida dashboard is a flexible tool that combines individual d3 documents together to create a complex dashboard.

(Work in progress, please check back for more information)

Adding documents

There’re two (2) ways to add a document in a dashboard.

• Add My Document option allows users to add their own documents
• Add VIDA Document option allows users to add Vida pre-selected documents

Applying master dataset

All individual documents can share the same master dataset which can be configured using Select a Dataset option. By choosing a dataset, all individual document will receive the same data passed inside.

Edit properties

Each document properties are editable and apply to the current dashboard only. An individual document may select a different dataset instead of using the shared master dataset.

Team

Team feature helps developers manage different access levels for their documents for different groups of users.

Notes:

• This feature is integrated with Vida d3 documents only. Other types are not yet supported.

Create New

To create a new team, on home screen after login go to: Teams > New Team

Privacy

The team privacy can be set with the following three (3) states:

• Public - can be seen and searched by any user
• Unlisted - cannot be searched, but can be seen to whoever has the team URL
• Private - can only be seen by owner and shared individuals

Documents

This list shows all the documents shared within the team. Any member of the team can share their documents within the team.

Notes:

• Only documents without any individual collaborator can be added to a team.

Members

This list show all the members with their access level within the team. There 4 different access levels for a member:

• Team admin - can edit the team documents and members, can also edit document
• Can Edit Document - can edit any documents shared within the team
• Can View Document - can view any documents shared within the team including private ones
• Can View Standalon - can only view shared documents, and view is presented in a standalone/embed mode

Notes:

• A member is not yet a team member if he hasn’t accept the team invitation. Thus, he cannot access documents within a team.

Google Chart

This wizard tool is a wrapper on top of Google Charts api for quickly build a google chart.

There are 9 supported chart types:

• Line
• Bar
• Horizontal Bar
• Area
• Pie
• Bubble
• Geo Map
• Scatter Plot
• Tree Map

To create a new chart, on home screen after login go to: Google Charts > New Chart

There are three (3) sections for a Google chart document:

1. Data - requires a dataset document
2. Properties - configures chart properties
3. Chart - a renderred chart svg from Google chart api

Dataset

This tool is used to build datasets that can be used in Vida d3 documents and Google Charts. A dataset can be shared across multiple documents.

To create a new chart, on home screen after login go to: Datasets > New Dataset

A dataset can be imported from a file or a data URL (JSON).

A dataset has similar privacy settings as a d3 document: * Public * Unlisted * Private

Additional Resources

Support

Users can contact and get help immediately by:

• Send an email to contact@vida.io
• Send a UserVoice request using the bottom right question mark

Tutorials and videos

D3.js Tutorial 1: Append

D3.js Tutorial 2: Select

View and Subscribe

Data Visualizations for IPython Notebooks

FAQs

What browsers are supported?

The following browsers are supported:

• Chrome 30+
• Internet Explorer 10+ or Microsoft Edge

The app should work mostly with any modern browsers including FireFox, Safari. However, they’re not officially supported and may result with errors.

What are the browser resolutions supported?

We have optimized our app view to work with resolution of 980x674 or higher. Lower resolutions are not recommended for document editing.

Download

Local builds are available for download. We have support for Windows and Mac.

Windows

• Click here to download Windows build
• Unzip file to a folder
• Open 2 command line windows and go to the unzipped folder
• In the first command line window, start database: start_db.bat
• In the second command line window, start vida server: start_vida.bat
• Open browser and go to application: http://localhost:8080

Note: Press Ctrl+C to exit batch processes. For vida server, after exit, you need to execute “cd ..” to get outside of bundle directory.

Mac

• Click here to download Mac build
• Unzip file to a folder
• Open 2 command line windows and go to the unzipped folder
• In the first command line window, start database: start_db.sh
• In the second command line window, start vida server: start_vida.sh
• Open browser and go to application: http://localhost:8080

Note: Press Cmd+C to exit batch processes. For vida server, after exit, you need to execute “cd ..” to get outside of bundle directory.

Upgrade

When you upgrade your build, you need to retain the previous data directory.

• After you download, rename your previous build into data directory (e.g. vida_data.)
• Extract your new build.
• Go inside vida_data directory, start mongodb database. On mac, start_db.sh. On windows, start_db.bat.
• Go inside your new build directory, start Vida service. On mac, start_vida.sh, On windows, start_vida.bat.

WARNING: Be cautious of deleting any folder. You may not able to recover your data.