The Web UI

The integrated web interface

SIP uses web page technology to provide its user interface (UI). The UI is built with web.py, one of many Python web frameworks. Web.py acts as a communication bridge between Python program code and the web pages that make up the interface.

Components of the UI

urls.py

The urls.py file contains a python list which acts as an address book for the application. Each entry consists of a web URI and a path to a Python class. For example:

'/',  'webpages.home',

Where '/' is the URI of the app's root and 'webpages.home' points to the home class within the webpages Python module (file).

When you point your browser to http://[url of your pi]:8080/ Web.py will run the code in webpages.home and return the result which will appear as the app's home page.

You can add new entries to the url list from within your plugin in order to include your own UI pages. In the proto plugin, the following code does this:

urls.extend([
    '/proto-sp', 'plugins.proto.settings',
    '/proto-save', 'plugins.proto.save_settings'
   
    ])

Notice that the second part always starts with "plugins.". Paths in sip are relative to the SIP directory and all plugins are located in the "plugins" sub-directory. Also important is the comma after all but the last entry in the list. If you miss a comma you will get an error!

The first url points to a class that will launch a "settings" UI page, while the second one points to a class that will save user input to a file.

####Naming URLs#### Names of URLs must be unique to ensure that links work as expected. You should take a look at the URLs already defined in urls.py and avoid duplicating them. Fortunately most of those URLs were ported from very compact micro-controller code and appear a bit cryptic at first. Keep in mind that other plugin authors will be adding new URLs also. You should use names that are easily recognized as belonging to your particular plugin.

##Templates The files that define pages of the UI are located in the templates sub-directory. They are a special type of .html file. Web.py templates contain a mixture of Python code, HTML markup, JavaScript/jQuery and CSS styling. This is where things can get a really interesting.

Templates are key points where the Python code of the core program is able to interact with a web page and transfer data to the JavaScript web language. They can also receive user input and send it back to the core program.

###How to Read a Template At first glance the code in a template file can appear daunting unless you are a seasoned web programmer. However, spending a couple of minutes looking through the file and identifying the various parts should get you up to speed quickly.

The proto.html template from the proto plugin is a good example.

This must be the first line of a template:

$def with(settings)

This line identifies the file as a web.py template. The settings argument inside the parentheses is optional but one or more such arguments can be used to pass data from the Python code that called the template. Python code within the template can use the argument(s) as a variable.

####Recognizing different types of code####

Python: the "$" character is used to specify python expressions. Expression can be enclosed in () or {} for explicit grouping. some examples:

a $variable 
an ${arbitrary + expression}. 

When defining a new variable a space following the $ is required:

$ new_var = "value"

Comments:

$# This is a Python comment in a web.py template.

See the web.py docs for more details.

JavaScript and jQuery: JavaScript is the "language of the web" it is used to add interactivity to web pages. JavaScript code is enclosed in <script></script> HTML tags:

<script>
    // Initialize behaviors
    jQuery(document).ready(function(){

        jQuery("#cSubmit").click(function() {
            jQuery("#pluginForm").submit();
        });
        jQuery("button#cCancel").click(function(){
            window.location="/";
        });

        jQuery("button#docButton").click(function(){
            window.open("${gv.baseurl}/static/docs/plugins/proto-docs.html", "_blank");
        });

    });
</script>

Can you spot the embedded Python code?

Notice the comment on the second line in the example above.

// This is a JavaScript comment.

jQuery is a cross-platform JavaScript library designed to simplify the client-side scripting of HTML. It is versitile and compact.

The $ symbol is also used as shorthand for jQuery statements. To avoid conflicts, an early decision was made to use the long form (jQuery) at the beginning of jQuery statements in the SIP project.

HTML: Everyone in probably familiar with HTML markup. It can be easily recognized by the angle brackets (<>) enclosing tag names and attributes:

<div id="controls">
    <button id="cSubmit" class="submit"><b>$_('Submit')</b></button>
    <button id="cCancel" class="cancel danger">$_('Cancel')</button>
</div>

And of course:

<!--This is an HTML comment.-->

You may have noticed the $_('Submit') and $_('Cancel') markup in the first HTML example. If you thought the leading $ symbol indicates Python code embedded in the HTML, you are right!

Those are actually instances of a Python function named "_()". It comes from the gettext module of the Python standard library and is used to enable translation of the text on the UI pages into different languages. The English text inside the parens can be replaced with text of another language when the SIP program is running.

#Documentation files You can include documentation for your plugin as a regular HTML file(s). They are kept in the static/docs/plugins directory. See the proto plugin and proto-docs.html in the directory indicated for an example. #webpages.py This file in the main SIP directory contains the classes pointed to by most of the URLs in core program. #base.html base.html in the templates directory provides page elements that are common to most of the other UI pages such as the clock, menu bar, and footer.