Button widget

This widget for the Appcelerator Titanium Alloy MVC framework provides a view that mimics Ti.UI.Button, but with more flexible styling and support for icon fonts.

The repository

The repository contains two branches. This master branch contains the widget. The other test branch has a complete Titanium Alloy demo/test project.

Quick Start

Get it

Download this repository and consult the Alloy Documentation on how to install it, or simply use the gitTio CLI:

$ gittio install nl.fokkezb.button

Use it

• Require the widget in a view:

<Widget src="nl.fokkezb.button" onClick="myCallback" icon="icon-on" title="My title" style="ios" />`

If you want to use icons:

• Specificy the font family to use via iconFont.
• Specificy the icon to use via icon. You probably have to give a unicode. Take a look at the demo to see how I use the fa.js generated by FontAwesomeJS to map icon names to unicodes.
• Follow the Custom Fonts guide to add a custom font to your app.

See the reference way down this document for all available properties.

Pre-defined styles

The widget comes with pre-defined styles that can be applied to a button just the style property, either in <Widget /> or via TSS.

For example:

<Widget src="nl.fokkezb.button" title="Primary" style="bs-primary" />

Style	Example	Description
ios		Like Ti.UI.Button on iOS
bs-default		Twitter Bootstrap's default button
bs-primary		Twitter Bootstrap's primar button
bs-info		Twitter Bootstrap's info button
bs-success		Twitter Bootstrap's success button
bs-warning		Twitter Bootstrap's warning button
bs-danger		Twitter Bootstrap's danger button
bs-inverse		Twitter Bootstrap's inverse button
bs-link		Twitter Bootstrap's link button

Adding styles and setting the default

Add styles by requiring the widget's styles-lib in your app's alloy.js and use the set() method to set (or override) a pre-defined style like this:

var Styles = require('nl.fokkezb.button/styles');
Styles.set('my-style', {
	borderWidth: 1,
	borderColor: '#000',
	backgroundColor: '#ccc',
	activeStyle: {
		backgroundColor: '#000',
		color: '#fff'
	}
});

The lib also exposes has() and get(). Use the latter to get and extend an existing style before overwriting it using set().

You can also set the default style to be used for any button that doesn't specify a style itself. On iOS the ios style is the default. Change it in your app's alloy.js like this:

var Styles = require('nl.fokkezb.button/styles');
Styles.setDefault('bs-default');

An example can be found in the demo app's app/alloy.js file.

TSS styling

Of course you can also style the widget like any other view using the TSS file of the controller-view where your require the widget. Just set a class or id to the <Widget /> and style it like this:

"#myButton": {
	borderWidth: 1,
	borderColor: '#000',
	backgroundColor: '#ccc',
	activeStyle: {
		backgroundColor: '#000',
		color: '#fff'
	},
	iconFont: 'FontAwesome',
	icon: Alloy.Globals.fa.powerOff
}

Run-time styling

You can use $.myId.applyProperties() to apply any new properties to the widget after it has been automatically initialized:

$.myId.applyProperties({
	color: 'red'
});

Event listeners

Listen to the click-event like you would do with a regular button.

Either in <Widget />:

<Widget onClick="myCallback" title="My title" id="myId" />

Or in the requiring controller:

$.myId.addEventListener('click', myCallback);

The callback receives an Object containing 2 properties:

• type: Always click.
• bubbles: Always FALSE.
• source: The widget's main controller, including all non-object properties defined via XML or TSS.

An example can be found in the demo app's app/controllers/index.js file.

Since 1.3, when listening to a parent of the button, the e.source will also contain all non-object properties defined for the widget via XML or TSS.

Property reference

To understand what properties are available and what they do, you need to understand how the button is constructed. The next illustration shows the outer (purple), inner (red), icon (blue) and title (green) elements and where padding and spacing is applied.

Widget-specific properties

Titanium-common properties

Public interface

Ideas for improvement

Feel free to help me improve this widget by forking and submitting pull requests or issues with more ideas. Here's my whishlist:

• Add more custom and run-time style examples to the 4th demo app tab.
• Add more iOS button styles, like those in the navigation bar.
• Add several Android system styles.
• Add Foundation and other well-known button styles.
• Add 'system' style that picks the right iOS or Android system style.
• Support more icon fonts.
• Support focusStyle for Android.

Changelog

• 1.4 BREAKING: For font icons you now have to give the unicode, no longer supports names!
• 1.3 Exposing creation properties via e.source. Fixed Android pass throughs.
• 1.2.2 Fixed iconSize not being retained. Added bubbleParent.
• 1.2.1 Fixed icon-bug, added new setters and getters
• 1.2 Added image icons, titleid, setStyle, backgroundImage, textAlign, verticalAlign
• 1.1 Added iconSize, setTitle, setIcon
• 1.0 Initial version

Licenses

This project is licensed under the Apache Public License (Version 2). Please see the LICENSE.txt file for the full license.

The Font Awesome font is licensed under the SIL Open Font License. The Font Awesome pictograms are licensed under the CC BY 3.0 License. Attribution is no longer required in Font Awesome 3.0, but much appreciated.

You can get Ligature Symbols for free. This Font is licensed under the SIL Open Font License for download and using. Ligature Symbols has broad support for the modern browser (Chrome, Safari, Firefox, iOS - Mobile Safari, Android Browser).

Appcelerator, Appcelerator Titanium and associated marks and logos are trademarks of Appcelerator, Inc.

Titanium is Copyright (c) 2008-2012 by Appcelerator, Inc. All Rights Reserved.

Titanium is licensed under the Apache Public License (Version 2). Please see the LICENSE file for the full license.