The layout of page should be correct. Every page should have a .page container, and put contents in .content container.
Here is the basic layout of a page:
<!-- page containet --><divclass="page"><!-- titlebar --><headerclass="bar bar-nav"><aclass="icon icon-me pull-left open-panel"></a><h1class="title">Title</h1></header><!-- toolbar --><navclass="bar bar-tab"><aclass="tab-item active"href="#"><spanclass="icon icon-home"></span><spanclass="tab-label">Home</span></a><aclass="tab-item"href="#"><spanclass="icon icon-star"></span><spanclass="tab-label">Fav</span></a><aclass="tab-item"href="#"><spanclass="icon icon-settings"></span><spanclass="tab-label">Settings</span></a></nav><!-- page content --><divclass="content"><divclass="content-block">content here</div></div></div><!-- popup, panel --><divclass="panel-overlay"></div><!-- Left Panel with Reveal effect --><divclass="panel panel-left panel-reveal"><divclass="content-block"><p>Here is a side panel</p><p></p><!-- Click on link with "close-panel" class will close panel --><p><ahref="#"class="close-panel">close</a></p></div></div>
Ever page should have a .page container.
Rem
Rem is related to htmlfont-size. We scale the whole page with Rem.
Infact, there is no px except border-width in css.
See rem.less For more information about how the page is scaled,
We will not init page on document loaded, because $.config.autoInit = false;. You should call $.init() on document loaded. $.init method will init all components in page, and trigger a pageInit event after init complete. You should call $.init after all pageInit events has binded.
But the page Loaded By router will always be inited.
Do not modify $.init please.
If you set $.config.autoInit = true;, the $.init method will auto be called after document onload. But your pageInit binds may have not executed at this time. So, please do not set autoInit=true, unless you don't listen to pageInit event or you can make sure that your code will be right.
Use router to load new page. The router will listen all links events and will prevent links' default behavior and use ajax to load new page
showPageLoadingIndicator
true
Show indicator when router is loading new page。Available only when router is true
swipePanel
"left"
Swipe to open a panel
swipePanelOnlyClose
true
Only Swipe to close panel, but can't swipe to open a panel
content padded
You can put content in .content-padded to add extra margin.
Donec et nulla auctor massa pharetra adipiscing ut sit amet sem. Suspendisse molestie velit vitae mattis tincidunt. Ut sit amet quam mollis, vulputate turpis vel, sagittis felis. Donec et nulla auctor massa pharetra adipiscing ut sit amet sem. Suspendisse molestie velit vitae mattis tincidunt. Ut sit amet quam mollis, vulputate turpis vel, sagittis felis.
<divclass="content-padded"><p>Donec et nulla auctor massa pharetra adipiscing ut sit amet sem. Suspendisse molestie velit vitae mattis tincidunt. Ut sit amet quam mollis, vulputate turpis vel, sagittis felis. </p></div>
Types
Basic text style.
Heading1
Heading2
Heading3
Heading4
Heading5
Heading6
This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.
<divclass="content-padded"><h1>Heading1</h1><h2>Heading2</h2><h3>Heading3</h3><h4>Heading4</h4><h5>Heading5</h5><h6>Heading6</h6><p>This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.This is a paragraph.</p></div>
Text and Background Color
There are some util class to set text color and background color:
<headerclass="bar bar-nav"><buttonclass="button pull-left">
Left
</button><buttonclass="button pull-right">
Right
</button><divclass="buttons-row"><ahref="#tab1"class="tab-link active button">Tab 1</a><ahref="#tab2"class="tab-link button">Tab 2</a><ahref="#tab3"class="tab-link button">Tab 3</a></div></header>
Toolbar
Toolbar is used as the main tab. You should put it sibling to .page elements to make it a global toolbar.Add a .no-tabbar class on .page when you want to hide toolbar on specific page. Or, you can use $.showToolbar(true/false) to toggle toolbar.
Note! If you use router to switch pages, you should use inline pages instead of ajax pages. Because when load ajax page, the router will not check if it is already exist. The same page may be loaded multi times.
<navclass="bar bar-tab"><aclass="tab-item active"href="#">
Text
</a><aclass="tab-item"href="#">
Text
</a><aclass="tab-item"href="#">
Text
</a></nav>
Secondary Titlebar and Toolbar
<navclass="bar bar-nav bar-standard"><h1class="title">Secondary Titlebar and Toolbar</h1></nav><!-- Block button in standard bar fixed below top bar --><divclass="bar bar-header-secondary"><buttonclass="button button-block">Block level button</button></div><!-- Block button in standard bar fixed above the footer --><divclass="bar bar-footer-secondary"><buttonclass="button button-block">Block level button</button></div><!-- Icons in standard bar fixed to the bottom of the screen --><divclass="bar bar-footer"><aclass="icon icon-edit pull-left"></a><aclass="icon icon-settings pull-right"></a></div>
Side panel is on left or right side of page, and you can swipe-left-to-right or swipe-right-to-left to open it.
How to use
Add .open-panel To any link to make it a button which can open a side panel. You can add data-panel='{panel's css selector}' to spcify which panel to open, if you have more than one panel.
Add .close-panel to any link to make it a close button which can close a panel. You have not need to spcify which panel to close, because only one panel can be opened at the same time.
Use .panel-left or .panel-right to spcify left panel or right panel.
Use .panel-cover or .panel-reveal to spcify then type of panel.
Config
The panel can be opened and closed by slide gestures by default.
You can set $.config.swipePanel and $.config.swipePanelOnlyClose to enable or disable the slide gestures in init config
.
<divclass="page"><headerclass="bar bar-nav"><h1class='title'>Side Panel</h1></header><divclass="content"><divclass="content-block"><p><ahref="#"class="button button-fill open-panel"data-panel='#panel-left-demo'>Open left side panel</a></p></div></div></div><divclass="panel-overlay"></div><!-- Left Panel with Reveal effect --><divclass="panel panel-left panel-reveal theme-dark"id='panel-left-demo'><divclass="content-block"><p>This is a side panel</p><p></p><p><ahref="#"class="close-panel">Close</a></p></div><divclass="list-block"><!-- .... --></div></div><divclass="panel panel-right panel-reveal"><divclass="content-block"><p>This is a side panel</p><!-- Click on link with "close-panel" class will close panel --><p><ahref="#"class="close-panel">Close</a></p></div></div>
Use JavaScript
We can also open and close Panels with JavaScript, for this we need to look at related App methods: $.openPanel(panel) and $.closePanel()
$.openPanel(panel) Open a panel.
$.closePanel():close currently opened Panel.
<divclass="page"><headerclass="bar bar-nav"><h1class='title'>Panel</h1></header><divclass="content"><divclass="content-block"><p><ahref="#"class="button button-fill my-btn">Open Panel with JS</a></p></div></div></div><divclass="panel-overlay"></div><!-- Left Panel with Reveal effect --><divclass="panel panel-right panel-cover theme-dark"id='panel-js-demo'><divclass="content-block"><p>I am on the right</p><p>I cover the page</p><p></p><!-- Click on link with "close-panel" class will close panel --><p><ahref="#"class="close-panel">Close</a></p></div></div><divclass="panel panel-right panel-reveal"><divclass="content-block"><p>I am a Panel</p><!-- Click on link with "close-panel" class will close panel --><p><ahref="#"class="close-panel">Close</a></p></div></div>
<headerclass="bar bar-nav"><h1class='title'>Tabs</h1></header><divclass="content"><divclass="buttons-tab"><ahref="#tab1"class="tab-link active button">All</a><ahref="#tab2"class="tab-link button">Potatos</a><ahref="#tab3"class="tab-link button">Tomatos</a></div><divclass="content-block"><divclass="tabs"><divid="tab1"class="tab active"><divclass="content-block"><p>This is tab 1 content</p></div></div><divid="tab2"class="tab"><divclass="content-block"><p>This is tab 2 content</p></div></div><divid="tab3"class="tab"><divclass="content-block"><p>This is tab 3 content</p></div></div></div></div></div>
Secondary Tabs
Secondary Tabs is less important than Primary tabs.
Modal is a small content pane that pops up over App's main content. Modals are usualy used to ask something from user, or to notify or warn user. Modal as all other overlays is part of so called "Temporary Views".
Modal can be opened only using JavaScript:
Predefined Modals
Buttons text for predefined modals (like "Ok" and "Cancel") can be also changed by $.modal.prototype.defaults
First of all, let's look on most used and already predefined modals in Framework7::
Alert
To open Alert modal we should call one of the following App methods:：$.alert(text, [title, callbackOk]) or $.alert(text, [callbackOk])
text - string. Text to alert
title - string. Optional. Alert modal title
callbackOk - function. Optional.Callback function that will be executed when user click "Ok" button on Alert modal
This method returns dynamically created modal's HTMLElement.
<headerclass="bar bar-nav"><h1class="title">Alert</h1></header>
...
<divclass="content"><divclass="content-block"><p><ahref="#"class="alert-text">Alert With Text</a></p><p><ahref="#"class="alert-text-title">Alert With Text and Title</a></p><p><ahref="#"class="alert-text-title-callback">Alert With Text and Title and Callback</a></p><p><ahref="#"class="alert-text-callback">Alert With Text and Callback</a></p></div></div>
...
Confirm modal usualy used when it is required to confirm some action. To open Confirm modal we should also call one of the following App methods:
$.confirm(text, [title, callbackOk, callbackCancel])
or
$.confirm(text, [callbackOk, callbackCancel])
text - string. Text to Confirm
title - string. Optional. Confirm modal title
callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button on Confirm modal (when user confirm action)
callbackCancel - function. Optional. Callback function that will be executed when user click "Cancel" button on Confirm modal (when user dismiss action)
<headerclass="bar bar-nav"><h1class="title">Confirm</h1></header>
...
<divclass="content"><divclass="content-block"><p><ahref="#"class="confirm-ok">Confirm with text and Ok callback</a></p><p><ahref="#"class="confirm-ok-cancel">Confirm with text, Ok and Cancel callbacks</a></p><p><ahref="#"class="confirm-title-ok">Confirm with text, title and Ok callback</a></p><p><ahref="#"class="confirm-title-ok-cancel">Confirm with text, title, Ok and Cancel callback</a></p></div></div>
...
$(document).on('click','.confirm-ok',function(){$.confirm('Are you sure?',function(){$.alert('You clicked Ok button');});});$(document).on('click','.confirm-ok-cancel',function(){$.confirm('Are you sure?',function(){$.alert('You clicked Ok button');},function(){$.alert('You clicked Cancel button');});});$(document).on('click','.confirm-title-ok',function(){$.confirm('Are you sure?','Custom Title',function(){$.alert('You clicked Ok button');});});$(document).on('click','.confirm-title-ok-cancel',function(){$.confirm('Are you sure?','Custom Title',function(){$.alert('You clicked Ok button');},function(){$.alert('You clicked Cancel button');});});
Prompt
Prompt modal used when it is required to get some data/answer from user. To open Prompt modal we should also call one of the following App methods:
$.prompt(text, [title, callbackOk, callbackCancel])$.prompt(text, [callbackOk, callbackCancel])
text - string. Prompt text/question
title - string. Optional. Prompt modal Title
callbackOk - function. Optional. OK button callback, As an argument function receives value of text input
<headerclass="bar bar-nav"><h1class="title">Prompt</h1></header>
...
<divclass="content"><divclass="content-block"><p><ahref="#"class="prompt-ok">Prompt with text and Ok callback</a></p><p><ahref="#"class="prompt-ok-cancel">Prompt with text, Ok and Cancel callbacks</a></p><p><ahref="#"class="prompt-title-ok">Prompt with text, title and Ok callback</a></p><p><ahref="#"class="prompt-title-ok-cancel">Prompt with text, title, Ok and Cancel callback</a></p></div></div>
...
$(document).on('click','.prompt-ok',function(){$.prompt('What is your name?',function(value){$.alert('Your name is "'+value+'". You clicked Ok button');});});$(document).on('click','.prompt-ok-cancel',function(){$.prompt('What is your name?',function(value){$.alert('Your name is "'+value+'". You clicked Ok button');},function(value){$.alert('Your name is "'+value+'". You clicked Cancel button');});});$(document).on('click','.prompt-title-ok',function(){$.prompt('What is your name?','Custom Title',function(value){$.alert('Your name is "'+value+'". You clicked Ok button');});});$(document).on('click','.prompt-title-ok-cancel',function(){$.prompt('What is your name?','Custom Title',function(value){$.alert('Your name is "'+value+'". You clicked Ok button');},function(value){$.alert('Your name is "'+value+'". You clicked Cancel button');});});
Modals
Ok, all predefined modals were just particular case (like shortcuts) of full Modal methods. Let's look how to create custom modals:
$.modal(parameters) - show custom modal
parameters - object. Parameters/options of modal
Here is the list of Modal parameters:
Parameter
Type
Default
Description
title
string
Optional. String with Modal title (could be HTML string)
text
string
Optional. String with Modal text (could be HTML string)
afterText
string
Optional. String with text (could be HTML string) that will be placed after "text"
buttons
array
Optional. Array of buttons. Each button should be presented as Object with button parameters (look below)
verticalButtons
boolean
false
Optional. Set to true to enable vertical buttons layout
onClick
function
Optional. Callback function that will be executed when user clicks any of Modal's button. As arguments it receives modal (with Modal's HTMLElement) and index (with index number of clicked button)
Let's look at Button's parameters:
Parameter
Type
Default
Description
text
string
String with Button's text (could be HTML string)
bold
boolean
false
Optional. Set to true for bold button text
close
boolean
true
Optional. If "true" then modal will be closed after click on this button
onClick
function
Optional. Callback function that will be executed when user click this button
Such configuration options allows to create flexible modals. Let's look at some examples.
<headerclass="bar bar-nav"><h1class="title">Custom Modals</h1></header>
...
<divclass="content"><divclass="content-block"><p><ahref="#"class="open-3-modal">Modal With 3 Buttons</a></p><p><ahref="#"class="open-slider-modal">Modal With Slider</a></p><p><ahref="#"class="open-tabs-modal">Modal With Tabs</a></p><p><ahref="#"class="open-vertical-modal">Modal With Vertical Buttons</a></p></div></div>
...
$(document).on('click','.open-3-modal',function(){$.modal({title:'Modal with 3 buttons',text:'Vivamus feugiat diam velit. Maecenas aliquet egestas lacus, eget pretium massa mattis non. Donec volutpat euismod nisl in posuere. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae',buttons:[{text:'B1',onClick:function(){$.alert('You clicked first button!')}},{text:'B2',onClick:function(){$.alert('You clicked second button!')}},{text:'B3',bold:true,onClick:function(){$.alert('You clicked third button!')}},]})});$(document).on('click','.open-slider-modal',function(){varmodal=$.modal({title:'Awesome Photos?',text:'What do you think about my photos?',afterText:'<div class="swiper-container" style="width: auto; margin:5px -15px -15px">'+'<div class="swiper-pagination"></div>'+'<div class="swiper-wrapper">'+'<div class="swiper-slide"><img src="..." height="150" style="display:block"></div>'+'<div class="swiper-slide"><img src="..." height="150" style="display:block"></div>'+'</div>'+'</div>',buttons:[{text:'Bad :('},{text:'Awesome!',bold:true,onClick:function(){$.alert('Thanks! I know you like it!')}},]})$.swiper($$(modal).find('.swiper-container'),{pagination:'.swiper-pagination'});});$(document).on('click','.open-tabs-modal',function(){$.modal({title:'<div class="buttons-row">'+'<a href="#tab1" class="button active tab-link">Tab 1</a>'+'<a href="#tab2" class="button tab-link">Tab 2</a>'+'</div>',text:'<div class="tabs">'+'<div class="tab active" id="tab1">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam convallis nunc non dolor euismod feugiat. Sed at sapien nisl. Ut et tincidunt metus. Suspendisse nec risus vel sapien placerat tincidunt. Nunc pulvinar urna tortor.</div>'+'<div class="tab" id="tab2">Vivamus feugiat diam velit. Maecenas aliquet egestas lacus, eget pretium massa mattis non. Donec volutpat euismod nisl in posuere. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae</div>'+'</div>',buttons:[{text:'Ok, got it',bold:true},]})});$(document).on('click','.open-vertical-modal',function(){$.modal({title:'Vertical Buttons Layout',text:'Vivamus feugiat diam velit. Maecenas aliquet egestas lacus, eget pretium massa mattis non. Donec volutpat euismod nisl in posuere. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae',verticalButtons:true,buttons:[{text:'Button 1',onClick:function(){$.alert('You clicked first button!')}},{text:'Button 2',onClick:function(){$.alert('You clicked second button!')}},{text:'Button 3',onClick:function(){$.alert('You clicked third button!')}},]})});
Close Modals with JavaScript
Any Modal can be closed with JavaScript, not only by clicking on its buttons. For this we need to look at relate App method:
$.closeModal(modal) - close modal
modal - HTMLElement or string ( CSS Selector). Optional. If not specified, any opened modal will be closed
Modal Events
Modal events could be very useful when you need to do something in JavaScript when Modal opened/closed
Event
Target
Description
open
Modal Element<div class="modal">
Event will be triggered when Modal starts its opening animation
opened
Modal Element<div class="modal">
Event will be triggered after Modal completes its opening animation
close
Modal Element<div class="modal">
Event will be triggered when Modal starts its closing animation
closed
Modal Element<div class="modal">
Event will be triggered after Modal completes its closing animation
Preloader Modal
Preloader Modal is used to indicate some background activity (like Ajax request) and to block any user actions during this activity. To open Preloader modal we should also call appropriate App method: $.showPreloader([title]) - show modal with Preloader
title - string. Optional. Preloader modal title. By default (if not specified) it is euqal to "Loading...".
$.hidePreloader() - hide/close modal with Preloader. Because Preloader modal has not any buttons, it should be closed by JavaScript
Toast is a verfy light modal, It will not disturb user and will disapear after 3 seconds
$.toast("Error!");
Popover
Popover compontent is used to manage the presentation of content in a popover. You use popovers to present information temporarily. The popover remains visible until the user taps outside of the popover window or you explicitly dismiss it.
Note that is not recommended to use Popover on small screens (iPhone). On small screens you should use Action Sheet.
Popover Layout
First of all let's look on Popover layout, it is pretty simple, just add somewhere in the end of the body:
<divclass="popover"><!-- Popover's angle arrow --><divclass="popover-angle"></div><!-- Popover content --><divclass="popover-inner"><!-- Any HTML content here --></div></div>
Open and close with HTML
It is possible to open and close required Popover using special classes and data attributes on links:
To open popover we need to add "open-popover" class to any HTML element (prefered to link)
To close popover we may add "close-popover" class to any HTML element (prefered to link)
If you have more than one popover in app, you need to specify appropriate popover via additional data-popover=".my-popover" attribute on this HTML element
When we open Popover with such method (from HTML), it will be automatically positioned around element that we clicked to call this Popover.
Open and close with JavaScript
We can also open and close Popover with JavaScript:
$.popover(popover, target) - open Popover around target element
popover - HTMLElement or string (with CSS Selector) of Popover to open. Requred
target - HTMLElement or string (with CSS Selector) of target element to set popover position around this element. Requred
This method returns Popover's HTMLElement
$.closeModal(popover) - close Popover
popover - HTMLElement or string (with CSS Selector). Optional. If not specified, any opened Popover will be closed
Dynamic Popover
It allows you to create Popover dynamically by passing its HTML to related methods:
$.popover(popoverHTML, target, removeOnClose) - open Popover with popoverHTML content around target element
popoverHTML - string. HTML string of popover
target - HTMLElement or string (with CSS Selector) of target element to set popover position around this element. Requred
removeOnClose - boolean. Optional, by default - true. If true then Popover will be removed from DOM when closed
This method returns dynamically created Popover's HTMLElement
Modal Defaults
The default config of modal is $.modal.prototype.defaults, you can change these config:
Parameter
Default
Description
modalButtonOk
"OK"
Text of OK button
modalButtonCancel
"Cancel"
Text of cancel button
modalPreloaderTitle
"Loading"
Text of preloader
closePrevious
true
Close all previous modal when open a new modal.
actionsCloseByOutside
true
点击背景关闭 ActionSheet
modalCloseByOutside
false
点击背景关闭 Modal
popupCloseByOutside
false
点击背景关闭 Popup
Popup
Popup is a popup window with any HTML content that pops up over App's main content
Popup
Popup layout is pretty simple. All you need to do is to put .popup right in the body:
<divclass="modal modal-no-buttons">
...
<divclass="popup">
Any HTML content goes here
</div></div><p>Note! Don't put <code>popup</code> into <code>page</code>.</p>
Open and Close Popup
From HTML
It is possible to open and close required popups using special classes and data attributes on links:
To open popup we need to add open-popup class to any HTML element (prefered to link)
To close popup we need to add close-popup class to any HTML element (prefered to link)
If you have more than one popups in app, you need to specify appropriate popup via additional data-popup=".my-popup" attribute on this HTML element
According to above note:
<divclass="page">
...
<divclass="content"><divclass="content-block"><p><ahref="#"class="open-popup open-about"data-popup=".popup-about">Open About Popup </a></p><p><ahref="#"class="open-popup open-services"data-popup=".popup-services">Open Services Popup </a></p></div></div>
...
</div><!-- About Popup --><divclass="popup popup-about"><divclass="content-block"><p>About</p><p><ahref="#"class="close-popup">Close popup</a></p><p>Lorem ipsum dolor ...</p></div></div><!-- Services Popup --><divclass="popup popup-services"><divclass="content-block"><p>Services</p><p><ahref="#"class="close-popup">Close popup</a></p><p>Lorem ipsum dolor ...</p></div></div>
Using JavaScript
We can also open and close Popups with JavaScript, for this we need to look at related App methods:
$.popup(popup) - Open Popup
popup - HTMLElement or string (with CSS Selector) of Popup to open . Required
$.closeModal(popup) - Close Popup
popup - HTMLElement or string (with CSS Selector). Optional. If not specified, any opened Popup/Modal will be closed
<headerclass="bar bar-nav"><h1class="title">Popup(JavaScript)</h1></header>
...
<divclass="content"><divclass="content-block"><p><ahref="#"class="open-about">Open About Popup </a></p><p><ahref="#"class="open-services">Open Services Popup </a></p></div></div><!-- About Popup --><divclass="popup popup-about"><divclass="content-block"><p>About</p><p><ahref="#"class="close-popup">Close popup</a></p><p>Lorem ipsum dolor ...</p></div></div><!-- Services Popup --><divclass="popup popup-services"><divclass="content-block"><p>Services</p><p><ahref="#"class="close-popup">Close popup</a></p><p>Lorem ipsum dolor ...</p></div></div>
<headerclass="bar bar-nav"><h1class="title">Popup Events</h1></header>
...
<divclass="content"><divclass="content-block"><!-- In data-popup attribute we specify CSS selector of popup we need to open --><p><ahref="#"data-popup=".popup-about"class="open-popup">Open About Popup </a></p><p><ahref="#"data-popup=".popup-services"class="open-popup">Open Services Popup </a></p></div></div><!-- About Popup --><divclass="popup popup-about"><divclass="content-block"><p>About</p><p><ahref="#"class="close-popup">Close popup</a></p><p>Lorem ipsum dolor ...</p></div></div><!-- Services Popup --><divclass="popup popup-services"><divclass="content-block"><p>Services</p><p><ahref="#"class="close-popup">Close popup</a></p><p>Lorem ipsum dolor ...</p></div></div>
$(document).on('click','.popup-about',function(){console.log('About Popup opened')});$(document).on('click','.popup-about',function(){console.log('About Popup is closing')});$(document).on('click','.popup-services',function(){console.log('Services Popup is opening')});$(document).on('click','.popup-services',function(){console.log('Services Popup is closed')});
Dynamic Popup
Light7 allows you to create Popup dynamically by passing its HTML to related methods:
$.popup(popupHTML, removeOnClose) - Open Popup
popupHTML - string. HTML String of popup
removeOnClose - boolean. Optional, by default - true. If true then Popup will be removed from DOM when closed
<headerclass="bar bar-nav"><h1class="title">Dynamic Popup</h1></header>
...
<divclass="content"><divclass="content-block"><!-- In data-popup attribute we specify CSS selector of popup we need to open --><p><ahref="#"class="create-popup">Create Popup</a></p></div></div>
$(document).on('click','.create-popup',function(){varpopupHTML='<div class="popup">'+'<div class="content-block">'+'<p>Popup created dynamically.</p>'+'<p><a href="#" class="close-popup">Close me</a></p>'+'</div>'+'</div>'$.popup(popupHTML);});
Calendar
Calendar is a touch optimized component that provides an easy way to handle dates.
Calendar can be created and initialized using JavaScript. We need to use related App's method:
$("#my-input").calendar();
A calendar will popup when user click the input, and the start date will be the value of input.
You can use data-toggle='date' to init calendar if you don't want to write any JS code:
<inputtype="text"data-toggle='date'/>
Params
Let's look on list of all available parameters:
Parameter
Type
Default
Description
Common Picker Modal Component Parameters
inputReadOnly
boolean
true
Sets "readonly" attribute on specified input
cssClass
string
Additional CSS class name to be set on calendar modal
closeByOutsideClick
boolean
true
If enabled, picker will be closed by clicking outside of picker or related input element
toolbar
boolean
true
Enables calendar modal toolbar
toolbarTemplate
string
Toolbar HTML Template
Specific Calendar Parameters
value
array
Array with initial selected dates. Each array item represents selected date
disabled
Date Range
Additonal disabled dates. Parameter accepts so called Date Range (look below for details)
formatValue
function (p, values)
Function to format input value, should return new/formatted string value. values is array where each item represents selected date
Enable to enable range picker. Not compatible with multiple
direction
string
'horizontal'
Months layout direction, could be 'horizontal' or 'vertical'
minDate
Date
null
Minimum allowed date
maxDate
Date
null
Maximum allowed date
touchmove
boolean
true
If enabled then calendar months slides follow finger during touch move
animate
boolean
true
Enables transition between months
closeOnSelect
boolean
false
Enable and calendar will be closed when user pick a date
yearPicker
boolean
true
Enable year picker in toolbar
Callbacks
onChange
function (p, values, displayValues)
Callback function that will be executed when picker value changed. values and displayValues are arrays where each item represents value/display value of related column
onMonthAdd
function (p, monthContainer)
Callback function that will be executed when newly generated month HTML element will be added to calendar.
onDayClick
function (p, dayContainer, year, month, day)
Callback function that will be executed when user clicks/select any date
onOpen
function (p)
Callback function that will be executed when picker is opened
onClose
function (p)
Callback function that will be executed when picker is closed
A change Event will triggered on input element when user selected date.
Use DateTimePicker if you want to select both date and time.
Inline
If you init calendar on an div or other element instead of an input element, it will auto change to inline mode.
<divdata-toggle='date'/>
Action sheet
Action sheet can show many action buttons for user to choose.
$.actions(buttons) - create and show Action Sheet.
buttons - buttons in action sheet, you can put buttons in different group.
<headerclass="bar bar-nav"><h1class="title">Actions</h1></header><divclass="content"><divclass="content-block"><!-- In data-popup attribute we specify CSS selector of popup we need to open --><p><ahref="#"class="create-actions">please choose</a></p></div></div>
You can set button color with color, or set background with bg. There are four different color: primary, success, warning, danger. In fact, the different color is defined in Text.
picker
Picker is a powerful component that allows you to create custom overlay pickers which looks like iOS native picker.
You should init a picker on an input element before you can use it.
Picker will use the value of input as default value. The default read value will be error if you have mutli cols, because picker don't know how to split one string to multi cols.Infact, Piker will use space to split the value of input, and set the them as the value of cols. If your input value is not split with space, you should set the default value with JavaScript.
Add .close-picker class to any link, and click it to close the picker
You can alose call $(".picker").picker("close") or $.closeModal(".picker-modal.modal-in") to close a picker。
Params
See the examplse:
$("#picker-name").picker({toolbarTemplate:'<header class="bar bar-nav">\
<button class="button button-link pull-right close-picker">OK</button>\
<h1 class="title">Please Choose</h1>\
</header>',cols:[{textAlign:'center',values:['Mr','Ms']// displayValues: [.....] the value to display, if not specified, it will display the values},{textAlign:'center',values:['Brook','Churchill','Hill','Field','Green','Baby']}]});
If you only want to select date, use Calendar please.
List
List views are versatile and powerful user interface compontents frequently found in iOS apps. A list view presents data in a scrollable list of multiple rows that may be divided into sections/groups.
List views have many purposes:
To let users navigate through hierarchically structured data
To present an indexed list of items
To display detail information and controls in visually distinct groupings
To present a selectable list of options
<headerclass="bar bar-nav"><h1class="title">List view</h1></header><divclass="content"><divclass="content-block-title">With icon, title and after</div><divclass="list-block"><ul><liclass="item-content"><divclass="item-media"><iclass="icon icon-f7"></i></div><divclass="item-inner"><divclass="item-title">Bom</div><divclass="item-after">12:12</div></div></li><liclass="item-content"><divclass="item-media"><iclass="icon icon-f7"></i></div><divclass="item-inner"><divclass="item-title">Gender</div><divclass="item-after">Male</div></div></li></ul></div><divclass="content-block-title">With title and after</div><divclass="list-block"><ul><liclass="item-content"><divclass="item-inner"><divclass="item-title">Bom</div><divclass="item-after">12:12</div></div></li><liclass="item-content"><divclass="item-inner"><divclass="item-title">Gender</div><divclass="item-after">Male</div></div></li></ul></div><divclass="content-block-title">With Arrow</div><divclass="list-block"><ul><liclass="item-content item-link"><divclass="item-media"><iclass="icon icon-f7"></i></div><divclass="item-inner"><divclass="item-title">Bom</div><divclass="item-after">12:12</div></div></li><liclass="item-content item-link"><divclass="item-media"><iclass="icon icon-f7"></i></div><divclass="item-inner"><divclass="item-title">Gender</div><divclass="item-after">Male</div></div></li></ul></div></div>
Where:
item-content - main flex wrapper for item-media and item-inner. Requred element.
item-media - container for your media element like icon, image, etc. Optional element.
item-inner - main flex wrapper for item-title and item-after. Requred element.
item-title - single-line list item title. Required element.
item-after - list item label. Could countain any additional HTML elements, like label text, or badge, or switch/toggle or button, etc. Optional element.
Add .item-link class on .item-content will make it show a right arrow。
Contacts List
Show contacts
Contacts list is a particular case of Grouped Lists with two differences:
list-block should have additional contacts-block class
page-content should have additional contacts-content class
Contacts list will auto have a iOS-like index list on the right side - it's named index list. Try it on the demo on the right side ->
The index list is a JS component, it will auto init when page init. You should init it like this if your contacts list is load by ajax:
item-content - main flex wrapper for item-media and item-inner. Requred element.
item-media - container for your media element like icon, image, etc. Optional element.
item-inner - Requred element.
item-title-row - main flex wrapper for item-title and item-after. Optional element.
item-title - single-line list item title. Optional element.
item-after - list item label. Could countain any additional HTML elements, like label text, or badge, or switch/toggle or button, etc. Optional element.
item-text - additional two-lines container for detailed description. Optional element.
Selectable List
List can be selected with checkbox or radio. You can put checkbox or radio in List, and the list item will have a selected style when user select. There is no JS at all, So you should read data from the hidden checkbox or radoi
<ul><li><labelclass="label-checkbox item-content"><inputtype="radio"name="my-radio"><divclass="item-media"><iclass="icon icon-form-checkbox"></i></div><divclass="item-inner"><divclass="item-title-row"><divclass="item-title">Lily</div><divclass="item-after">17:14</div></div><divclass="item-subtitle">New messages from John Doe</div><divclass="item-text">Lorem ipsum dolor sit amet...</div></div></label></li><li><labelclass="label-checkbox item-content"><inputtype="radio"name="my-radio"><divclass="item-media"><iclass="icon icon-form-checkbox"></i></div><divclass="item-inner"><divclass="item-title-row"><divclass="item-title">Lucy</div><divclass="item-after">17:14</div></div><divclass="item-subtitle">New messages from John Doe</div><divclass="item-text">Lorem ipsum dolor sit amet...</div></div></label></li></ul>
Change the type of input to "checkbox" to make multiple select.
Cards
Cards, along with List View, is a one more great way to contain and orginize your information. Cards contains unique related data, for example, a photo, text, and link all about a single subject. Cards are typically an entry point to more complex and detailed information.
<headerclass="bar bar-nav"><h1class="title">Cards</h1></header><divclass="content"><divclass="content-block-title">Simple Cards</div><divclass="card"><divclass="card-content"><divclass="card-content-inner">This is simple card with plain text. But card could contain its own header, footer, list view, image, and any elements inside.</div></div></div><divclass="card"><divclass="card-header">Card header</div><divclass="card-content"><divclass="card-content-inner">Card with header and footer. Card header is used to display card title and footer for some additional information or for custom actions.</div></div><divclass="card-footer">Card Footer</div></div><divclass="card"><divclass="card-content"><divclass="card-content-inner">Another card. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse feugiat sem est, non tincidunt ligula volutpat sit amet. Mauris aliquet magna justo. </div></div></div><divclass="content-block-title">Styled Cards</div><divclass="card demo-card-header-pic"><divstyle="background-image:url(...)"valign="bottom"class="card-header color-white no-border">Journey To Mountains</div><divclass="card-content"><divclass="card-content-inner"><pclass="color-gray">Posted on January 21, 2015</p><p>Quisque eget vestibulum nulla...</p></div></div><divclass="card-footer"><ahref="#"class="link">Like</a><ahref="#"class="link">Read more</a></div></div><divclass="content-block-title">Facebook Cards</div><divclass="card facebook-card"><divclass="card-header no-border"><divclass="facebook-avatar"><imgsrc="http://gqianniu.alicdn.com/bao/uploaded/i4//tfscom/i3/TB10LfcHFXXXXXKXpXXXXXXXXXX_!!0-item_pic.jpg_250x250q60.jpg"width="34"height="34"></div><divclass="facebook-name">John Doe</div><divclass="facebook-date">Monday at 3:47 PM</div></div><divclass="card-content"><imgsrc="http://gqianniu.alicdn.com/bao/uploaded/i4//tfscom/i3/TB10LfcHFXXXXXKXpXXXXXXXXXX_!!0-item_pic.jpg_250x250q60.jpg"width="100%"></div><divclass="card-footer no-border"><ahref="#"class="link">Like</a><ahref="#"class="link">Comment</a><ahref="#"class="link">Share</a></div></div><divclass="card facebook-card"><divclass="card-header"><divclass="facebook-avatar"><imgsrc="http://gqianniu.alicdn.com/bao/uploaded/i4//tfscom/i3/TB10LfcHFXXXXXKXpXXXXXXXXXX_!!0-item_pic.jpg_250x250q60.jpg"width="34"height="34"></div><divclass="facebook-name">John Doe</div><divclass="facebook-date">Monday at 2:15 PM</div></div><divclass="card-content"><divclass="card-content-inner"><p>What a nice photo i took yesterday!</p><imgsrc="http://gqianniu.alicdn.com/bao/uploaded/i4//tfscom/i3/TB10LfcHFXXXXXKXpXXXXXXXXXX_!!0-item_pic.jpg_250x250q60.jpg"width="100%"><pclass="color-gray">Likes: 112 Comments: 43</p></div></div><divclass="card-footer"><ahref="#"class="link">Like</a><ahref="#"class="link">Comment</a><ahref="#"class="link">Share</a></div></div></div>
Pull to refresh
Pull to refresh is a special component that can be used to initiate the refreshing of a page’s contents.
demo
HTML:
Pull to refresh
card
Hello there! I am a card;
<headerclass="bar bar-nav"><h1class='title'>Pull to refresh</h1></header><divclass="content pull-to-refresh-content"data-ptr-distance="55"><divclass="pull-to-refresh-layer"><divclass="preloader"></div><divclass="pull-to-refresh-arrow"></div></div><divclass="card"><divclass="card-header">card</div><divclass="card-content"><divclass="card-content-inner">
Hello there! I am a card;
</div></div></div></div>
javascript:
$(document).on('refresh','.pull-to-refresh-content',function(e){setTimeout(function(){varcardHTML='<div class="card">'+'<div class="card-header">New Card</div>'+'<div class="card-content">'+'<div class="card-content-inner">'+'Hello! I am the new card!'+(Math.random()*1000000)+'</div>'+'</div>'+'</div>';$(e.target).find('.card').replaceWith(cardHTML);// done$.pullToRefreshDone('.pull-to-refresh-content');},2000);});
Where
page-content should have additional pull-to-refresh-content class. This is required to enable pull to refresh
pull-to-refresh-layer hidden layer with pull to refresh visual elements: preloader and arrow.
data-ptr-distance="55" additional attribute that allows to set custom pull to refresh trigger distance. By default (if not specified) it is 44px.
Pull To Refresh Sequence
When user starts to pull pull-to-refresh-content down, then pull-to-refresh-layer will receive additional "pull-down" class.
When user pulls down pull-to-refresh-content on a distance more than 44px (when pull-to-refresh-layer will be fully visible), then pull-to-refresh-layer will receive additional "pull-up" class which changes arrow rotation to notify user about refresh action on release.
When user release pull to refresh content when it is in "pull-up" state, then pull-to-refresh-layer will receive additional "refreshing" class. In "refreshing" state arrow will be hidden and user will see preloader indicator. On this stage you probably need to do Ajax request and refresh page content.
Pull To Refresh Events
There is a special JavaScript event that helps us to recognize when we need to refresh content:
Event
Target
Description
refresh
Pull To Refresh content<div class="pull-to-refresh-content">
Event will be triggered when pull to refresh enters in "refreshing" state
Reset Pull To Refresh
After we refreshed page content, we need to reset pull to refresh component to let user pull it again:
$.pullToRefreshDone(ptrContent)
Trigger Pull To Refresh
We can also trigger Pull To Refresh manually by using the following method:
$.pullToRefreshTrigger(ptrContent)
Destroy/Disable Pull To Refresh
Sometimes you may need to disable Pull To Refresh on page. We can do that using the following method:
$.destroyPullToRefresh(ptrContent)
And if we need to initialize/enable it again:
$.initPullToRefresh(ptrContent)
See demos for how to use pull to refresh with tabs.
Infinite scroll
Load new items when user scroll to bottom of page。
demo
What you should do is only add a infinite-scroll class to div.content
You need to use $.attachInfiniteScroll only after you have called $.detachInfiniteScroll. The $.detachInfiniteScroll method will auto be called when infinite scroll component init.
Notification
You can show some notifications. It's a iOS like notification that you can set icon, title and text, and you can alose drag to close the notification.
Use JavaScript to open/close notification:
$.notification({title:"Baby",text:"I miss you",media:"<img src='...'>",data:"123",onClick:function(data){$.alert("Click"+data);},onClose:function(data){$.alert("Close "+data);}});//close notification$.closeNotification();
There is only one notification can shown in the same time. It means that the new notification will replace the old one.
Params
Param
Default
Description
title
undefined
Title of notification
text
undefined
Text of notification
media
undefined
Media of notification. It should be a icon with image or iconfont.
data
undefined
This data will be the param of onClick and onClose function.
By default, the router will listen to all links click event, and use ajax to load new page instead of directly jump to the new page.
Add class="external" or external to a link if you don't want router to proxy it.
Set $.config.router = false to close router globally. It's recommend to use pageInit event to init the page, event if you closed the router.
The new page will slide from right to left by default. Add class="no-transition" to link to prevent the animation.
There is a stack to manage the history, the new page will push to stack, you can add class='replace' to replace the stack instead of push.
Inline Page
You can write multi page in one html file. Each page is in a .page container. If you have multi page in one html, you should use .page-current to make it a visiable at first enter.
Every .page container must have an id attr.Router will use id as the unique identify of a page. And you can use the id to jump to the page like this: <a href='#{page-id}'>jump</a>. And if the new Page has the same id to a old page , the DOM of old page will be replace by new page.
JS And CSS
Router will ignore all scripts and styles when load new page! You should import all CSS file and JS file(pack them into one js and css file) in the entry page, And use 'pageInit' to load different page's JS code.
Because users may refresh the page, the subpage will broken if it don't import any CSS and JS. So, you can import all CSS and JS file in every page.
<divclass="page page-current"id='router'><headerclass="bar bar-nav"><h1class='title'>Router</h1></header><divclass="content"><divclass="content-block"><ul><li><ahref="/docs-demos/router2">Ajax Page</a></li><li><ahref="#router3">Inline Page</a></li></ul></div></div></div><divclass="page"id='router3'><headerclass="bar bar-nav"><aclass="button button-link button-nav pull-left back"href="/docs-demos/router"><spanclass="icon icon-left"></span>
Back
</a><h1class='title'>Router</h1></header><divclass="content"><divclass="content-block">
This is an Inline Page，Click <ahref="#"class='back'>Back </a> to go back。
</div></div></div>
Note that you can only write multi inline page in the entry html file. There can only be one .page in new page loaded by ajax.
Ajax Page
Router will prevent all links' click event, and load new page via Ajax by default.
<!-- page 1 --><divclass="page page-current"id='router'><headerclass="bar bar-nav"><h1class='title'>Router</h1></header><divclass="content"><divclass="content-block"><ul><li><ahref="/docs-demos/router2">Ajax New Page</a></li></ul></div></div></div>
<!-- page 2 --><divclass="page"id='router2'><headerclass="bar bar-nav"><aclass="button button-link button-nav pull-left back"href="/docs-demos/router"><spanclass="icon icon-left"></span>
Back
</a><h1class='title'>Router</h1></header><divclass="content"><divclass="content-block">
This is an Ajax Page，click <ahref="#"class='back'>Back </a> to go back。
</div></div></div>
Go Back
It's very easy to go back, what you need to do is only add a .back class on any link. In case of can't go back, you can set the href attr of the link, and router will load the href if it can't go back in history(For example, the user refreshed the page or enter the link directly)
You can also call$.router.back(url) to go back. The url param is optional but recommend too.
If set true, the new page will replace old page in history, you can't back to old page because it has been removed from histroy(but not removed from DOM).
The loadPage method will load new page, and push to history. If you dont't want to push to history, but want to replace history, you should use replacePage:
$.router.replacePage(url,noAnimation);
Infact, replacePage is only a shortcut of loadPage, but set the param replace as true.
And if you want to refresh current page, you can simply use $.router.reloadPage();.
Event
There are many events：
Event
Description
pageLoadStart
before Ajax
pageLoadCancel
the ajax is canceled
pageLoadError
Ajax error
pageLoadComplete
Ajax complete
pageAnimationStart
after the DOM of new page insert into document, before the animation start
pageAnimationEnd
animation end
pageInit
all components in the page have been inited
pageReinit
when back to previous page
pageLoad* Events is trigger on window，The others is on .page Element.