Developer Deep Dive: Building Your First Extension

awesome thankful thanks for patiently waiting until all the things are so good morning off hello and welcome to TC 19 at one of the best spots in the country my name is I shouldn't say car but we use my colleague Savior we bought software juniors at tableau I just want to talk a little bit about myself so I work for our I'm working for tableau for the past one and a half years so last year at TC I gave a talk on how do you build your web data connector from scratch a few months ago I joined extensions and today I'm extra pumped to show you how do you build your first extension from scratch welcome to our session developer deep dive building your first extension so these buckets represent what we're all covered by the developer platform team we do a bunch of stuff we do automation integration extensibility advanced analytics embedding and data connectivity but today we'll focus on extensibility which enables integrating external or third-party applications in tableau dashboard extensions can light up dashboards with energy dynamic parameters custom business and lots more sure what we are going to learn today we will know the tooling stack what's needed to build the extension we will go over major areas or extensions API how to use them and we will understand how to persist data in workbooks to ensure best and user experience we will also truly understand the security implications of building and running extensions and lastly I'm excited to show you how to build better extensions using best practices like typescript react and tableau UI so what is the dashboard extension think of it as a lightweight web web application that has a dual way communication with the tableau dashboard that to deliver custom insight rather than handing out a book definition let me just show you what it is so here I have a table open so you're a half table open and this is our famous superstore sample right so as you can see here there are a bunch of dashboards I'm on the overview dashboard here so I'm gonna pull in the little jigs up as like looking icon call extension ok so here I get an option to either select an extension from the gallery are from a local extension a head extension gallery it opens up the gallery where we have a lot of extensions I'm gonna scroll down to the extension that I'm most interested in called filter bookmarks and hit download I'm gonna go back to tableau click on my extensions and I'm gonna just point it to the one that I just downloaded ok cool so imagine you're interested in a very limited data set so I'm gonna filter for one year of data and a very limited profit ratio ok now I wanna bookmark those filters so I go configure to my extension I rename this to my favorite filter ok head save settings okay now when I reset the filters and imagine you come up to your desk every morning and you have this dashboard up now I can click this button and it'll instantly filter to a view that your interests interested in that is the power of extension running inside a blur dashboard so what really happens in the background right so to give me give you an overview when I grabbed in the extension object we get a mini web browser we call that as an extension Trenton now this Trenton opens the URL of where the extension is hosted now just as any other web page the web page that hosts the extension ships the HTML and JavaScript over to the client to render it now the fronton can send data back to the host where the data can be further processed the extensions Trenton has dual way communication with the tableau dashboard using JavaScript API using our extensions API which is a JavaScript API now this communication happens on the client side so what really makes up an extension there are three files you have the manifest file where this is the place where we load the extension from that that file has other attributes which we'll go over later now the HTML file and the JavaScript file from the core components of the extension which is where we'll spend majority of our time coding now for complex extensions there are more than three files if some of you folks have a feeling that they're the wrong session just because you said JavaScript don't worry we have an array of tools to help you build your first extension so what do we need first is a good text editor we're gonna use Visual Studio code for the purpose remember we talked about hosting the extension we are going to use node for that purpose and lastly we need to download the extensions API from github now this extensions api contains the it's a JavaScript library and the samples so now we have all of this are we ready to build our extension live on stage it's part of that I want to show you how our extension is finally going to look said that as our goal and then incrementally build that extension out hey guys cool awesome let's take a quick look so this time I am going to do this back here cool so this time I'm gonna go to the product dashboard here I'm going to put in the extension again and I'm gonna point it to my fully complete extension great now it gives you an option to select which sheet from the dashboard I want to select the product details sheet okay now I'm gonna select a few marks and it builds me a nice table with the values from the selected marks I can filter on these values in the search box or I can click on one of the columns here now look look at the sheet while I click on a subcategory column when it what happens it filters the sheet to the relevant values in subcategory now this is the extension we are going to build so we've broken building of our extension into six stages first stage it's set up this is where we will set up and configure the extension we will talk about our cool environment and tools and we'll create our basic files needed for extension at the end of it you will have a hollow world printing extension initialize we will talk about how your extension gets initialized you will as a bonus we will also talk about how to configure your extension Reed now this is where we learn learn to read some basic information from the dashboard listen here we'll learn about how to how to listen to different dashboard events and how to respond to them versus how do we solve the problem of storing the state of the extension why is it needed so the next time when you open the extension you know exactly where you left off last remember remember the two-way communication I talked about earlier where in the read section we read data from the dashboard here in the control section we go the opposite way and perform some actions on the dashboard so let's get started setup okay so this is my Visual Studio code and I have the extensions API download from github and on the left pane is where my project is loaded so let's focus on the Left pane for now so look at these two folders here it contains the samples right samples contains all of the extension samples we provide out of the box so the very first thing to do is to copy an existing sample don't be shy it's okay we can start off with copying and copying a sample so I'm going to copy the data sources sample make a copy of it I'm gonna rename to something more specific for our extension I'm gonna rename this to superstore you want to increase the brightness is it weiter okay give me one second we're gonna cry bring your lights down so you can see let me know if it's okay there okay great thank you for your patience again so let's focus on the left pane here okay and so what I'm going to do is I'm gonna create I have already created a copy right so I'm gonna rename this to something more specific for our extension so I'm gonna rename this to superstore and with what I'm going to do is open these three files in the bottom section okay and since I I'm also going to rename these files do you match our extension rename the HTML file to you this the JavaScript file to this and the manifest file to superstore okay so what really I'm gonna explain the setup a little bit here in the top section we have the snippets of code that we're going to copy from and the bottom section here is our actual extension files so the let's clear out the HTML content and the JavaScript content for now cuz it just contains the stuff from data source right let's talk about the manifest file here now what happens is the very first thing is the extension ID we want to change that to something more meaningful so we're gonna rename this to superstore and we're also going to rename the description to superstore sample and the Risso is too great now you remember I talked about the line of code that's most important in the manifest file that is the URL this tells tableau where to load the extension from we're going to point this to our superstore folder and the superstore dot HTML file we just renamed and this block over here is an optional block that lets you configure your extension I'm gonna hit save and move on to the HTML file I'm gonna copy some simple HTML and then just go over that the very the very first thing to do is to include your extensions API JavaScript library the next thing to do is you would want to include your JavaScript file here the newly created one and the last is the one in body and all that contains is just hello world and a test Dib you had save go back to table let's reset this closed design but on the extension and point to the one that we just created which is inside samples superstore superstore t-rex open it okay great there is our hollow world printing extension now you when you notice if you click the context menu you see configured and that is because of the optional block we added to the manifest file okay so let's go back now before we start typing in more code more JavaScript code referring to documentation is super important I'm going to quickly open up the documentation and show you what it is so get started here explain some of the key extension concepts now if you have questions as to how do i call an api extensions api reference is your friend now all of our API czar contained in the tab load or extensions namespace if you want to call an api called initialize async what you would do is you will call tableau that extension start initialized async in your javascript file let's move on to initialize stage the documentation if you remember we know there are some API functions that ended an async right what's that really so in order to do that we need to truly understand the difference between synchronous and asynchronous JavaScript Mic Check guys can you me alright so in the documentation you understood if you see you had suffixes that eighths that's at a sink right so let's talk about the difference between synchronous and asynchronous now imagine you're at Burger King waiting in queue ordering a burger your order gets processed after the person ahead of you correct that's the increment JavaScript where you need to wait for your turn so say Burger King has up their game allowing you to order from a mobile app now when you place an order from the app Burger King notifies you that it's complete then you go pick it up that's a synchronous JavaScript there is no waiting game now there are two other relevant JavaScript keywords that I want to talk about which is Java scripts promise and promise dot then now when you order from your mobile app barking notifies you that your order is being proud of processed which means Burger King is making a promise that your order will be ready right that's JavaScript promise now when your order is complete Burger King notifies you that your order is ready right that is similar to promise God then now tying all of this back when you call tableau the extensions initialize async you get a promise and while that call is being processed other pieces of code can execute now once the promise fulfills you can then proceed to do other things with the extensions API now let's see how initialize works I'm gonna go back to the editor but this time I'm gonna copy some JavaScript code okay so what happens here is once the document is ready I'm going to call tableau the extensions that initialize async and once initialization is complete that is in the den method right promise dot then what happens is I'm gonna just print have initialized now remember in the setup I talked about the configure context menu right so in order for that to work we need to tie that up with some JavaScript code I'm gonna do that right now so the first thing to do is to copy or to pass in a map like this so when you hit the configure button you need to tell JavaScript which function to call so in this case I'm gonna call this show choose sheet dialog function and all you do the next is you just implement that function okay and all the function does is it just prints choose sheet I'm gonna head safe I'm gonna go back to tableau and reload as you can see the extension is initialized and when I hit the configure button we produce sheep for the next part in my Xavier on stage who's gonna make this extension do way more useful things hello hear me in the back hello okay there we go thanks Ashwin for getting a set up and initialized so now before I start just one introduce myself my name is Xavier I'm a software engineer at tableau joined about two years ago and since then I've been primarily working on extensions last year I gave a talk at TC in New Orleans which was an introduction to extensions this year I'm here to help you on your journey to building your first one so let's get back to that so Ashwin left off we've initialized and now we're ready to use the rest of the extensions API and usually one of the first things you want to do after initializing is getting some data from the dashboard and that data can be as small and simple as just the dashboard name or it can be as big and complex as all of the underlying data that's actually powering your viz so these are this word cloud shows some of the api's that are available to get data from your dashboard as you can see there are a lot so let's start with dashboard you can access the dashboard from that line at the top of the slide and when you call that line you're gonna get an object return with those properties and methods and once we have the dashboard we'll be able to access our worksheets our filters our fields pretty much everything you can kind of think of it as our one of the main entry points into the extensions API so it's a really good place to start so let's go back to our extension and get some data from the dashboard okay so quickly before I get started coding you're gonna see demo helpers you're gonna see that variable throughout the demo and that's we've taken all of the code that isn't directly related to the extensions API and we put that in a file called demo helpers just to save time because there's a lot to go over and we don't have much time so the first thing I want to do is copy over some HTML and like I said we don't a lot of time so I'm not going to explain the HTML completely but this is just gonna set up the UI for our extension so I'll paste that here replace Ashwin's old body and now we can get to the fun stuff we'll copy some JavaScript and then we'll talk about what it does so I can copy this okay so we're gonna replace this old implementation of shochu sheet dialogue right here I wanna take a look at what it does so here in the first line you can see we use that line that I showed on the slide before to get the dashboard name then right below that we do the same thing we call dashboard about worksheets to get an array of all of the worksheets on the dashboard then from there we actually don't want the worksheet object worksheet objects we just want the names so we use the array map function to iterate over all of our worksheets and extract the names and put that into a worksheet names array then finally you'll see our first use of demo helpers the show dialog function is gonna pop up that dialog the ashram showed us before where we choose our sheet and you can see we pass in the dashboard name so we hit the dashboard name at the top of the dialog and we pass in our worksheet names so the buttons have our worksheet names on them so we can it save and go back to our extension now when we reload this oh let me go back to our code and I need to make sure that I call shochu sheet dialog after we initialize instead of writing that text so paste this right here after initialization within the dot then function and then I'll come back to our dashboard now when I reload now we get the dialogue but now we don't get our selected marks loading after we choose the dialogue or after we choose our worksheet so let's go back and add that functionality so after we choose our worksheet we want to load our selected marks so we'll copy this load selected marks function paste that into the bottom of our extension and talk about what it does again okay so here we reference our HTML to set the text to our worksheet name next we use demo helpers to get our worksheet and then we use get selected marks async to get all of the selected marks that are currently on the dashboard and you'll notice that this is another asynchronous function so if we want to use the marks that are returned from get selected marks async we need to do that inside of dot then then we use this populate data table function to populate that data table that Ashwin showed us before that has all of our selected marks and some extra insights right there to see we'll call populate data table with our selected marks to load up that data table and now all we need to do is make sure that load selected marks gets called when we choose one of our worksheets so we can do that by actually passing that into our show dialog function all right because this is the function that creates a dialog so if we want those buttons to call the load selected marks function this is where we'll put it okay now we can go back to our dashboard and we'll select some marks and that when we reload we should see those marks and here we have our selected marks with some extra insight but now if we want to change our selection if I just select this single mark you can see that change isn't reflected in the extension it's still just all of our initial selection selections so how do we how do we account for that if we just start brainstorming we can call get selected marks async every few seconds to see what new marks have been selected that's definitely one option or we can actually just listen so event listeners are really useful when you want to know in the code when something on your dashboard changes there are four different kinds of events in the extensions API they're all accessed through the tableau tableau event type enum and you can think of adding an event as a two-step process step one you're gonna write a function that you want to be called when the event occurs so in our sample that's the event handler function and that function takes one parameter which is the event object and that's gonna have information about the event that occurred so that you can take action based on that event then step two you're gonna add the event listener so for filter and mark selection changed events those are worksheet events so you'll add that event listener to a worksheet object and then for parameter or setting change events you'll add that event listener directly to the parameter or settings object and then the last thing to remember about event listeners is when you call the add event listener function that's going to return another function that you can call to then remove that event listener that you just added so does anybody want to take a guess what kind of event listener we're gonna add to our extension call it out think you know try again up heard it back there mark selection so when we select our marks we want that to get updated in the extension okay so the first thing we'll do we'll copy this variable that we're gonna use to store the function that's returned when we call addeventlistener and then we'll copy this code that actually adds the event listener and we want to make sure that we we add the event listener as soon as we get the selected marks the first time so right away we're ready to get any new selection so we'll paste this code right here under get selected marks async and then we could take a look so right here you'll see step one where we define our event handler function and all its gonna do is call load selected marks so we show that so we load our marks again and then down here is where we actually add the event listener you can see we do mark selection change as the event type and mark selected event handler as our event handler function and here we store the unregister function in our remove event listener variable now the last thing we want to do here is copy this code that checks to see if we've already added an event listener if we have let's remove it because we don't want duplicates and we'll paste that right at the top of load selected Mark's async okay so now when we go back to our extension and we reload we should be able to select new marks without having to reload every time so here we have our single mark selected let's select some more and that immediately gets updated awesome so that's how you can add an event listener it's a two-step process step one write your a event handler function step two add the event listener to the object okay now we come to persist so you've probably noticed that every time we reload our extension we have to choose the sheet but we're just choosing the same sheet every time so why don't we just save that after the first election and what if we actually had more settings and configuration than just that sheet name what if it was actually kind of a hassle to set it up every time in that case it would be really useful to just soil that information directly in the workbook so then we could reload our extension without having to go through the setup again we could even close the workbook send it to somebody else have them reopen it and have the same settings applied without them having to go through setting it up so we can actually achieve that through settings so you can access settings by that line at the top tab load extension settings it's going to return an object with the properties and methods shown here and settings allow you to store key value pairs directly in your workbook so you can call tableau settings that set to set a setting the key is gonna be the key that you use to retrieve it later the value is what actually gets stored in the workbook then you can use save async to actually persist those settings into the workbook so if you don't call save a sink and you reload your extension after setting a setting you're just going to lose that setting so make sure to always call save async and finally you can call get to retrieve your settings so let's go back to our code and save our sheet name using settings so we'll copy this safe sheet and load selected marks function so we can see that first it saves our worksheet name with the key sheet and then we call save async to persist that in the workbook and then we call load selected marks and we do that because we're going to replace our call to load selected marks with a call to this function so we'll copy this and come up to where we call where we pass in load selected marks and we'll replace it with our new function and then we'll also copy this code paste it in initialization we're gonna remove our call to shochu sheet dialog and now let's take a look at what this does so the new code I had it starts right here on this line the first thing it does is it retrieves it tries to retrieve our saved sheet name using settings if that sheet name exists that means we already say we've already selected a sheet previously so we'll just load our selected marks right away if it doesn't exist will show the choose sheet dialog and ask the user to choose a sheet okay so let's hit save and go back to our dashboard and see if it works so now when we reload we'll choose it the first time let's reload again and now we don't have to make that selection also one more thing to note we saw the configure option before if we look at that now now that we've actually implemented shochu sheet dialog to show the dialog if we click on configure now it shows us that dialog yep okay so finally we get to control so to me control is one of the most powerful and interesting aspects of the extensions API and that's because we actually get to control the dashboard from the extension so we can do things like select marks change parameter values even toggle the visibility of the extension zone or other zones on the dashboard but in our extension we want to apply a filter so if we think back to Ashwin's demo when he clicked on the column headers that actually filtered to the vault to the values in the column so we want to add that functionality now we can do that with apply filter async so apply filter async has three required parameters the first one is the field name this is the field that you want to filter on the second is a list of values that you want to filter to and the third is how you want the filter to be applied you want to replace an existing filter add a new filter something like that so let's go ahead and add that functionality to our extension so first we will copy this filtered columns array that we're going to use to store the names of all the fields that we filter and you'll see why we do that later next I'll copy this filter by column function paste that into the bottom of our extension and take a look as usual okay so you can see we use demo helpers here twice first to get the column values these are all the values going down in the column then we use it again to get the worksheet and then we actually call apply filter async you can see the first parameter first argument is our field name so this is going to be the column header second argument our column values and the third argument is replaced because we want to replace any existing filters and then here we store the name of the field that we filtered it's no let's go back to our dashboard and we should be able to filter so we'll select the single mark let's filter to our segment to consumer oh let me reload again see what's oh okay I forgot one step we need to make sure we call filter by column so I pasted it here but you can see it's grayed out we haven't actually called it anywhere so we're actually just gonna pass this into the populate data table function this takes another optional parameter we're passing it in here because this is where we build the data table so if we want this filter by column function to be executed when we click on one of the headers we need to do that when we build the data table so we'll save that go back to our extension and now we should be able to apply some filters so I'll click on segment and there it applies the filter but now if we actually wanted to clear these filters we don't actually have a way to do that so let's add that functionality now to so all we need to do is copy this reset filters function we'll paste that to the bottom and then we'll also copy this line of code that ties our reset filters button our HTML reset filters button to the reset filters function so that when we click it it resets the filters and I'll just paste that after we initialize so that's setup right away so now when we load this and we hit our replay button which is actually say reset oh okay so it looks like it's not working actually but that is a good segue into debugging so debugging an extension is fairly simple on Mac we'll open up terminal on Windows go open up command prompt then you'll enter that command scene there the path to tableau your tableau installation and then regardless of your operating system you'll open up Chrome to local host port 86 96 or whatever port you supplied as an argument there so we've already launched tableau with debugging enabled so I'm going to go ahead and open up Chrome till sorry to localhost 86 96 did we launch this with debugging enabled already okay so let's read I don't think we have this launch with debugging enabled so I'll go ahead and see if I can do that Thank You Ashley 86 96 so now the tableau is relaunching with remote debugging enabled we'll need to bring our extension back in yeah oh okay so we launched it with a different word and I'll see he clicked on see there was a couple options here but we know ours is called super sample so we'll click on will click on that one and let's try it we'll hit this so let's select some marks again apply the filter and we see that our button still doesn't work so now we can go back to our debugger and we see right away that there's an error makes that bigger for you so clear filters async is not a function that makes sense because clear filters async is not a function I think we've made a typo and we so if we can click on this and see exactly where our error is so let's go to reset filters and now they should say clear filter async instead of clear filters async so let's go back to our extension and reload this now when we click our reset filter button you can see it reset the filter if you didn't catch that I'll filter again to subcategory filter gets reset awesome so we did it we built an extension in the past hour we learned how to get set up now to get initialized how to get data from our dashboard how to add an event listener how to persist settings in the workbook finally how to call dashboard actions from your extension and we even saw how to debug when any of that isn't going right so now I'd like to pass it back to Ashland to talk a little bit about security and best practices can you guys yummy perfect okay so now that we built up we build our cool extension there are some additional considerations you need when building your extension first you need so this makes sure you will be our extension as well proofed and you all have a great developer experience on a high level we have security coding with less errors and native looking extensions security now extensions in the current world can be hosted anywhere which means it makes them extremely flexible but at the same time are subject to data exfiltration which means your personal data can get outside tableaus environment and that's not great right how do we solve the problem we built sandbox extensions sandbox extensions are a class of extensions that are hosted in an own tableau environment that where they are exfiltration cannot happen in other words if you are thinking of building an extension which doesn't need additional Network calls or additional you know it doesn t connect connecting to third-party sites go for sandbox extensions if you want to know more there's a whole new session on sandbox extensions is happening tomorrow at 10:30 as a bonus you even get to meet the developers of sandbox extensions coding with less errors for some of you in the crowd who are like are you kidding me another language I was like you a few months back now I'll rather prefer typescript to JavaScript what makes typescript so great simple it's a typed superset of JavaScript for example in JavaScript you can have something really confusing where you can assign to two person name apparently it's okay whereas in typescript once you type person name to the type string and then you've if you assign to it'll complain as you type that line isn't that cool as of extentions api 1.3 we've introduced typescript support for extensions you can still build things in JavaScript but if you want to build extensions with less errors use typescript one other advantage it autocompletes some lines of code for you also you get a brand new developer environment which means you can it lets you host your typescript extension so let's see this in action I'm gonna close all of these okay now as you can see here we provide JavaScript samples and also we provide typescript samples right I've built the same exact superstore extension in typescript as you can see here the super instead of a javascript file we have a typescript file now let's get let's let me show you something interesting now if you all remember this line during Xavier's demo there was a typo in that line right now let's see if we can type the same thing in typescript and what it gives for us I'm gonna type in worksheet as they type in CL it tells me what our api's are available right it autocompletes I can select that and once I insert brackets it pulls in the documentation right in the editor you don't have to go back to Docs and refer to it right it haven't tells me how do I use this API I need to pass and feel name so here my variable is called column name I'm gonna pass on that head safe now I talked about typescript developer environment right so all you have to do is in your terminal just have to type in NPM run death now this starts up your typescript developer environment and host this extension on typescript alright let's go back the last best practice how do you build native looking extensions right you need to know two things for that one is react in the other establish I react is a quick one one-liner would be is a declarative library that allows you to control the flow of your application it has a lot of advantages but some of them being you can code things and react components which is easy to test and reuse in fact if you use react you can build really fast and efficient rendering web applications now what is tableau UI table UI is the library developed by tableau that lets you create react components that has the native look and feel of tableau so if say if you're building an extension that has an HTML button using react and tableau UI you can have a native looking tableau button alright so let's see the magic of react and table UI coke so this time I've opened up the editor but it points to a brand new project I've built just for the session now this contains the same exact superstore extension but it is built with tableau UI react and typescript and as you can see it's called a dot TSX file which means it's a type script and a react file and all I do here is i when i do npm start it will host my react extension and it'll start up the developer environment for that now when I go back to tableau let me reset this okay I'm gonna close this and I'm going to open up our react extension which is inside here here and here okay and as you can see here here is our native looking extension and if you look closely to the buttons they look very native to tableau so that's the power of tableau UI if y'all fell asleep now's the time to wake up we talked to a lot of stuff today we talked about how to get your tool set up to build extensions how to use the extensions API the six stages of building extensions and also the basic files needed for extension and it's up to you to Goble your own here are four things I'd like you to remember from today's talk read the tutorials never start from scratch use Chrome debugging and always use best practices here is that a view of our developer program and what we provide we provide an array of things you can come down visit us at the booth downstairs will tell you what it is about but it gets you some of the cool tools and sneak peeks into our latest features here are some additional resources from our data deaf community we will include all the slights and resources as possession content here are other related sessions you can definitely check them out in your app I would highly recommend you to work with extensions API the hands-on training and the extension security I know this is not really ideal we had a lot of technical glitches and some other issues but feedback is really important please complete the session survey in the mobile app thank you and we'll stay back for any questions [Applause]

Channel: Tableau Software

Views: 2,912

Rating: 5 out of 5

Keywords: Visual data, Visual analytics, Business analysis, Business analytics, Business analysis tool, Data analytics tool, Data Analytics, Analytics, Analytics platform, Cloud application, Business analytics platform, data analysis, data visualization, business dashboards, business intelligence, tableau, tableau software

Id: Mgl5IWy5lws

Length: 52min 35sec (3155 seconds)

Published: Fri Nov 15 2019