Kukuicup Responsive UI - Part I

For the past few months I've been working on developing a mobile layout for the Kukuicup, an energy conservation project at the University of Hawaii at Manoa.  The mobile version of the site sported a series of list-like menus (similar to the Yelp application), but user comments at the end of the competition said the mobile site was too different from the desktop site, and therefore confusing. 

Enter Responsive UI (RUI). 

Essentially, RUIs are webpages that re-arrange (or replace) content based on screen size.  The canonical example our group has been throwing around is the BostonGlobe's website (try re-sizing your browser window from wide to skinny).  The goal of creating a RUI is to have one dynamic webpage for any screen size, and hopefully giving users a sense of continuity and uniformity.

You're probably thinking to yourself "this sounds like black-magic".  Well, you're right.  But you don't have to deal with it (much).  There are a slew of prepackaged frameworks out there designed to do just such sorcery.  There seem to be two schools of thought on RUI frameworks - grids and magic hot-swappable CSS.  Grids are pretty much what they sound like, predefined grids that either scale or have a few fixed layouts.  With grids, content gets pinned to a row/column, and flows around as the screen re-sizes.  With CSS magic, media queries are used and load various CSS files based on screen size.  Essentially you build several CSS files and the media query figures out the screen size and points to the right file (in real time).   These methods are completely integrable, but frameworks usually swing one way or the other.

I've chosen Skeleton.js for this project, and so far it's working pretty well.  Skeleton favors the grid-system, rocking class tags for up to sixteen columns.  Skeleton also features a nice in-line labeling system:

<div id="a" class="two columns alpha">A</div> 
<div id="b" class="four columns omega">B</div>

The above divs will try to render on the same line if possible, with A preceding B. When space becomes limited, B will pop under A.  This is a nice feature that I didn't see in most other frameworks, and was a motivating factor in my decision.

I've been toying around with it, and find simply relying on the framework to do ALL the re-arranging isn't going to cut it.  So I've integrated some media queries to make things run more smoothly.  Media queries are part of HTML5 and part of the CSS3 standard.  They work in both HTML and CSS files, although each has its own syntax.  For example, in HTML:

<link rel="stylesheet" type="text/css" href="a.css" media="screen and (min-width:975px)">

 The above code loads the file a.css if the screen size is at least 975px.  However, placement is still important, as CSS files loaded farther down in code have priority.

In CSS, a media query looks like this:

 @media only screen and (max-width: 924px) and (min-width: 438px){
    #className {
        //new CSS definition
   }
}

This snippet will provide an alternate CSS definition for className IF the screen size is between 924 and 483 pixels.
Again, placement within the code matters as later definitions take priority.

Hopefully Skeleton, paired with media queries, will be enough to produce an elegant webpage. 
Details as they unfold.

API Development

If you think about it abstractly enough, Lego has one of the most powerful APIs in existence (Yes, I'm really using Legos as a segway into API design...).  Simple and elegant, anything with those iconic plastic nubs will connect to anything else with the same plastic nubs.  The only restriction? No diagonals.  Of course there's various extensions and spin-offs, but at it's core, lies a simple system of nubs and circles.  This simple system allows users to manifest almost any physical construct that gravity and static-friction will allow.

I've spent the past week and a half working with a group to design the API for a energy efficient house (Solar Decathlon).  Basically we had to figure out how to shuttle data between Sensors, Actuators, the back-end Database, and of course the user.  I wanted our API design to be like Lego bricks.  Ideally, it would be simple but powerful, just a few abstract classes and interfaces that let the user decide how to handle their data.  So I went off and wrote up the divine code.  Then my team informed me that my design used too much energy.  Crap.  A long afternoon spent at a round-table in the library found us quibbling over energy, extensibility, and a few other point-less grains of sand.  Eventually we settled on a very static and manual approach that saved a few watts. 

One area of interest worth expanding on is the method of data transfer.  It should be realized that passing everything around as a String is not the best idea.  After all, you'd have to spend time parsing data out.  Java objects might be a nice compromise, except they tend to take up a lot of memory, and still have an associated Class type.  XML is my new go-to-guy.  Storing a Document in a database is like saying there's molecules in my house, they could be anything.  Documents are nice and generic, and support OOP designs.  They enable a single-typed database that actually stores a range of different object types.  Our API relies heavily upon the mysterious, but generic XML Document.  Processes know how to access their designated Documents, and only their designated Documents.  Thus, processes are the only thing responsible for knowing how to handle the Document's internal format.  This helps to promote encapsulation, extensibility and information hiding.

...And now,I humbly offer these low-hanging fruits of wisdom regarding API design:

1.  Figure out what's important.  

  Will energy savings trump extensibility and elegance of design?  Is simplicity the better part of valor?  Odds are you'll have to take one aspect at the cost of another.  Figure it out before you start.  It'll save you a long afternoon of face-palming.

2.  Make sure the design is at least as extensible as it needs to be.

  We made concessions in our extensibility because there's only so many sensors that a house can have (plus were on a budget).  But make sure its flexible enough to grow.

3. Trace transactions from end to end.

We scrapped several ideas only after coding them, and then realizing they didn't work.  Make sure the functionality is there.

4.  "When in doubt, leave it out"

What does it mean? Who knows.  But if you can find an applicable context, apply it! 

5.  Don't tell them how you did it.

A wise man once told me  (I saw it on a Google Video) that users should never know exactly how a method does what it does, or else they may come to rely on it's process rather than it's result.  For example, if you tell users how a hash value is calculated, they may use the hash function else where.  If you ever change the hash function, you break their code.

BerkeleyDB

This week's assignment focused on bringing everything together into one monster webservice.  The build requirements called for a Wicket Client which accessed a RESTful Restlet server, which stored data in a BerkeleyDB database.  Basically, a nice web-based GUI that pulled data from a Server that stored stuff in a Database; a Turducken if you will. 

Recursively-stuffed fowl aside, the focus of this week was on Persistency (read: saving stuff).  Prior to this, my only method of storing data was in a Property Map, or Static Class, which unfortunately didn't stick around after execution  <insert guillotine joke here>.  The answer of course is to put things in a database. 

BerkeleyDB (BDB) is a neat little database service that runs in Java and a myriad of other languages (but most importantly, Java).  Having worked with DBs and webservices before, let me tell you, this thing rocks.  Set up is a breeze, and BDB is pretty darn flexible.  The best part?

NO CONNECTION STRINGS.

In this exercise, I had Contact objects which had unique IDs as primary keys.  All I had to do to was throw a @PrimaryKey attribute above the uniqueID attribute in the Contact class, and BDB associated it as the PrimaryKey.  Then, in the ContactDAO Class, a few lines of code let me define a "mini-DB" object, which let me call out mini-DB.get(key), mini-DB.delete(key), etc. BDB supports multiple mini-DB objects for various keys; in Kata 01, I used two (one for the PrimaryKey, and one for the SecondaryKey).  BDB even has built-in iterators if you need to return multiple entities.  Long story short, if you need a java database, go with BDB.

While I praise BDB for its ease of use and great utility, I should point out that Wicket (*glare*) is not so nice and took up all of a very nice Saturday afternoon.

On to the Katas!
Kata 01:
Easy Peasy introduction into BDB, simply add a timestamp as a secondary key, and add functionalities for a get-timestamp and get-range function.  <3 hrs (actually less than 2, but I accidentally overwrote it and had to do it again :c )

Kata 02:
The mastery Kata, combining Wicket, Restlet, and BDB to make an end-to-end Java-based web-service.   I theoretically had all the pieces from previous Katas, but putting them together took some thought.  I had to draw a diagram...twice.  Coding the back end was easy enough, and took about an hour.  Although many painful hours were spent on Wicket, which sent me maliciously deceptive error messages, before mysteriously clearing itself up. 


BerkeleyDB: http://en.wikipedia.org/wiki/Berkeley_DB

Distribution:
NOTE* Katas are in two separate files in the zip.
http://ics414-spring2011.googlecode.com/files/BerkeleyDB-GBurgess.zip

Restlet pt II

Distribution: http://ics414-spring2011.googlecode.com/files/restlet-contactservice-gburgess-1.0.122.zip
This past week my ICS 414 class dove deeper into Restlet.  Interestingly, we started using XML, which had me overjoyed, because I've had quite a bit of self-taught experience with XML, webservices and java.  Sufficed to say the assignment this week was pretty simple.  After completing the assignment, I ended up with a cute non-persistant local server hosting a little webservice that sent both XML and Java objects back and forth between client and server applications. 

The back-end(java) database used for this assignment was a single, static (black magic!) class that held a map between keys and values.  The important part was the static declaration, which meant that StaticClass.class.get() from anywhere returned the database.  Pretty nifty.

As disussed in a previous post, the REST interface supports GET, PUT, POST and DELETE protocols for resources living on the web.  You may be asking yourself how XML fits into the equation.  Well, most webservices available online or over intranets usually pass data formatted as XML.  XML is extremely well suited to being a "go between" language as data and metadata can be presented in a universally-readable format.  In fact, many proprietary software systems (I'm looking at you Microsoft) use XML as a back-end data storage mechanism.  If you think about it, this is pretty handy, it means that you, the average (or maybe not so average) Joe can parse data out of these files (granted theres a lot of meta-garbage floating around in there). 

DOM (Document Object Model) is used extensively in XML based webservices.  Basically its a Document object (read: box) that has a root element (read: tree).  The nice thing is that because XML is well suited to handling objects, so Java objects translate over nicely, and since XML is implemented as a linked-list/tree heiarchy, you can easily loop/iterate through the whole thing, pulling whatever data you need.  Handling these DOM objects in Restlet is a bit troublesome (LOTS of auxilliary method calls), however it should be noted that most XML extention libraries have fairly simmiliar method names.  One of the cool things about Java is that it supports a system by which XML and Java Objects can be encoded and decoded between eachother.  This is extremely useful as constructors on the Java side can be passed XML representations of Objects, saving you a bunch of method calls. 


If your planning on investigating on your own, here are a few tips:
1. Make sure you're using a browser that can parse XML (almost anything except chrome and safari), or else the tags will disappear, and you'll never know whats going on.
2. If in doubt about traversing/handling the DOM, getChildNodes() will return a NodeList of child nodes, and getItem(x) will return the node at position x in a NodeList.
3. You may have to call getChildNodes() twice to get to the NodeList that contains all the data.


As for the Katas:
Kata 05: Agregate Contacts
This kata focused on creating a DOM object that held the URIs of objects in the database.  My experience with the DOM system made this one pretty easy, less than two hours.

Kata 06: Implement a get-all and delete-all command for the database
This was more like Kata 05 pt II, basically parsing the URI's from the first part and getting the data out of each link in order to display.  Deletion was even easier, just grab the unique ID and call delete().  <2hrs

Kata 07: Extend Contact to implement a phone number
Easy peasy, until I had to deal with a FindBugs/PMD argument over somestupid Exception.  Basically updating the Contact object, and all calls & adding the phone number variable to various locations.  <2hrs

Distribution:
http://ics414-spring2011.googlecode.com/files/restlet-contactservice-gburgess-1.0.122.zip

Restlet pt I

As part of my ICS 414 (Software Engineering II) class (the continuation of ICS 413 from last semester), I was recently thrown into the deep end of Restlet.  REST, or REpresentational State Transfer is basically a set of concepts dreamt up by Roy Fielding a number of years ago.  REST provides a way for resources (and services) to be accessed remotely by machines.  Sounds a lot like the web doesn't it?  Well, your right, but wrong at the same time.  The WWW protocol provides a perfect platform to implement REST, but not vice-a-versa. 

Honestly its all a bit confusing, so screw your head back on and enjoy these educational links:
http://tomayko.com/writings/rest-to-my-wife (Highly reccomended)
http://en.wikipedia.org/wiki/Representational_State_Transfer
https://sites.google.com/site/ics414spring2011/modules/rest

The last link is my class webpage, which holds the assignment du jour: Assignment A04 : Restlet Code Katas.
I should point out that these were not the nice little Katas from last semester.  These were big, scary, nun-chuck-wielding, feat-of-programming-prowess Katas.  Let me start by pointing out that the documentation for Rest is not great, so if your thinking about picking it up in your spare time, expect to spend a few hours trolling tech-forums for the most obscure solutions you've never thought of.  The crowning jewel in all this is that you can programatically pull data from online resources, and use them for your own (potentially nefarious) purposes. 

To the Katas:
Distribution: http://ics414-spring2011.googlecode.com/files/gburgess-restlet-1.0.118.zip

Kata 1: Time resources
This was fairly simple, just copying, pasting and tweaking.  This ultimately provides resources to pull the hour, minute, and second.  This was simple enough to finish in class (<60 mins).

Kata2: Logging
This sounded easy, especially since my professor indicated "logging in restlet can be done in just a few lines".  Well, I spent hours working on this one.  The restlet API was of help.  I came pretty close to figuring it out before one of my teammates solved it.  I passed over the answer in my search for truth, but overlooked it because it didn't sound like it fit the bill.  (>5 hours)

Kata 3: Authentication
It sounded easy...but unfortunately these things rarely are.  I got it working, although my cohorts report some difficulty getting it to work on Mac (*scoff*) platforms (to which I point out the ninety-something-percent compatibility rating).  The devils in the details.  I swear I spent more than 8 hours trying to figure out how to make three lines of code jive.  Although I must say, this is actually pretty useful.  (>8hrs)

Kata 4: Wicket
Writing this little program was like trying to catch a hornet with a thimble.  It sounded difficult, and it was.  After a marathon 8 hour programming session, I gave up.  Essentially the order was for a wicket form that pulled data using rest from the dateserver.  I could pull data from the date server without a problem, and the other little details (jar.build.xml & ivy downloads) were taken care of by another team member.  My real struggle was with the wicket form.  I for the life of me could not figure out how to handle the session properties.  The plan was to implement a bunch of checkboxes, so users could choose what data to pull, and then have them click a submit button to pull up the desired data.  Well as it turns out, keeping track of what checkboxes are checked, is really hard.  Aside from the wicket form, everything else worked all right. ( >8hrs)



http://ics414-spring2011.googlecode.com/files/gburgess-restlet-1.0.118.zip

Solar Decathlon Home Management System 2.0

As the final project for my software development class, our team was assigned to create a mockup of our system using HTML, Wicket, and CSS.  We based our project off of the Balsamique mockups that we had previously done.  Fortunately for our group, our design was fairly simple to implement, and had alot of reoccuring elements like the menu and side bars.  We were able to design a base page wich incorporated the main menu bar, and built all of our other pages off of it.  This project, which threw us into the deep end of web development, brought me a great respect for HTML and Wicket.  However, it also made me wonder why in the word CSS was invented.  It seems strange that anyone would want all of the elements in their webpage to be exactly the same.  I found myself time and time again having to trudge through several hundred lines of obscure code to find the one line that was messing up my child page.  Working with BluePrint CSS was painful, and many of the overriding <Style> tags that should have modified the main CSS file, didn't.  It seems like it would have been much easier just to define each page individually.  In my short-lived experience, I find that CSS is painful, but necessary to render content across different browsers and operating systems. 

With respect to how our group managed the development of our project, I can happily say that it was a breeze.  Our team started a bit late, but once we allocated the workload, our project chugged along nicely.  Our only hang up occured when we realized that our software environments were slightly inconsistent, but that was a simple fix.  Overall, I find the combination of Google Project Hosting, Subversion and Eclipse made this project very straightforward. 

All in all, our project went very smoothly, but in hindsight, I wish we had started a litte sooner.  For the most part, our team worked at a fairly regular pace on the project, however there were a few key items that had to be completed before other members could proceed.  In particular, the creation of our "base page" (off of which every other page was built) created a hang up in both the development and planning of our child pages.  Starting a little earlier might have prevented alot of lost sleep.
 


One of the goals of our project was to satisfy "The Three Prime Directives of Software Engineering".


The Three Prime Directives of Software Engineering:
1. The system successfully accomplishes a useful task.


Our system does indeed accomplish a useful task.  It both illustrates the final product and sets a working foundation for the next phase of development for our system.  Ultimatently, the system will be used to control the home that will be entered into the Solar Decathlon competition.  Until then, the system is useful in providing a more formalized simulation of what the final product will be.  This gives the clients, in this case the Solar Decathlon Team, something to interact with and lets them provide us with highly detailed feedback.  This in turn lets us, the developers, align our product with their specific needs.

2. An external user can successfully install and use the system.

Our current system is extremely easy to use, requiring only one command line statement to execute.  A user simply has to download the distribution jar, and then type "java -jar wicket-solardecathlon1.2.jar".  The project site also features a "User Guide" in its wiki section, which provides step by step instructions for installation and execution.

3. An external developer can successfully understand and enhance the system.

Our system is built in a consistent and elegant fashion, making it easy to understand and modify.  While every system has a learning curve, our system is fairly simple, and very straightforward.  All of our pages are built off of one "base page", which provides the basic background and menu bar.  After that, each individual page has its own package and implements a specific page.  Each package contains all of the resources needed to render its own page. 
The documentation included with the code is fairly straightforward, and the variable names for various elements help to identify their use.  The code is also very uniform in style and function, making it easy to read and understand. 

Project site: http://code.google.com/p/solar-decathlon-teamhawaii-2/

Wicket Katas

The assignment-of-the-week over my all-too-short thanksgiving weekend was to complete 11 "Wicket Katas."  Each "Kata" consisted of making a small change to an existing set of project files.  Additionally, we were supposed to time ourselves on how long we took to complete each Kata. 

The goal of "<Tech> Katas" in general is to gain expertise in a particular technology (in this case Wicket).  While I have some issue with the use of the word "Kata" in this situation, I must say that they were rather enjoyable to figure out, and I feel like I learned a lot of valuable Wicket concepts.  <Tech> Katas are excellent exercises for learning basic concepts in a new language, and I would definitely consider using them to teach others. 

I ended up working with two classmates to complete the assignment, which worked out well, as we all started out on different Katas, and helped each other whenever we got stuck.  It ended up being a small superiority contest, but it was all in good fun. 

The Katas:
http://code.google.com/p/wicketkatasglb/wiki/Katas

Kata 1A
~10 mins
I finished this in class, not too difficult.

Kata 1B
The rest of the class period...(~50 mins)
This one was a pain.  My environment wasn't configured correctly, and it took forever to finally figure out that I should have ran "ant build" first...  I should point out that the actual coding only took about 20 mins to complete.  The rest of the time was spent wrestling with Eclipse.

Kata 1C
~2 mins
Trivial.  Copied a block of code into my application class.

Kata 2A
~60 mins.
This was a little bit odd.  I actually did Kata 3A first, and tried copying my code into this project...it didn't work.  It turns out that my approach was too sophisticated for the implementation.  I had to get one of my friends to help me.  Honestly, I thought this one was a pointless repeat of  3A.

Kata 2B
~90 mins.
Originally, I had a single page with dynamic tags at the beginning and end of the page so that I could simply change the tags based on the current situation.  Didn't work.  I struggled for an hour trying to get my method calls to work with Wicket's framework.  In the end I just created three separate pages and linked them together.

Kata 3A
~30 mins
Not too bad, I had to look up how to do this on Google.  At one point the system was changing the variable name for my image from "image.jpg" to "image_en_.jpg" or something similar.  I eventually figured it out.

Kata 4A
~10 mins
Easy peasy.  Just follow the example and copy paste.

Kata 4B
~45 mins
Seemed simple enough...then I realized there was more going on that I was comprehending.  The program mysteriously told me i needed a get() method.  I stared it down for a good twenty minutes before phoning a friend.  As it turns out I needed to update the Address object...  I must say, the Cheeser program is really cool.

Kata 6A
~15 mins
Looked shockingly difficult.  The first place I looked was in the CSS files.  I tried deleting bits of code, but that didn't do anything.  Then I looked in the .html files and found what I was looking for. 

Kata 6B
~5 mins
Trivial after doing 6A.  I went straight to the FormPage.html file, saw the table structure, and moved the Wicket tag.

Kata 6C
Unfinished
This one sounded scary.  I read up on Java Properties, but couldn't figure it out...  (By this time I'm feeling totally burnt out, and willing to make do with 10/11).

Total Time:
~317 mins (approx 5 hrs).

There's about two hours of hidden time in there that was allocated to getting the system to pass quality assurance, uploading files, and writing this blog.

Our professor estimated that it would take 11hours to finish all 11 Katas, and he probably would have been right if I didn't have group members to ask for help.

Original Examples:
http://code.google.com/p/ics-wicket-examples/

The Katas:
http://code.google.com/p/wicketkatasglb/wiki/Katas

My Implementations:
http://code.google.com/p/wicketkatasglb/downloads/list (Individual Examples)
http://wicketkatasglb.googlecode.com/files/glb_Wicket_Katas.zip (All Examples)