GETTING STARTED
Intro AF UI Tips and Tricks

Views

Views are the driving force for App Framework 3.0. A view has an optional header and footer. Your view can then have N number of panels and side menus.

            
Views do not have a transition when navigating between them. You can have them transition, but the footer and header will also transition.

View History

History is kept for each view, allowing navigation back in the view from the current state. It is not a "global" history, but view based.

Modal Views

Modal views operate just like a normal view. You invoke them by adding a special option to the transition.
            Login
        
You can set "up-reveal" or "down-reveal" as the transition. This will keep the previous view in the same state and transition the new view.

Dismiss Modal Views

To dismiss the modal view, simply set the data-transition to have ":dismiss" in it.
            Cancel
        

Disable routing

In some cases, you do not want AF UI to handle routing/click capture.

               //before AFUI launches
               $.afui.useInternalRouting=false;
        

Disable History

If you want to disable history, simply set the property before AFUI launches
               //before AFUI launches
               $.afui.manageHistory=false;
        

$.afui.ready

The $.afui.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-include pages are loaded and lets you know when App Framework UI is ready to accept and execute commands.

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

Initiate Page Transition

To programatically initiate a page transition, or load a new URL, you use the $.afui.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.

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

            $.afui.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 $.afui.updateBadge JavaScript function.

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

            $.afui.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.

Swipe and prevent scroll

There are cases where you want to swipe and block scrolling, such as swipe to reveal. To do this, you can add the following classes

  1. .swipe //Blocks for any swipeStart
  2. .swipe-x //Blocks for any horizontal swipe
  3. .swipe-y //Blocks for any vertical swipe
  4. .swipe-reveal //blocks for any swipeStart

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 $.afui.launch finishes, so to it display longer disable auto launch by setting $.afui.autoLaunch to false and triggering the launch later using $.afui.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 $.afui.loadDefaultHash JavaScript parameter appropriately.

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

Custom Transitions

You can create new transitions via CSS. The easiest way is to modify animgenerator/anims.json file and run the generate.js script. Due to Android < 4.4 not support animation-direction:reverse, we must create the reverse animation

Below are the classes for "slide" transition that must be created

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();
                }

                $.afui.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 $.afui.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:
            $.afui.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 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 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.

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.

Views

Views are the driving force for App Framework 3.0. A view has an optional header and footer. Your view can then have N number of panels and side menus.

Headers

Each view has only one header. If you need a different header, create a different view
                

My Header

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

                

My Area

Pages

The pages area holds your panels. This allows the content area to scroll and have the header and footer remain in the viewport

                

My Header

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 data-title.

            

My Header

Hello World

Panels have additional panel properties.

Footer

The footer is a persistant navagation bar in your app. You can place it after the "pages" div to get it at the bottom of the viewport. You can also place it below the header to get a second level navigation.
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.

            

My Header

Hello World

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. selected="true" - When set, this will make the panel the default panel that gets loaded.
  2. data-include="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.
  3. 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.

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="login" selected="true"> </div> 

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

                                    <div class="panel" id="login" data-include="app/login"> </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> 


                                

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. $.afui.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 $.afui.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:
                                        $.afui.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
                                        $.afui.loadAjax("content.html",false,false,"slide",true);
                                    

$.afui.isAjaxApp=true

When setting the isAjaxApp property to "true", any link clicked, or $.afui.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.
                                        $.afui.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(Drawers)

To enable a left side menu in your app, add <nav> objects to the view and set id attributes. You can load the side menu on the left or right side, along with three transitions

                                            
                                        

Sub Views

Side Menu's act as a sub view, so you can transition to pages within the view you create. If you navigate to a panel in the main view, the side menu will automatically close.

Displaying Drawers

To display the menu, you can use the data directives
                                        
                                    
The data-left-menu attribute will load the menu with id "leftMenu" on the left side. The data transition attribute tells it what transition to run.
                                        Left Menu
                                        Right Menu
                                        Right Menu
                                    
You can find more information about the drawer plugin here

Split View

A split view allows your left side menu to be always shown on tablets. Simply add the class "splitview" to the view you want to enable
                                    
                                    

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 $.afui.useOSThemes to false.

                                        $.afui.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 $.afui.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.

                                                $.afui.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 $.afui 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.

                                                panelbeforeload - this event is fired before the panel is transitioned/loaded
                                                panelload  - This event is fired when a panel has been loaded.
                                                panelbeforeunload - this event is fired before the panel is transitioned/unloaded
                                                panelunload  - This event is fired when a panel has been unloaded.
                                                nestedviewunload - This event is fired when a nested view has been unloaded (used in the drawer widget).
                                                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.
                                                swipeStart - This event is fired when a user starts swiping a DOM node that has the .swipe class
                                            
See Touch/Swipe Events for more on touch and

App Framework is a a UI/UX library for smartphone and tablets

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. App Framework UI supports Android* 4+, iOS* 6+, IE*10+, Blackberry* 10+ and Firefox* OS.

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 the compiled App Framework files for jQuery* found in the build folder
                                            <script src="jquery.js"></script>
                                            <script src="af.ui.jquery(.min).js"></script>
                                        
You can find this plugin in github here and at plugins.jquery.com

UI Quickstart

Get started on a basic app following the tab sample. 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. build - this has all the files you should use
  2. src - This is where the source lives

3rd party libraries

App Framework no longer provides a query selector library. We recommend using jQuery* and FastClick libaries.

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>
                                        
                                        <html>

                                        <head>

                                            Tab View Template
                                            
                                            
                                            
                                            
                                            
                                            
                                            


                                            
                                            
                                            

                                        
                                        


Next, setup the default JavaScript properties and functions that end the meta setup.
                                        <script type="text/javascript">

                                            $.afui.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 content is loaded.*/
                                             $(document).ready(function(){
                                                setTimeout(function(){
                                                    $.afui.launch();
                                                },1500);
                                            });
                                        </script>
                                        </head>
                        


Next, setup the body HTML and special div elements.
                        
App Framework - Tab View

Starting app

Tab View

This is view for first Tab
This is view for second Tab

About
This is view for third Tab
This is view for fourth Tab

Put it all together to get the full page

            <!DOCTYPE html>
            
            <html>

            <head>

                Tab View Template
                
                
                
                
                
                
                


                
                
                

            

            

                
App Framework - Tab View

Starting app

Tab View

This is view for first Tab
This is view for second Tab

About
This is view for third Tab
This is view for fourth Tab
</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 $.afui.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($){
        $.afui.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(){
           $.afui.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);

Creating custom App Starter widgets

App Starter now allows App Framework plugin developers the ability to integrate their own plugins into App Starter. Plugin developers will simply create a _pluginname_.appstarter.js file that implements API functions. App Starter can automatically detect the file and load it for the developer.

Below, we will go over exactly what the plugin developer can do. To get started, we suggest reviewing the label plugin found below and carousel plugin found here. The label plugin is a very basic example, where the carousel goes more in depth.

_plugin_.appstarter.js

You can start with the template below The following are a few tips.

Below are the properties and methods you need to implement.





Label example



{
    css:".my_label { background:#ccc}",
    name:"label",
    template:"",
    editTemplate: '
'+ '
'+ '
', editInit: function() { $prefs.find("#label_id").val(activeItem.attr("id")); $prefs.find("#for_id").val(activeItem.attr("for")); $prefs.find("#for_text").val(activeItem.html()); }, editSave: function() { activeItem.attr("id",$prefs.find("#label_id").val()); activeItem.attr("for",$prefs.find("#for_id").val()); activeItem.html($prefs.find("#for_text").val()); }, importSelector:"label.my_label" }

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