Page 1
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 1/70
ContentsDeveloper Guide:
About
Philosophy
Summary
Building
Directory Map
Quick StartClass Hierarchy
Class Patterns
Data Driven Controls
Observer Pattern
Supported Platforms
Release Notes
License
API Reference:
Core
Data Layer
UI Widgets
Index:
Keywords
Jo JavaScript Framework for HTML5
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
1 of 70 05/01/2011 11:54 PM
Page 2
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 2/70
About
Jo is a lightweight JavaScript framework designed for HTML5 apps.
jo does:
Embrace JavaScript's object model and loosely typed nature
Leverage CSS3 to handle as much of the pretty presentation and animation as
possible
Provide a consistent and modular event model between objects
Wrap DOM and device-specific events into a cohesive gesture system
Insulate developers from different persistent storage solutions
Play nicely with other libraries like PhoneGap
jo doesn't:
Use a lot of resources
Depend on other frameworks
Have a lot of browser dependent code
Require detailed knowledge of the DOM
Force you to deeper into its framework than you want to go
Use $ and other arcane looking symbols in place of proper identifiers
Author:
Dave Balmer: davebalmer.wordpress.com , follow @balmer on Twitter , or email
[email protected]
Downloads:
Version 0.4.1 is the latest stable release, check the Release Notes for details.
Available from GitHub as a git repo or a zip file .
Philosophy
If you want to jam an existing web page into an application framework, jo probably isn't for you. jo
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
2 of 70 05/01/2011 11:54 PM
Page 3
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 3/70
is designed to create applications. While it will play nicely with a mixture of new and old web
development techniques, it uses HTML5 as a development stack and does not require direct DOM
manipulation.
Application Stack:
JavaScript Application
jo
PhoneGap (optional)
joView joEvent joDataSource
CSS3 Canvas DOM Events XHR SQLite Device OS
Documentation
All documentation for the framework is based on Markdown and provides a simple, natural and
flexible way to document the code. This simple set of perl scripts has become its own tool called
joDoc.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
3 of 70 05/01/2011 11:54 PM
Page 4
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 4/70
Summary
Jo is a JavaScript framework for HTML5 capable browsers and devices. It was originally designed
to work on mobile platforms as a GUI and light data layer on top of PhoneGap. Since its creation, Jo
has also been tested successfully as a lightweight framework for mobile browsers, newer desktop
browsers, and even Dashboard widgets.
Building
It's pretty easy to build on your own, but to get the most out of it you'll want to get a minifier like
jsmin or the YUI Compressor. Minified and gzipped, Jo weighs in around 9K with no other
JavaScript library dependancies.
Mac OSX, Linux & BSD:
cd jo
./build
Windows:
cd jo
build.bat
If you're not up for building the library yourself, there's nothing wrong with downloading the latest
stable release, all built and ready to plug in from: jo /downloads">GitHub Downloads
Directory Map
Important files in the directory tree are:
js/jo_min.js
This is the jo library bundled and minified, ready to drop into your project. You will
need to build the library to make this file (as well as the un-minified version jo.js
which is useful for debugging).
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
4 of 70 05/01/2011 11:54 PM
Page 5
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 5/70
css/aluminum
This is a CSS3 bundle ready to ship your app with. Also serves as a good example of
modern HTML5 styling capabilities. Looks pretty bad in IE up through version 8.
css/jo.css
This is a newer base CSS theme for Jo, preferred over Aluminum for now. Built with
Less CSS compiler.
docs/*.mdown
These are supplimental doc files which are used by joDoc to build out the developer
guide portions of the documentation.
Quick Start
index.html:
The complete jo library is small, so in most cases you'll just want to pull it all in, like this:
<html>
<head>
<link rel="stylesheet" type="text/css" href="css/aluminum.css">
<link rel="stylesheet" type="text/css" href="css/webkit.css">
<!-- <link rel="stylesheet" type="text/css" href="css/webos.css"> -->
<!-- <link rel="stylesheet" type="text/css" href="css/chrome.css"> -->
</head>
<body>
<!-- any static page content goes here -->
<!-- load jo library -->
<script src="jo_min.js"></script>
<!-- any application JavaScript files go here -->
<script src="hello.js"></script>
</body>
</html>
If you're using jo to create all the UI for your application, you won't need any content or tags in
your index.html file.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
5 of 70 05/01/2011 11:54 PM
Page 6
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 6/70
Since the framework is highly dependent on CSS, your mileage may vary across platforms. In
particular, Internet Explorer before 9 will have limited eye candy and no animated transitions.
You can also completely skin your app with your own CSS, or augment the basic jo CSS to suit
your purposes.
Since jo is geared for HTML5 applications, I recommend you develop and test your apps with
Safari or Chrome before moving to mobile devices. In fact, this makes the code/test/debug cycle
go very quickly.
hello.js:
jo has some initialization which should only be done when your browser is ready to have its DOM
fiddled with, so you may want to wrap your code in a function that's called when your page loads,
or your device signals that your app is ready to go.
The simplest UI would be something like:
// initialize jo
jo.load();
// define a wrapper for document.body
var scn = new joScreen();
// setup your UI
scn.alert("Hello, Jo!", "This is a simple alert.");
Something more interesting would look like:
// initialize jo
jo.load();
// setup a stack and screen
var stack = new joStackScroller();
var scn = new joScreen(stack);
// create our view card
var card = new joCard([
new joTitle("Hello"),
new joCaption("Hello World!"),
new joDivider(),
new joButton("OK").selectEvent.subscribe(function() {
stack.hide();
})
]);
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
6 of 70 05/01/2011 11:54 PM
Page 7
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 7/70
// put the card on our view stack
stack.push(card);
Notice above that jo supports "chaining", meaning you can make successive calls inline to a given
object (see the joButton line above for an example).
Of course, it is recommended you use more robust OOP coding patterns to make a proper
application. While there's nothing illegal about putting everything in global space in a single
JavaScript file, but if you're looking to build something big or more easy to maintain, I recommend
you check out "JavaScript: the Good Parts" by Doug Crockford (O'Reilly Press).
Class Hierarchy
The following is a class hierarchy for the framework, organized by general function.
User Interface:
joView
joContainer
joCaption
joCard
joDialog
joFlexcol
joFlexrow
joFooter
joForm
joGroup
joNavbar
joPopup
joScreen
joScroller
joShim
joStack
joStackScroller
joTitle
joToolbar
joControl
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
7 of 70 05/01/2011 11:54 PM
Page 8
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 8/70
joButton
joBackButton
joCaption joExpando
joSelect
joHTML
joInput
joDateTime
joPasswordInput
joTextarea
joLabel
joList
joMenu
joSelectList
joTabBar
joTable
joKnob
joSlider
joToggle
joOption
joDivider
Data:
joDatabase
joDataSource
joFileSource
joProperty
joRecord
joSQLDataSource
joYQL
joFile
joScript
Events:
joEvent
joSubject
joGesture
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
8 of 70 05/01/2011 11:54 PM
Page 9
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 9/70
Processing:
joChain joDefer
joWait
Utility:
joDOM
joInterface
joJSON
joLocal joString
joTime
Debugging:
joLog
Application:
jo
joClipboard
joDevice
joFocus
joPreference
joUser
Class PatternsInstead of a complex set of pseudo-class methods, jo uses a few simple coding patterns: singleton,
base class, subclass, and module. All of these are found in modern JavaScript implementations. A
good reference to have while developing your app is JavaScript: The Good Parts by Douglas
Crockford (O'Reilly Press)
Singleton:
The pattern for creating a singleton is really just an object literal. For example:
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
9 of 70 05/01/2011 11:54 PM
Page 10
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 10/70
MyApp = {
init: function() {
// some sort of initialization code goes here
},
mymethod: function() {
// some custom method
},
// properties can also be declared inline
myproperty: true
};
Base Class:
Prototypal inheritance does well with "fat" base classes which do most everything you anticipate a
subclass would want. This type of inheritance benefits greatly from shallow/wide prototypes for a
number of reasons. A base class looks something like:
MyClass = function(x) {
// constructor
this.x = x;
};
MyClass.prototype = {
mymethod: function() {
// some method
},
myothermethod: function() {
// another method
}
};
Subclass:
Strictly speaking, JavaScript doesn't have classes and subclasses. But it does know how to make
copies of an object, and keeps track of "inheritance" through its prototype chain. A subclass in jo
looks something like this:
MySubclass = function(x, y) {
//constructor
this.y = y;
// call to our "superclass" constructorMyClass.call(this, x);
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
10 of 70 05/01/2011 11:54 PM
Page 11
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 11/70
};
MySubclass.extend(MyClass, {
mynewmethod: function() {
// this subclass has its own new method
}
});
A couple things to note. jo augments the Function object in JavaScript to have an extend() method.
This is just some syntactic sugar which makes it easier to extend an object, giving us a pseudo-
subclass with syntax that's not too awkward. The advantage here is we're using JavaScript's natural
object model behind the scenes. We're not creating any extra fluff, just automating the process
somewhat.
Note that objects created using prototypal inheritance also get the benefit of using JavaScript's
built-in instanceof operator which works up the prototype chain. For example:
// given this new subclass
var someobject = new MySubclass(1, 2);
// both of these tests are "true"
joLog(someobject instanceof MySubclass);
joLog(someobject instanceof MyClass);
You may also notice a "call to super" comment in our MySubclass constructor. This is a convenient
coding pattern which makes it easier to create subclasses, with methods that augment the
superclass' functionality. Like this:
MySubclass.extend(MyClass, {
mynewmethod: function() {
// this subclass has its own new method
},
mymethod: function() {
this.x += 5;
// call super's mymethod() with this object's context
MyClass.prototype.mymethod.apply(this, arguments);
}
});
It may look slightly odd at first, but this approach gives us more of the benefits of subclassing
you'd find in other languages without having to step outside of JavaScript's natural object model.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
11 of 70 05/01/2011 11:54 PM
Page 12
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 12/70
Data Driven Controls
Jo isn't just a pretty face with some DOM fiddling and standard DOM events. It also has a versatile
application-level event model (see Observer Pattern). In addition, Jo has a simple event-driven layer
for asynchronous data storage and retrieval using extensions of joDataSource.
As a matter of convenience, all children of joControl (which includes most list or widget-driven UI
elements) can be easily tied to data.
The most convenient for most purposes is joRecord. This class wraps a property list, which can be
used to save or load using whatever your application requires. In addition, this class allows you tolink a UI control to the data in one quick action.
For more on this, check out the joRecord docs which include an example or two.
joDoc
joDoc is a plain text code documentation scheme for JavaScript. It was created out of frustration felt
working with various documentation systems available.
Source code formatting:
/**
myClass
=======
This is my class. It rocks, and this is its _description_, which also
rocks.
Extends
-------
- someOtherClass
Methods
-------
- setName(name)
Where `name` is a `String`.
Use
---
// here is some sample code which shows how to use this class
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
12 of 70 05/01/2011 11:54 PM
Page 13
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 13/70
var x = new myClass(name);
> Note: use of the `name` reserved word is probaly a bad idea.
*/
Comment placement:
You can put your comments for your code either:
in your source code (anywhere and in as many pieces as you want) denoted with /** ...
*/ multiline-comment blocks
1.
separate markdown (*.mdown) files, probably (tho not necessarily) named to match your
JavaScript files
2.
Can't get much more flexible than that.
Comparison:
JavaScript is an extremely expressive language which is often difficult to describe in terms of meta
data and fields. Often, important information that needs to be documented just doesn't fit into a
neat, tidy spot.
jsdoc:
jsdoc in its various incarnations and some of its spawn like yuidoc take the approach that "what is
good for Java is good for JavaScript". All these flavors are based on javadoc formatting, and have
been in use for some time.
Aside from the regimented markup being a bit odd to read (admit it, even Java developers don't
love it), it suffers from an inflexibility with regard to all the coding patterns available with
JavaScript. Basically, it fails due for the same reason that all JavaScript libraries which attempt tosubvert JavaScript's natural object model fail. These solutions, while influential in the idea that some
form consistent coding approach could help us make better code, are not in the spirit of embracing
JavaScript.
Why then do so many developers continue to use a documentation tool which was born of the same
well-meaning yet misguided logic of "let's pretend JavaScript is Java"?
Natural Docs:
Excellent effort, but complex to set up and also tries to make a regimented system for documenting
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
13 of 70 05/01/2011 11:54 PM
Page 14
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 14/70
source code. It is extendable, but again, we have a documentation solution which is trying to force
JavaScript into a more limited set of features.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
14 of 70 05/01/2011 11:54 PM
Page 15
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 15/70
Observer Pattern
jo uses a variant on this OOP pattern quite extensively for notifications between objects.
When you think about JavaScript, most of the interesting things that happen are asynchronous: XHR
calls, loading scripts, accessing at database, making device-specific system calls; even user
interactions are all asynchronous in nature.
Instead of trying to hide from this often complex-looking stuff, jo embraces it and provides a
scheme to wrap all these different use cases in a consistent interface using joSubject.
PhoneGap
This excellent, lightweight mobile application library by Nitobi neutralizes device differences and
provides a stable webkit application shell. Jo is designed to work with PhoneGap out of the box,
and it's highly recommended.
LawnChairAnother tool by Nitobi , LawnChair is a client-side storage solution which stores JSON objects (in
SQLite or whatever the device supports). It looks promising, and the jo core has a special subclass
of joDataSource called joLawn which folds Nitobi's library into the Jo event model.
Supported Platforms
Jo is built on HTML5, so anything with decent support for these emerging standards should work
with Jo. The list of devices and platforms you can distribute your apps on is growing, but here's a
list of
Mobile Apps:
Most require PhoneGap to create a native app "shell". webOS doesn't require PhoneGap, but it is
useful for some things.
iOS 3+ for iPhone, iPad, iPod Touch
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
15 of 70 05/01/2011 11:54 PM
Page 16
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 16/70
Android 2.1+
webOS 1.4+
Symbian ^ 3
It's been reported that Jo works great with newer releases of Blackberry, but I haven't done any
testing with it yet.
Mobile Browsers:
All the mobile app platforms supported by Jo will work, but note that in most cases you'll be
fighting against the browser scroller (Android and webOS, I'm looking at you), and in some cases
event and rendering bugs will make life interesting and might require some CSS fiddling.
Desktop Apps:
HTML5 is making its way into desktop applications. Both native Mac OSX and Windows require
special builds of PhoneGap.
ChromeOS
Windows
Mac OSX 10.5+
Mac OSX DashBoard Widgets
It's been reported that Jo will work with Adobe AIR, but I haven't done any testing with it.
Desktop Browsers:
In general, all modern browsers which have decent HTML5 support will work well with Jo and its
CSS3. Note that Internet Explorer and FireFox 3.x can work, but you will have to play with the CSS
to get things going.
Safari 5+
Chrome 9+
Opera 10+
FireFox 4+
Internet Explorer 8+
For browsers, you will want to include css/browser.css in your project to revert joScroller and
joStackScroller to use native scrollbars.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
16 of 70 05/01/2011 11:54 PM
Page 17
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 17/70
Release Notes
Jo 0.4.1:
Emergency fix for joScroller on iOS, was affecting performance and tapability on
controls.
Jo 0.4.0:
Added new joSlider control and corresponding josliderthumb to CSS
Added css/browser.css for cases where you want to allow the browser to handle
scrolling purely with overflow:scroll
Tweaked joScroller, including removed the 50px fixed "bump" size (you can add it
back if you want)
Tweaked default CSS, made some controls less "roundy", thinned border on
joToggle
Changed readOnly and editable methods to setReadOnly()
Fixed some broken method chaining in joSound, joNavbar and a few other places
Important fixes in joDataSource, joRecord, joProperty and joList relating to the dataproperty
Fixed background image bug in joMenu
Fixed enable/disable methods for joButton and joControl
Fixed joEvent capture method to properly return event handler reference
Added resizeEvent to joGesture
Added clientX/clientY to joEvent
Added optional parameter passing for joCache get() method
Added pageOffsetTop and pageOffsetLeft methods to joDOM
Updated docs for joDOM, joEvent, joFileSource, jo, joControl, joSlider, joSound, joStack, joTable and joView
Jo 0.3.0:
New data methods: joFile, joFileSource, joRecord, joYQL
New widgets: joToggle, joExpando, joSelect, joOption, joNavbar
Even more improved joScroller performance, and the beginnings of horizontal and
free scroll support
Better "downgraded" scroller experience for less fancy browsers
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
17 of 70 05/01/2011 11:54 PM
Page 18
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 18/70
Changed default tags for input fields to input, etc.
New samples for file loading, YQL and a "kitchen sink" sample (which is more of a
bathroom sink; look for - more in the samples/test.html for now)New CSS default theme (built with Less CSS for those who are using our git repo)
Added joInterface, a method which will slurp HTML into Jo objects (experimental,
read the docs please)
Definitely check out the docs for joRecord as it's even easier to bind UI controls to a
data object
joPreference has been deprecated for now; see joRecord
joYield has been renamed to joDefer
CSS Skinning
jo makes extensive use of CSS for its widgets. As a result, it's extremely easy to skin and adapt
your user interface for different devices. The project will have a community-driven theme collection
to help reduce development time by choosing a stylesheet that most closely matches your
application (or device native controls).
HTML TagsOne feature jo exploits is the fact that modern browser engines treat unknown tags as -- tags. So
instead of mucking up your application's DOM and CSS space with a horde of div tags with
different CSS classes, it uses namespaced tags which are outside of your document's typical CSS
name space (except body).
Special Tag Examples:
<jocard>
<jotitle>My title</jotitle>
<jogroup>
<jolabel>Username</jolabel>
<input type="text">
<jodivider></jodivider>
<jobutton>Save</jobutton>
</jogroup>
</jocard>
One side benefit of this is that it is possible to load styled HTML content from another source and
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
18 of 70 05/01/2011 11:54 PM
Page 19
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 19/70
not have that content's CSS corrupt your application's user interface.
Bottom line here is the special UI controls you add with Jo can coexist with your standard HTML
content-driven tags without undue CSS headaches.
See joInterface and joView for more uses of direct HTML and DOM nodes which are common for
all UI elements.
License
Copyright 2010 Dave Balmer, Jr. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted
provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions
and the following disclaimer.
1.
Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials
provided with the distribution.
2.
THIS SOFTWARE IS PROVIDED BY DAVE BALMER, JR. "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL DAVE BALMER, JR. OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The views and conclusions contained in the software and documentation are those of the authors
and should not be interpreted as representing official policies, either expressed or implied, of Dave
Balmer, Jr.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
19 of 70 05/01/2011 11:54 PM
Page 20
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 20/70
jo
Singleton which the framework uses to store global infomation. It also is responsible for initializing
the rest of the framework, detecting your environment, and notifying your application when jo is
ready to use.
Methods:
load()
This method should be called after your DOM is loaded and before your app uses jo.Typically, you can call this function from your document's onLoad method, but it is
recommended you use more device-specific "ready" notification if they are available.
getPlatform()
Returns the platform you're running in as a string. Usually this is not needed, but can
be useful.
getVersion()
Returns the version of jo you loaded in the form of a string (e.g. 0.1.1).
matchPlatform(string)
Feed in a string list of desired platforms (e.g. "mozilla chrome ipad"), and
returns true if the identified platform is in the test list.
Events:
loadEvent
unloadEvent
These events are fired after jo loads or unloads, and can be used in your application
to perform initialization or cleanup tasks.
Function
jo extends the Function object to add a few goodies which augment JavaScript in a farily
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
20 of 70 05/01/2011 11:54 PM
Page 21
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 21/70
non-intrusive way.
Methods:
extend(superclass, prototype)
Gives you an easy way to extend a class using JavaScript's natural prototypal
inheritance. See Class Patterns for more information.
bind(context)
Returns a private function wrapper which automagically resolves context for this
when your method is called.
HTMLElement
This is a standard DOM element for JavaScript. Most of the jo views, continers and controls deal
with these so your application doesn't need to.
Methods:
Not a complete list by any means, but the useful ones for our purposes are:
appendChild(node)
insertChild(before, node)
removeChild(node)
Properties:
jo uses these properties quite a bit:
innerHTML
className
style
joCache
A singleton which makes it easy to setup deferred object creation and cached results. This is a
performance menchanism initially designed for UI views, but could be extended to handle data
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
21 of 70 05/01/2011 11:54 PM
Page 22
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 22/70
requests and other object types.
Methods:
set(key, call, context)
Defines a factory (call) for building an object keyed from the key string. The
context argument is optional, but provides a reference for this.
get(key)
Returns an object based on the key string. If an object has not been created which
corresponds to the key, joCache will call the constructor defined to create it and storethe reference for future calls to get().
Use:
Defining a view for on-demand use:
joCache.set("home", function() {
return new joCard([
new joTitle("Home"),
new joMenu([
"Top Stories",
"Latest News",
"Old News",
"No News"
])
]);
});
Displaying a view later:
mystack.push(joCache.get("home"));
// the first call to get() will instantiate
// the view, subsequent calls will return the
// view that was created the first time
// you can pass parameters into your view factory
var x = joCache.get("home", "My Title");
// note that if you want to use joCache to cache
// views which differ based on parameters passed in,
// you probably want your own caching mechanism instead.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
22 of 70 05/01/2011 11:54 PM
Page 23
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 23/70
joChain
Class which strings asyncronous calls together.
Methods:
add(Function, context, data)
start()
stop()
next()
joClipboard
Singleton which abstracts the system clipboard. Note that this is a platform dependant interface. By
default, the class will simply store the contents in a special joPreference named "joClipboardData"
to provide clipboard capabilities within your app.
Methods:
get()
set(String)
Low level methods which use just strings. At this time, you will need to stringify
your own data when setting, and extract your data when getting.
cut(joControl)
copy(joControl)
paste(joControl)
In serious need of rework; doesn't meet original goal of sequencing these calls. This class might
also become deprecated.“ „
Even if you think you're just going to use the default behavior, it is recommended that you
never manipulate the "joClipboardData" preference directly.“ „
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
23 of 70 05/01/2011 11:54 PM
Page 24
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 24/70
High level methods which work with any joControl or subclass. If a control supports
selections, cut() will automatically remove the selection after copying its contents.
Otherwise, cut() will work the same as copy().
joDOM
Singleton with utility methods for manipulating DOM elements.
Methods:
get(id)
Returns an HTMLElement which has the given id or if the id is not a string returns
the value of id.
create(type, style)
Type is a valid HTML tag type. Style is the same as setStyle() method. Returns anHTMLElement.
// simple
var x = joDOM.create("div", "mycssclass");
// more interesting
var x = joDOM.create("div", {
id: "name",
className: "selected",
background: "#fff",
color: "#000"
});
setStyle(tag, style)
Style can be an object literal with style information (including "id" or "className") or
a string. If it's a string, it will simply use the style string as the className for the new
element.
Note that the preferred and most cross-platform method for working with the DOM
Note: this is not working yet, steer clear (or contribute some working code!)“ „
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
24 of 70 05/01/2011 11:54 PM
Page 25
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 25/70
is to use className and possibly id and put your actual style information in your
CSS file. That said, sometimes it's easier to just set the background color in the code.
Up to you.
getParentWithin(node, ancestor)
Returns an HTMLElement which is the first child of the ancestor which is a parent of
a given node.
addCSSClass(HTMLElement, classname)
Adds a CSS class to an element unless it is already there.
removeCSSClass(HTMLElement, classname)
Removes a CSS class from an element if it exists.
toggleCSSClass(HTMLElement, classname)
Auto add or remove a class from an element.
pageOffsetLeft(HTMLElement) and pageOffsetHeight(HTMLElement)
Returns the "true" left and top, in pixels, of a given element relative to the page.
applyCSS(css, stylenode)
Applies a css string to the app. Useful for quick changes, like backgrounds and other
goodies. Basically creates an inline <style> tag. This method returns a reference to
the new <style> tag, which you can use with removeCSS() and subsequent calls to
applyCSS() as the stylenode argument.
loadCSS(filename)
Works the same as applyCSS() but loads the CSS from a file instead of a string.
removeCSS(stylenode)
Removes a <style> tag created with applyCSS() or loadCSS().
joEvent
Singleton with DOM event model utility methods. Ideally, application-level code shouldn't have to
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
25 of 70 05/01/2011 11:54 PM
Page 26
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 26/70
use this, but library code does.
Methods:
on(HTMLElement, event, Function, context, data)
Set a DOM event listener for an HTMLElement which calls a given Function with an
optional context for this and optional static data. Returns a reference to the handler
function, which is required if you need to remove() later.
capture(HTMLElement, event, function, context, data)
This is the same os on(), but captures the event at the node before its children. If indoubt, use on() instead.
remove(HTMLElement, event, handler)
Removes a previously declared DOM event. Note that handler is the return value of
the on() and capture() methods.
stop(event)
Stop event propogation.
preventDefault(event)
Prevent default action for this event.
block(event)
Useful for preventing dragging the window around in some browsers, also
highlighting text in a desktop browser.
getTarget(event)
Returns the HTMLElement which a DOM event relates to.
joLog
Wrapper for console.log() (or whatever device-specific logging you have). Also could be
extended to send log information to a RESTful service as well, handy for devices which don't have
decent logging abilities.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
26 of 70 05/01/2011 11:54 PM
Page 27
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 27/70
Use:
It's an all-in-one utility that's smart enough to ferret out whatever you throw at it and display it inthe console.
joLog("x=", x, "listdata=", listdata);
Basically, fill it up with strings, variables, objects, arrays and the function will produce a string
version of each argument (where appropriate; browser debuggers tend to display objects nicely) in
the same console line. Simple, effective, easy to use.
joSubject
Class for custom events using the Observer Pattern. This is designed to be used inside a subject to
create events which observers can subscribe to. Unlike the classic observer pattern, a subject can
fire more than one event when called, and each observer gets data from the subject. This is very
similar to YUI 2.x event model.
You can also "lock" the notification chain by using the capture() method, which tells the event to
only notify the most recent subscriber (observer) which requested to capture the event exclusively.
Methods:
subscribe(Function, context, data)
Both context and data are optional. Also, you may use the Function.bind(this)
approach instead of passing in the context as a separate argument. All subscribers
will be notified when the event is fired.
unsubscribe(Function, context)
Does what you'd think. The context is only required if you used one when you set
up a subscriber.
capture(Function, context, data)
Only the last subscriber to capture this event will be notified until it is released. Note
that you can stack capture() calls to produce a modal event heiarchy. Used in
conjunction with the resume() method, you can build an event chain where each
observer can fire the next based on some decision making.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
27 of 70 05/01/2011 11:54 PM
Page 28
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 28/70
release(Function, context)
Removes the most recent subscription called with capture(), freeing up the next
subscribers in the list to be notified the next time the event is fired.
fire(data)
Calls subscriber methods for all observers, and passes in: data from the subject, a
reference to the subject and any static data which was passed in the subscribe()
call.
resume(data)
If you used capture() to subscribe to this event, you can continue notifying other
subscribers in the chain with this method. The data parameter, as in fire(), is
optional.
Use:
In the subject (or "publisher") object:
// inside the Subject, we setup an event observers can subscribe to
this.changeEvent = new joSubject(this);
// to fire the event inside the Subject
this.changeEvent.fire(somedata);
In the observer (or "subscriber") object:
// simple case, using Function.bind()
somesubject.changeEvent.subscribe(this.mymethod.bind());
// explicit context (this)
somesubject.changeEvent.subscribe(this.mymethod, this);
// optional data which gets passed with the event fires
somesubject.changeEvent.subscribe(this.mymethod, this, "hello");
This is a very flexible way to handle messages between objects. Each subject may have multiple
events which any number of observer objects can subscribe to.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
28 of 70 05/01/2011 11:54 PM
Page 29
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 29/70
joTime
Time utility functions. More will be added, but only as needed by the framework. There are entire
libraries dedicated to extensive datetime manipulation, and Jo doesn't pretend to be one of them.
Methods:
timestamp()
Returns a current timestamp in milliseconds from 01/01/1970 from the system clock.
Constants:
SEC, MIN, HOUR, DAY
Convenience global constants which make it easier to manipulate timestamps.
Use:
var twoHoursLater = joTime.timestamp() + (HOUR * 2);
joDefer
Utility function which calls a given method within a given context after n milliseconds with optional
static data.
Use:
joDefer(Function, context, delay, data);
Note that delay defaults to 100ms if not specified, and data is optional.
joYield
Deprecated, use joDefer instead.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
29 of 70 05/01/2011 11:54 PM
Page 30
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 30/70
joDatabase
Wrapper class for WebKit SQLite database.
Methods:
open(datafile, size)
datafile is a filename, size is an optional parameter for initial allocation size for the
database.
close()
now()
Deprecated convenience method which returns a SQLite-formatted date string for use
in queries. Should be replaced with a utility function in joTime.
joDataSource
Wraps data acquisition in an event-driven class. Objects can subscribe to the changeEvent to
update their own data.
This base class can be used as-is as a data dispatcher, but is designed to be extended to handle
asynchronous file or SQL queries.
Methods:
set()
get()
clear()
setQuery(...)
getQuery()
load()
refresh()
Events:
changeEvent
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
30 of 70 05/01/2011 11:54 PM
Page 31
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 31/70
errorEvent
joFileSource
A special joDataSource which loads and handles a file. This class wraps joFile.
Extends:
joDataSource
joFile
A utility method which uses XMLHttpRequest to load a text-like file from either a remote server or
a local file.
Calling:
joFile(url, call, context, timeout)
Where:
url is a well-formed URL, or, in most cases, a relative url to a local file
call is a function to call when the operation completes
context is an optional scope for the function to call (i.e. value of this). You can also
ignore this parameter (or pass in null and use Function.bind(this) instead.
timeout is an optional parameter which tells joFile to wait, in seconds, for a
Under construction, use with care.
“ „
Note that some browsers and mobile devices will not allow you to load from just any URL,
and some will restrict use with local files especially (I'm looking at you, FireFox).
If your aim is to load JavaScript-like data (also, JSON), you may want to look at joScript
instead, which uses script tags to accomplish the job.
“„
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
31 of 70 05/01/2011 11:54 PM
Page 32
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 32/70
response before throwing an error.
Use:
// simple call with a global callback
var x = joFile("about.html", App.loadAbout);
// an inline function
var y = joFile("http://joapp.com/index.html", function(data, error) {
if (error) {
console.log("error loading file");
return;
}
console.log(data);
});
joPreference
A class used for storing and retrieving preferences in your application.
The interface for this is changing. joPreference will become a specialized application-level extension of joRecord in the near future. Until then, you should use joRecord to achieve this use-case.
Extends:
joRecord
joRecord
An event-driven wrapper for an object and its properties. Useful as a data interface for forms and
other collections of UI controls.
Extends:
joDataSource
Methods:
link(property)
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
32 of 70 05/01/2011 11:54 PM
Page 33
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 33/70
Returns a reference to a joProperty object which can be used with UI controls
(children of joControl) to automatically save or load data based on user interaction.
save()
Saves the object's data. The base class does not itself save the data; you will need to
make your own action for the save method, or have something which subscribes to
the saveEvent.
load()
Loads the object's data, and fires off notifications to any UI controls which are linked
to this joRecord object. Same as thesave()
method, you will have to make thisfunction do some actual file loading if that's what you want it to do.
getProperty(property)
setProperty(property, value)
Get or set a given property. Used in conjunction with setAutoSave(),
setProprty() will also trigger a call to the save() method.
getDelegate(property)
Returns a reference to the joProperty object which fires off events for data changes
for that property. If none exists, one is created. This method is used by the link()
method, and can be overriden if you extend this class to provide some other flavor
of a joDataSource to manage events for your properties.
Use:
// setup a joRecord
var r = new joRecord({
user: "Jo",
password: "1234",
active: true
});
// bind it to some fields
var x = new joGroup([
new joLabel("User"),
new joInput(r.link("user")),
new joLabel("Password"),
new joPasswordInput(r.link("password")),
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
33 of 70 05/01/2011 11:54 PM
Page 34
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 34/70
new joFlexBox([
new joLabel("Active"),
new joToggle(r.link("active"))
])
]);
And if you want the data to be persistent, or interact with some cloud service, you'll need to do
something like this:
// make something happen to load the data
r.load = function() {
// some AJAX or SQL call here
};
// make something happen to save the data
r.save = function() {
// some AJAX or SQL call here
};
You could also make your own subclass of joRecord with your own save and load methods using
extend() like this:
var preferences = function() {
// call to the superclass constructor
joRecord.apply(this, arguments);
};
preferences.extend(joRecord, {
save: function() {
// do an AJAX or SQL call here
},
load: function() {
// do an AJAX or SQL call here
}
}
See Class Patterns for more details on this method of "subclassing" in JavaScript.
joProperty
Used by joRecord to provide an event-driven binding to properties. This class is instantiated by
joRecord and not of much use on its own.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
34 of 70 05/01/2011 11:54 PM
Page 35
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 35/70
Extends:
joDataSource
Use:
See joRecord for examples.
joScript
Script tag loader function which can be used to dynamically load script files or make RESTful callsto many JSON services (provided they have some sort of callback ability). This is a low-level utility
function.
Calling:
joScript(url, callback, context, errorcallback, errorcontext)
url
callback is a function (supports bind, in which case context is optional)
context (usually this, and is optional)
Returns:
Calls your handler method and passes a truthy value if there was an error.
Use:
joScript("myscript.js", function(error, url) {
if (error)
console.log("script " + url + " didn't load.");
}, this);
joSQLDataSource
Need a URL with some examples of this.“ „
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
35 of 70 05/01/2011 11:54 PM
Page 36
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 36/70
SQL flavor of joDataSource which uses "HTML5" SQL found in webkit.
Methods:
setDatabase(joDatabase)
setQuery(query)
setParameters(arguments)
execute(query, arguments)
Events:
changeEvent
Fired when data is loaded after an execute() or when data is cleared.
errorEvent
Fired when some sort of SQL error happens.
Extends:
joDataSource
joYQL
A joDataSource geared for YQL RESTful JSON calls. YQL is like SQL, but for cloud services.
Pretty amazing stuff:
The Yahoo! Query Language is an expressive SQL-like language that lets you query, filter,
and join data across Web services. With YQL, apps run faster with fewer lines of code and a
smaller network footprint.
Yahoo! and other websites across the Internet make much of their structured data available to
developers, primarily through Web services. To access and query these services, developers
traditionally endure the pain of locating the right URLs and documentation to access and
query each Web service.
With YQL, developers can access and shape data across the Internet through one simple
language, eliminating the need to learn how to call different APIs.
“
„
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
36 of 70 05/01/2011 11:54 PM
Page 37
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 37/70
Yahoo! Query Language Home
Use:
A simple one-shot use would look like:
// setup our data source
var yql = new joYQL("select * from rss where url='http://davebalmer.wordpress.com'");
// subscribe to load events
yql.loadEvent.subscribe(function(data) {
joLog("received data!");
});
// kick off our call
yql.exec();
A more robust example with parameters in the query could look something like this:
// quick/dirty augmentation of the setQuery method
var yql = new joYQL();
yql.setQuery = function(feed, limit) {
this.query = "select * from rss where url='"
+ feed + "' limit " + limit
+ " | sort(field=pubDate)";
};
// we can hook up a list to display the results
var list = new joList(yql).attach(document.body);
list.formatItem = function(data, index) {
var html = new joListItem(data.title + " (" + data.pubDate + ")", index);
};
// later, we make our call with our parameters
yql.exec("http://davebalmer.wordpress.com", 10);
Methods:
setQuery()
Designed to be augmented, see the example above.
exec()
Extends:
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
37 of 70 05/01/2011 11:54 PM
Page 38
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 38/70
joDataSource
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
38 of 70 05/01/2011 11:54 PM
Page 39
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 39/70
joBusy
The idea here is to make a generic "spinner" control which you can overlay on other controls. It's
still in flux, don't use it just yet.
Extends:
joView
Methods:
setMessage(status)
You can update the status message in this busy box so users have a better idea why
the busy box is showing.
joButton
Button control.
// simple invocation
var x = new joButton("Done");
// optionally pass in a CSS classname to style the button
var y = new joButton("Cancel", "cancelbutton");
// like other controls, you can pass in a joDataSource
// which could be useful, so why not
var z = new joButton(joPreference.bind("processname"));
Extends:
joControl
Methods:
enable()
disable()
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
39 of 70 05/01/2011 11:54 PM
Page 40
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 40/70
joCaption
Basically, a paragraph of text.
Extends:
joControl
joCard
Special container for card views, more of an application-level view.
Extends:
joContainer
Methods:
activate()
deactivate()
These methods are called automatically by various joView objects, for now joStack is
the only one which does. Basically, allows you to add application-level handlers to
initialize or cleanup a joCard.
joCollectDEPRECATED use joInterface instead. This function is planned to die when jo goes beta.
joContainer
A view which is designed to contain other views and controls. Subclass to provide different layout
types. A container can be used to intantiate an entire tree of controls at once, and is a very powerful
UI component in jo.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
40 of 70 05/01/2011 11:54 PM
Page 41
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 41/70
Use:
// plain container
var x = new joContainer();
// HTML or plain text
var y = new joContainer("Some HTML");
// HTMLElement
var w = new joContainer(joDOM.get("mydiv"));
// nested inline structure with text, HTML, joViews or HTMLElements
var z = new joContainer([
new joTitle("Hello"),
new joList([
"Red",
"Green",
"Blue"
]),
new joFieldset([
"Name", new joInput(joPreference.bind("name")),
"Phone", new joInput(joPreference.bind("phone"))
]),
new joButton("Done")
]);
// set an optional title string, used with joNavbar
z.setTitle("About");
Extends:
joView
Events:
changeEvent
Methods:
setData(data)
The constructor calls this method if you provide data when you instantiate (see
example above)
push(data)
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
41 of 70 05/01/2011 11:54 PM
Page 42
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 42/70
Same support as setData(), but places the new content at the end of the existing
content.
setTitle(string)
getTitle(string)
Titles are optional, but used with joStack & joStackScroller to update a joNavbar
control automagically.
joControl
Interactive, data-driven control class which may be bound to a joDataSource, can receive focus
events, and can fire off important events which other objects can listen for and react to.
Extends:
joView
Events:
changeEvent
selectEvent
Methods:
setValue(value)
Many controls have a value in addition to their data. This is particularly useful for
joList, joMenu, joOption and other controls which has a list of possibilities (the
data) and a current seletion from those (the value).
enable()
disable()
Enable or disable the control, pretty much does what you'd expect.
focus()
blur()
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
42 of 70 05/01/2011 11:54 PM
Page 43
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 43/70
Manually control focus for this control.
setDataSource(joDataSource)
Tells this control to bind its data to any joDataSource or subclass.
setValueSource(joDataSource)
Tells this control to bind its value to any joDataSource type.
setReadOnly(state)
Certain controls can have their interaction turned off. State is either true or false.
See Also:
joRecord and joProperty are specialized joDataSource classes which make it simple to
bind control values to a data structure.
joDialog
This is a higher level container that wraps a joPopup with a joShim.
joDivider
Simple visual divider.
Extends:
joView
joExpando
A compound UI element which allows the user to hide/show its contents. The first object passed in
becomes the trigger control for the container, and the second becomes the container which expands
and contracts. This action is controlled in the CSS by the presence of the "open" class.
Use:
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
43 of 70 05/01/2011 11:54 PM
Page 44
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 44/70
This is a typical pattern:
// normal look & feel
var x = new joExpando([
new joExpandoTitle("Options"),
new joExpandoContent([
new joLabel("Label"),
new joInput("sample field")
])
]);
Note that joExpando doesn't care what sort of controls you tell it to use. In this example, we have a
joButton that hides and shows a DOM element:
// you can use other things though
var y = new joExpando([
new joButton("More..."),
joDOM.get("someelementid")
]);
Extends:
joContainer
Methods:
open()
close()
toggle()
Events:
openEvent
closeEvent
joExpandoContent
New widget to contain expando contents. This is normally used with joExpando, but not required.
Extends:
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
44 of 70 05/01/2011 11:54 PM
Page 45
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 45/70
joContainer
joExpandoTitleCommon UI element to trigger a joExpando. Contains a stylable arrow image which indicates
open/closed state.
Extends:
joControl
Use:
See joExpando use.
joFlexrow
Uses the flexible box model in CSS to stretch elements evenly across a row.
Use:
// a simple row of things
var x = new joFlexrow([
new joButton("OK"),
new joButton("Cancel")
]);
// making a control stretch
var y = new joFlexrow(new joInput("Bob"));
Extends:
joContainer
joFlexcol
Uses the flexible box model in CSS to stretch elements evenly across a column.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
45 of 70 05/01/2011 11:54 PM
Page 46
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 46/70
Use:
// fill up a vertical space with things
var x = new joFlexcol([
new joNavbar(),
new joStackScroller()
]);
Extends:
joContainer
joFocus
Singleton which manages global input and event focus among joControl objects.
Methods:
set(joControl)
Unsets focus on the last control, and sets focus on the control passed in.
clear()
Unsets focus on the last control.
refresh()
Sets focus back to the last control that was focused.
joFooterAttempt to make a filler object which pushed subsequent joView objects further down in the
container if possible (to attach its contents to the bottom of a card, for eaxmple).
This behavior requires a working box model to attach properly to the bottom of your container
view.“ „
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
46 of 70 05/01/2011 11:54 PM
Page 47
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 47/70
Extends:
joContainer
joGesture
Experimental global gesture handler (keyboard, dpad, back, home, flick?). This needs a lot more
fleshing out, so it's not (quite) ready for general consumption.
Events:
upEvent
downEvent
leftEvent
rightEvent
backEvent
forwardEvent
homeEvent
closeEvent
activateEvent
deactivateEvent
joGroupGroup of controls, purely visual.
Extends:
joContainer
joHTML
Note that the events setup here are for the browser or webOS. The setEvents method most
likely needs to change based on which OS you're running, although looking more deeply into
PhoneGap event layer.“ „
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
47 of 70 05/01/2011 11:54 PM
Page 48
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 48/70
A simple HTML content control. One interesting feature is it intercepts all <a> tag interactions and
fires off a selectEvent with the contents of the tag's href property.
This is a relatively lightweight approach to displaying arbitrary HTML data inside your app, but it
is not recommended you allow external JavaScript inside the HTML chunk in question.
Also keep in mind that your app document already has <html>, <head> and <body> tags. When
you use the setData() method on this view, make sure you don't use any of these tags to avoid weird
issues.
Extends:
joControl
Use:
// simple html string
var x = new joHTML("<h1>Hello World!</h1><p>Sup?</p>");
// use a joDataSource like a file loader
var y = new joHTML(new joFileSource("sample.html"));
joInput
Single-line text input control. When you instantiate or use setData(), you can either pass in aninitial value or a reference to a joDataSource object which it, like other joControl instances, will bind
to.
Use:
// simple value, simple field
var x = new joInput(a);
// set up a simple joRecord instance with some default data
var pref = new joRecord({
In a future version, it is feasible to load in stylesheets references in the HTML document's
<head> section. For now, that entire can of worms will be avoided, and it's left up to you,the developer, to load in any required CSS files using joDOM.loadCSS().“ „
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
48 of 70 05/01/2011 11:54 PM
Page 49
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 49/70
username: "Bob",
password: "password"
});
// attach the value to a data structure property
var y = new joInput(pref.link("username"));
Extends:
joControl
Methods:
focus()
blur()
You can manually set focus or call the blur() method (which also triggers a data
save).
setData()
Pass in either some arbitrary value for the control, or a reference to a joDataSource if
you want to automatically bind to a storage system (e.g. joPreference).
joInterface
EXPERIMENTAL
This class parses the DOM tree for a given element and attempts to attach appropriate joView
subclasses to all the relevant HTML nodes. Returns an object with references to all elements with
the id attribute set. This method helps turn HTML into HTML + JavaScript.
Use:
// an HTML element by its ID
This utility method is experimental! Be very careful with it. NOTE that for now, this class
requires you to remove whitespace in your HTML. If you don't know a good approach offhand
to do that, then this thing probably isn't ready for you yet.“ „
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
49 of 70 05/01/2011 11:54 PM
Page 50
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 50/70
var x = new joInterface("someid");
// a known HTML element
var y = new joInterface(someHTMLElement);
// the entire document body (careful, see below)
var z = new joInterface();
Returns:
A new object with a property for each element ID found. For example:
<!-- this DOM structure -->
<jocard id="login">
<jotitle>Login</jotitle>
<jogroup>
<jolabel>Username</jolabel>
<input id="username" type="text">
<jolabel>Password</jolabel>
<input id="password" type="password">
</jogroup>
<jobutton id="loginbutton">Login</jobutton>
</jocard>
Parsed with this JavaScript:
// walk the DOM, find nodes, create controls for each
var x = new joInterface("login");
Produces these properties:
x.login is a reference to a new joCard
x.username is a reference to a new joInput
x.password is a reference to a new joPassword
x.loginbutton is a reference to a new joButton
This in essence flattens your UI to a single set of properties you can use to access the controls that
were created from your DOM structure.
In addition, any unrecognized tags which have an id attribute set will also be loaded into the
properties.
Parsing complex trees:
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
50 of 70 05/01/2011 11:54 PM
Page 51
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 51/70
Yes, you can make a joInterface that encapsulates your entire UI with HTML. This is not
recommended for larger or more complex applications, some reasons being:
Rendering speed: if you're defining multiple views within a <jostack> (or another
subclass of joContainer), your users will see a flicker and longer load time while the
window renders your static tags and the extra views for the stack are removed from
view.
Double rendering: again with <jostack> tags, you're going to see a separate render
when the first view is redrawn (has to).
Load time: especially if you're doing a mobile app, this could be a biggie. You are
almost always going to be better off building the app controls with JavaScript
(especially in conjunction with joCache, which only creates DOM nodes for a given
view structure on demand).
If you really want to use HTML as your primary means of defining your UI, you're better off
putting your major UI components inside of a <div> (or other tag) with display: none set in its
CSS property. Like this:
<!-- in your CSS: .hideui { display: none } -->
<div class="hideui" id="cards"><jocard id="about">
<jotitle>About this app</jotitle>
<johtml>
This is my app, it is cool.
</johtml>
<jobutton>Done</jobutton>
</jocard>
<jocard id="login">
... etc ...
</jocard>
</div>
Then in your JavaScript:
// pull in all our card views from HTML
var cards = new joInterface("cards");
Definitely use this class judiciously or you'll end up doing a lot of recatoring as your application
grows.
Flattening UI widget references:
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
51 of 70 05/01/2011 11:54 PM
Page 52
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 52/70
This is both good and bad, depending on your coding style and complexity of your app. Because
all the tags with an ID attribute (regardless of where they are in your tag tree) get a single
corresponding property reference, things could get very messy in larger apps. Again, be smart.
joLabel
Label view, purely a visual presentation. Usually placed in front of input fields and other controls.
Extends:
joView
joList
A widget class which expects an array of any data type and renders the array as a list. The list
control handles DOM interactions with only a single touch event to determine which item was
selected.
Extends:
joControl
Events:
selectEvent
Fired when an item is selected from the list. The data in the call is the index of the
item selected.
changeEvent
Fired when the data is changed for the list.
Methods:
formatItem(data, index)
When subclassing or augmenting, this is the method responsible for rendering a list
item's data.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
52 of 70 05/01/2011 11:54 PM
Page 53
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 53/70
compareItems(a, b)
For sorting purposes, this method is called and should be overriden to support
custom data types.
// general logic and approriate return values
if (a > b)
return 1;
else if (a == b)
return 0;
else
return -1
setIndex(index)
getIndex()
DEPRECATED USe setValue() and getValue() instead, see joControl.
refresh()
setDefault(message)
Will present this message (HTML string) when the list is empty. Normally the list isempty; this is a convenience for "zero state" UI requirements.
getNodeData(index)
getLength()
next()
prev()
setAutoSort(boolean)
joMenu
Simple menu class with optional icons.
Extends:
joList
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
53 of 70 05/01/2011 11:54 PM
Page 54
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 54/70
Methods:
setData(menudata)
See the example below for the format of the menu data.
Use:
// simple inline menu; you can always setup the menu items (or change
// them) but using the `setData()` method, same as any joView
var menu = new joMenu([
{ title: "About" },
{ title: "Frequently Asked Questions", id: "faq" },
{ title: "Visit our website", id: "visit", icon: "images/web" }
]);
// simple inline function event handler
menu.selectEvent.subscribe(function(id) {
switch (id) {
case "0":
// the "About" line; if no id, the index of the menu item is used
stack.push(aboutCard);
break;
case "faq":
stack.push(faqCard);
break;
case "visit":
stack.push(visitCard);
break;
}
});
Advanced Use:
This could actually be called "more consistent and simple" use. If your menus are static, you couldalways setup an id-based dispatch delegate which pushes the appropriate card based on the menu
id selected.
You could use the id in conjunction with view keys you create with joCache. The handler would
then be something like:
menu.selectEvent.subscribe(function(id) {
mystack.push(joCache.get(id));
});
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
54 of 70 05/01/2011 11:54 PM
Page 55
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 55/70
joNavbar
Floating navigation control. Usually tied to a joStack or joStackScroller. Will handle display of a
"back" button (controllable in CSS) and show the title string of the current view in a stack (if it
exists).
Use:
// make a stack
var stack = new joStackScroller();
// new navbar
var x = new joNavbar();
// link to a stack
x.setStack(stack);
Methods:
back()
Signals the associated stack to move back in its stack (i.e. calls the stack's pop()
method).
setStack(joStack or joStackScroller)
Links this control to a stack.
joBackButton
A "back" button, which can be made to be shown only in appropriate platforms (e.g. iOS, Safari,
Chrome) through CSS styling.
See joNavbar for more information.
Extends:
joButton
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
55 of 70 05/01/2011 11:54 PM
Page 56
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 56/70
joOption
This controls lets the user select one of a few options. Basically, this is a menu with a horizontal
layout (depending on your CSS).
Use:
// simple set of options
var x = new joOption([
"Red",
"Blue",
"Green"
]);
// set the current value
x.setValue(2);
// or, associate the value with a joRecord property
var pref = new joRecord();
var y = new joOption([
"Orange",
"Banana",
"Grape",
"Lime"
], pref.link("fruit"));
// you can even associate the list with a datasource
var fruits = new joDataSource( ... some query stuff ...);
var z = new joOption(fruits, pref.link("fruit"));
Extends:
joMenu
joPasswordInput
Secret data input field (e.g. displays ****** instead of secret).
Extends:
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
56 of 70 05/01/2011 11:54 PM
Page 57
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 57/70
joInput
joPopup
A simple popup control. Pass in the UI contents as you would any other subclass of joContainer
(e.g. joCard).
Methods:
show()
hide()
These do what you'd expect.
Extends:
joContainer
Events:
showEvent
hideEvent
joScreenAbstraction layer for the device screen. Uses document.body as its DOM element and allows other
controls to be nested within (usually a joStack or other high-level containers or controls).
Methods:
alert(title, message, buttons)
Simple alert box. The buttons parameter is optional; a simple "OK" button is added
if nothing is specified.
Note that this requires CSS3 which is known not to be currently supported in Opera or
Internet Explorer.“ „
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
57 of 70 05/01/2011 11:54 PM
Page 58
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 58/70
showPopup(joView)
hidePopup(joView)
These methods allow you to do a completely custom modal joPopup. Pass in either a
joView, an array of them, or and HTMLElement or a string, the same as you would
when you create a joCard or other child of joContainer.
Extends:
joContainer
Use:
var x = new joScreen([
new joNav(),
new joStack(),
new joToolbar()
]);
// show a simple alert dialog
x.alert("Hello", "This is an alert");
// a more complex alert
x.alert("Hola", "Do you like this alert?", [
{ label: "Yes", action: yesFunction, context: this },
{ label: "No", action: noFunction, context: this }
]);
// a completely custom popup
x.showPopup(myView);
Events:
resizeEvent
menuEvent
activateEvent
deactivateEvent
backEvent
forwardEvent
joScroller
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
58 of 70 05/01/2011 11:54 PM
Page 59
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 59/70
A scroller container. Ultimately, mobile webkit implementations should properly support scrolling
elements that have the CSS overflow property set to scroll or auto. Why don't they, anyway?
Until some sanity is adopted, we need to handle this scrolling issue ourselves. joScroller expects asingle child to manage scrolling for.
Use:
// make a scroller and set its child later
var x = new joScroller();
x.setData(myCard);
// or define things inline, not always a good idea
var y = new joScroller(new joList(mydata));
// you can dump a big hunk of HTML in there, too
// since jo wraps strings in a container element, this works
var z = new joScroller('Some giant HTML as a string');
Extends:
joContainer
Methods:
scrollBy(position)
scrollTo(position or joView or HTMLElement)
Scrolls to the position or the view or element. If you specify an element or view,
make sure that element is a child node, or you'll get interesting results.
setScroll(horizontal, vertical)
Tells this scroller to allow scrolling the vertical, horizontal, both or none.
// free scroller z.setScroll(true, true);
// horizontal z.setScroll(true, false);
// no scrolling z.setScroll(false, false);
joSelect
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
59 of 70 05/01/2011 11:54 PM
Page 60
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 60/70
Multi-select control which presents a set of options for the user to choose from.
Methods:
setValue(value)
Set the current value, based on the index for the option list.
getValue()
Returns the index of the current selected item.
Extends:
joExpando
Consumes:
joSelectTitle
joSelectList
Properties:
field
Reference to the value field for this control.
list
Reference to the joSelectList for this control.
Use:
// pass in an array of options
var x = new joSelect([ "Apples", "Oranges", "Grapes" ]);
// pass in a current value
var y = new joSelect([ "Apples", "Oranges", "Grapes" ], 2);
// respond to the change event
y.changeEvent = function(value, list) {
console.log("Fruit: " + list.getNodeValue(value));
});
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
60 of 70 05/01/2011 11:54 PM
Page 61
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 61/70
joSelectTitle
joSelect flavor of joExpandoTitle.
Extends:
joExpandoTitle
joSelectList
A selection list of options used by joSelect.
Extends:
joList
joShim
A simple screen dimmer. Used mostly for popups and other modal use cases.
Methods:
show()
hide()
These do what you'd expect.
Extends:
joView
Events:
showEvent
hideEvent
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
61 of 70 05/01/2011 11:54 PM
Page 62
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 62/70
joSlider
Slider control, horizontal presentation (may be extended later to allow for vertical and x/y).
Extends:
joControl
Methods:
setRange(min, max, snap)
Where min/max is a number, either integer or decimal, doesn't matter. If max and min are integers,
then snap defaults to 1, otherwise it is set to 0 (no snap, which allows free movement).
The optional snap value adjusts the granularuty of choices. Set to 0 for free-floating, or any other
positive number. Any snap that is less than 0 or greater than the total range of possible values will
be ignored.
Use:
// basic slider, will allow any decimal value
// between 0 and 1, defaults to 0
var x = new joSlider();
// custom range and default value set
var y = new joSlider(0).setRange(-10, 10);
// percent slider, with 5% snap
var z = new joSlider(0).setRange(0, 100, 5);
// responding to change events
var r = new joSlider().changEvent.subscribe(function(value) {
console.log(value);
}, this);
joSound
Play preloaded sound effects using the HTML5 Audio object. This module could be wildly
different for various platforms. Be warned.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
62 of 70 05/01/2011 11:54 PM
Page 63
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 63/70
Methods:
play()
pause()
rewind()
stop()
Basic sound controls.
setLoop(n)
Tell the joSound to automatically loop n times. Set to -1 to loop continuously until
pause().
setVolume(level)
Level is a decimal value from 0 to 1. So, half volume would be 0.5.
Events:
endedEvent
errorEvent
joStack
A UI container which keeps an array of views which can be pushed and popped.
The DOM elements for a given view are removed from the DOM tree when popped so we keep the
render tree clean.
Extends:
joView
Methods:
push(joView | HTMLElement)
Pushes a new joView (or HTMLELement) onto the stack.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
63 of 70 05/01/2011 11:54 PM
Page 64
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 64/70
pop()
Pulls the current view off the stack and goes back to the previous view.
home()
Return to the first view, pop everything else off the stack.
show()
hide()
Controls the visibility of the entire stack.
forward()
back()
Much like your browser forward and back buttons, only for the stack.
setLocked(boolean)
The setLocked() method tells the stack to keep the first view pushed onto the stack
set; that is, pop() won't remove it. Most apps will probably use this, so setting it as a
default for now.
Events:
showEvent
hideEvent
homeEvent
pushEvent
popEvent
Notes:
Should set classNames to new/old views to allow for CSS transitions to be set (swiping in/out,
cross fading, etc). Currently, it does none of this.
Also, some weirdness with the new forward() and back() methods in conjuction with push() --
need to work on that, or just have your app rigged to pop() on back to keep the nesting simple.
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
64 of 70 05/01/2011 11:54 PM
Page 65
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 65/70
joStackScroller
What happens when you mix joStack and joScroller? You get this class. Use exactly as you would
joStack, only it automatically puts a scroller in the stack as needed. At some point, this might get
folded into joStack, but for now it's a special class.
It also handles the scrollTo() and scrollBy() methods from joScroller.
Extends:
joStack joScroller
joTabBar
Tab bar widget.
Extends:
joList
Model:
Data is expected to be an array of { type: "", label: ""} objects, in the display order for the
bar.
joTableTable control, purely visual representation of tabular data (usually an array of arrays).
Use:
// simple table with inline data
var x = new joTable([
["Nickname", "Phone", "Email"],
["Bob", "555-1234", "[email protected] "],
["Jo", "555-3456", "[email protected] "],
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
65 of 70 05/01/2011 11:54 PM
Page 66
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 66/70
["Jane", "555-6789", "[email protected] "]
]);
// we can respond to touch events in the table
x.selectEvent.subscribe(function(index, table) {
// get the current row and column
joLog("Table cell clicked:", table.getRow(), table.getCol());
// you can also get at the cell HTML element as well
joDOM.setStyle(table.getNode(), { fontWeight: "bold" });
});
Extends:
joList
Methods:
setCell(row, column)
Sets the active cell for the table, also makes it editiable and sets focus.
getRow(), getCol()
Return the current row or column
joTextarea
Multi-line text input control. When you instantiate or use setData(), you can either pass in an
initial value or a reference to a joDataSource object which it, like other joControl instances, will bind
to.
Basically, this is just a multi-line version of joInput.
Use:
// simple multi-line field
var sample = "This is some sample text to edit.";
var x = new joTextarea(sample);
// setting the style inline using chaining
var f = new joTextarea(sample).setStyle({
minHeight: "100px",
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
66 of 70 05/01/2011 11:54 PM
Page 67
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 67/70
maxHeight: "300px"
});
// adding a simple change event handler using chaining
var h = new joTextarea(sample).changeEvent.subscribe(function(data) {
joLog("text area changed:", data);
});
// attach the value to a preference
var y = new joTextarea(joPreference.bind("username"));
// attach input control to a custom joDataSource
var username = new joDataSource("bob");
var z = new joTextarea(username);
Extends:
joInput
joTitle
Title view, purely a visual presentation.
Extends:
joContainer
joToggle
Boolean widget (on or off).
Methods:
setLabels(Array)
You can change the labels for this control, which default to "Off" and "On".
Extends:
joControl
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
67 of 70 05/01/2011 11:54 PM
Page 68
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 68/70
Use:
// simple
var x = new joToggle();
// with value
var y = new joToggle(true);
// with custom labels
var z = new joToggle().setLabels(["No", "Yes"]);
See Data Driven Controls for more examples.
joToolbar
Locks UI controls to the bottom of whatever you put this container into.
Extends:
joContainer
joView
Base class for all other views, containers, controls and other visual doo-dads.
Use:
var x = new joView(data);
Where data is either a text or HTML string, an HTMLElement, or any joView object or subclass.
Methods:
setData(data)
getData()
createContainer(type, classname)
setContainer(HTMLElement)
getContainer()
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
68 of 70 05/01/2011 11:54 PM
Page 69
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 69/70
clear()
refresh()
attach(HTMLElement or joView)
detach(HTMLElement or joView)
Convenience methods which allow you to append a view or DOM node to the
current view (or detach it).
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html
69 of 70 05/01/2011 11:54 PM
Page 70
8/7/2019 Jo Documentaion
http://slidepdf.com/reader/full/jo-documentaion 70/70
Index
Jo HTML5 Mobile App Framework Documentaion http://joapp.com/docs/index.html