Merge pull request #6 from demartsc/docs/readme-update

Docs/readme update

README.md

@@ -1,162 +1,113 @@
-# Tableau Extension Framework
+# Annotate All The (Tableau)Things!
+### Layering React Annotation on top of Tableau
 
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+## Introduction
 
-## Creating a Tableau Extension via `create-tableau-extension`
-The easiest way to create a new Tableau Extension is by using `create-tableau-extension` tool from NPM.
+![React Annotation in Tableau Image](./docs/D1-Annotations.gif)
 
-Installation:
+This is the tableau extension that allows you to layer [Susie Lu's](https://twitter.com/datatoviz?lang=en) [react-annotation](https://react-annotation.susielu.com/) library on top of Tableau. When you add this to your dashboard (you will likely want to cover your entire dashboard with it) you can leverage the majority of annotation types and options available in [react-annotation](https://react-annotation.susielu.com/) directly within Tableau. We have built a simple configuration UI that you can take advantage of to be able annotate your viz to your heart's delight. 
 
-```sh
-npm install -g create-tableau-extension
-or
-yarn global add create-tableau-extension
-```
-
-Then you simply run `create-tableau-extension` command from your work folder and an interactive terminal will guild you throw the process.
-
-## Available Scripts
-
-In the project directory, you can run: 
-
-### `yarn install`
-
-Installs all the dependencies.
+This extension is supported on **Tableau Desktop >=2018.3** and **Tableau Server**. It works best when deployed directly on to the Tableau Server you are using and the content of the extensions is also viewable on **Tableau Mobile**.
 
-### `yarn start`
+## Env Requirements
+Tableau Desktop >= 2018.2 and Tableau Server >= 2018.2
 
-Make sure you have a correct name, description and version inside the `package.json` file. 
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app) along with [StarSchema](https://starschema.com/) & [DataBlick's](https://www.datablick.com/) **Tableau Extension Framework**.
 
-**Note!** If you try running this project after cloning it, you may have to remove the # from the name before the run.
+## Quick Start
+#### Step 1: Locate Annotate All The (Tableau) Things on the [Tableau Community Extensions](https://tableau.github.io/extensions-api/community/) page
 
-Runs the app in the development mode.<br>
-Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+Note: If you want the best experience, you should deploy a compiled version of this code directly to your Tableau Server and point your .trex file to that deployment of the extension. 
 
-The page will reload if you make edits.<br>
-You will also see any lint errors in the console.
+#### Step 2: Click ‘Allow’ to permit the extension to run.
 
-### `yarn run build`
+![Allow Extension in Desktop Image](./docs/Allow-extension.png)
 
-Builds the app for production to the `build` folder.<br>
-It correctly bundles React in production mode and optimizes the build for the best performance.
-
-The build is minified and the filenames include the hashes.<br>
-Your app is ready to be deployed!
-
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
-
-## Configuration
-The main entry point of customization is the `src/extension_assets` folder.
-
-### Creating a custom splash screen
-
-To create a custom splash screen (front screen of your extension) you have to modify the `src/extension_assets/splash/index.js` file. 
-
-Note the `Button` component on the 29th row:
-```js
- <Button 
- value="Configure"
- onClick={props.onClick}
- style={buttonStyle}
- />
-```
-This is the config window laucher. You can change the style and the text value as you want, but let the `onClick` method as it is right now. This callback method tells the Extension to launch the config window.
+#### Step 3a: Cover your Dashboard with the Extension Object. The best experience for now is to work with the extension using web edit on Tableau Server. Tableau Desktop is lacking transparency for Extension Objects. You are not required to cover your dashboard, but I found this the easiest way to use React Annotation across your viz. 
 
-### Creating the custom viz
+#### Step 3b: Click the `Let's Annotate Things!` button. 
 
-To implement your custom vizualization you have to edit the `src/extension_assets/viz/index.js`.
+![Tableau React Annotation Splash Screen](./docs/Cover-Dashboard.png)
 
-In the file you can see an exaple how to pull data from the dashboard.
+#### Step 4: Edit the default annotation to your desire by clicking on the edit icon (pencil) and changing the many configurations. 
 
-### Configuration wizard
-Here are the types of available configuration layouts. You can set or configure the configuration steps inside the `src/extension_assets/stepperConfig.js` file. 
+Note: You can reference the [react-annotation](https://react-annotation.susielu.com/) site for additional details and information on the configurations available to you.
 
-There is a `steps` attributes which contains the used layouts in the order. You can have multiple steps from one layout type. 
-#### Sheet selector layout
-- `"type": "sheet_selector"`
+Note: You may need to select "configure" again in the extension object menu if you do not see the edit icon and/or edit mode initially. 
 
-This is a very basic layout which allows to select one or two datasheet.
+![Tableau React Annotation Edit Annotation Screen](./docs/Edit-Annotation.png)
 
-If you want to use two datasheet you have to set allowMultiSheets property to true.
+#### Step 5: You can delete an annotation by clicking on the trash can icon and then confirming via the dialog box which pops up. 
 
-`"allowMultiSheets": true`
+![Tableau React Annotation Delete Annotation Screen](./docs/Delete-Annotation.png)
 
-You can overwrite specific labels by setting these values inside the `overwrites` object:
-- `add_other_datasheet` - Default: **Add another datasheet**
-- `add_sheet` - Default: **Add sheet**
-- `revert` - Default: **Revert**
+Note: If you want to hide the annotation, but not delete it (e.g., save it for later, but don't show) you can click on the eyeball icon to toggle visibility of the annotation when not in Edit Mode. 
 
-#### Drag and Drop options
+#### Step 6: You can add more annotations by toggling the icon on the top left and then clicking anywhere on the extension object's surface. Once the configuration pops up just fill it out and you will have a new annotation!
 
-- `"type": "drag_and_drop"`
+![Tableau React Annotation Add Annotation Screen](./docs/Add-Annotation.png)
 
-The Drag and Drop screen can be configured via a json-like javascript object. You can find an example under `src/extension_assets/stepperConfig.js`. Feel free to modify it. 
+#### Step 7: Once you have added all of your extensions you can hide the ability to modify the annotations from the end user by toggling these two configurations in the add/edit annotation config (these settings are global even though they are accessed in the add/edit annotation config).
 
-First you have to add columns. The first column should be a `measures` type one. This will contain the field names from the selected sheet.
+![Tableau React Annotation Global Config Screen](./docs/Global-Config.png)
 
-The following two should be `options` type. They will contain the drop areas. 
+* Show Controls - When no is selected the end user will not be able to toggle add/edit mode on as the icons on the top left will be hidden. This will also default to turning off add/edit mode. 
 
-You have to configure the `drop_area` as well. Currently we are supporting `single_drop` type only. 
+* Click Through Mode - Use this only when the extension is deployed directly onto your Tableau Server. It allows you to enable the end user to click through the extension layer and still interact with the Tableau Dashboard behind it. 
 
-Last thing you have to configure the column render order.
+#### Step 8: If you want your changes to be retained, you **MUST** save your workbook before you close/exit Tableau. This will write the extension changes to your twb/twbx file. 
 
-#### Custom viz options 
-- `"type": "viz_options"`
+#### Step 9: If you want to see something different, submit an issue on this Github repo. 
 
-You have the opportunity to add custom configuration (e.g.: text inputs, dropdown select). In order to set up this config layout you have to edit the `src/extension_assets/stepperConfig.js` file. You can define option groups. In each group you have to add input fields. We are supporting the following input types:
-* Text input - `text`
-* Checkbox - `check`
-* Radio buttons - `radio`
-* Dropdown select - `dropdown`
+## Local Development Setup
+For a development installation (requires npm, node and yarn):
 
-You can find exaples of each and every type inside the `src/extension_assets/stepperConfig.js` file. 
+Install [node](https://nodejs.org/en/download/package-manager/) (`> 8.15.0`), [yarn](https://yarnpkg.com/en/docs/install). For best management of Node versions, use [nvm](https://github.com/creationix/nvm)
+then simply run `nvm use 8`.
 
-#### Custom config layout
-- `"type": "custom"`
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app) along with [StarSchema](https://starschema.com/) & [DataBlick's](https://www.datablick.com/) **Tableau Extension Framework**.
 
-You can define custom config layout as well. In order to create one you have to import the component into the `src/extension_assets/stepperConfig.js` file and define a new step with `custom` type. You have to pass this component to the `component` property. You can define component props under `props` key. 
-
-
-#### Summary layout
-- `"type": "summary"`
-
-There is a overview page for development purposes only called Summary Layout. This view diplays the previously set up options. 
+### Start local app
+##### 1. Clone repo
+```sh
+git clone [email protected]:demartsc/tableau-react-annotation.git
+```
 
-### The `name` property
-As you can see in the example config there are `name` attributes specified. This name attribut is goint to be the *key* inside the Tableau Settings object and the selected or given value will be the *value* of this key. 
+##### 2. Install
+```sh
+yarn
+# or
+npm install
+```
 
-**Note!** Tableau stores everything as a string. If you need to store complex data structures, like arrays or objects, you have to stringify it first. 
+##### 3. Start local app session
+```sh
+yarn start
+# or
+npm run start
+```
 
-### Custom css syle
+### Setup local extension in Tableau Desktop
+##### 1. Launch Tableau
+open tableau workbook (get it from public folder of this repo)
+- NOTE: if you want to enable remote debugging, use this command in terminal to open tableau
 
-You can define custom styling options, like `font-family` by editing `src/extension_assets/extension.css`. 
-You can define your own color schemes as well by editing the `src/extension_assets/style.js` file. 
+```sh
+open /Applications/Tableau\ Desktop\ 2019\.3.app --args --remote-debugging-port=8696
+```
 
-### Custom logo
+A debug session will be available in browser http://localhost:8696
 
-You are able to use your own brand logo inside the extension. The only thing you have to do is edit the `src/index.js` file, and import your logo like so:
-```js
-import brandLogo from './extension_assets/logo.png';
-```
+##### 2. Execute extension in tableau
 
-## Hosting
-To create a build version of the extension you have to build it first.
+- copy the `datablick-react-annotation-local.trex` file (inside the `public` folder) into your `extensions` folder of the `My Tableau Repository` (likely in your `Documents` folder).
 
-```bash
-yarn run build
-```
+- Go to the Tableau window that opened when running the above command.
 
-This command will create a new folder called `build` and generates all the necessary files. You can simply upload the files into a server or S3 and put it under a public domain, and you are ready to use it or share it. 
+- Drag the extension onto dashboard and select the trex file from your my tableau repository\extensions folder.
 
-### Hosting under subfolder
-If you want to host your extension under a specific subfolder, you have to specify the folder structure in the `package.json` file under the `homepage` key.
+- More information on [Tableau Extensions API](https://tableau.github.io/extensions-api/#) about [Get Started with Dashboard Extensions
+](https://tableau.github.io/extensions-api/docs/trex_getstarted.html)
 
-```json
-{
- "name": "BestExtension",
- "description": "Awesome extension",
- "version": "0.0.1",
- "homepage": "/path/to/subdir",
- "private": true,
- ...
-```
+## Links
+- [Susie Lu's](https://twitter.com/datatoviz?lang=en) [react-annotation](https://react-annotation.susielu.com/) library