The DashXML framework provides a method for creating dashboards that combine Yellowfin content and custom items without the need for programming. The dashboards are configured in a single XML document that describes each element on each tab as a widget. All layout and styling can be achieved via customised CSS.
DashXML is designed to be implemented by a highly advanced user. This user would either be a developer, or someone with a strong technical background.
In order to implement a DashXML solution the user would require the following technical skills as a minimum:
Implementation | Skills | Description |
---|---|---|
Basic |
| This implementation would use reports (tables, charts, multi-charts, maps) called from a Yellowfin instance, with custom images and styling applied. This would not include the use of advanced CustomHTML widgets that use custom JavaScript, only purely HTML. |
Basic + Custom Widgets |
| This implementation would use reports (tables, charts, multi-charts, maps) called from a Yellowfin instance, with custom images and styling applied. This could also include the use of advanced CustomHTML widgets that use custom JavaScript and HTML. CustomHTML widgets can be used to pass Yellowfin report results through to other visualisation libraries. |
Basic + Third Party Security |
| This implementation would use reports (tables, charts, multi-charts, maps) called from a Yellowfin instance, with custom images and styling applied. This could also include the use of a Java Servlet Filter to apply source filters based on external user credentials, while still running reporting content as the nominated Yellowfin user (from the web.xml file). |
No user security is offered out-of-the-box with DashXML. Third party user security can be implemented using a Java Servlet Filter. This can test access for a user for a given dashboard, apply appropriate source filters for that user, and run the reports as the nominated user specified in the web.xml file.
Source filter can be passed for a particular session to enable row-level security. Source filters will need to be defined in the Yellowfin interface, and then referenced within the DashXML.
DashXML does not replicate all functionality found in the Yellowfin interface. Some of the functions that can't be replicated within DashXML include:
Edit your Yellowfin web.xml file.
Navigate to \Yellowfin\appserver\webapps\ROOT\WEB-INF\
and edit the web.xml file. You will need to uncomment the following section in order to enable Web Services.
Update your file from this:
| To this:
|
Save your changes.
Yellowfin Tomcat | Separate Tomcat |
---|---|
Copy the DashXML folder (from your downloaded zip) into your \Yellowfin\appserver\webapps\ directory. You should now have both a ROOT and DashXML directory sitting within webapps . | Copy the DashXML folder (from your downloaded zip) into your \Tomcat\webapps\ directory. You will now have a DashXML directory sitting within webapps. |
\webapps\DashXML\WEB-INF\
and edit the web.xml file. You will need to make three changes to this file, in order for DashXML to be able to connect to your Yellowfin instance.Set your Yellowfin URL.
<init-param> <param-name>PathToServer</param-name> <param-value>http://server-name:7171</param-value> <!-- update to Yellowfin server --> </init-param> |
Set your Yellowfin username.
<init-param> <param-name>Username</param-name> <param-value>admin@yellowfin.com.au</param-value> <!-- update to Yellowfin username --> </init-param> |
Set your Yellowfin password.
<init-param> <param-name>Password</param-name> <param-value>test</param-value> <!-- update to Yellowfin password --> </init-param> |
In order to get started with DashXML walk through the following steps to familiarise yourself with the development process.
Edit your dashboard.xml file.
Navigate to \DashXML\WEB-INF\
and edit the dashboard.xml file. This is the file you will use to build your dashboards. To start with, all you need is this:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application-definition> <!-- Start Dashboard --> <dashboard> <id>1</id> </dashboard> </application-definition> |
Edit your dashboard.css file.
Navigate to \DashXML\css\
and edit the dashboard.css file. This is the file you will use to style your dashboards. To start with, it will look like this:
|
Paste the Report URL into a text file and locate the UUIDs as follows:
URL | UUID | Description |
---|---|---|
http://localhost/RunReport.i4?reportUUID=39fc0f87-77c8-4a5b-aec3-2a04ed78bae3&primaryOrg=1&clientOrg=1&filterUUID9d1dc0bb-ab9a-4852-b408-a9a6b94af66a=2015-09-01%5C%7C2015-09-30 | This is the full Report URL. From here you can locate the Report UUID and any Filter UUIDs you need. | |
http://localhost/RunReport.i4?reportUUID=39fc0f87-77c8-4a5b-aec3-2a04ed78bae3&primaryOrg=1&clientOrg=1&filterUUID9d1dc0bb-ab9a-4852-b408-a9a6b94af66a=2015-09-01%5C%7C2015-09-30 | 39fc0f87-77c8-4a5b-aec3-2a04ed78bae3 | This is the Report UUID, which will be referenced in the DashXML in order to display the results of the report on the dashboard. |
http://localhost/RunReport.i4?reportUUID=39fc0f87-77c8-4a5b-aec3-2a04ed78bae3&primaryOrg=1&clientOrg=1&filterUUID9d1dc0bb-ab9a-4852-b408-a9a6b94af66a=2015-09-01%5C%7C2015-09-30 | 9d1dc0bb-ab9a-4852-b408-a9a6b94af66a | This is the Filter UUID, which will be referenced in the DashXML in order to pass filter values through to the report displayed on the dashboard. |
Set up the Dashboard
To begin, you will need the <application-definition>
and <dashboard>
elements. As we're creating our first dashboard, the ID can be '1'.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application-definition> <!-- Start Dashboard --> <dashboard> <id>1</id> </dashboard> </application-definition> |
Prepare the User Prompt date filter
In order to ask the user for filter values you will need to include the <filter>
element. What we've done in this example is set up four possible options for the user for a date filter; All Time, Year, Month, Custom.
The All Time filter has been defined within the XML to cover a 200 year range, effectively covering all data in our database. The Year and Month filters have been set using predefined ranges within the XML that will be dynamically set in relation to the current date when the report is run. The Custom range has been left as completely User Prompt, meaning that the user will be provided with date pickers to choose their start and end dates.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application-definition> <!-- Start Dashboard --> <dashboard> <id>1</id> <!-- Year Filters --> <filter> <sync>true</sync> <datatype>DATE</datatype> <!-- This is the data type expected for the filter, in this case we're looking for dates. --> <name>dateFilter</name> <!-- This is the name of the filter, to be referenced by reports in their filterMap elements --> <operator>BETWEEN</operator> <!-- This is the date filter operator that we used in Yellowfin. This means we are expecting a start and end date. --> <styleClass>topFilter</styleClass> <!-- This is the CSS class name we've assigned to the filter for styling purposes from our dashboard.css file. --> <options> <!-- This is the first option available to the user - a hard coded date range to cover all dates. --> <title>All Time</title> <value>1900-01-01\|2100-01-01</value> <defaultOption>true</defaultOption> </options> <options> <!-- This is the second option available to the user - a predefined range that covers the year to date based on current date. --> <title>Year</title> <typeCode>PREDEF</typeCode> <value>YEARTODATE</value> </options> <options> <!-- This is the third option available to the user - a predefined range that covers the month to date based on the current date.--> <title>Month</title> <typeCode>PREDEF</typeCode> <value>MONTHTODATE</value> </options> <options> <!-- This is the last option available to the user - a user prompt date calendar picker where they can define two custom dates. --> <title>Custom</title> <prompt>true</prompt> </options> </filter> </dashboard> </application-definition> |
Set up the Report and Filter Map
In order to display the report and pass through the filter values that the user selects you will have to include the <report>
and <filterMap>
elements. We've used the UUIDs we identified earlier in order to populate the elements, defined the report to display as a CHART, and styled it with the canvasChart class from our css file. The filter map has linked the filter UUID we found on the report, to the dateFilter that we defined in the previous step.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application-definition> <!-- Start Dashboard --> <dashboard> <id>1</id> <!-- Year Filters --> <filter> <sync>true</sync> <datatype>DATE</datatype> <name>dateFilter</name> <operator>BETWEEN</operator> <styleClass>topFilter</styleClass> <options> <title>All Time</title> <value>1900-01-01\|2100-01-01</value> <defaultOption>true</defaultOption> </options> <options> <title>Year</title> <typeCode>PREDEF</typeCode> <value>YEARTODATE</value> </options> <options> <title>Month</title> <typeCode>PREDEF</typeCode> <value>MONTHTODATE</value> </options> <options> <title>Custom</title> <prompt>true</prompt> </options> </filter> <!-- Canvas Chart --> <report> <display>CHART</display> <!-- This is the display type for the report. CHART means that the report will be displayed as a chart. --> <uuid>39fc0f87-77c8-4a5b-aec3-2a04ed78bae3</uuid> <!-- This is the report UUID used to retrieve the report results from Yellowfin. --> <styleClass>canvasChart</styleClass> <!-- This is the CSS class we've assigned to the filter for styling purposes from our dashboard.css file. --> <filterMap> <filterUUID>9d1dc0bb-ab9a-4852-b408-a9a6b94af66a</filterUUID> <!-- This is the filter UUID used to pass filter values to the correct filter on the report in Yellowfin. --> <mapToFilter>dateFilter</mapToFilter> <!-- This is the name of the filter the values are coming from, defined in the filter element earlier. --> </filterMap> </report> </dashboard> </application-definition> |
Save your changes.
reloadcontent.jsp
file. To do this load the following URL in your browser:Load your DashXML Dashboard.
To view your dashboard load the following URL in your browser:
http://<location of Yellowfin>/DashXML/dashboard.jsp?id=<dashboard ID number> so for example: http://localhost:80/DashXML/dashboard.jsp?id=3
You should now see something like this:
As you can see, the dates need some formatting.
Apply styles to the filters.
Return to your dashboard.css file and apply the following styles. We found the classes required through dev tools within our browser.
/* Top Nav Filters */ .topFilter { height: 24px; line-height: 24px; padding-top: 14px; font-size: 12px; } .topFilter .filterOption { text-align: center; float: right; color: #393737; cursor: pointer; width: 70px; margin-left: 5px; } .topFilter .selected { background-color: #393737; color: #FFFFFF; } .topFilter .filterOption .customEntry { background-color : #393737; color: #FFFFFF; position: absolute; overflow: hidden; z-index: 100; margin-top: 5px; width: 115px; } .topFilter .filterOption .customEntry input{ background-color : #FFFFFF; border: 0px; font-family: arial, sans-serif; font-size: 12px; color: #393737; height: 24px; width: 70px; line-height: 24px; margin: 12px 12px 0px 12px; padding: 0px 10px; text-align: center; } /* Date Entry */ .submitCustom { float: left; line-height: normal; margin: 10px 3px 10px 12px; } .cancelCustom { float: right; line-height: normal; margin: 10px 12px 10px 3px; } /* Date Picker */ .ui-datepicker { background-color : #FFFFFF; border: 1px solid #393737; color: #393737; font-family: arial, sans-serif; font-size: 12px; margin-top: 5px; } .ui-datepicker a{ color: #393737; } .ui-datepicker .ui-datepicker-prev { left: 10px; top: 6px; } .ui-datepicker .ui-datepicker-next { right: 10px; top: 6px; } .ui-datepicker .ui-datepicker-prev:before { content: "\f104"; color: #393737; display: inline-flex; font-family: FontAwesome; font-style: normal; font-weight: normal; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; font-size: 18px; cursor: pointer; } .ui-datepicker .ui-datepicker-next:before { content: "\f105"; color: #393737; display: inline-flex; font-family: FontAwesome; font-style: normal; font-weight: normal; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; font-size: 18px; cursor: pointer; } .ui-datepicker .ui-datepicker-prev-hover:before { content: "\f104"; color: #393737; display: inline-flex; font-family: FontAwesome; font-style: normal; font-weight: normal; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; font-size: 18px; cursor: pointer; } .ui-datepicker .ui-datepicker-next-hover:before { content: "\f105"; color: #393737; display: inline-flex; font-family: FontAwesome; font-style: normal; font-weight: normal; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; font-size: 18px; cursor: pointer; text-align: right; } .ui-datepicker .ui-datepicker-prev-hover { left: 10px; top: 6px; } .ui-datepicker .ui-datepicker-next { text-align: right; } .ui-datepicker .ui-datepicker-next-hover { right: 10px; top: 6px; text-align: right; } |
Save your changes, clear your browser cache, and refresh your dashboard page. You should now see this:
Try out the filters and ensure they update your report after each selection.
You have now completed a very simple dashboard. From here you can design dashboards and styling based on your business requirements. Explore the widgets available to DashXML here: