Creating a Tableau Extension / Part One

I have experimented with the new Tableau Extensions API since the Tableau Beta for 2018.2 and found this new feature to be a real game changer. Being an experienced web developer, this came very easy to me but if you have never programmed before, this could all be a bit daunting. In this four-part series, I will be walking through the setup of the development environment and helping you build your very own Tableau Data Extension.

Part 1: Getting Started

In the first part of this series, we will get started by installing and setting up the development environment (and relevant tools), getting the Tableau Extensions Library and integrating with GitHub for your storing and sharing your projects.

Installing GitHub

Git (/ɡɪt/) is a version control system for tracking changes in computer files and coordinating work on those files among multiple people. It is primarily used for source code management in software development, but it can be used to keep track of changes in any set of files. As a distributed revision control system, it is aimed at speed, data integrity, and support for distributed, non-linear workflows.

You can download Git for your desktop here: https://git-scm.com

GitHub Inc. is a web-based hosting service for version control using Git. It is mostly used for computer code. It offers all of the distributed version control and source code management (SCM) functionality of Git as well as adding its own features. It provides access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project.

GitHub offers plans for both private repositories and free accounts which are commonly used to host open-source software projects. As of June 2018, GitHub reports having over 28 million users and 57 million repositories (including 28 million public repositories.), making it the largest host of source code in the world.

On June 4, 2018, Microsoft announced it had reached an agreement to acquire GitHub for US$7.5 billion. The purchase is expected to close by the end of the year.

Please go to the GitHub website and create yourself an account, we will save our work to here: https://github.com

Note: GitHub does come with a Desktop tool, however, for this tutorial we will be using a command line (cmd) to check in our new code into GitHub.

Installing Microsoft Visual Studio Code

Visual Studio Code is a source code editor developed by Microsoft for Windows, Linux and macOS. It includes support for debugging, embedded Git control, syntax highlighting, intelligent code completion, snippets, and code refactoring. It is also customizable, so users can change the editor’s theme, keyboard shortcuts, and preferences. It is free and open-source, although the official download is under a proprietary license.

Visual Studio Code is based on Electron, a framework which is used to deploy Node.js applications for the desktop running on the Blink layout engine. Although it uses the Electron framework, the software does not use Atom and instead employs the same editor component (codenamed “Monaco”) used in Visual Studio Team Services (formerly called Visual Studio Online).

In the Stack Overflow 2018 Developer Survey, Visual Studio Code was ranked the most popular development environment tool, with 34.9% of 75,398 respondents claiming to use it.

I use Microsoft Visual Studio Code for most of my coding and you can download it here: https://code.visualstudio.com

Installing Node.js

We will install the Yarn Package Manager to help manage our javascript packages and dependencies, don’t worry, we will go through this a little later, but for now a little bit about Node.js and Node Package Manager (NPM).

Node.js is an open-source, cross-platform JavaScript run-time environment that executes JavaScript code outside of a browser. Historically, JavaScript was used primarily for client-side scripting, in which scripts written in JavaScript are embedded in a webpage’s HTML and run client-side by a JavaScript engine in the user’s web browser. Node.js lets developers use JavaScript to write Command Line tools and for server-side scripting—running scripts server-side to produce dynamic web page content before the page is sent to the user’s web browser. Consequently, Node.js represents a “JavaScript everywhere” paradigm, unifying web application development around a single programming language, rather than different languages for server side and client side scripts.

npm is a package manager for the JavaScript programming language. It is the default package manager for the JavaScript runtime environment Node.js. It consists of a command line client, also called npm, and an online database of public and paid-for private packages called the npm registry. The registry is accessed via the client, and the available packages can be browsed and searched via the npm website. The package manager and the registry are managed by npm, Inc.

Download and install Node.js (this includes NPM) here: https://nodejs.org

Installing YARN

Yarn is a package manager for your code. It allows you to use and share code with other developers from around the world. Yarn does this quickly, securely, and reliably so you don’t ever have to worry.

Yarn allows you to use other developers’ solutions to different problems, making it easier for you to develop your software. If you have problems, you can report issues or contribute back, and when the problem is fixed, you can use Yarn to keep it all up to date.

Code is shared through something called a package (sometimes referred to as a module). A package contains all the code being shared as well as a package.json file which describes the package.

We will use Yarn to get a hold of various Javascript packages. Download and install Yarn here: https://yarnpkg.com/en/docs/install

Now that we have all the required software installed, let us go about putting this all together.

Putting it all together

Let us first start by creating a repository on GitHub to store your code and manage your changes.

• Log into GitHub.com
• Click Create a repository
  • In Repository name enter tableau-extensions-tutorial-part-one
  • Leave the repository as Public
  • Tick Initialize this repository with a README
  • Click on Create repository

Congratulations, you have created a GitHub repository with a single file called README.md. This file is used to give browsers an idea of what is inside your repository. MD files have their own markup language that gives some basic formatting. You can read more about it, if you are curious, click here: https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet 

Now that we have our GitHub repository setup, let us start up VS Code and import the directory.

• Open Visual Studio Code
• Go to View and click on Terminal
  • This is your command terminal which will send commands to your operating system.
• Let us test to see that we have all the software installed and available on your operating system.  
  • Enter the following command in the Terminal and press enter: git --version
  • Enter the following command in the Terminal and press enter: node --version
  • Enter the following command in the Terminal and press enter: yarn --version
  • In all cases, you should receive a single line with the version number. 
• If all goes well, let us clone your newly created GitHub repository to a local folder, we will make changes, and then commit and push those changes back to your repository.
  • Enter the following command in the Terminal and press enter: https://github.com/<your username>/<your repository name>
  • For example, git clone https://github.com/thoang1000/tableau-extensions-tutorial-part-one
  • If all is successful you will have copied the GitHub folder to the current folder set in your Terminal.

Note: if you are not familiar with command line navigation, please check out this cheat sheet: https://www.lifewire.com/list-of-command-prompt-commands-4092302

• Now go to File Menu and click Open Folder
  • Open the local copy of your directory that you have just created.
  • Once the folder is open you should see a single file called README.md
• We are going to change this and push our changes back up to GitHub
  • Double click the README.md
    • You should see the following: #tableau-extensions-tutorial-part-one
  • Change this to # Tableau Data Extension Tutorial Part One
  • Add in a new line below: This is my first Tableau Data Extension
  • Click Save
• On the far left side menu, you should see a number 1 appearing in a blue next to the middle most button. This means you now have a file that you have modified by not committed.
  • Click on the third button on the left sidebar to see the Source Control tab
  • In the Source Control: Git panel, click on the tick to commit your changes to your local repository
    • You will be asked for a message, enter in My first commit, and click enter.
    • Your update has now been committed locally
  • Now we will push the changes to GitHub by clicking on the … and select push
    • A GitHub window may pop up, or you may see it in your tasks bar
    • Enter in your credentials and click login
  • Now go back to your GitHub directory in your web browser (or Desktop and see your changes)

Boom, so with that all said and done you have now installed the required tools, created a GitHub repository, started up Visual Studio Code, and connected to your GitHub Directory. We will now go about coding your first Tableau Data Extensions Project.

Your Project

To start the project:

• Open up your terminal by going to View and then clicking on Terminal
  • Make sure your terminal is pointing to your project directory (see terminal commands)
  • Enter the following command: yarn init
    • This will create your project.json where your project yarn details will be installed; this file will be used for dependency management.
    • Enter whatever information you fancy with regards to the project details.
  • Now in your Explorer window create the following folders.
    • js – for your javascript application code files
    • css – for your component styling files
    • libs – for your third-party libraries (reuse is awesome)
  • In the root directory of your project, create the following files (make sure both start if a period)
    • .yarnrc
      • Add the following line: --modules-folder libs
      • This is where Yarn will save your third-party libraries
    • .gitignore
      • Add the following line: /libs/
      • This tells git to ignore the files within the libs directory. You should not be pushing your third-party libraries into your GitHub directory.

Now we are going to install two of the most common Javascript libraries, jQuery and Bootstrap, into our project; we will make use of these later in our project.

In your terminal, make sure you are in the root directory:

• Enter the following command and press enter: yarn add jquery
• Enter the following command and press enter: yarn add bootstrap
• Check your libs folder and see that you should have extra stuff added.
  • With those simple commands, you have added two of the most widely used web libraries to your project. As easy as that.

jQuery – jQuery is a lightweight, “write less, do more”, JavaScript library. The purpose of jQuery is to make it much easier to use JavaScript on your website. jQuery takes a lot of common tasks that require many lines of JavaScript code to accomplish and wraps them into methods that you can call with a single line of code.

Bootstrap – Bootstrap is a free and open-source front-end framework for designing websites and web applications. It contains HTML- and CSS-based design templates for typography, forms, buttons, navigation and other interface components, as well as optional JavaScript extensions. Unlike many earlier web frameworks, it concerns itself with front-end development only.

Now let us get the Tableau Data Extensions API.

• Go to the Tableau Data Extension API website and download and save the latest file to your project js directory.
  • Open the following in your web browser: https://github.com/tableau/extensions-api/tree/master/lib 
  • Right click and save the following: tableau-extensions-1.latest.min.js

Note: If anyone from Tableau is reading this, please add the Tableau Extension libraries to the Yarn repository. Pretty please.

To this point, we have done a lot of work, and I assure you, you won’t have to do this all the time. We will now finally create the Tableau Data Extension.

Extension

We will start by creating a file in your project directory called index.html with the following content: Hello World !!!. Yes, this is very exciting so far.

We will now use npm to install an http-server by entering the following command in the Terminal and pressing enter: npm install http-server -g

Now in the Terminal enter the following command to start a web server and run the index.html file: http-server. This will launch a web server which hosts your web page at http://localhost:8080. Copy this into your web browser to see the result.

We will now proceed to create a simple extension that will show all the worksheet on a dashboard. Create the following files in the project folder.

Note: we will walk through the exact details in the later tutorials.

TutorialOne.trex

<?xml version="1.0" encoding="utf-8"?>
<manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
  <dashboard-extension id="com.tableaumagic" extension-version="0.1.3">
    <default-locale>en_US</default-locale>
    <name resource-id=""/>
    <description>Tableau Data Extension Part One</description>
    <author name="Your Name" email="Your Email" organization="Your Org" website="https://tableau.toanhoang.com"/>
    <min-api-version>0.9</min-api-version>
    <source-location>
      <url>http://localhost:8080</url>
    </source-location>
    <icon></icon>
    <permissions>
      <permission>full data</permission>
    </permissions>
  </dashboard-extension>
  <resources>
    <resource id="name">
      <text locale="en_US">Tutorial One</text>
    </resource>
  </resources>
</manifest>

Index.html

<html>
    <head>
        <!-- imports the Bootstrap css files -->
        <link rel="stylesheet" type="text/css" href="libs/bootstrap/dist/css/bootstrap.min.css">
    </head>
    <body>
        <h4 class="text-center">Worksheets</h4>
        <!-- Displays a list of worksheets -->
        <div id="worksheets" class="p-2">

        </div>
    </body>
    <!-- imports the Javascript files -->
    <script type="text/javascript" src="libs/jquery/dist/jquery.min.js"></script>
    <script type="text/javascript" src="libs/bootstrap/dist/js/bootstrap.min.js"></script>
    <script type="text/javascript" src="js/tableau-extensions-1.0.0.min.js"></script>
    <script type="text/javascript" src="js/application.js"></script>    
</html>

js/application.js

'use strict';

(function () {
  $(document).ready(function () {
    // Initialises Tableau Data Extension
    tableau.extensions.initializeAsync().then(function () {
        refresh();
    }, function () { console.log('Error while Initializing: ' + err.toString()); });
  });

  function refresh() {
    // Gets a list of the worksheets and adds them to the web page.
    $("#worksheets").text("");
    tableau.extensions.dashboardContent.dashboard.worksheets.forEach(function (worksheet) {
        $("#worksheets").append("<button class='btn btn-secondary btn-block'>"+worksheet.name+"</button>");
    });
  }
})();

And that is a wrap, open up Tableau desktop, add some worksheets to the dashboard, and then add the Tableau Data Extension by browsing to the TutorialOne.trex.

Commit your work to GitHub, mine is located here: https://github.com/simplifyinsights/tableau-extensions-tutorial-part-one

Summary

In this lengthy tutorial, we have covered a large amount of ground. We looked at:

• Setting up the development environment
• Set up and published your project to GitHub
• Downloaded various web libraries
  • Tableau Extension API to access to the Dashboard’s worksheets
  • Bootstrap for the look and feel of the component
  • jQuery to manipulate and add remove the worksheets

I hope you enjoyed this tutorial and look forward to the other parts of this series where we will go through the following:

• Tableau Data Extension Part 2 – Accessing Underlying Data
• Tableau Data Extension Part 3 – Adding Extension Configurations
• Tableau Data Extension Part 4 – Adding Event Listeners

If you like our work, do consider supporting us on Patreon, and for supporting us, we will give you early access to tutorials, exclusive videos, as well as access to current and future courses on Udemy:

• Patreon: https://www.patreon.com/tableaumagic

Also, do be sure to check out our various courses:

• Creating Bespoke Data Visualizations (Udemy)
• Introduction to Tableau (Online Instructor-Led)
• Advanced Calculations (Online Instructor-Led)
• Creating Bespoke Data Visualizations (Online Instructor-Led)