javascript lacks classes for many widgets

Bug #1243248 reported by Kyle Nitzsche on 2013-10-22
10
This bug affects 2 people
Affects Status Importance Assigned to Milestone
Ubuntu HTML5 UI SDK
Wishlist
Alexandre Abreu
ubuntu-html5-theme (Ubuntu)
Wishlist
Unassigned

Bug Description

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)

description: updated
description: updated
description: updated
Revision history for this message
David Barth (dbarth) wrote :

+1

Changed in ubuntu-html5-theme:
status: New → Confirmed
importance: Undecided → Medium
Changed in ubuntu-html5-theme:
assignee: nobody → Kyle Nitzsche (knitzsche)
Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

shape and page now added, and getEl() function, with rev 94 merged today.

If we find others we should add, we can reopen this.

Changed in ubuntu-html5-theme:
status: Confirmed → Fix Committed
Revision history for this message
Launchpad Janitor (janitor) wrote :

This bug was fixed in the package ubuntu-html5-theme - 0.1+14.04.20140107-0ubuntu1

---------------
ubuntu-html5-theme (0.1+14.04.20140107-0ubuntu1) trusty; urgency=low

  [ Adnane Belmadiaf ]
  * s/parentNode/parendNode Spaces instead of tabs. (LP: #1241215)
  * Add option selector widget. (LP: #1232533)

  [ daker ]
  * Passe the UI variable name so we will not lock the variable. (LP:
    #1222878)
  * Made variable declaration locale. (LP: #1222881)
  * Fixed z-index for the list items aside. (LP: #1223973)
  * s/parentNode/parendNode Spaces instead of tabs. (LP: #1241215)
  * Space instead of tab. (LP: #1240682)
  * Made list items with headers differentes. (LP: #1246446)
  * Updated the progressbar component to match the design.
  * Move tabs closer to what they should be, Expand API to match the QML
    one (at least at the Tabs level), .
  * Add option selector widget. (LP: #1232533)

  [ Kyle Nitzsche ]
  * Add button id to "Invalid button ID" error message .
  * This MR does three main things: 1) Implements yuidoc comments in all
    js files to support API doc generation, and provides yuidoc assets
    (theme dir and json file) needed to build the API docs. Bug LP:
    #1241029 3) Provides JS classes for shape and page with
    corresponding UbuntuUI prototype constructor functions. Bug LP:
    #1243248 4) Adds a getEl(UbuntuUIObject) to return the element for
    any Ubuntu class. Also LP: #1243248. (LP: #1243248, #1241029)

  [ Colin Watson ]
  * Make ubuntu-html5-theme Multi-Arch: foreign.

  [ Alexandre Abreu ]
  * Fix exec path in app-gallery app desktop file. (LP: #1235321)
  * Add convenient element() function to most widgets ... (we might want
    to factor those out in a second step).
  * Move tabs closer to what they should be, Expand API to match the QML
    one (at least at the Tabs level), .
  * Add HTML5 webapp container package.

  [ Ubuntu daily release ]
  * Automatic snapshot from revision 98
 -- Ubuntu daily release <email address hidden> Tue, 07 Jan 2014 23:46:53 +0000

Changed in ubuntu-html5-theme (Ubuntu):
status: New → Fix Released
Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

<div data-role="mainview"> has no JS obect in UbuntuUI.

This means that the design.ubuntu.com page that discusses mainview CAN provide a link to docs for QML but cannot for JS.

Let's add a mainview object and provide some minimal docs description of it so that devs know they need it, where it must be (child of body) and etc.

Changed in ubuntu-html5-theme:
status: Fix Committed → Confirmed
assignee: Kyle Nitzsche (knitzsche) → Alexandre Abreu (abreu-alexandre)
Revision history for this message
Michael Hall (mhall119) wrote :
tags: added: docs html5-block
tags: added: html5-blocker
removed: html5-block
Changed in ubuntu-html5-theme (Ubuntu):
status: Fix Released → Confirmed
Changed in ubuntu-html5-theme:
status: Confirmed → Incomplete
status: Incomplete → Opinion
status: Opinion → Fix Committed
Changed in ubuntu-html5-theme (Ubuntu):
status: Confirmed → Invalid
Colin Watson (cjwatson) on 2014-06-06
Changed in ubuntu-html5-theme:
status: Fix Committed → Confirmed
Changed in ubuntu-html5-theme (Ubuntu):
status: Invalid → Confirmed
David Barth (dbarth) on 2015-03-27
Changed in ubuntu-html5-theme:
importance: Medium → Wishlist
Changed in ubuntu-html5-theme (Ubuntu):
importance: Undecided → Wishlist
David Barth (dbarth) on 2015-03-27
tags: removed: html5-blocker
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers