This tutorial covers a quick and easy way to create your own page on the web, with a custom presentation of Xively Feeds and Channels.
At the end of this tutorial, you’ll know how to:
- Publish a webpage from Github
- Use open-source tools to create customized graphs
- Set up a page that displays just the Xively Feeds and Channels you want, how you want them
The best part is that all of this is done with open-source tools, which means that you can modify and build on this base to create your own visualizations, whether you just prefer scatter plots or bar graphs to lines, or you want to strip this code down and totally rebuild it your own way.
Sharing code with Github
Github is an online storage house for code. It doesn’t matter whether it’s the code of your latest Arduino project, or the code for your website - Github will hold a history of all of its changes, and keep a copy of the latest version available.
This uses a feature of Github called Github Pages. Github Pages allows you to host a small external webpage for your Github repository. Any repository can have a Github Pages page, Pages simply displays any code in the ‘gh-pages’ branch. We have designed the Channel Visualization tool to be a standalone Github pages branch. This means that the only branch in the repository is a ‘gh-pages’ branch (there is no master branch).
Hosting a page with Github
You are free to use our hosted page at http://xively.github.io/channel-viz as much as you want. However, we recommend that you fork our repository to your own Github account, which will automatically create the GH Pages page for you. Once you’ve done this, you can also download the code, make some edits and then host your own personalized version on GH Pages. Here is how to get started:
- If you don’t have one, create a GitHub account here.
- Go to our Channel-Viz GitHub repository.
- Click the ‘Fork’ button in upper right hand corner. Then select the account you would like to fork it to.
- GitHub will now take care of the rest. You will see a loading graphic of the repo being ‘forked’ and you will then be brought to your copy of the code on your own repo.
- Forking the repo as opposed to just downloading the code will not only allow you have your own GH Pages page but also allows you receive and submit updates and changes to the code.
- Click on index.html, a text viewer with line numbers will appear. Click on edit in the upper left hand corner.
- On line 15, change the text inside the
</title>tags. You can make it anything, such as YOUR NAME’S Feeds.
- Scroll down to the bottom and and click the green ‘Commit Changes’ button. If you make any other changes it is recommended you keep track of them by putting a short description of changes in the ‘Commit sumarry’ field. However, this is optional.
- Your page should now be all set. However, it usually takes 10 - 15 minutes in order for new GitHub Pages to get pushed to the server. When your page is ready you will be able to see it at http://GH_USERNAME.github.io/channel-viz
- You now have your own hosted Xively front-end application. Move on to the next section to customize it.
Make it Yours
This tool can be used as a standalone visualization engine. It contains all the necessary UI elements for people to enter information for any feed. However, you may want to use this tool to solely view only your specified feeds. For this reason we have given people the ability to fork the code on Github or download the code so you can run it on your own server or locally on your computer, all that’s required is a browser.
If you choose to run your own version of the code, we have built in several options for you to customize the visualization page to make it your own. These customizations allow you to permanently set keys and feeds for viewing, as well as change the look and feel of the webpage.
If you completed the previous section of the tutorial and want to use GitHub Pages to host your page you can actually make these edits right in GitHub. Just open up follows.js and make the edits outlined below.
- defaultKey - Put your * READ-ONLY * master API key here so you don’t need it every time. Be sure to designate the API Key as read-only when you generate it, to maintain security.
- defaultFeeds - This is where you can put in default feeds, same syntax as the box except if you are specifying a single datastream, the entire entry including feed ID and datastream ID must be surronding with single quotes.
- applicationName - This lets you make the page your own. You can set the title in page header to whatever string you want.
- dataDuration - This allows you to set the default data duration when the page is opened. You can still change the duration with the buttons, this only sets the duration of the initial page load.
- dataInterval - This allows you to change the frequency of points returned. CAUTION: This value is usually set automatically to work with your chosen duration. If set to an incompatible interval, the graphs will return no data.
- dataColor - This changes the color of the trendline on the graph. Hex color codes only, omit leading #.
- hideForm - If you have already set default keys and feeds you may no longer need the UI bar under the header. If so, set this value to 1 to hide the bar.
Add Custom Duration
Perhaps a 90 day graph is not enough for your specific sensor data. A one time duration can be set by following the instructions above for the dataDuration and dataInterval fields. This will allow you load the page with any duration you please. However, if you want to always have the option of that time range, you may want to change the preset options. This will show you how to customize the duration buttons to be whatever you want them to be. In this example we will show you how to switch the 90 day button to a 1 year button.
- Find the line that contains ‘ .duration-90’ in follows.js, it should be around 314, this function is what we will be editing. We can leave it named ‘ .duration-90’ to make things a little bit easier.
- Change where is says ‘90days’ to a value of your choice, for a year, we will be changing the value to ‘1year’.
- IMPORTANT: You must also change the interval, which is the number directly after the duration value. Your interval must be compatible with your duration, such that it matches the historical API limit. You must also ensure that the interval you select will return less than 1000 datapoints per datastream. For a 1 year duration I will choose an interval of 43200 (one datapoint every 12 hours).
- Now we will change the button label in index.html. Find the “button-group” div, which should be around line 309. We will be editing the 90 day button, which is last. We want to leave all the reference information the same so only change the text, this is the plain text which is followed by
</a>. Change where it says 90 Days to 1 Year.
- Save both follows.js and index.html and reload your page. You should now have the option for a 1 year graph.
You can use this same process to change any or all of the preset button time frames.
Change Graph Type
- You want to look for the line starting with ‘renderer:’, this should be around line 126, depending on your modifications.
- The rednerer line should currently have the value ‘line’, this means that the line graph is being drawn.
- We can now change where it says ‘line’ to one of the values that works well with Xively data. Try changing ‘line’ to ‘area’ or ‘scatterplot’.
- Refresh your page and see what happens to your graphs, the display should change. Note: Depending on the data in your graph, it may not change drastically. Try looking at a few types and durations of graph with your new renderer.
Take this and run!
The code that makes this happen is only the beginning. Because the Xively Channel Visualizer is built on completely open-source tools, you can modify and build on it however you’d like. Try some of the following:
- changing the colour of the graph
- try a bar graph
- visualize more than one Xively channel on the same graph
- build an interactive legend
All of these ideas can be found at Rickshaw’s site.