GETTING STARTED
Intro App Framework AF UI Tips and Tricks Upgrade Guide

Upgraded from 2.0 to 2.1

This should be a drop in replacement. If you modified the default stylesheet, you will loose those changes. There were new modifications made, so the 2.0 stylesheet will not work with the 2.1 branch.


Upgrading Your App Framework (jqMobi 1.x) App

App Framework 2.0 is not a drop in replacement, but the upgrade process is simple. Below we will outline what you must do, and then provide examples. Keep in mind, the new themes and code are not backwards compatible. If you had a custom theme, you will need to re-create it.

  1. Get the latest code from github and add it to your project
  2. Replace your reference to jq.mobi.(min)js with appframework.(min)js
  3. Replace your reference to jq.ui.(min)js with appframework.ui.(min)js
  4. Replace your reference to your css theme (jq.ui.css) with af.ui.css)
  5. Rename the "jQUi" div to "afui" (all lower case)
  6. If you have any <ul> style lists, add the class "list" to them
  7. Rename any "jq-badge" classes to "af-badge"
  8. Upgrade any toggle switches to the new format below

New CSS

App Framework 2.1 has new CSS for almost all elements. If you did not edit your stylesheet, you can replace the CSS files. If you made changes, or used a custom theme, you will have to make changes manually.

Lists now require class="list"

App Framework 2.1 no longer applies styles to the default <ul> tags. You must add class="list" to any styled lists.

New Toggle Switch

To use the new toggle switch control as a checkbox or radio button, follow these steps:

  1. Add class "toggle" to the input element
  2. Set the data-on attribute on the label to show the text when the option is selected
  3. Set the data-off attribute on the label to show the text when the option is not selected
  4. Add an empty span inside the label to show the handle that animates for toggling the option
For example:

                    <label>Gender</label>
                    <input id="toggle1" type="checkbox" name="toggle1" value="1" class="toggle">
                    <label for="toggle1" data-on="On" data-off="Off"><span></span></label>
                

Below describes the new HTML

  1. Add class "toggle" to the input element
  2. Set the data-on attribute to show the text when the option is selected
  3. Set the data-off attribute to show the text when the option is not selected
  4. Add an empty span inside the label to show the handle that animates for toggling the option

Disable Routing

To disable the default routing of App Framework, simply set
                    $.ui.useInternalRouting = false;
                
If you are using another framework, like Angular* or Backbone*, you will want to disable App Framework's internal route management and use theirs. To load a panel, then call
                    $.ui.loadDiv("#id",resetHistory,goBack,transition);
                

Page Transitions

App Framework UI includes with six panel transitions. Alternately, you may use these transitions as examples to create your own. Add these attributes to a panel to control how it appears when activated by the UI.

  1. data-transition="slide" - slide right/left transition
  2. data-transition="up" - slide up/down transition
  3. data-transition="down" - slide down/up transition
  4. data-transition="pop" - Pop in/out transition
  5. data-transition="flip" - Flip along the y axis transition
  6. data-transition="fade" - fade transition

Hide Back Button

There are two ways to hide the back button. The first is to set the $ui.showBackButton JavaScript variable.

                        $.ui.showBackButton=false
                    

Alternately, you may hide the back button by overriding the CSS display property of the button itself.

                            #backButton {
                            display:none !important;
                        }
                    

Hide Header Menu

There are two ways to hide the header menu. The first is to call the $ui.toggleHeaderMenu JavaScript function.

                        $.ui.ready(
                        function(){
                        $.ui.toggleHeaderMenu(false); //force hide
                    }
                    ); //Toggle the header menu on load
                

The second way to hide the header menu is to override the CSS display property of the header.

                    .header {
                    display:none !important;
                }
            

Hide Footer Menu

You can remove the footer menu everywhere in your app, or only for specific panels. To remove it globally, either call the $.ui.removeFooterMenu JavaScript function or override the CSS display property.

                    $.ui.ready(
                    function(){
                    $.ui.removeFooterMenu();
                }
                ); //Toggle the footer menu on load
            
                .footer {
                display:none !important;
            }
        

To remove the footer menu only for a selected panel, set the data-footer attribute to "none".

            <div class='panel' id='main' data-footer='none'> </div>
        

$.ui.ready

The $.ui.ready event is fired immediately after af.ui has completely launched and parsed everything. This runs after the first panel is loaded and all data-defer pages are loaded and lets you know when App Framework UI is ready to accept and execute commands.

                $.ui.ready(
                function(){
                //do something
            }
            );
        

Initiate Page Transition

To programatically initiate a page transition, or load a new URL, you use the $.ui.loadContent function. There are four parameters.

  1. ID - id of the div to load (can be an Ajax URL)
  2. New Tab - Boolean if you want to reset the history (new tab)
  3. Go back - is this initiating a back transition
  4. Transition - the name of the transition you want to show

Here are some examples of how to initiate a page transition using App Framework UI.

            $.ui.loadContent(_div_id,newTab,goBack,transition);

            $.ui.loadContent("mydiv",false,false,"pop");
        

Badges

App Framework UI has support for badges to show on any content. Badges add more flexibility and functionality to elements of your app. There are two ways to add a badge. The first way is using inline HTML.
To add a badge using HTML, create a span and set the class="jq-badge". You can set the position of the badge on the element by adding thse additional classes:

  1. tl - Top Left
  2. tr - Top Right (default)
  3. br - Bottom Right
  4. bl - Bottom Left

Here is an example of how to add a badge in the using HTML.

            <span class="af-badge tr">3</span>
        

Alternately, a badge may be added through the $.ui.updateBadge JavaScript function.

            $.ui.updateBadge("id",value,position,color)//ID is the HTML element you want to add it to

            $.ui.updateBadge("id",'3','bl','green')//ID is the HTML element you want to add it to
        

Touch Events

App Framework UI provides many touch events based from the ZeptoJS* touch library. Here is a list of the events you can register listeners for.

  1. tap //similar to click
  2. singleTap //tapped once
  3. doubleTap //two quick taps
  4. longTap //Long press/tap
  5. swipe //screen was swiped
  6. swipeLeft //screen was swiped left
  7. swipeRight //screen was swiped right
  8. swipeUp //screen was swiped up
  9. swipeDown //screen was swiped down

The swipe event is always triggered with the direction of the swipe. The tap event is always triggered when singleTap, doubleTap or longTap are dispatched.

Splashscreen

Add a splashscreen to your app by creating a div in the afui div and setting the id to "splashscreen". When af.ui.launch is called, it will remove the splashscreen from the DOM.


                    <div id="afui">
                    <div id="splashscreen" class='ui-loader'>
                    <img src="kitchensink/images/splash.png">
                    <br><br>
                    <span class='ui-icon ui-icon-loading spin'></span><h1 >Starting app</h1>
                    </div>
                    </div>
                

Remember, this will only be visible until $.ui.launch finishes, so to it display longer disable auto launch by setting $.ui.autoLaunch to false and triggering the launch later using $.ui.launch().

Default Panel/Hash

You can load a panel by default based of the hash in the URL. This is useful for linking users into your app, or keeping state when resuming. This is enabled by default. To disable this behavior and force the app to always start with the default panel, set the $.ui.loadDefaultHash JavaScript parameter appropriately.

                            $.ui.loadDefaultHash=false; //Never load based off the hash/url
                        

Custom Transitions

Use new transitions you create by adding them to the $.ui.availableTransitions object. Some notes regarding that that object include:

  1. The variable "this" is the $.ui object.
  2. You must implement the forward and backward cases.
  3. The function takes three parameters:
      - The panel you are loading.
      - The current viewable panel (old panel).
      - Is this a back transition? (true or false).
  4. After your transition is executed, you must call $.ui.finishedTransition on the objects to reset permissions and CSS classes.

When you have finished writing your transition, add it to $.ui.availableTransitions and set the key to the value you want to reference the data-transition attribute by,

                        function myNewTransition(oldDiv,currentDiv,back){
                        //the magic goes here
                        this.finishTransition(oldDiv);
                    }


                    $.ui.availableTransitions["newTransition"]=myNewTransition;
                

Custom Click Handlers

App Framework UI can be programmed to ignore anchor clicks. There are two ways to turn anchor clicks off. The first way is setting an HTML attribute on the anchor tag.

                    Main 
                

The second method of programming App Framework UI to ignore anchor clicks is registering a click handler function.

                    function myClickHandler(evt){
                    evt.preventDefault();
                }

                $.ui.customClickHandler=myClickHandler;
            

Pull to Refresh

App Framework UI gives you the tools to implement a "pull to refresh" feature. Essentially, the users of the app would swipe the app down in order to trigger the app to check the server for an update.

Here is a quick guide to show you how to implement pull to refresh, inclucing which events to look for and what you can do with it.

Enabling pull to refresh

You can enable pull to refresh in two ways. The first is by setting the refresh property to true on the config object for the scroller.

                    var myScroller=$("#scroller").scroller({
                    refresh:true,
                    scrollBars: true,
                    verticalScroll: true,
                    horizontalScroll: false,
                    vScrollCSS: "jqmScrollbar",
                    hScrollCSS: "jqmScrollbar"
                });
            

The second is calling addPullToRefresh on a scroller object.

                var myScroller=$("#scroller").scroller({
                scrollBars: true,
                verticalScroll: true,
                horizontalScroll: false,
                vScrollCSS: "jqmScrollbar",
                hScrollCSS: "jqmScrollbar"
            });
            myScroller.addPullToRefresh();
        

Enabling in UI

All scrollers for panels are stored in $.ui.scrollingDivs object. That makes implementing "pull to refresh" through JavaScript easy. For example, to set pull to refresh on a panel with id="main", you could execute the following code:
            $.ui.scrollingDivs['main'].addPullToRefresh();
        

Refresh event

Be sure to listen for the "refresh-release" event on our scroller object.
            $.bind(myScroller,"refresh-release",function(){
            console.log("Pulling to refresh");
        })
    

Closing the pull to refresh

By default, the pull to refresh object will automatically close in two seconds. If you are loading remote content though, you may want to close this manually. By returning false in your refresh-release listener, it will leave the pull to refresh window open.
        $.bind(myScroller,"refresh-release",function(){
        fetchRemoteContent(this); //Async call
        return false; //Keep the pull to refresh open
    })
To close it, call .hideRefresh on the scroller object.
    $.bind(myScroller,"refresh-release",function(){
    fetchRemoteContent(this); //Async call
    return false; //Keep the pull to refresh open
});
function fetchRemoteContent(scroller){
//load content
scroller.hideRefresh();
}

About App Framework UI

App Framework UI, also known as AFUI, is the only mobile framework that treats Android*, iOS*, Blackberry* and Win8* the same. In other words, AFUI does not degrade features or performance in order to resolve conflicts or bugs. For example, most frameworks consider Android* to be "broken" and ignore specific versions of that operating system or take shortcuts that perform poorly. App Framework solves these key issues to provide a clean and responsive HTML5 user interface.

App Framework UI provides a Web developer with the JavaScript resources to build an app to look and function (from a users point) exactly like a native app would. For example, standard user interface elements such as headers, footer, and transitions are all automatically provided. App Framework UI supports the HTMl5 history APIs to handle back button navigation. App Framework UI works great along side MVC frameworks like Backbone.js.

App Framework JavaScript Plugins power the core of AFUI. AFUI uses the scrolling library, the CSS3 animation library, and adds plugins like the popup box and action sheet to create a top notch user experience. App Framework UI has App Framework baked right into it, so those APIs are available in your app as well.

Page Layout and Construction

Here we will show you how to construct and lay out the main elements of your app's user interface. This tutorial will start wtih the basic building blocks of an HTML5 app written using App Framework UI, and then move on to demonstrate how to implement headers, footers, panels, custom headers, and custom footers.

UI container

Your app lives inside a div element with the id attribute of "afui". This allows App Framework to segment out the code and styles from the rest of your app if you choose to use AFUI. Be sure this div element has the id attribute of "afui". The App Framework core code references this particular element.

            <div id="afui">

            </div>
        

Headers

Once the container is created, the next basic building block to an app is a header div element. Create a div element inside the container element with the id of "header". This generally lives at the top of the page, but is fully controlled via CSS so it could reasonably work anywhere whithin the UI container element. By default, App Framework will add a "title" h1 tag and a back button to this div element.

                <div id="afui">
                <div id="header">
                
                </div>
                </div>
            

When the page renders this element, by default the HTML will look something like this:

                <div id="afui">
                <div id="header">
                <a id="backButton" href="javascript:;" class="button" style="visibility: hidden; ">Back</a>
                <h1 id="pageTitle">Page Title</h1>
                </div>
                </div>
            

Content Area

The content div element contains all your app's informational panels. It expands automatically to include all the screen space available on the device that it runs on.

                <div id="afui">
                <div id="header">
                
                </div>
                <div id="content">
                
                </div>
                </div>
            

Panels

Panels are the individual content areas for your app. This is the heart of UI. Panel div elements will actually hold the information and controls that you want your app to manage and share.

Creating panels is very easy. Drop a div element with the class attribute of "panel" within the Content Area div element, then set an id attribute and a title. App Framework UI does a lot of "magic" on panels, like adding scrolling logic and fixing Android bugs. If you happen to accidentally leave any panel div elements outside the content div element, AFUI will automatically move them into the content div when the framework starts up.

            <div id="afui">
            <div id="header">
            
            </div>
            <div id="content">
            <div id="main" data-title="Welcome" class="panel" selected="true">

            </div>
            </div>
            </div>
        

Panels have additional properties available such as a switch to turn off auto scrolling or make the panel into a modal window. To see the full list, check out panel properties.

Footer

The footer is a persistant navagation bar at the bottom of your app. App Framework UI uses vector based icons to draw a series of tabs at the bottom of the screen. These tabs are drawn just as they would appear in a native app. The general idea is that you segment your app based on the bottom tabs. For instance, an app displaying a restaurant menu might have one bottom tab for each menu served. Touching one of these would reveal the appropriate panel that displays a list of dishes available for that particular meal. By default, App Framework UI clears its history stack when an item on the footer is selected to prevent users from getting lost.

To create a footer, add a div to your app with the id attribute of "navbar". Add anchor elements within the footer to create the tabs. The class attribute will determine the size and icon image associated with the tab. All events are automatically added to these tab anchor elements, there is no need to write any complex JavaScript code.

            <div id="afui">
            <div id="header">
            
            </div>
            <div id="content">
            <div id="main" data-title="Welcome" class="panel" selected="true">

            </div>
            </div>
            <div id="navbar">
            <a target="#welcome" class="icon home">Home</a>
            </div>
            </div>
        

Anchors go inside the navbar and we auto-wire events for them. You can update the #navbar div directly with more anchors and not have to worry.

Side Menu

A side menu is a way to slide the main UI interface to one side, freeing up a third of the screen on one side for a temporary menu. You can create a side menu by adding a nav element inside the UI container. The position ot the side menu is driven by CSS, but if AFUI finds any nav tags at page start it will create a special container div and add scrolling logic automatically. You can create multiple side menus by creating multiple navs and setting an ID. The first nav tag AFUI finds will be the default. The other side menus can be assigned by setting data-nav="id" on the panel.

                <div id="afui">
                <div id="header">
                
                </div>
                <div id="content">
                <div id="main" data-title="Welcome" class="panel" selected="true" data-nav="main_nav">

                </div>
                </div>
                <div id="navbar">
                <a target="#welcome" class="icon home">Home</a>
                </div>

                <nav id="main_nav">
                <div class='title'>Home</div>
                <ul>
                <li ><a class="icon home mini" href="#main">Home</a></li>
                </ul>
                </nav>
                </div>
            

There is a JavaScript command to show or hide the side menu - $.ui.toggleLeftSideMenu() .
Below is an example of how an app might use multiple side menus.

                    <div id="afui">
                    <div id="header">
                    
                    </div>
                    <div id="content">
                    <div id="main" data-title="Welcome" class="panel" selected="true">
                    
                    </div>

                    <div id="about" data-title="About" class="panel" data-nav="second_nav">
                    
                    </div>
                    </div>
                    <div id="navbar">
                    <a target="#welcome" class="icon home">Home</a>
                    </div>

                    <nav >
                    <div class='title'>Home</div>
                    <ul>
                    <li ><a class="icon home mini" href="#main">Home</a></li>
                    </ul>
                    </nav>
                    <nav id="second_nav">
                    <div class='title'>Second</div>
                    <ul>
                    <li ><a class="icon info mini" href="#about">About</a></li>
                    </ul>
                    </nav>
                    </div>
                

Custom Headers

Custom headers give you the opportunity to individualize an application and give it an identity. You can create custom headers in two ways. The first way is by creating header tags inside the AFUI container and placing an id attribute on them. You then reference them on the panel using the data-header attribute. Be aware that AFUI will not insert any markup inside any custom headers you create, so you are you responsible for building out anything inside them such as the back button and title.

                    <div id="content">
                    <div class="panel" id="main" data-header="custom_header">
                    
                    </div>
                    </div>
                    <header id="custom_header">
                    <h1>Welcome</h1>
                    <a class="button" style="float:right;" class="icon home"></a>
                    </header>
                

You can also create custom headers by inlining them in the panel content. This technique allows you to have unique custom headers only for a particular panel, without the need to create them in the HTML and reference by the data-header attribute.

                    <div id="content">
                    <div class="panel" id="main">
                    
                    <header>
                    <h1>Welcome</h1>
                    <a class="button" style="float:right;" class="icon home"></a>
                    </header>

                    
                    </div>
                    </div>

                

Custom Footers

Custom footers also allow you to set your app apart. You can create custom footers the same way you create custom headers. The only difference is that they use the footer tag instead of the header element. Reference the data-footer attribute on panels to assign them to a particular custom footer.

You can create custom footers in two ways. The first way is by creating footer tags and placing an idea on them. You then reference that footer on the panel via the data-footer attribute. Be aware that AFUI will not insert any markup inside any custom footers you create, so you are responsible forbuilding out anything inside them.

                        <div id="content">
                        <div class="panel" id="main" data-footer="custom_footer">
                        
                        </div>
                        </div>
                        <footer id="custom_footer">
                        <a href='#about' class='icon info'>About</a>
                        </footer>
                    

You can also create custom footers by inlining them in the panel content. This technique allows you to have unique custom footers only for a particular panel, without the need to create them in the HTML and reference by the data-footer attribute.

                        <div id="content">
                        <div class="panel" id="main">
                        
                        <footer>
                        <a href='#about' class='icon info'>About</a>
                        </footer>

                        
                        </div>
                        </div>

                    

Panel Attributes and CSS Properties

You may add attributes to panel div elements to change their default behavior. Changing some CSS properties of a panel div element will also make some changes to the default behavior of the panel that affects more than the style of the element. The CSS properties and element attributes that alter a panel's behavior include:

  1. css property - overflow:hidden - When set, this will disable auto-wiring of the scroller. Usefull for panels that need to auto expand, like carousels or google maps
  2. selected="true" - When set, this will make the panel the default panel that gets loaded.
  3. modal="true" - When set, this turns the panel into a modal window that takes up 100% of the screen (can be changed via CSS).
  4. data-header="id" - when set, it will load the custom <header> tag with that ID for that panel
  5. data-footer="id" - when set, it will load the custom <footer> tag with that ID for that panel
  6. data-nav="id" - when set, it will load the custom <nav> tag with that ID for that panel
  7. data-defer="filename.html" - This will load content into the panel from a remote page/url. This is useful for separating out content into different files. af.ui.ready is not available until all files are loaded asynchronously.
  8. data-tab="anchor_id" - This will set the selected tab in the bottom navbar to the id. Useful for when you update your panel via JS and not clicking a bottom tab.
  9. data-load="func_name" - This is the string name of a function to run when the panel is loaded. The div is passed in as a parameter so you can use a single function and act upon other attributes.
  10. data-unload="func_name" - This is the string name of a function to run when the panel is unloaded

Keep in mind, you can add any attribute to your panel to do what you want, but these attributes are special ones that trigger logic within AFUI.
Here are some examples:

                                    <div class="panel" id="about" style="overflow:hidden"> </div> 

                                    <div class="panel" id="login" selected="true"> </div> 

                                    <div class="panel" id="login" modal="true"> </div> 

                                    <div class="panel" id="about" data-header="default"> </div> 

                                    <div class="panel" id="login" data-footer="none"> </div> 

                                    <div class="panel" id="login" data-nav="settings"> </div> 

                                    <div class="panel" id="login" data-tab="settings"> </div> 

                                    <div class="panel" id="login" data-defer="app/login"> </div> 

                                    <div class="panel" id="login" data-load="showCount" data-counter='5'> </div> 
                                    <script> function showCount(div){alert($(div).data('counter'));} </script>

                                    <div class="panel" id="loggin" data-unload="showCount" data-counter='3'> </div> 

                                

Anchor Attributes

Anchors have special attributes that allow you to change how your app interacts with its user.

  1. data-transition="pop" - This attribute identifies the transition you want to show when navigating. The options available in AFUI are slide, up, down, flip, fade, pop, or none. If no transition is specified, the slide transition is used.
  2. data-persist-ajax="true" - Ajax request will persist and be added to the DOM
  3. data-refresh-ajax="true" - Ajax request will always make a request. Useful for persistant divs to update content
  4. data-ignore="true" Do not use our special click handler, treat the link normally

Here are some examples of how these special attributes are used:

                                    <a href="#home" data-transition="fade">Home </a> 

                                    <a href="products/list" data-persist-ajax="true">Products </a> 

                                    <a href="products/list" data-refresh-ajax="true">Products </a> 

                                    <a href="index.html?bb" data-ignore="True">Load BB10 Theme </a> 


                                

Add or Update a panel

Because AF UI handles wiring of the scroller, and os level fixes (like select boxes for Android), you must use thes API to dynamically add or update panels.


Adding a panel

To add a panel, call $.ui.addContentDiv(id,content,title);
                                $.ui.addContentDiv("newdiv","This is the content","New Div");
                                

Updating a panel content

To update a panel content, call $.ui.updateDiv(id,content);
                                $.ui.updateDiv("newdiv","This is updated content");
                                

Scrolling

App Framework UI automatically adds scrolling logic for you using the af.scrolling.js plugin. On iOS* version 5 and above, AFUI uses -webkit-overflow-scrolling:touch for native scrolling. On all other platforms, AFUI uses a JavaScript scroller. Here are some notes on three specific scrolling issues that developers should be aware of.

Native Scrolling

Native scrolling provides amazing performance, but has some downfalls. The page can not be locked in place and the user can "drag" it. If you have an intensive list on iOS*, you can suffer from memory issues and require native scrolling.

Disable Automatic Scrolling

You can disable scrolling on a panel by setting the CSS "overflow:hidden" on the panel's style.

                                        <div class="panel" id="maps" data-title="Maps" style="overflow:hidden">

                                        </div>
                                    

Force JS scrolling

You can disable native scrolling in two ways. To disable it globally, change the "nativeTouchScroll" JavaScript property.
                                        $.feat.nativeTouchScroll=false; //Disable native scrolling globally
                                    
To disbale native scrolling on a per panel basis, set the "js-scrolling" panel attribute. This will override native scrolling when the panel is created.
                                        <div class="panel" id="maps" data-title="Maps" js-scrolling="true">
                                        </div>
                                    

Ajax based apps

App Framework UI has great built in support for Ajax and server side apps. When you need to load content or panels on the fly, these techniques can really help. AFUI can load Ajax data using these there methods:

  1. Just loading remote content
  2. Loading panels into the DOM
  3. $.ui.isAjaxApp=true style (all panels/customization from Ajax)

Loading remote content

Loading remote content is simple. You can set the href in the anchor to your content, or call $.ui.loadContent with the URL.

The content is loaded into "afui_ajax" div. There is only one instance of this div, so continuous calls will not provide animations or history. Here's an example of how to load content using an anchor tag:
                                        <a href="content.html" data-transition="pop">Remote Content </a>
                                    
Alternately, content may be loaded using a JavaScript call like this:
                                        $.ui.loadContent("content.html");
                                    

Loading panels into the DOM

You can load panels into the DOM (Document Object Model) and persist them so that your app can interact with them normally.

The easiest way to persist the panels is by adding the data-persist-ajax="true" attribute. It will create a new div and add it to the DOM. When you try to load the URL again, it will navigate to the newly added panel instead.
                                        <a href="content.html" data-transition="pop" data-persist-ajax="true">Remote Content </a>
                                    
Alternately, persist panels with a JavaScript call like this:
                                        //you must set every parameter, with the last being "true" so it knows to perist the div
                                        $.ui.loadAjax("content.html",false,false,"slide",true);
                                    

$.ui.isAjaxApp=true

When setting the isAjaxApp property to "true", any link clicked, or $.ui.loadContent call executed, will hit the server again to load the content. The first request will load the panel into the DOM, then subsequent requests will update the content. This technique allows you to use the internal history to manage your application.
                                        $.ui.isAjaxApp=true;
                                    
This technique is particularly useful if your app loads content remotely. You can define custom panel properties, headers, and footers inside the content. Alternately, just pull in HTML that will be added to a new panel.

Styled Lists

App Framework UI 2.1 no longer applies a default style to <ul> elements. Now you must apply the attribute class="list" to render styled lists.
                                        <ul class="list">
                                        <li>Test</li>
                                        </ul>
                                    
The newest App Framework UI introduces inset lists, which provide padding and rounded corners to your list. Add the attribute class="list inset" to use inset lists.

Side Menus

To enable a left side menu in your app, add <nav> objects to the DOM and set id attributes. To enable a right side menu, add <aside> objects to the DOM and set the id attributes. You can load custom menu's on your panel based off atrributes

                                            
These should be declared at the bottom of your HTML, below the #content and #navbar div elements.

                                        <div id="#navbar"></div>

                                        <-- first side menu is the default -->
                                        <nav id="main">
                                        Default side menu
                                        </nav>

                                        <nav id="second">
                                        Second menu
                                        </nav>

                                        <aside id="right">
                                        Right Side menu
                                        <
                                    

.hasMenu class

When <nav> tags are found by App Framework UI, the class "hasMenu" is added to the #header, #content and #navbar divs so AFUI knows what to move when the menu is shown.

Split View

A split view allows your left side menu to be always shown on tablets. This is defaulted to "true" to be backards compatible with 2.0.
                                        $.ui.splitview=true;
                                    

Phone Menu Toggling

To trigger showing the menu programatically, you can call $.ui.toggleLeftSideMenu.

                                        $.ui.toggleLeftSideMenu();//Toggle opening/closing the left side menu
                                        $.ui.toggleRightSideMenu();//Toggle opening/closing the right side menu
                                    

$.ui.toggleLeftSideMenu takes a parameter that allows you to force showing or hiding it

                                        $.ui.toggleLeftSideMenu(true);//Force the menu to show
                                        $.ui.toggleLeftSideMenu(false);//Force the menu to hide

                                        $.ui.toggleRightSideMenu(true);//Force the menu to show
                                        $.ui.toggleRightSideMenu(false);//Force the menu to hide
                                    

Changing the Side Menu

To change the side menu for a panel, set the data-nav attribute on a panel to target a new nav element.

                                        <div class="panel" data-nav="main" data-aside="right" data-title="Test">

                                        </div>

                                        <div class="panel" data-nav="second" data-aside="right" data-title="Test 2">
                                        </div>
                                    

Changing the Side Menu Width

You can change the width of the side menu by calling $.ui.setLeftSideMenuWidth.

                                        $.ui.setLeftSideMenuWidth("200px"); //Set to 200px wide;

                                        $.ui.ready(function(){
                                        $.ui.setLeftSideMenuWidth($("#afui").width()-50);//Set it to be full width - 50 pixels
                                        $.ui.setRightSideMenuWidth("300px"); //Set the right side menu to be 300 pixels wide
                                    });
                                

Split View

To enable splitview on the tablet, which has the left menu always being shown, simply set the property

                                        $.ui.splitview=true;
                                    
This must be set before $.ui.launch gets called.
To disable it, set it to false. This will then allow you to toggle the menu programatically

Force Disable

If you need to disable the splitview after the app has launched
                                    $.ui.disableSplitView();
                                

OS Custom Themes

App Framework UI 2.1 provides themes for the following operating systems. They are enabled by default for the device at launch time.

  1. iOS* (default theme)
  2. Android* (Holo - light and dark)
  3. Windows* 8/Windows* Phone 8 (light and dark)
  4. Blackberry* 10

Disable custom OS themes

To disable custom operating system themes, set $.ui.useOSThemes to false.

                                        $.ui.useOSThemes=false; //This must be set before $(document).ready() triggers;
                                    

Forcing a theme for all devices

To enable a theme for all devices, after you disabled $.ui.useOsThemes, set the class of the afui div to what you want.
                                        
<!-- ios7 --->
<!-- ios --->
<!-- android --->
<!-- android light theme--->
<!-- WP8/Win8 --->
<!-- WP8/Win8 light theme--->
<!-- Blackberry 10 --->
<!-- tizen --->

Creating a custom theme

Interested in creating your own custom themes? Take a look at one of the existing OS themes to see how it is done. Pay particular attention to how the App Framework team modifies the DOM elements and the CSS classes.

CSS Grid System

App Framework UI 2.1 provides support for a basic grid system for positioning elements. This is useful for creating apps that will allow the content to flow to fit the appropriate form factor of the device they are running on.

You can choose from the following grid layouts:

  1. col2 - 50% (2x2)
  2. col3 - 33.3% (3x3)
  3. col1-3 - 33.3% (33.3% for 3 column)
  4. col2-3 - 66% (66.6% for 3 column)
On phones, the grid system will always default to a single row. On tablets, the grid will display inline.

2 column

                                        <div class="grid">
                                        <div class="col2">This is the left column</div>
                                        <div class="col2">This is the right column</div>
                                        </div>
                                    
This is the left column
This is the right column

3 column

                                        <div class="grid">
                                        <div class="col3">This is the left column</div>
                                        <div class="col3">This is the middle column</div>
                                        <div class="col3">This is the right column</div>
                                        </div>

                                    
This is the left column
This is the middle column
This is the right column

1-3/2-3 column


                                        <div class="grid">
                                        <div class="col1-3">This is the left column</div>

                                        <div class="col2-3">This is the right column</div>
                                        </div>


                                    
This is the left column
This is the right column

2-3/1-3 column

                                        <div class="grid">
                                        <div class="col2-3">This is the left column</div>

                                        <div class="col1-3">This is the right column</div>
                                        </div>
                                    
This is the left column
This is the right column

CSS Overview

UI's layout is driven by CSS. You can make a few changes via CSS and drastically change the apperance of your app. You can get rid of the header, footer, make the side menu persistent, change colors, etc. Below we will show some of the key classes you can change.

#header

This is the header that appears at the top. You can change the position, change the size, change the color, or set display:none to hide it.

                                        #header{
                                        height:30px; /* Change the height to 30px*/
                                    }
                                

#content

This is the container for panels. If you are looking to remove a header or footer element, or change the dimensions or a header or footer element, you must update the css properties for top and bottom.

                                        #afui.android #content {
                                        bottom:0px; /* The header isn't shown and the navbar is moved to the top*/
                                    }
                                

.panel

This is the class that panels inherit from. The only thing you should override is the background color. If you are permanently hiding a header or footer, make sure you update the top and bottom attributes appropriately.

                                        .panel {
                                        top:30px; /* Change top to what the header height is */
                                        bottom:0px; /* We are not showing the navbar */
                                        background:rgba(0,0,0,.7);
                                    }

                                

#navbar

The element with the navbar id is the bottom navigtion bar where the tabs are. Here is an example of how you might remove the navbar from your app.

                                    #navbar {
                                    display:none;
                                }
                            

Form Styles

App Framework UI has special form styles built into the css classes. AFUI styles input tags, and provides sprite sheets for checkboxes, radio buttons, and toggles.

Input and Textarea Style

Input, textareas, and select boxes are styled by default and customized for each platform theme.

Checkbox and Radio Button Style

To use the checkbox and radio button sprite sheets, create the input element normally and add a label element immediately after it.

                                    
                                    <input type="checkbox" name="confirm" id="confirm">  <label for="confirm">Do you agree to the terms?</label>

                                    
                                    <input type="radio" name="gender" value='Male' id="Male" >  <label for="Male">Male</label>
                                    <input type="radio" name="gender" value='Female' id="Female" >  <label for="Female">Female</label>

                                

Toggle

App Framework UI provides a toggle switch that can can be used instead of a radio button or checkbox. To create a toggle, add class="toggle" to an input element.

Additionally, the label MUST have a span tag inside of it to get the handle. Use data-on and data-off attributes to set the text that appears in the label.

                                            
                                            Do you agree to the terms?
                                            <input type="checkbox" name="slider" id="slider" class="toggle"> <label for="slider" data-on="Yes" data-off="No"> <span></span> </label>

                                        

Buttons

You can make anything look like a button by applying the "button" class to it. The following all render the same.

                                            <a class="button">Home</a>
                                            <span class="button">Home</span>
                                            <div class="button">Home</div>
                                        

Previous Arrow

You can make a "previous" arrow button by applying the class "previous" to the button

                                            <a class="button previous">Home</a>
                                        

Next Arrow

You can make a "next" arrow button by applying the class "next" to the button

                                            <a class="button next">Home</a>
                                        

Icons on buttons

You can add vector icons to your buttons by adding the classes to them

                                            <a class="button icon home">Home</a>
                                        

Colors

App Framework UI 2.1 provides colors for buttons in iOS* and BlackBerry* 10 themes. On Android* and Windows* Phone 8, buttons are always the same color. To change button colors, simply add one of the following classes:

  1. gray
  2. yellow
  3. red
  4. green
  5. orange
  6. black
  7. slate

Vector Icons

To use App Framework UI's vector icons, make sure you include the icons.css file.

                                            <link rel="text/stylesheet" href="http://cdn.app-framework-software.intel.com/1.2/icons.css"/>
                                        

Once the icons.css file is included, you can reference icons by setting the class name. Find the name of the image you want, and set the class on the element to include that name as well as the class "icon". Icons will appear before any content, and you get the larger or smaller icon by adding "big" or "mini" to the class. For example:

                                                
                                                <div class='icon home'>Home</div>

                                                
                                                <div class='icon home mini'>Home</div>

                                                
                                                <div class='icon home big'>Home</div>
                                            

Events

Below are the following events triggered in App Framework UI.

                                                $.ui.load - This event is fired once when App Framework UI is loaded and ready to go.
                                            

These events are only triggered on the window object

                                                hashchange - This event is fired when the a panel has been changed.
                                                orientationchange - This event is fired when the page rotates.
                                                afui:init - This event fires when then $.ui object has been initialized
                                            

These events are triggered on the document.

                                                afui:ready - App Framework UI has launched and ready to be used
                                                missingpanel - This event is fired when the panel was not found in the DOM
                                            

These events are triggered on a DOM node. They will bubble up.

                                                unloadpanel  - This event is fired when a panel has been unloaded.
                                                loadpanel  - This event is fired when a panel has been loaded.
                                                tap  - This event is fired when tap event happened on a node.  It is similar to a click event.
                                                doubleTap  - This event is firedd when a DOM node is double tapped.
                                                singleTap  - This event is fired when a node is single tapped.  There is a delayed trigger for this event.
                                                longTap  - This event is fired when a user holds down a tapped a node for over 750 milliseconds.
                                                swipe - This event is fired when a user swipes a DOM node.
                                            

These events are triggered by a scroller object. These events are handled using $.trigger and $.bind. These events will not bubble.

                                                refresh-release  - This event is fired when a scroller object pull to refresh has been released.
                                                refresh-cancel - This event is fired when a refresh has been triggered, but a user scrolls then we cancel it.
                                                refresh-trigger - This event is fired when a refresh request has happened on the scroller.
                                                refresh-finish - This event is fired when a refresh has been processed and finished.

                                                infinite-scroll - This event is fired  when a scroller has hit the end of the content and is requesting more info.
                                                infinite-scroll-end - This event is fired when a scroller has stopped scrolling after triggering an infinit-scroll event.

                                                scrollstart - This event is fired when a scroller object starts scrolling.
                                                scrollend - This event is fired when a scroller stops scrolling.

                                                swipeLeft/swipeRight/swipeDown/swipeUp - These events are fired in response to a swipe event.  They indicate the direction of the swipe.

                                            

App Framework is comprised of three parts

  1. App Framework - a query selector library
  2. UI - a UI/UX library for smartphone and tablets
  3. Plugins - plugins built on top of App Framework

App Framework was built from the ground up to excel on mobile devices by being light and fast. It takes advantage of new browser features and supports valid W3C CSS selectors. User generated performance tests at jsperf.net have shown it to be faster than every other JavaScript* library available.

App Framework UI, also known as AFUI, is the only mobile framework that treats Android*, iOS*, Blackberry* and Win8* the same. In other words, AFUI does not degrade features or performance in order to resolve conflicts or bugs. For example, most frameworks consider Android* to be "broken" and ignore specific versions of that operating system or take shortcuts that perform poorly. App Framework solves these key issues to provide a clean and responsive HTML5 user interface.

Plugins are separate JavaScript libraries created to augment apps written using App Framework App Framework. Plugins provide useful features or functionality that may be outside the scope of basic applications. App Framework UI harnesses a few of the core plugins like af.scroller.js and af.css3animate.js.

App Framework

App Framework is sponsored by Intel.

App Framework is released under the MIT X11 license, with the source hosted at gitHub. All copyright is held by Intel unless otherwise noted.

Want to get involved?

First, head over to Github and fork the code. You can start playing around with the core, break things, fix things, and make enhancements. When you are ready, submit a pull request with the following

  1. Overview of the pull request
  2. Bugs fixed/Features added
  3. Test cases for the above
  4. Does this change affect current installs (will it break them)?
We will then review the pull request and either auto merge it or offer feedback. If you are proposing something drastic, it's best to get in touch with us first to discuss the overall impact and go from there. If we find it diverts from our core goals or will affect users, we will deny it.

Use jQuery* and App Framework UI

With App Framework 2.1, you can now use jQuery and App Framework UI, instead of using appframework.js. We have created a jQuery* plugin called jq.appframework.js. Now you do not have to worry about conflicts with jQuery* plugins and App Framework.

Using the plugin

To use the plugin, include jQuery* first, then jq.appframework.js and finally appframework.ui.js (not the minified version).
                                            <script src="jquery.js"></script>
                                            <script src="jq.appframework.js"></script>
                                            <script src="appframework.ui.js"></script>
                                        
You can find this plugin in github here and at plugins.jquery.com

UI Quickstart

Get started on a basic, skeleton App Frmework UI app using this tutorial. First, this tutorial will explain where to find and download the source code. Next, the tutorial will go over individual parts of the HTML page that creates the skeleton app. Finally this tutorial will provide a complete basic sample. To see more complex examples, look in the "examples" folder of the download.

Get the code

You can download the latest release from Github. You should get the following key folders:
  1. plugins - This is where additional plugins live
  2. kitchensink - This includes all the CSS and images for the themes
  3. ui - The main UI JavaScript library (appframework.ui.min.js) is found in this directory


Basic page structure

For this basic sample, add these basic meta tags and include these files. All the code in this sample will work right off the default folders defined in the downloaded code, so don't change folder names unless you know what you're doing.
                                            <!DOCTYPE html>
                                            <!--HTML5 doctype-->
                                            <html>

                                            <head>
                                            <title>UI Starter</title>
                                            <meta http-equiv="Content-type" content="text/html; charset=utf-8">
                                            <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
                                            <meta name="apple-mobile-web-app-capable" content="yes" />
                                            <link rel="stylesheet" type="text/css" href="build/css/icons.css" />
                                            <link rel="stylesheet" type="text/css" href="build/css/af.ui.css"  />
                                            <!-- uncomment for  apps
                                            <script type="text/javascript" charset="utf-8" src="indelxdk.js"></script>        
                                            -->
                                            <script type="text/javascript" charset="utf-8" src="build/ui/appframework.ui.min.js"></script>
                                        


Next, setup the default JavaScript properties and functions that end the meta setup.
                                            <!-- emulate touch events on desktop browsers only -->
                                            <script>
                                            if (!((window.DocumentTouch && document instanceof DocumentTouch) || 'ontouchstart' in window)) {
                                            var script = document.createElement("script");
                                            script.src = "plugins/af.desktopBrowsers.js";
                                            var tag = $("head").append(script);
                                        }
                                        </script>
                                        <script type="text/javascript">

                                        $.ui.autoLaunch = false; //By default, it is set to true and you're app will run right away.  We set it to false to show a splashscreen
                                        /* This function runs when the body is loaded.*/
                                        var init = function () {
                                        $.ui.backButtonText = "Back";// We override the back button text to always say "Back"
                                        window.setTimeout(function () {
                                        $.ui.launch();
                                    }, 1500);//We wait 1.5 seconds to call $.ui.launch after DOMContentLoaded fires
                                };
                                document.addEventListener("DOMContentLoaded", init, false);

                                /* This code is used for Intel native apps */
                                var onDeviceReady = function () {                    
                                intel.xdk.device.hideSplashScreen();

                            };
                            document.addEventListener("intel.xdk.device.ready", onDeviceReady, false);
                            </script>
                            </head>
                        


Next, setup the body HTML and special div elements.
                            <body>
                            <div id="afui"> <!-- this is the main container div.  This way, you can have only part of your app use UI -->
                            <!-- this is the header div at the top -->
                            <div id="header">
                            <a href="javascript:$.ui.toggleLeftSideMenu()" class="button" style="float:right">Toggle Nav</a>
                            </div>
                            <div id="content">
                            <!-- here is where you can add your panels -->
                            <div data-title='Welcome' id="main" class="panel" selected="true">This is a basic skeleton UI sample</div>
                            </div>
                            <!-- bottom navbar. Add additional tabs here -->
                            <div id="navbar">
                            <div class="horzRule"></div>
                            <a href="#main" id='navbar_home' class='icon home'>home</a>
                            </div>
                            <!-- this is the default left side nav menu.  If you do not want any, do not include these -->
                            <nav>
                            <div class='title'>Home</div>
                            <ul>
                            <li >
                            <a  class="icon home mini" href="#main">Selectors</a>
                            </li>
                            </ul>
                            </nav>
                            </div>
                            </body>
                            </html>
                        

Put it all together to get the full page

                            <!DOCTYPE html>
                            <!--HTML5 doctype-->
                            <html>

                            <head>
                            <title>UI Starter</title>
                            <meta http-equiv="Content-type" content="text/html; charset=utf-8">
                            <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
                            <meta name="apple-mobile-web-app-capable" content="yes" />
                            <link rel="stylesheet" type="text/css" href="build/css/icons.css" />
                            <link rel="stylesheet" type="text/css" href="build/css/af.ui.css" />
                            <!-- uncomment for apps
                            <script type="text/javascript" charset="utf-8" src="indelxdk.js"></script>        
                            -->
                            <script type="text/javascript" charset="utf-8" src="build/ui/appframework.ui.min.js"></script>
                            <!-- emulate touch on desktop browsers only -->
                            <script>
                            if (!((window.DocumentTouch && document instanceof DocumentTouch) || 'ontouchstart' in window)) {
                            var script = document.createElement("script");
                            script.src = "plugins/af.desktopBrowsers.js";
                            var tag = $("head").append(script);
                            $.os.android = true; //let's make it run like an android device
                            $.os.desktop = true;
                        }

                        </script>
                        <script type="text/javascript">

                        var webRoot = "./";
                        $.ui.autoLaunch = false; //By default, it is set to true and you're app will run right away.  We set it to false to show a splashscreen
                        /* This function runs when the body is loaded.*/
                        var init = function () {
                        $.ui.backButtonText = "Back";// We override the back button text to always say "Back"
                        window.setTimeout(function () {
                        $.ui.launch();
                    }, 1500);//We wait 1.5 seconds to call $.ui.launch after DOMContentLoaded fires
                };
                document.addEventListener("DOMContentLoaded", init, false);
                $.ui.ready(function () {
                //This function will get executed when $.ui.launch has completed
            });


            /* This code is used for Intel native apps */
            var onDeviceReady = function () {
            intel.xdk.device.hideSplashScreen();

        };
        document.addEventListener("intel.xdk.device.ready", onDeviceReady, false);
        </script>
        </head>

        <body>
        <div id="afui"> <!-- this is the main container div.  This way, you can have only part of your app use UI -->
        <!-- this is the header div at the top -->
        <div id="header">
        <a href="javascript:$.ui.toggleLeftSideMenu()" class="button" style="float:right">Toggle Nav</a>
        </div>
        <div id="content">
        <!-- here is where you can add your panels -->
        <div data-title='Welcome' id="main" class="panel" selected="true">This is a basic skeleton UI sample</div>
        </div>
        <!-- bottom navbar. Add additional tabs here -->
        <div id="navbar">
        <div class="horzRule"></div>
        <a href="#main" id='navbar_home' class='icon home'>home</a>
        </div>
        <!-- this is the default left side nav menu.  If you do not want any, do not include these -->
        <nav>
        <div class='title'>Home</div>
        <ul>
        <li >
        <a class="icon home mini" href="#main">Selectors</a>
        </li>
        </ul>
        </nav>
        </div>
        </body>
        </html>
    

App Framework - Query Selector Library

App Framework is a blazingly fast query selector library built from the ground up for mobile devices. Recognizing the previous groundwork that existing frameworks like jQuery* and ZeptoJS* laid out, we identified ways to speed up performance, while only implementing the necessary API's. We currently support over 60+ API's for App Framework with jQuery* compatible syntax. For a full list, go here

AMD compatibility

AMD (Asynchronous Module Definition) is an API specifying a mechanism for defining modules such that the module and its dependencies can be asynchronously loaded. App Framework 2.1 is AMD compatible. It was tested against Require JS.

// Configure the RequireJS paths to use an alias for the
// App Framework library.
require.config({
    paths: {
        "appframework": "./build/appframework"
    }
});


// Now that we have configured a named alias for the App Framework
// library, let's try to load it using the named module.
require(
    [
        "appframework"
    ],
    function($){
        console.log($,af);
    }
);

App Framework UI and AMD

When using App Framework UI with AMD, it will automatically set $.ui.autoLaunch=false;
require.config({
    paths: {
        "afui": "./build/ui/appframework.ui"
    }
});


// Now that we have configured a named alias for the App Framework
// library, let's try to load it using the named module.
require(
    [
        "afui"
    ],
    function($){
        $.ui.launch()
    }
);

    

App Framework UI, jQuery and AMD

require.config({
        paths: {
            "af": "http://code.jquery.com/jquery-1.11.0.min",
            "jqaf": "https://rawgithub.com/01org/appframework/master/jq.appframework",
            "appframeworkui": "https://rawgithub.com/01org/appframework/master/build/ui/appframework.ui"
        },
        shim: {            
            jqaf: {
                deps: [
                    'jquery'
                ]
            },
            appframeworkui:{
                deps: [
                    'jqaf'
                ]
            }
        }
    });
     
     
    // Now that we have configured a named alias for the App Framework
    // library, let's try to load it using the named module.
    require(
        ["jquery","jqaf","appframeworkui"],//,"jqaf","appframeworkui"],
        function(){
           $.ui.launch()
        }
    );

Plugin Template


        /**
        * @author _your_name
        * @description App Framework plugin template
        * @copyright _your_company
        *
        * *
        */
        // please replace _plugin_ with the name of your plugin
        ;(function ($) {
        //internal cache of objects
        var cache = {};
        //Plugin constructor for AF
        $.fn["_plugin_"] = function (opts) {
        if (this.length == 0) return;
        opts = opts || {};
        //Loop through the AF object and setup each item
        for (var i = 0; i < this.length; i++) {
        this[i]._plugin_id = this[i]._plugin_id || $.uuid();
        if (!cache[this[i]._plugin_id]) cache[this[i]._plugin_id] = new (this[i], opts);
        tmp = cache[this[i]._plugin_id];
    }
    return this.length == 1 ? tmp : this;
}

//Actual plugin object
var _plugin_ = function (el, opts) {
this.el = el;
this.$el = $(el);
var self=this;
//destroy gets called on DOM nodes so we can clean up
//the JS object
$(this.$el).one("destroy", function (e) {
if (cache[self._plugin_id]) delete cache[self._plugin_id];
});
};
//Prototype for the plugin
_plugin_.prototype = {
};
})(af);

Plugins

App Framework Plugins are reusable pieces of JavaScript* code to help augment your application. They can be used to perform trivial tasks or to create complex UI widgets. There are two types of plugins you can create.
  1. Utility plugins that do not act on objects
  2. Plugins that act on a bucket/element

If you already have a jQuery* plugin that uses the functions we implement, your code should be fairly easy to port over. For the most part, you will just need to change the reference in the IIFE (Immediately Invoked Function Expression) from "jQuery" to "jq".

Creating a Plugin for App Framework

First, this document will illustrate the basic structure for creating a plugin, then demonstrate how to create a utility plugin. Finally this page will share how to create a plugin that acts upon elements in a bucket.

The first step to createing a plugin is creating an IIFE (Immediately Invoked Function Expression) and extend the $.fn object. For example:

                (function($){
                $.fn.myPlugin=function(){

            };
        })(af)
    

The code above creates a simple function that can then be accessed using the object returned by the $().myPlugin() function. There are a few tips to remember when operating inside the plugin.

  1. The JavaScript* variable "this" will be the master App Framework object.
  2. To enable chaining, the plugin must return "this".

Next, here is an example of how to make a utility plugin that does not act on objects.

        (function($){
        $.foo=function(){
        alert("bar");
    };
})(af)

To access this function, call the function $.foo(). Once it is executed, it will show an alert with the text of "bar". This plugin may be chained. Here's an example of how to write the function to chain on itself and keep a local counter variable of the number of times it has executed in the chain.

        (function($){
        var counter=0;
        $.foo=function(){
        alert("Counter = "+counter);
        counter++;
        return this;
    };
})(af);

When this sample code above is executed, the first time it will show an alert that reads "Counter = 0". The next time it executes it will display an alert reading "Counter= 1", and so on. Notice the "return this" part, this allows us to chain the command so we can then run it as $.foo().foo();

Finally, here is an example of a plugin that acts on HTML elements. In this sample, the code will get the innerHTML of all the elements in the document and show them in alert boxes.

        (function($){
        var counter=0;
        $.foo=function(){
        var str="";
        for(var i=0;i<this.length;i++)
        {
        str+=this[i].innerHTML;
        str+=" | ";
    }
    alert(str);
    return this;
};
})(af)

The sample plugin above could alert the contents of all div elements by executing $("div").foo().

Here is an example of an advanced plugin. This plugin creates a Google* Maps object in the containers you specify. It caches the Google Maps object so you can then access it later on.

    // @author Ian Maffett
    // @copyright App Framework 2012

    (function () {
    var gmapsLoaded = false; //internal variable to see if the google maps API is available

    //We run this on document ready.  It will trigger a gmaps:available event if it's ready
    // or it will include the google maps script for you
    $(document).ready(function () {
    if(window["google"]&&google.maps){
    $(document).trigger("gmaps:available");
    gmapsLoaded = true;
    return true;
}
var gmaps = document.createElement("script");
gmaps.src = "http://maps.google.com/maps/api/js?sensor=true&callback=gmapsPluginLoaded";
$("head").append(gmaps);
window["gmapsPluginLoaded"] = function () {
$(document).trigger("gmaps:available");
gmapsLoaded = true;
}
});

//Local cache of the google maps objects
var mapsCache = {};

//We can invoke this in two ways
//If we pass in positions, we create the google maps object
//If we do not pass in options, it returns the object
// so we can act upon it.

$.fn.gmaps = function (opts) {
if (this.length == 0) return;
if (!opts) return mapsCache[this[0].id];
//Special resize event
if(opts=="resize"&&mapsCache[this[0].id])
{
 return google.maps.event.trigger(mapsCache[this[0].id], "resize");
}

//loop through the items and create the new gmaps object
for (var i = 0; i < this.length; i++) {
new gmaps(this[i], opts);
}
};


//This is a local object that gets created from the above.
var gmaps = function (elem, opts) {
var createMap = function () {
if (!opts || Object.keys(opts).length == 0) {
opts = {
zoom: 8,
center: new google.maps.LatLng(40.010787, -76.278076),
mapTypeId: google.maps.MapTypeId.ROADMAP
}
}
mapsCache[elem.id] = new google.maps.Map(elem, opts);
google.maps.event.trigger(mapsCache[elem.id], 'resize');
}

//If we try to create a map before it is available
//listen to the event
if (!gmapsLoaded) {
$(document).one("gmaps:available", function () {
createMap()
});
} else {
createMap();
}
}
})(af);

Quickstart

When using App Framework, you can only use W3C valid selectors. To see the full list, go to W3C . We do not support the custom psuedo selectors that jQuery* has created. Below are some examples of how App Framework can help speed up your development.

First, include App Framework into your page.

        <script src="//cdn.app-framework-software.intel.com/2.1/appframework.min.js" type="text/javascript"></script>
    
App Framework works by adding elements into a "bucket". All elements inside the bucket have access to the special App Framework api functions that help speed up your development.

To use App Framework, you first call the $() function with a parameter. The parameter can be one of the following.
  1. String - this could be an element id "#id", classname ".foo", a combination "#id .foo", or an HTML string to create an object "<div id='foo'></div>"
  2. Element - This will create a new App Framework object and add the element to the bucket.
  3. Array/Object - this will create a new App Framework object and add the items to the bucket.
  4. Function - this will execute a function when DOMContentLoaded has triggered, or immediatly after the case
You can also pass an addtional parameter "Context" that allows you to search/filter within that.

Below are some basic samples of finding elements.

            $("#foo"); //find the element with id="foo";

            $("div"); //Find all the divs on the page;

            $(".foo"); //Find all elements that have the classname ="foo";

            $("#foo span"); //Find all span's that exist inside the element with id="foo"
        


Below, we will find all list items (<li>) and add a class "foo" to them.
            $("li").addClass("foo");
        
Here we will find an element "foo" by the id and hide it.
            $("#foo").hide();
        
Here we will find everything with class name "removeme" and remove it from the DOM
            $(".removeme").remove();
        
Let's look at some of the more advanced things we can do. Below, we will create a div, append it to the body and register a click event.
            var div=$("
This is some content
"); $(document.body).append(div); div.bind("click",function(){ alert("I was clicked"); });