4 Replies Latest reply on Feb 17, 2016 6:48 AM by Stephen Hellyar

    JavaScript brain dump - "what could go wrong?!"

    Russell Christopher

      Let's use this thread for hard won lessons when programming with the JavaScript API. Maybe we can save some other folks a few minutes here and there.

       

      I'll start:

       

      Manipulating sheets in a dashboard

       

      The API is somewhat worksheet centric (vs. dashboard-centric), and for good reason. It was created to allow a developer to add multiple worksheets from multiple workbooks into the same page and be "one ring to rule them all" in terms of filtering, doing mark selection, etc.

       

      As a result, if everything you want to show is already in a single dashboard, you'll have a little bit MORE work to do than usual. The reason for this is just about ALL of our methods (filtering, mark selection, etc) operate against the "active sheet". If you're showing a single worksheet, then duh - it's active. However, if you're showing multiple sheets inside your dashboard -- which sheet is active? Well the DASHBOARD worksheet is active - not the individual worksheets inside it which you actually want to filter. You need to "grab" one of those worksheets inside the dashboard before you get busy...

       

      SO, if want to filter a worksheet INSIDE a dashboard, you'll need to do something like this:

       

      function selectMarksInsideDashboard() {

       

       

          // First, access the workbook. Ask for the active sheet (getActiveSheet), which will be sheet "Dashboard"

          // (assuming that the Dashboard sheet has focus). Ask the Dashboard sheet for the the collection

          // of worksheets it contains (getWorksheets). Finally, pull "Profit v. Sales" from that collection and assign it

          // to a variable

          mainWorkbook = mainViz.getWorkbook();

          var worksheet = mainViz.getWorkbook().getActiveSheet().getWorksheets().get("Profit v Sales");

       

       

          worksheet.selectMarksAsync("Category", "Technology", "REPLACE");

      }

        • 1. Re: JavaScript brain dump - "what could go wrong?!"
          Russell Christopher

          Setting any option you want when rendering a viz

           

          When you render a viz with the API, we include a few options that you can use to do things like control viz size, toolbar and tab visibility, etc. 

           

          However, you also set just about anything you need to, as well. For example, filter and parameter values, a trusted ticket, etc:

           

          function renderVizMoreOptions() {

           

           

              // Define variables for viz

              var mainVizDiv = $("#mainViz");

              var mainWorkbookUrl = "http://" + serverName + "/t/SkunkWorks/views/JavaScriptTarget/Dashboard";

              var mainVizOptions = {

                  hideTabs: false,

                  hideToolbar: false,

                  width: mainVizDiv.parent().innerWidth() + "px",

                  height: mainVizDiv.parent().innerHeight() + "px",

                  //Filter Category field - note NO spaces between multiple filter values. Just a comma

                 Category: "Office Supplies,Furniture",

                  //Set Top Customers Parameter Value - note wrapping quotes on parameter name since it contains spaces

                  "Top Customers": 22,

                  //Set trusted ticket

                   ticket: "123456789",

                  onFirstInteractive: function () {

                      mainWorkbook = mainViz.getWorkbook();

                  }

              };

              //  Create viz

              mainViz = new tableauSoftware.Viz(mainVizDiv[0], mainWorkbookUrl, mainVizOptions);

          }


          • 2. Re: JavaScript brain dump - "what could go wrong?!"
            colum.mccoole

            Russell,

            I'm trying to get to grips with the Javascript API and my particular use case. I noted your comment "The API is somewhat worksheet centric (vs. dashboard-centric), and for good reason" above.  I am hoping to be able to embed a dashboard in a web page and programatically display associated text/annotations in a column (external to the dashboard) alongside. Ideally, I was looking to see if there was a way to embed a reference icon (such as 1, 2, 3) within the dashboard, which would then refer to my blocks of text externally.  These 'annotations' are not Tableau-specific annotations, as it's my understanding that the initial Javascript API doesn't handle this.

             

            Do you see this as being possible?

            Is there any way for me to uniquely identify a worksheet's placement within a dashboard so that I can associate that identifier with my block of text?

            Related to the above, is there a way for me to 'add' or 'position' an icon on the appropriate worksheet?

            Your remark that the API works better at handling multiple worksheets within a web page, rather than multiple worksheets within a dashboard within a web page worries me ... since that would make it more messy for me to achieve the layouts that the dashboard (especially in v8) is so good at assembling.

            If you or anyone else in the community has some suggestions on how I might solve this, that would be much appreciated.

             

            Colum

            dashboad_annotate.PNG

            ps. Is there anywhere I can get documentation on the functions in the Javascript API?  The pushback I get each time I ask is that they will only ship with the production version of Tableau 8.

            • 3. Re: JavaScript brain dump - "what could go wrong?!"
              Russell Christopher

                I am hoping to be able to embed a dashboard in a web page and programatically display associated text/annotations in a column (external to the dashboard) alongside. Ideally, I was looking to see if there was a way to embed a reference icon (such as 1, 2, 3) within the dashboard

               

              "Yes" to your basic scenario -- drive behavior in your portal when the user interacts with your viz.

               

              Example:

               

              http://russellchristopher.me/htdocs3/htdocs/index2.html

               

              • In the map, zoom into the Middle East
              • Single-select or Lasso-select Saudi Arabia, UAE, Oman, Bahrain
              • Note that "Other Resources" panel populates with "other reading" about what you are interacting with

               

              This is driven by Mark Selection event listeners.  We don't don't directly support the sort of "floating annotations" that you're talking about, but I suspect you could get there by creating one-small-worksheet per annotation (1, 2, 3), then add them to the dashboard as "floating objects". You'd then put event listeners on each one of those sheets.

               

              Your remark that the API works better at handling multiple worksheets within a web page, rather than multiple worksheets within a dashboard within a web page worries me ... since that would make it more messy for me to achieve the layouts that the dashboard (especially in v8) is so good at assembling.

               

              ps. Is there anywhere I can get documentation on the functions in the Javascript API?  The pushback I get each time I ask is that they will only ship with the production version of Tableau 8.

               

              See above - nothing really to worry about. This is only a "gotcha" because at first, many people will assume they can interact with the viz by always talking "to the dashboard" with JavaScript. In fact, they often need to "talk to the worksheet(s) inside the dashboard", instead.

               

              The JavaScript API documentation is being tech reviewed as I write - it won't be made available until the rest of the product is signed off on, however. Please use the "Reference Platform" (sample) until then. Not too much longer.

              • 4. Re: JavaScript brain dump - "what could go wrong?!"
                Stephen Hellyar

                Can this same approach be used to have the API switch between two dashboards within the same workbook. 

                 

                The normal switchView does not work with dashboards. 

                 

                Also, is there a way to use dashboard actions on one dashboard to filter a second dashboard (without immediately switching to it) so that the data is filtered when a user chooses to switch to it?  The workaround is pretty archaic, I embed a copy of a worksheet from the second dashboard onto the first and size it to 1px by 1px. 

                 

                Thanks