A scaffolding tool for Tableau Web Data Connectors, built on yeoman.
Jump to the information you need:
brew install node
npm install -g yo grunt-cli bower
Once all prerequisites are met, you can install the generator itself by running
npm install -g generator-web-data-connector
yo web-data-connectorand answer a few questions about the web data connector you want to build.
gruntto build and run your connector,
Run all of these steps as often as you need in new directories to create and prototype connectors for all of your web data needs.
This generator attempts to take care of as much boilerplate and development workflow best-practices on your behalf as possible. For an explanation of what's available, continue reading.
When you run
yo web-data-connector, the generator will dynamically create
files and write them to your connector folder. The exact contents of the files
will vary depending on the answers you provide to the generator's prompts; below
is an overview of files and folders to help orient yourself.
gruntat least once, this folder will appear. It contains files built by grunt that your connector relies on, such as the concatenated JS file
This generator attempts to offer you a smooth development workflow, encapsulated
in a single command:
grunt. When you run
grunt, the following is taken care
of for you:
Of course, once initialized, you can make tweaks to your connector's workflow by adding or editing tasks and task configurations in the generated Gruntfile.js file at the root of your connector.
When the generator scaffolds your connector, it includes the latest copy of the Tableau Web Data Connector simulator as a development dependency. You can start the simulator from your project root by running one of the following:
# Open the simulator with your WDC in "production" mode npm run simulate # Open the simulator with your WDC in "development" mode (like running grunt) npm run simulate:dev
ctrl+c to return to kill the simulator and your WDC and return to your
normal command prompt.
Recognizing that you're a responsible developer concerned with the long-term maintainability of your connector, this generator stubs out some simple unit tests to get you started.
Unit tests can be executed by running
npm test at the root directory of your
This generator makes heavy use of a node package called Web Data Connector Wrapper (or WDCW for short). Think of it as a sort of WDC on training wheels that allows you to focus on application logic necessary to retrieve your data, not tedious tasks like registering your connector, saving and retrieving connection details, stepping through Tableau's connector phases, etc.
Rather than learning the Tableau Web Data Connector API, you can dive right into
src/main.js. Although the file is heavily annotated, brief
explanations of the various hooks can be found below.
If you wish to make use of some of WDCW's more advanced features, check the complete WDCW docs.
The web data connector wrapper plugin will fully instantiate a Tableau WDC when it's called with a configuration object. Everything in main.js is simply building up this configuration object using specific attributes that correspond roughly to the four phases of a WDC's lifecycle.
wdcwConfig.setup = function(phase)
wdcwConfig.schema = function()
wdcwConfig.tables['yourTableId'].getData = function(lastRecord)
main.js, and must be provided as the data returned when the Promise it returns is resolved.
wdcwConfig.tables['yourTableId'].postProcess = function (data)
wdcwConfig.teardown = function()
The web data connector wrapper plugin also includes the concept of an "extended
connector." The connector, just a plain object passed in as the
in each of the lifecycle methods outlined above, provides helper methods that
simplify the way you interact with Tableau in your WDCW config. All methods are
this within the immediate scope of your
this.getConnectionData(). This will return an object whose keys correspond to form input names in
this.ajaxErrorHandleras the method called when jQuery AJAX requests fail. This will inform Tableau of the error, and pop an error dialog.
Complete details on this "extended" connector can be found here:
Great! You've built your web data connector, but how do you make it accessible to Tableau users? Although this generator does setup and some boilerplate for several deployment strategies, additional work is necessary to actually deploy the app. Documentation for each option is provided below:
Heroku is a cloud platform for building, scaling, and delivering apps. You can spin up a sandbox application for free, though paid tiers are available. If you selected "Heroku" as your desired deployment strategy with this generator, everything required to successfully deploy your connector as a NodeJS app on Heroku is done for you. However, you'll need to perform some setup beforehand. Details on that below:
git add . && git commit -m "Initial commit."
heroku apps:create name-of-your-app
git push heroku master
heroku ps:scale web=1
GitHub Pages is a free static file hosting service provided by GitHub. It
works by serving files from a special branch (
gh-pages) on a repository hosted
on the service. If you selected "GitHub Pages" as your desired deployment
strategy with this generator, most everything is taken care of for you in a
grunt deploy task. See below for complete setup details.
git remote add origin [url]where
[url]is the repo URL you noted above.
Travis CI is a hosted continuous integration service that can be used to build, test, and deploy applications hosted on GitHub. It's free for open source projects, though a paid version is available for private projects.
Travis hinges its builds off of a YAML file located at the root of projects
.travis.yml which describes how to build your app (things like the
language and version your app is built in, installation steps, etc). This
generator provides a sample
.travis.yml file that--once you have an account
and enable Travis on your repo--should work right out of the box.
If you'd like Travis to deploy your app for you, depending on your chosen deployment strategy, you'll need to make small modifications to the YAML file. In all cases, you'll need the Travis commandline interface installed.
deploy.app.masteris the real name of your web data connector app on Heroku.
travis encrypt $(heroku auth:token) --add deploy.api_keyThis will add an encrypted version of your Heroku authentication token to the
.travis.ymlfile, allowing deployments from Travis.
travisDeployconfiguration in the Gruntfile.js file at the root of your connector.
public_reposcopes. Copy the generated token.
travis encrypt GH_TOKEN=yourToken --add env.globalWhere you replace
yourTokenwith the token value you copied above. This will add an encrypted version of your GitHub personal access token to the
.travis.ymlfile, allowing deployments from Travis.
This generator is a perpetual work-in-progress. Your contributions are welcome and encouraged! For full details, check CONTRIBUTING.md.