Skip to main content

Decipher Support

All the topics, resources needed for Decipher.

FocusVision Knowledge Base

Best Practices for Dashboard Programming

1:  Best Practices

When it comes to building software, best practices are the techniques or procedures that are considered to be the most correct or effective. Please see below for common tasks that you may need to perform when building a dashboard.

For each task below, there will be a comparison between the procedure that uses best practices and one that does not. Both are shown because there are some situations where the alternative approach may be preferred.

1.1:  Upload a File

Instead of using an FTP program to upload files to the server, the Research Hub is equipped with an easy-to-use file uploading system.

For example, to use an image in your project, you must first upload it to the server and grab the URL to reference it by. Listed below are two methods for uploading files to the server, one that uses best practices and one that uses the alternative route. 

 

Using the File Manager
(Best Practices)

Using an FTP client
(Alternative)

1. Click on the project menu    

2. Beneath Actions, select  Upload System Files

3. In the top-right corner, click    Add Files

4. Select the file from your computer that you wish to use and click   Upload

5. Once the upload is complete, click on the file name that you just uploaded. This will redirect you to the file where you can copy the URL

6. Go back to your dashboard and use this URL to reference your file

Done!

1. Open an FTP client such as FileZilla or SFTP

2. Connect to the server

3. Navigate to your project's static directory

4. Select and upload the file you wish to use

5. In a browser, navigate to the file you just uploaded by manually typing in the address and copy this URL

6. Go back to your dashboard and use this URL to reference your file

Done!

Though the number of steps is roughly the same for each, using the file manager is the quickest way to upload a file.

Learn more: Using the File Manager

1.2:  Add Javascript & CSS

You can add Javascript and CSS code to create beautifully interactive dashboards. These languages are always available to you and can be incorporated in one of two ways. The preferred way is to create static files that the system will automatically detect and include, and the easiest way is to write the code inline, directly to the dashboard. Both methods are detailed in the sections below.

1.2.1:  Static Files

The system will automatically detect the presence of dashboard.js or dashboard.css files located in your project's static directory. If found, these files will be included and ran on each page of the dashboard.

These files must be named dashboard.css or dashboard.js and located in your project's static directory.

dashboard.css

For example, a file named dashboard.css containing the following code updates all of the table headers to the color blue:

h4 { color: blue !important; }

dashboard.js

The following code is a callback function and can be used as a starting template for building great Javascript functionality into your dashboard. Add this code to your project's dashboard.js file and you will see a "Hello world!" dialog box appear when you view the dashboard.

Use the following template to speed up your workflow!

$(document).on('globalUpdate', function() {
    // BEGIN YOUR JAVASCRIPT CODE HERE
    alert("Hello world!");
    // END YOUR JAVASCRIPT CODE HERE
});

1.2.2:  Inline Code

Javascript and CSS can also be written directly inside the dashboard. To write inline code, you must use the html keyword. For example, the following code produces the same result as the two examples above that use static files:

html
<style>
    h4 { color: blue !important; }
</style>
<script>
    $(document).on('globalUpdate', function() {
        alert("Hello world!");
    });
</script>
end

The code above works just like it would inside a normal HTML document. The CSS code is included using the <style> tag and the Javascript code is executed using a self-invoking jQuery function within the <script> tag.

If you add the code above to your dashboard project, you will see a blank white box. This is because there is no visible content in the html tag (everything between the <style> and <script> is executed, not displayed). 

To avoid this blank white box, combine all of your Javascript and CSS code to a pre-existing html tag that has content visible in the dashboard viewer. For example, consider the following example:

html width=3
<h1 class="main-title">Customer Satisfaction Survey</h1>
<h4 class="sub-title">Quarter 4</h4>
end

html width=3
<style>
    .main-title { color: green; text-align: center; }
    .sub-title { font-weight: bold; }
</style>
end

This code produces the following result:

See the blank white box? To obtain the same result without the blank box, simply combine the CSS code with the html element that contains visible content:

html width=3
<h1 class="main-title">Customer Satisfaction Survey</h1>
<h4 class="sub-title">Quarter 4</h4>
<style>
    .main-title { color: green; text-align: center; }
    .sub-title { font-weight: bold; }
</style>
end

This code produces the following result:

When writing inline Javascript or CSS code, you can safely add it to a single html tag and it will execute for all dashboard pages. If your project does not contain an html tag to add inline code to, then there is no way to avoid the blank white box.

1.3:  Add or Remove Company Branding

By default, dashboard projects are branded with the Decipher logo. This branding can be changed or removed at anytime. 

The preferred way is to overwrite the template using the nstyles file. An alternative approach would be to write inline Javascript code that updates the branding on-the-fly. See below for details.

1.3.1:  Using Javascript

You can update the logo with Javascript by modifying the branding image element. The following code replaces the branding image and can be placed in the dashboard.js file or written inline using an html keyword tag:

function swap_branding(img_url) {
   $("#branding img").prop('src', img_url).css({'width':'100px'});
}
swap_branding('/s/images/newLogo.gif');

If you wish to remove the branding altogether, use the following code:

$("#branding img").remove();

Learn More: Add Javascript & CSS

1.3.2:  Using the nstyles file

  Requires Decipher Cloud

The style *dashboard.branding can also be overridden in the client or survey directory's nstyles file to modify branding. The image can be replaced using the following code: 

*dashboard.branding:
<div id='branding'>
    <img src='/s/images/newLogo.gif' alt='company logo' />
</div>

If you wish to remove the branding altogether, leave the attribute blank:

*dashboard.branding:

1.4:  Useful Functions & Patterns

The following table contains links to useful Javascript functions that you can add to your project's dashboard.js file or html tag.

Click on an item to jump to that section.

  • Tab Navigation:  Allows you specify a tab to navigate to. For example, click_tab( 1 ) will navigate to the first tab.
  • Get Active Tab:  Returns the number representing the current, active tab.
  • Go To Next or Previous Tab:  Uses "Tab Navigation" and "Get Active Tab" to create a dynamic tab navigation system.
  • Auto-Navigate Tabs:  Navigates each tab after a specific amount of time. Returns to the first tab when the cycle is complete.
  • Javascript Code Template:  Generic template for adding Javascript code to your project.
  • Auto-Refresh Dashboard:  Refreshes the dashboard page after a specific amount of time.

1.4.1:  Tab Navigation

The following Javascript function clicks dashboard tabs for you. This is necessary when your project needs to navigate to a particular tab without forcing the user to click the tab itself.

Input: The number representing the tab you want to click
Output: The tab will be clicked

Javascript Code:


function click_tab( tab_number ) { 
    var tab_index = tab_number - 1;
    $('[href="#tab-' + tab_index + '"]').click();
    return;
}

Javascript Code Explanation:
The function above accepts a number value representing the tab you wish to navigate to (must be 1 or more). It uses jQuery to select the corresponding tab and calls the click function.

Example XML:

page Tab 1

html
<a href="javascript: click_tab(1);">GoTo First Tab</a> | 
<a href="javascript: click_tab(2);">GoTo Second Tab</a> | 
<a href="javascript: click_tab(3);">GoTo Third Tab</a>
<script>
function click_tab( tab_number ) { 
    var tab_index = tab_number - 1;
    $('[href="#tab-' + tab_index + '"]').click();
    return;
}
</script>
end

page Tab 2
page Tab 3

Demo:
Click here for a live demo!

1.4.2:  Get Active Tab

The following Javascript function returns the tab number for the active tab that is currently being viewed. 

Input: None
Output: A number representing the active tab

Javascript Code:


function get_active_tab() {
    return $(".dashboard-tabs").find("li").index($(".ui-tabs-active"))+1;
}

Javascript Code Explanation:
This function simply selects the active tab and returns the tab number based on an available attribute.

Example XML:

page Tab 1

html
<a href="javascript: click_tab(1);">GoTo First Tab</a> | 
<a href="javascript: click_tab(2);">GoTo Second Tab</a> | 
<a href="javascript: click_tab(3);">GoTo Third Tab</a>
<script>
function click_tab( tab_number ) { 
    var tab_index = tab_number - 1;
    $('[href="#tab-' + tab_index + '"]').click();
    return;
}
function get_active_tab() {
    return $(".dashboard-tabs").find("li").index($(".ui-tabs-active"))+1; }

var t = setInterval(function() { click_tab(get_active_tab() + 1); }, 5000);

</script>
end

page Tab 2
page Tab 3

Demo:
Click here for a live demo! The tabs automatically progress after 5 seconds.

1.4.3:  Go To Next or Previous Tab

The following Javascript code combines the previous two examples to create working tab navigation buttons. Use this function to navigate to the next or previous tab. This function will loop around when the ends have been reached.

Input: "next" or "previous"
Output: The next or previous will be clicked

Javascript Code:


function navigate_tabs( direction ) {
    var current_tab = get_active_tab(),
          last_tab = $(".dashboard-tabs li").length,
          next_tab = 1;

    if (direction == "next") {
        if (current_tab < last_tab)
            next_tab = current_tab + 1;
    } else {
        if (current_tab > 1)
            next_tab = current_tab - 1;
        else
            next_tab = last_tab;
    }
    click_tab(next_tab);
}

Javascript Code Explanation:
The function uses the click_tab and get_active_tab functions to create navigation system. If you click "Next" while on the last tab, it will cycle back to the beginning. If you click "Previous" while on the first tab, it will jump to the last tab.

Demo:
Click here for a live demo!

1.4.4:  Auto-Navigate Tabs

Using the examples above, it is not difficult to setup an automated system that cycles the tabs after a specific amount of time. Using the functions click_tab, get_active_tab and navigate_tabs, we can setup a timer to cycle the tabs automatically.

Input: None
Output: The tabs will automatically cycle, looping after the end is reached.

Javascript Code:


var t = setInterval(function() { navigate_tabs( "next" ); }, 5000);

Javascript Code Explanation:
This code navigates to the "Next" tab after 5 seconds.

Demo:
Click here for a live demo!

1.4.5:  Javascript Code Template

When using Javascript to modify your dashboard, you must wait until the DOM elements are ready. Use the following self-invoking jQuery function template to execute Javascript code when the dashboard elements are ready. Replace the alert function call with your code.

Input: None
Output: None

Javascript Code:


(function() {
   'use strict';
   $(document).on('globalUpdate', function() {
     // BEGIN YOUR JAVASCRIPT CODE HERE
     alert("Hello world!");
     // END YOUR JAVASCRIPT CODE HERE
   });
})();

Javascript Explanation:
When the dashboard is ready, it provides a callback named 'globalUpdate'. You can use this callback to create a function that will execute after all of the elements have been loaded. If you attempt to reference or modify elements without this function, you may not get the desired result because the elements haven't loaded yet.

Learn more: Race condition (Wikipedia)

Demo:
Click here for a live demo!

1.4.6:  Auto-Refresh Dashboard

When a project is fielding, you can update the data calculations by refreshing the dashboard. To do this automatically, simply add the following code to your project.

Input: None
Output: None

Javascript Code:


var t = setInterval(function() { window.location.reload(true); }, 300000);

Javascript Code Explanation:
The code above will refresh the dashboard page every 5 minutes.

Demo:
Click here for a live demo!