JQuery::Mobile - interface to jQuery Mobile
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) print $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' }, ] );
JQuery::Mobile is an interface to jQuery Mobile. It generates HTML markups, such as navbars, forms, and listviews, that are compatible with jQuery Mobile.
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 'jquery-mobile-css' => 'http://code.jquery.com/mobile/1.3.2/jquery.mobile-1.3.2.min.css', 'jquery-mobile-js' => 'http://code.jquery.com/mobile/1.3.2/jquery.mobile-1.3.2.min.js', 'jquery' => 'http://code.jquery.com/jquery-1.9.1.min.js', '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 strict to ensure a clean markup. For data-* attributes, see reference: http://api.jquerymobile.com/data-attribute/.
# 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', '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' => ['clear-btn', 'clear-btn-text', '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' => ['clear-btn', 'clear-btn-text', '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:
label
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().
head()
page()
pages()
new()
header
header() generates header toolbars. Text, buttons, or navbar() can be passed to the content parameter.
header()
navbar()
content
print $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:
header-footer-html-attribute
header-footer-data-attribute
print $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().
footer()
print $jquery_mobile->footer( position => 'fixed', content => 'Footer content' );
popup
popup() generates popup container divs. Content can be passed via the content parameter:
popup()
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)".
popup-html-attribute
popup-data-attribute
page
page() generates a container divs. It accepts the following parameters:
role
role can be either "page" or "dialog", defaulted to "page".
page() includes HTML head and body wrapper tags by default. Set head to "0" to disable that:
body
print $jquery_mobile->page(head => 0);
content accepts text string.
header includes a header toolbars. header accepts a hashref of parameters that gets passed directly to header().
footer includes a footer toolbars. footer accepts a hashref of parameters that gets passed directly to footer().
For example:
print $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:
pages() includes HTML head and body wrapper tags by default. Set head to "0" to disable that.
pages accepts an arrayref of parameters acceptable by page().
print $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.
form()
form-html-attribute
form-data-attribute
fields
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']}, {type => 'rangeslider', name => 'range', mini => 'true', from => {label => 'Range', name => 'from', min => 18, max => 100}, to => {name => 'to', min => 18, max => 100}}, ], 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'} ], ); print $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'}, ], ); print $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.
listview()
listview-html-attribute
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', ); print $jquery_mobile->page(content => $list);
table
table() generates tables. It accepts attributes defined in table-html-attribute and table-data-attribute.
table()
table-html-attribute
table-data-attribute
my $table = $jquery_mobile->table( class => 'ui-responsive', th => { 'First Name' => {priority => '1'}, 'Last Name' => {priority => '2'}, 'Email' => {priority => '3'}, 'Gender' => {priority => '4'}, }, headers => ['First Name', 'Last Name', 'Email', 'Gender'], rows => [ ['John', 'Smith', 'john@work.com', 'Male'], ['Ann', 'Smith', 'ann@work.com', 'Female'], ], ); print $jquery_mobile->page(content => $table);
numbered
numbered can be set to "1", defaulted to false, i.e. HTML ul.
ul
anchor
anchor accepts a hashref to control the attributes of the item anchor links. It accepts attributes defined in button-html-anchor-attribute and button-data-attribute.
button-html-anchor-attribute
button-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 in button-html-anchor-attribute and button-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 of aside, count, image, title, value and href. Alternative, formatted content can be passed in via the content parameter, which takes precedent over the other parameters.
aside
count
image
title
value
href
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:
collapsible()
collapsible-html-attribute
collapsible-data-attribute
my $collapsible = $jquery_mobile->collapsible( content => '<h3>Title Heading</h3><p>Excepteur sint occaecat cupidatat non</p>' ); print $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.
active
collapsible_set()
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:
collapsible-set-html-attribute
collapsible-set-data-attribute
collapsibles
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>'}, ] ); print $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 => '#'}, ] } }, ] ); print $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.
navbar-html-attribute
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 => '#'} ] ); print $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.
li
navbar-item-data-attribute
navbar-item-html-attribute
persist
button
button() generates anchor and input buttons.
button()
input
# an anchor button print $jquery_mobile->button( role => 'button', # could be 'button' or 'none', defaulted to 'button' href => 'https://www.google.com', mini => 'true', value => 'Learn More', icon => 'arrow-r', iconpos => 'right', inline => 'true', ajax => 'false', ); # a submit button print $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.
button-html-attribute
panel
panel() generates panel containers. Content can be passed via the content parameter:
panel()
my $panel = $jquery_mobile->panel( content => 'Panel Content' );
It accepts attributes defined in panel-html-attribute and panel-data-attribute.
panel-html-attribute
panel-data-attribute
controlgroup
controlgroup() generates controlgroup containers. Content (usually buttons) can be passed via the content parameter:
controlgroup()
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.
controlgroup-html-attribute
controlgroup-data-attribute
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.
input()
input-html-attribute
input-data-attribute
print $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.
select()
select-html-attribute
select-data-attribute
print $jquery_mobile->select( name => 'into', options => ['Movies', 'Music', 'Photography', 'Everything'], value => 'Everything' );
options can be arrayref or hashref.
options
checkbox
checkbox() generates checkboxes. It accepts attributes defined in radio-checkbox-html-attribute and radio-checkbox-data-attribute.
checkbox()
radio-checkbox-html-attribute
radio-checkbox-data-attribute
print $jquery_mobile->checkbox( name => 'web_language', options => ['PHP', 'Perl', 'Python', 'Ruby'] );
radio
radio() generates radio button groups. It accepts the same parameters as checkbox().
radio()
print $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.
textarea()
textarea-html-attribute
textarea-data-attribute
print $jquery_mobile->textarea( name => 'comments', rows => '3', cols => '50' );
rangeslider
rangeslider() generates rangesliders. It accepts attributes defined in rangeslider-html-attribute and rangeslider-data-attribute.
rangeslider()
rangeslider-html-attribute
rangeslider-data-attribute
print $jquery_mobile->rangeslider( type => 'rangeslider', name => 'range', mini => 'true', from => { label => 'Range', name => 'from', min => 18, max => 100}, to => {name => 'to', min => 18, max => 100} );
http://jquerymobile.com, https://github.com/dannyglue/jQuery-Mobilevalidate
Xufeng (Danny) Liang (danny.glue@gmail.com)
Copyright 2013 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.
To install JQuery::Mobile, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JQuery::Mobile
CPAN shell
perl -MCPAN -e shell install JQuery::Mobile
For more information on module installation, please visit the detailed CPAN module installation guide.