Whizu

jQuery Mobile in Java

View project on GitHub
Whizu Download
jQuery Mobile widgets
Pages Accordions Buttons Collapsibles

jQuery Mobile Buttons

Buttons are core widgets in jQuery Mobile and are used within a wide range of other plugins. The button markup is flexible and can be created from links or form buttons. Whizu provides you with a fluent ButtonBuilder API to create Buttons in Java.

How to use ButtonBuilder to create a jQuery Mobile button

Check out the ButtonBuilder API to find out how to create buttons and see which options are available in the API. Here's a basic example on how to use the ButtonBuilder API. The static .create() and .createXYZ() methods create a new ButtonBuilder instance that your can further configure using any of the other member methods to specify exactly how you want your button to be built. Finally call .build() on the ButtonBuilder to build the button.

import org.whizu.jquery.mobile.Button;
import org.whizu.jquery.mobile.ButtonBuilder;

Button button = ButtonBuilder.createWithTitle("Click here").build();

Which could also be written as follows. The @formatter comments are optional and basically tell Eclipse to turn off the code formatter for the code between the @formatter:off (turn formatting off) and the @formatter:on (turn formatting back on) tags.

import org.whizu.jquery.mobile.Button;
import org.whizu.jquery.mobile.ButtonBuilder;

// @formatter:off
Button button = ButtonBuilder.create()
    .title("Click here")
    .build();
// @formatter:on

Basics of jQuery Mobile button markup

jQuery Mobile supports different button types. Have a look at the ButtonType API for more information. Use anchor buttons (HTML a elements) to mark up navigation buttons, and HTML input or button elements for form submission. The different button types (anchor, button, input, submit, reset) look all the same.

Any of these button types has the possibility to only show an icon and hide the title. Here's some possibilities.

By default, all buttons in the body content of a jQuery Mobile page are styled as block-level elements so they fill the full width of the screen.

ButtonType.ANCHOR

Use anchor type buttons with ButtonType.ANCHOR for navigation buttons. This is the default button type when using ButtonBuilder to create a button; if you don't specify the button type, the ButtonBuilder will build an anchor type button.

Here's an example of three ways to achieve the same result.

// use the default button type
Button button = ButtonBuilder.createWithTitle("Anchor").build(); 

//set the button type explicitly
Button button = ButtonBuilder.create()
    .type(ButtonType.ANCHOR) 
    .title("Anchor")
    .build();

//use a convenience method
Button button = ButtonBuilder.createAnchorButton()
    .title("Anchor")
    .build();   

The generated markup is the same in each of these cases.

<a data-role="button">Anchor</a>

ButtonType.BUTTON

The type ButtonType.BUTTON is usable for form submission. Here's some examples.

//set the button type explicitly
Button button = ButtonBuilder.create()
    .type(ButtonType.BUTTON) 
    .title("Button")
    .build();

//use a convenience method
Button button = ButtonBuilder.createButtonButton()
    .title("Button")
    .build();   

The generated markup is the following.

<button>Button</button>

ButtonType.INPUT

The type ButtonType.INPUT is usable in forms. Here's some examples.

//set the button type explicitly
Button button = ButtonBuilder.create()
    .type(ButtonType.INPUT) 
    .title("Input")
    .build();

//use a convenience method
Button button = ButtonBuilder.createInputButton()
    .title("Input")
    .build();   

The generated markup is the following.

<input value="Input" type="button">

ButtonType.SUBMIT

The type ButtonType.SUBMIT is very similar for usage in forms. Here's some examples.

//set the button type explicitly
Button button = ButtonBuilder.create()
    .type(ButtonType.SUBMIT) 
    .title("Submit")
    .build();

//use a convenience method
Button button = ButtonBuilder.createSubmitButton()
    .title("Submit")
    .build();   

The generated markup is the following.

<input value="Submit" type="submit">

ButtonType.RESET

The usage of ButtonType.RESET in forms is almost identical.

//set the button type explicitly
Button button = ButtonBuilder.create()
    .type(ButtonType.RESET) 
    .title("Reset")
    .build();

//use a convenience method
Button button = ButtonBuilder.createResetButton()
    .title("Reset")
    .build();   

The generated markup is the following.

<input value="Reset" type="reset">

Inline buttons

By default, all buttons in the body content of a jQuery Mobile page are styled as block-level elements so they fill the full width of the screen. If you have multiple buttons that should sit side-by-side on the same line, add the data-inline=“true” attribute to each button. This will style the buttons to be the width of their content so the buttons sit on the same line.

Button true = ButtonBuilder.createAnchorButton("True")
    .inline() // inline this button
    .build();

Button false = ButtonBuilder.createAnchorButton("False")
    .inline() // inline this button
    .build();

It generates the following markup.

<a href="#" data-role="button" data-inline="true">True</a>
<a href="#" data-role="button" data-inline="true">False</a>

Assigning a button theme

Buttons can be manually assigned any of the button color swatches from the theme to add visual contrast with their container by adding the data-theme attribute on the button markup and specifying a swatch letter. When a link is added to a container, it is automatically assigned a theme swatch letter that matches its parent bar or content box to visually integrate the button into the parent container, like a chameleon.

These are the different default possibilities (theme A, B, C, D, E).

In Whizu it's done like this.

Button cancel = ButtonBuilder.create()
    .title("Cancel")
    .theme(Theme.A) // set the button theme
    .build();

While this is the generated markup.

<a href="#" data-role="button" data-theme="A">Cancel</a>

Mini for smaller-sized buttons

For a more compact version that is useful in toolbars and tight spaces, add the data-mini=“true” attribute to the button to create a mini version.

Button cancel = ButtonBuilder.create()
    .title("Cancel")
    .mini() // make it a mini button
    .inline()
    .build();

This is the markup that will be generated by Whizu.

<a href="#" data-role="button" data-mini="true" 
    data-inline="true">Cancel</a>

Adding an icon to a button

Any of the following icons can be added to a button by adding a data-icon attribute.

Button placeOrder = ButtonBuilder.create()
    .title("Place order")
    .icon(DataIcon.CHECK) // set the icon
    .theme(DataTheme.B)
    .mini()
    .inline()
    .build();

Here's the generated markup.

<a href="#" data-role="button" data-mini="true" data-inline="true" 
    data-icon="check" data-theme="b">Place order</a>

Icon positioning

By default, all icons in buttons are placed to the left of the button text. This default may be overridden using the data-iconpos attribute to set the icon to the right, above (top) or below (bottom) the text. You can also create an icon-only button.

An example setting the icon on the right.

Button placeOrder = ButtonBuilder.create()
    .title("Place order")
    .icon(DataIcon.CHECK)
    .iconPosition(DataIconPosition.RIGHT) // set the icon position
    .theme(DataTheme.B)
    .build();

Here's the generated markup.

<a href="#" data-role="button" data-icon="check" 
    data-iconpos="right" data-theme="b">Place order</a>

Icon-only buttons

Any of the available button types has the possibility to only show an icon and hide the title. You can create an icon-only button by setting the data-iconpos attribute to notext. The button plugin will hide the text on-screen, but add it as a title attribute on the link to provide context for screen readers and devices that support tooltips.

Here's how to do it in Whizu.

Button delete = ButtonBuilder.create()
    .iconOnly(DataIcon.DELETE)
    .title("Delete") // optional
    .inline()
    .build();

The generated markup is the following.

<a href="#" data-role="button" data-icon="delete" 
    data-iconpos="notext" data-inline="true">Delete</a>

Corners and shadows

There are options for making the corners square instead of rounded (data-corners), for dropping the button shadow (data-shadow), and for dropping the icon shadow (data-iconshadow) for the highlight under the icon disc.

Here's how to do it in Whizu.

Button defaultButton = ButtonBuilder.create()
    .title("Default")
    .build();

Button squareButton = ButtonBuilder.create()
    .title("No rounded corners")
    .square() // make the corners square
    .build();

Button noShadow = ButtonBuilder.create()
    .title("No button shadow")
    .noShadow() // drop the button shadow
    .build();

Button noIconShadow = ButtonBuilder.create()
    .title("No icon disc shadow")
    .noIconShadow() // drop the icon disc shadow
    .build();

Disabling buttons

Form input or buttons can be disabled via the disabled attribute. Links styled like buttons have all the same visual options as true form-based buttons, but aren't part of the button plugin so the form button methods (enable, disable, refresh) aren't supported. If you need to disable a link-based button (or any element), apply the disabled class ui-disabled yourself with JavaScript to achieve the same effect.

In Whizu it's very simple. It's done the same way for all button types.

Button anchor = Button.create()
    .title("Disabled anchor via class")
    .disable() // disable this button
    .build();

Button button = Button.createButton()
    .type(ButtonType.BUTTON)
    .title("Button with disabled attribute")
    .disable() // disable this button
    .build();

Button input = Button.createInputButton()
    .title("Input with disabled attribute")
    .disable() // disable this button
    .build();

It generates the following markup.

<a href="#" data-role="button" class="ui-disabled">
    Disabled anchor via class</a>
<form>
    <button disabled="">Button with disabled attribute</button>
    <input value="Input with disabled attribute" disabled="" 
        type="button">
</form>

Javadoc API reference

The core classes and interfaces involved in creating jQuery Mobile buttons are the following.

Some related API's include:

Written by Rudy D'hauwe | Copyright © 2013 | All rights reserved.