We currently have two places where Ubuntu HTML "widgets" are implemented: JavaScript and CSS. Some widgets exist in JavaScript and in CSS, but some only exist in CSS with no corresponding JavaScript class.
For example, we have shape.css that uses a selector that assumes the shape is declared like this: <div data-role="shape" ... >. But there's no Shape class in JavaScript and therefore no place to document how we expect an Ubuntu HTML5 shape to be declared. The same goes for pages, and other widgets too.
So we have a couple problems. These are not technical problems, but rather they create a framework that is difficult to learn, communicate, understand and use.
Problem 1: It is difficult to determine the complete set of Ubuntu widgets from source. One has to read all the JavaScript and all the CSS (or consult hand-crafted external documentation) to understand what's available.
Problem 2: With the coming move to generated API docs from source using yuidoc, there is no single type of source file in which we can document how every Ubuntu widget is declared in HTML.
A solution is to set the standard that every Ubuntu HTML5 widget (including all that are mentioned in CSS) should have a corresponding JS class and should be a part of the UbuntuUI prototype class. For example, we should have shape.js and page.js (among other currently missing types). And the UbuntuUI prototype should follow the current pattern and provide constructor functions for each:
shape: function() {...}
page: function() {...}
These prototype constructor functions should exist even when there are apparently no useful functions in the classes themselves (but there alway is, with one additional function described below). That is, we should have a page class that looks something like this:
/**
* An Ubuntu app consists of a Pagestack made of one or more Pages. Each page displays full-window.
* @class Page
* @constructor
* @example
Declare in HTML like this:
<div data-role="page" id="ID">
[...]
</div>
*/
var Page = function (id) {
this.id = id;
};
Page.prototype = {
/*
* placeholder for future methods
*/
};
Although it appears that there is no useful function for the class, there actually can be. I propose adding the following to the UbuntuUI class prototype:
/**
* Gets the Ubuntu HTML element
* @method getEl
* @param {UbuntuWidget} widget - An UbuntuUI widget object
* @return {Element} - The HTML element
*/
getEl: function(widget) {
return document.getElementById(widget.id);
},
This allows one to obtain the HTML element from any Ubuntu widget type that has a class, like this:
var mypage = UI.page("PAGEID");
var mypageEl = UI.getEl(mypage)
+1