In this article
This article describes best practices for common tasks that you may need to perform when building a dashboard. Best practices are the techniques or procedures that are considered to be the most correct or effective.
Each task listed below compares 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: Upload a File
Instead of using an FTP program to upload files to the server, the Portal 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 identify 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 |
Using an FTP client |
|---|---|
|
1. Open your project from the portal. 2. In the navigation menu at the top of the project page, click Build. Then click More Tools and 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. |
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. |
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: Uploading System Files
2: Add Javascript & CSS
You can add Javascript and CSS code to create beautifully interactive dashboards. These languages are always available 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. The easiest way is to write the code inline, directly to the dashboard. Both methods are detailed in the sections below.
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.
2.1.1: 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; }
2.1.2: dashboard.js
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
});
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. 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:
Notice the blank white box. To obtain the same result without the blank box, 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 one box with content, instead of two boxes.
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.
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 is to write inline Javascript code to update the branding dynamically.
3.1: 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:
3.2: 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: 2: Add Javascript & CSS
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.
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
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 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
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 tab 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.
4.4: Auto-Navigate Tabs
Using the examples above, you can 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, you 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.
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 have not loaded yet.
Learn more: Race condition (Wikipedia)
4.6: Auto-Refresh Dashboard
When a project is fielding, you can update the data calculations by refreshing the dashboard. To do this automatically, 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.