NAV

Introduction

This document is VIDA.IO web app User Guide.

Home

alt text

After login, the app home shows a document explorer

Top Menu

alt text

The top menu contains the following options:

Notifications

alt text

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.

alt text

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

Document List

alt text

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:

Profile Settings

alt text

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

D3 Document

alt text

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:

Create New

alt text

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:

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):

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:

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

Data

alt text

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

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.

Notes:

Properties

alt text

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:

Notes:

Javascript

alt text

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

alt text

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.

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

alt text

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:

Child

alt text

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:

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:

Embed & Share

alt text

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:

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:

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

alt text

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:

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:

Dashboard

alt text

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.

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

alt text

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

Notes:

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:

Documents

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

Notes:

Members

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

Notes:

Google Chart

alt text

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

There are 9 supported chart types:

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

alt text

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:

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:

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

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

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.

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