NAME
JQuery::Mobile - interface to jQuery Mobile
SYNOPSIS
use
JQuery::Mobile;
my
$jquery_mobile
= JQuery::Mobile->new(
config
=> {
'app-title'
=>
'Hello Mobile World'
});
# create a listview
my
$list
=
$jquery_mobile
->listview(
anchor
=> {
rel
=>
'dialog'
,
transition
=>
'pop'
},
items
=> [
{
value
=>
'Quick List'
,
divider
=> 1},
{
aside
=>
'02/06'
,
count
=>
'6'
,
image
=>
'http://placehold.it/100x100'
,
title
=>
'One'
,
href
=>
'#item-link'
},
{
aside
=>
'03/07'
,
count
=>
'8'
,
image
=>
'http://placehold.it/100x100'
,
title
=>
'Two'
,
href
=>
'#item-link'
},
{
aside
=>
'04/08'
,
count
=>
'10'
,
image
=>
'http://placehold.it/100x100'
,
title
=>
'Three'
,
href
=>
'#item-link'
},
],
filter
=>
'true'
,
);
# renders a complete HTML page using a "multi-page" template (see reference http://jquerymobile.com/test/docs/pages/page-anatomy.html)
$jquery_mobile
->pages(
pages
=> [
{
id
=>
'home'
,
header
=> {
content
=>
'<h1>Home</h1>'
},
content
=>
$list
},
{
id
=>
'item-link'
,
header
=> {
content
=>
'<h1>Item Heading</h1>'
},
content
=>
'Lorem ipsum dolor sit amet, consectetur adipisicing elit'
},
]
);
DESCRIPTION
JQuery::Mobile is an interface to jQuery Mobile. It generates HTML markups, such as navbars, forms, and listviews, that are compatible with jQuery Mobile.
METHODS
new
To instantiate a new JQuery::Mobile object:
my
$jquery_mobile
= JQuery::Mobile->new();
Here is a list of optional parameters when instantiating a JQuery::Mobile object:
# default values are shown
my
$jquery_mobile
= JQuery::Mobile->new(
config
=> {
'head'
=> 1,
# include <html>, <head>, and <body> tag when rendering a page
'viewport'
=>
'width=device-width, initial-scale=1'
,
# default viewport
'apple-mobile-web-app-capable'
=> 1,
# enable as apple web app
'apple-touch-icon'
=>
''
,
# path to apple web app icon image
'apple-touch-icon-72'
=>
''
,
# path to apple web app icon image (72x72 pixels)
'apple-touch-icon-114'
=>
''
,
# path to apple web app icon image (114x114 pixels)
'apple-touch-startup-image'
=>
''
,
# path to apple web app startup image
'app-css'
=> [],
# global application CSS files
'app-js'
=> [],
# global application JS files
'app-inline-css'
=>
' span.invalid{color:#F00000;line-height: 1.5;}'
, # inline CSS code
'app-inline-js'
=>
''
,
# inline JS code
'app-title'
=>
''
,
# <title> in <head>
}
);
The allowed HTML and data-* attributes for each UI component can be customised. By default, HTML attributes are very stict to ensure a clean markup. For data-* attributes, see reference: http://jquerymobile.com/test/docs/api/data-attributes.html.
# default values are shown
my
$jquery_mobile
= JQuery::Mobile->new(
config
=> {
'header-footer-html-attribute'
=> [
'id'
,
'class'
],
'header-footer-data-attribute'
=> [
'id'
,
'fullscreen'
,
'position'
,
'theme'
],
'navbar-html-attribute'
=> [
'id'
,
'class'
],
'navbar-data-attribute'
=> [
'disable-page-zoom'
,
'enhance'
,
'fullscreen'
,
'iconpos'
,
'tap-toggle'
,
'theme'
,
'transition'
,
'update-page-padding'
,
'visible-on-page-show'
],
'navbar-item-html-attribute'
=> [
'id'
,
'class'
,
'target'
],
'navbar-item-data-attribute'
=> [
'ajax'
,
'icon'
,
'iconpos'
,
'iconshadow'
,
'prefetch'
,
'theme'
],
'page-html-attribute'
=> [
'id'
,
'class'
],
# combine data-attributes for page and dialog
'page-data-attribute'
=> [
'add-back-btn'
,
'back-btn-text'
,
'back-btn-theme'
,
'close-btn-text'
,
'corners'
,
'dom-cache'
,
'enhance'
,
'overlay-theme'
,
'role'
,
'shadow'
,
'theme'
,
'title'
,
'tolerance'
,
'url'
],
'popup-html-attribute'
=> [
'id'
,
'class'
],
'popup-data-attribute'
=> [
'corners'
,
'overlay-theme'
,
'shadow'
,
'theme'
,
'tolerance'
,
'position-to'
,
'rel'
,
'role'
,
'transition'
],
'listview-html-attribute'
=> [
'id'
,
'class'
],
'listview-data-attribute'
=> [
'autodividers'
,
'count-theme'
,
'divider-theme'
,
'enhance'
,
'filter'
,
'filter-placeholder'
,
'filter-theme'
,
'filtertext'
,
'header-theme'
,
'inset'
,
'split-icon'
,
'split-theme'
,
'theme'
],
'listview-item-html-attribute'
=> [
'id'
,
'class'
],
'listview-item-data-attribute'
=> [
'ajax'
,
'mini'
,
'rel'
,
'theme'
,
'transition'
],
'collapsible-html-attribute'
=> [
'id'
,
'class'
],
'collapsible-data-attribute'
=> [
'collapsed'
,
'collapsed-icon'
,
'content-theme'
,
'expanded-icon'
,
'iconpos'
,
'inset'
,
'mini'
,
'theme'
],
'collapsible-set-html-attribute'
=> [
'id'
,
'class'
],
'collapsible-set-data-attribute'
=> [
'collapsed-icon'
,
'content-theme'
,
'expanded-icon'
,
'iconpos'
,
'inset'
,
'mini'
,
'theme'
],
'controlgroup-html-attribute'
=> [
'id'
,
'class'
],
'controlgroup-data-attribute'
=> [
'enhance'
,
'iconpos'
,
'theme'
,
'type'
],
'button-html-attribute'
=> [
'id'
,
'name'
,
'class'
,
'maxlength'
,
'size'
,
'type'
,
'value'
],
'button-html-anchor-attribute'
=> [
'id'
,
'class'
,
'href'
,
'target'
],
'button-data-attribute'
=> [
'ajax'
,
'corners'
,
'dialog'
,
'direction'
,
'dom-cache'
,
'external'
,
'icon'
,
'iconpos'
,
'iconshadow'
,
'inline'
,
'mini'
,
'position-to'
,
'prefetch'
,
'rel'
,
'role'
,
'shadow'
,
'theme'
,
'transition'
],
'form-html-attribute'
=> [
'id'
,
'action'
,
'class'
,
'enctype'
,
'method'
],
'form-data-attribute'
=> [
'enhance'
,
'theme'
,
'ajax'
],
'input-html-attribute'
=> [
'id'
,
'class'
,
'disabled'
,
'max'
,
'maxlength'
,
'min'
,
'name'
,
'pattern'
,
'placeholder'
,
'readonly'
,
'required'
,
'size'
,
'type'
,
'value'
,
'accept'
,
'capture'
],
'input-data-attribute'
=> [
'corners'
,
'highlight'
,
'icon'
,
'iconpos'
,
'iconshadow'
,
'inline'
,
'mini'
,
'shadow'
,
'theme'
,
'track-theme'
],
'textarea-html-attribute'
=> [
'id'
,
'name'
,
'class'
,
'rows'
,
'cols'
,
'readonly'
,
'disabled'
,
'title'
,
'required'
,
'placeholder'
,
'title'
,
'pattern'
],
'textarea-data-attribute'
=> [
'mini'
,
'theme'
],
'select-html-attribute'
=> [
'id'
,
'class'
,
'size'
,
'maxlength'
,
'readonly'
,
'disabled'
,
'title'
,
'required'
,
'placeholder'
,
'title'
,
'pattern'
],
'select-data-attribute'
=> [
'icon'
,
'iconpos'
,
'inline'
,
'mini'
,
'native-menu'
,
'overlay-theme'
,
'placeholder'
,
'theme'
],
'radio-checkbox-html-attribute'
=> [
'id'
,
'class'
,
'readonly'
,
'disabled'
,
'title'
,
'required'
,
'placeholder'
,
'title'
,
'pattern'
,
'value'
],
'radio-checkbox-data-attribute'
=> [
'mini'
,
'theme'
]
}
);
The label
parameter accepts a sub callback to alter how form field labels are being generated:
my
$jquery_mobile
= JQuery::Mobile->new(
config
=> {
'label'
=>
sub
{
my
$args
=
shift
;
return
'<strong>'
.
$args
->{label} .
'*</strong>'
if
$args
->{required};
return
$args
->{label};
},
}
);
head
head()
is called by page()
and pages()
internally to render the HTML header. Parameters via new()
controlls the output of head()
.
header
header()
generates header toolbars. Text, buttons, or navbar()
can be passed to the content
parameter.
$jquery_mobile
->header(
content
=>
$jquery_mobile
->button(
href
=>
'#'
,
value
=>
'Home'
,
icon
=>
'home'
,
iconpos
=>
'notext'
) .
'<h1>Main Title</h1>'
,
);
prints:
<div data-role=
"header"
>
<a data-icon=
"home"
data-iconpos=
"notext"
data-role=
"button"
href=
"#"
>Home</a>
<h1>Main Title</h1>
</div><!-- /header -->
Attributes defined in header-footer-html-attribute
and header-footer-data-attribute
can be passed to header()
, based on the default configuration:
$jquery_mobile
->header(
'content'
=>
'<h1>Header Content</h1>'
,
'id'
=>
'home-main-header'
,
'class'
=>
'site-header'
,
'data-id'
=>
'main-header'
,
# use the 'data-*' prefix since 'id' is both a HTML and data atrribute
'fullscreen'
=>
'true'
,
'position'
=>
'fixed'
,
'theme'
=>
'e'
);
footer
Similar to header()
, footer()
generates footer toolbars. Attributes defined in header-footer-html-attribute
and header-footer-data-attribute
can be passed to footer()
.
$jquery_mobile
->footer(
position
=>
'fixed'
,
content
=>
'Footer content'
);
popup
popup()
generates popup container divs. Content can be passed via the content
parameter:
my
$popup
=
$jquery_mobile
->popup(
id
=>
'popup'
,
content
=>
'Lorem ipsum dolor sit amet, consectetur adipisicing elit'
);
Attributes defined in popup-html-attribute
and popup-data-attribute
can be passed to popup()
. Please note that as of writing (jQuery Mobile 1.2), according to the jQuery Mobile website, popups "must live within the page wrapper (for now)".
page
page()
generates a container divs. It accepts the following parameters:
role
-
role
can be either "page" or "dialog", defaulted to "page". head
-
page()
includes HTMLhead
andbody
wrapper tags by default. Sethead
to "0" to disable that:print
$jquery_mobile
->page(
head
=> 0);
content
-
content
accepts text string. header
-
header
includes a header toolbars.header
accepts a hashref of parameters that gets passed directly toheader()
. -
footer
includes a footer toolbars.footer
accepts a hashref of parameters that gets passed directly tofooter()
.
For example:
$jquery_mobile
->page(
header
=> {
content
=>
$jquery_mobile
->button(
href
=>
'#'
,
value
=>
'Home'
,
icon
=>
'home'
,
iconpos
=>
'notext'
) .
'<h1>Main Title</h1>'
,
},
footer
=> {
position
=>
'fixed'
,
content
=>
'<h3>Footer content</h3>'
},
content
=>
'Lorem ipsum dolor sit amet, consectetur adipisicing elit'
);
pages
pages()
generates a "multi-page" template. It accepts the following parameters:
head
-
pages()
includes HTMLhead
andbody
wrapper tags by default. Sethead
to "0" to disable that. pages
-
pages
accepts an arrayref of parameters acceptable bypage()
.
$jquery_mobile
->pages(
pages
=> [
{
id
=>
'page-1'
,
header
=> {
content
=>
'<h1>Page One Heading</h1>'
},
content
=>
'Cillum dolore eu fugiat nulla pariatur. '
.
$jquery_mobile
->button(
icon
=>
'arrow-r'
,
value
=>
'Page 2'
,
href
=>
'#page-2'
)},
{
id
=>
'page-2'
,
header
=> {
content
=>
'<h1>Page Two Heading</h1>'
},
content
=>
'Excepteur sint occaecat cupidatat non'
},
]
);
form
form()
generates web forms. It accepts attributes defined in form-html-attribute
and form-data-attribute
. Fields are passed in via the fields
arrayref. See form inputs below for reference.
my
$form
=
$jquery_mobile
->form(
title
=>
'The Form'
,
description
=>
'A description of the form'
,
action
=>
'/'
,
method
=>
'get'
,
# defaulted to 'post'
fields
=> [
{
name
=>
'first_name'
,
required
=>
'required'
},
{
name
=>
'last_name'
,
label
=>
'Surname'
,
required
=>
'required'
},
{
name
=>
'email'
,
type
=>
'email'
,
required
=>
'required'
},
{
name
=>
'password'
,
type
=>
'password'
},
{
name
=>
'avatar'
,
type
=>
'file'
,
accept
=>
'image/*'
,
capture
=>
'camera'
},
{
name
=>
'comment'
,
type
=>
'textarea'
},
{
type
=>
'radio'
,
name
=>
'gender'
,
options
=> [
'Male'
,
'Female'
]},
{
type
=>
'checkbox'
,
name
=>
'country'
,
options
=> {
'AU'
=>
'Austalia'
,
'US'
=>
'United States'
},
value
=>
'AU'
},
{
type
=>
'select'
,
name
=>
'heard'
,
label
=>
'How did you hear about us'
,
options
=> [
'Facebook'
,
'Twitter'
,
'Google'
,
'Radio'
,
'Other'
]},
],
controlgroup
=> {
type
=>
'horizontal'
},
# use controlgroup to group the buttons, default to false, accepts "1" or a hashref
buttons
=> [
{
value
=>
'Submit'
,
type
=>
'submit'
,
icon
=>
'arrow-r'
,
theme
=>
'b'
},
{
value
=>
'Cancel'
,
href
=>
'#'
,
icon
=>
'delete'
}
],
);
$jquery_mobile
->page(
content
=>
$form
);
Javascript validation can be added to the form using jQuery-Mobilevalidate https://github.com/dannyglue/jQuery-Mobilevalidate/:
my
$jquery_mobile
= JQuery::Mobile->new(
config
=> {
'app-title'
=>
'Hello Mobile World'
,
'app-js'
=> [
'https://raw.github.com/dannyglue/jQuery-Mobilevalidate/master/jquery.mobilevalidate.min.js'
],
'app-inline-js'
=> '$(document).
bind
(
"pageinit"
, function(){
$(
"form"
).mobilevalidate({novalidate: true});
});',
}
);
my
$form
=
$jquery_mobile
->form(
title
=>
'Testing Form Validation'
,
action
=>
'/'
,
fields
=> [
{
name
=>
'email'
,
type
=>
'email'
,
required
=>
'required'
},
{
name
=>
'password'
,
type
=>
'password'
,
required
=>
'required'
},
{
type
=>
'checkbox'
,
name
=>
'country'
,
options
=> {
'AU'
=>
'Austalia'
,
'US'
=>
'United States'
},
value
=>
'AU'
,
required
=>
'required'
},
{
type
=>
'select'
,
name
=>
'heard'
,
label
=>
'How did you hear about us'
,
options
=> [
'Facebook'
,
'Twitter'
,
'Google'
,
'Radio'
,
'Other'
],
required
=>
'required'
},
],
buttons
=> [
{
value
=>
'Submit'
,
type
=>
'submit'
,
icon
=>
'arrow-r'
,
theme
=>
'b'
},
],
);
$jquery_mobile
->pages(
pages
=> [
{
id
=>
'form'
,
content
=>
$form
},
{
id
=>
'errordialog'
,
role
=>
"dialog"
,
header
=> {
content
=>
'<h1>Validating</h1>'
},
content
=>
''
},
]
);
listview
listview()
generates listviews. It accepts attributes defined in listview-html-attribute
and listview-data-attribute
.
my
$list
=
$jquery_mobile
->listview(
anchor
=> {
rel
=>
'dialog'
,
transition
=>
'pop'
},
# anchor configuration
items
=> [
{
value
=>
'Quick List'
,
divider
=> 1},
{
aside
=>
'02/06'
,
count
=>
'6'
,
image
=>
'http://placehold.it/100x100'
,
title
=>
'One'
,
href
=>
'#'
},
{
aside
=>
'03/07'
,
count
=>
'8'
,
image
=>
'http://placehold.it/100x100'
,
title
=>
'Two'
,
href
=>
'#'
},
{
aside
=>
'04/08'
,
count
=>
'10'
,
image
=>
'http://placehold.it/100x100'
,
title
=>
'Three'
,
href
=>
'#'
},
],
inset
=>
'true'
,
filter
=>
'true'
,
);
$jquery_mobile
->page(
content
=>
$list
);
numbered
-
numbered
can be set to "1", defaulted to false, i.e. HTMLul
. anchor
-
anchor
accepts a hashref to control the attributes of the item anchor links. It accepts attributes defined inbutton-html-anchor-attribute
andbutton-data-attribute
. split_anchor
-
split_anchor
accepts a hashref to control the attributes of the item split anchor links (Split button lists). It accepts attributes defined inbutton-html-anchor-attribute
andbutton-data-attribute
.my
$list
=
$jquery_mobile
->listview(
anchor
=> {
rel
=>
'dialog'
,
transition
=>
'pop'
},
split_anchor
=> {
transition
=>
'fade'
,
theme
=>
'e'
},
items
=> [
{
title
=>
'One'
,
href
=>
'#link-1'
,
split
=>
'#split-link-1'
,
split_value
=>
'Split Value One'
},
{
title
=>
'Two'
,
href
=>
'#link-2'
,
split
=>
'#split-link-2'
,
split_value
=>
'Split Value Two'
},
{
title
=>
'Three'
,
href
=>
'#link-3'
,
split
=>
'#split-link-3'
,
split_value
=>
'Split Value Three'
},
]
);
print
$jquery_mobile
->page(
content
=>
$list
);
items
-
items
accepts an arrayref of items. Each item accepts a hashref ofaside
,count
,image
,title
,value
andhref
. Alternative, formatted content can be passed in via thecontent
parameter, which takes precedent over the other parameters.
collapsible
collapsible()
generates collapsible blocks. It accepts attributes defined in collapsible-html-attribute
and collapsible-data-attribute
. Content can be passed via the content
parameter:
my
$collapsible
=
$jquery_mobile
->collapsible(
content
=>
'<h3>Title Heading</h3><p>Excepteur sint occaecat cupidatat non</p>'
);
$jquery_mobile
->page(
content
=>
$collapsible
);
collapsible()
also accepts title
, active
, and listview
as parameters for creating accordion menus via collapsible_set()
. See collapsible_set()
below.
collapsible_set
collapsible_set()
generates collapsible sets. It accepts attributes defined in collapsible-set-html-attribute
and collapsible-set-data-attribute
. Collapsible content can be passed via the collapsibles
parameter:
my
$collapsible_set
=
$jquery_mobile
->collapsible_set(
collapsibles
=> [
{
content
=>
'<h3>Item Heading One</h3><p>Item One Content</p>'
},
{
content
=>
'<h3>Item Heading Two</h3><p>Item Two Content</p>'
},
]
);
$jquery_mobile
->page(
content
=>
$collapsible_set
);
collapsible_set()
can also create accordion menus when using with listview()
:
my
$accordion
=
$jquery_mobile
->collapsible_set(
active
=> {
option
=>
'title'
,
# what listview item attribute to check for and set it as active
value
=>
'Menu A Item Two'
# open the accordion menu where the listview item has the title: 'Menu A Item Two'
},
collapsibles
=> [
{
title
=>
'Menu A'
,
listview
=> {
items
=> [
{
title
=>
'Menu A Item One'
,
href
=>
'#'
},
{
title
=>
'Menu A Item Two'
,
href
=>
'#'
},
]
}
},
{
title
=>
'Menu B'
,
listview
=> {
items
=> [
{
title
=>
'Menu B Item One'
,
href
=>
'#'
},
{
title
=>
'Menu B Item Two'
,
href
=>
'#'
},
]
}
},
]
);
$jquery_mobile
->page(
content
=>
$accordion
);
navbar
navbar()
generates navbars that are often used in header()
and footer()
. It accepts attributes defined in navbar-html-attribute
and navbar-data-attribute
.
my
$navbar
=
$jquery_mobile
->navbar(
items
=> [
{
value
=>
'Item One'
,
href
=>
'#'
},
{
value
=>
'Item Two'
,
href
=>
'#'
,
active
=> 1,
persist
=> 1},
{
value
=>
'Item Three'
,
href
=>
'#'
}
]
);
$jquery_mobile
->page(
header
=> {
content
=>
$navbar
},
);
items
accepts an arrayref of items (i.e. generates HTML li
tags). Navbar item attributes are controlled by navbar-item-data-attribute
and navbar-item-html-attribute
. active
adds the 'ui-btn-active' class to the item's CSS. persist
adds the 'ui-btn-persist' class to the item's CSS.
button
button()
generates anchor
and input
buttons.
# an anchor button
$jquery_mobile
->button(
role
=>
'button'
,
# could be 'button' or 'none', defaulted to 'button'
mini
=>
'true'
,
value
=>
'Learn More'
,
icon
=>
'arrow-r'
,
iconpos
=>
'right'
,
inline
=>
'true'
,
ajax
=>
'false'
,
);
# a submit button
$jquery_mobile
->button(
type
=>
'submit'
,
value
=>
'Join Now'
,
theme
=>
'e'
);
Please note that anchor
buttons accepts button-html-anchor-attribute
as data-* attributes, whereas input
buttons uses button-data-attribute
. HTML attributes for both are defined in button-html-attribute
.
controlgroup
controlgroup()
generates controlgroup containers. Content (usually buttons) can be passed via the content
parameter:
my
$controlgroup
=
$jquery_mobile
->controlgroup(
mini
=>
'true'
,
type
=>
'horizontal'
,
content
=>
'<a href="#" data-role="button">Yes</a><a href="#" data-role="button">No</a>'
);
It accepts attributes defined in controlgroup-html-attribute
and controlgroup-data-attribute
. form()
uses controlgroup()
internally.
input
input()
generates various input elements, such as text, email, password, and file. It accepts attributes defined in input-html-attribute
and input-data-attribute
. form()
uses input()
internally.
$jquery_mobile
->input(
id
=>
'logo'
,
# optional element ID. If not defiend, input 'name' will be used as the 'id'
name
=>
'avatar'
,
# MUST have a 'name'
label
=>
'Member Avatar'
,
# optional 'label' for the input. If not defined, JQuery::Mobile will generate a label based on the input 'name'
type
=>
'file'
,
# optional HTML input types, e.g. 'email', 'password', 'file'. Defaulted to 'text'
accept
=>
'image/*'
,
# accepts only images (iOS 6+)
capture
=>
'camera'
# allow taking new pictures (iOS 6+)
);
The generated HTML conforms to jQuery Mobile form elements. For instance, inputs are wrapped in a 'fieldcontainer' div.
select
select()
generates select boxes. It accepts attributes defined in select-html-attribute
and select-data-attribute
.
$jquery_mobile
->
select
(
name
=>
'into'
,
options
=> [
'Movies'
,
'Music'
,
'Photography'
,
'Everything'
],
value
=>
'Everything'
);
options
can be arrayref or hashref.
checkbox
checkbox()
generates checkboxes. It accepts attributes defined in radio-checkbox-html-attribute
and radio-checkbox-data-attribute
.
$jquery_mobile
->checkbox(
name
=>
'web_language'
,
options
=> [
'PHP'
,
'Perl'
,
'Python'
,
'Ruby'
]
);
radio
radio()
generates radio button groups. It accepts the same parameters as checkbox()
.
$jquery_mobile
->radio(
name
=>
'country'
,
options
=> {
'AU'
=>
'Austalia'
,
'US'
=>
'United States'
}
);
textarea
textarea()
generates textareas. It accepts attributes defined in textarea-html-attribute
and textarea-data-attribute
.
$jquery_mobile
->textarea(
name
=>
'comments'
,
rows
=>
'3'
,
cols
=>
'50'
);
SEE ALSO
http://jquerymobile.com, https://github.com/dannyglue/jQuery-Mobilevalidate
AUTHOR
Xufeng (Danny) Liang (danny.glue@gmail.com)
COPYRIGHT & LICENSE
Copyright 2012 Xufeng (Danny) Liang, All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.