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 app branch has a complete Titanium Alloy demo project, including the widget as submodule and some optional external libs and assets:

app/lib: The IconicFont lib folder, required for using icons.
app/assets/fonts: Thef Font Awesome font folder - one of the three icon fonts supported by IconicFont.

Quick start

How to use this widget in your own project?

Download the latest release of the widget.
Copy app/widgets/nl.fokkezb.button to your app's app/widgets folder.
Add the widget as a dependency to your app's app/config.json file:

"dependencies": {
	"nl.fokkezb.button": "1.3"
}

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:

Download the latest version of IconicFont.
Copy Resources/lib/IconicFont.js and one or more of the (non deprecated) icon font libs to your app's app/lib folder.
Download the Font Awesome, LigatureSymbols or one the commercial Symbolset SS Pika .tff files to your app's app/assets/fonts folder.
Follow the Custom Fonts guide's Additional iOS steps.

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'
	}
}

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

Property	Type	Purpose
enabled	Boolean	If `false`, the disabledStyle will be applied and no events are triggerd
title	String	Optional text for the title of the button
titleid	String	Optional textid for an internationalized title of the button
icon	String	Optional icon font name (e.g. `icon-lightbulb`) or file name
iconFont	String	One of IconicFont's lib's (without `.js`). Defaults to `FontAwesome`.
iconSize	Number	Font size for the icon, overruling the button fontSize
iconPosition	String	Positions the icon to the `left` (default) or the `right` of the title
padding	Number/String/Object	Padding between the outer and the inner. Either pass one dimension, a list of 1 to 4 dimensions or an object containing one of `top`, `right`, `bottom` and `left` as keys and their dimension as values. Don't use padding if you specify a width and height and want the inner to be centered in the outer.
spacing	Number/String	Spacing between the icon and the title
style	String	Pre-defined style to load before applying any of the common properties in the next table.
activeStyle	Object	Object containing any of the common properties listed in the next table that will be applied while the user presses the button.
disabledStyle	Object	Object containing any of the common properties listed in the next table that will be applied if the button is not enabled.

Titanium-common properties

Property	Type	Applied to	Comments
width, height	Number/String	outer
top, right, bottom, left	Number/String	outer
center	Point	outer
borderWidth	Number/String	outer
borderColor	String	outer
borderRadius	Number/String	outer
backgroundColor	Number/String	outer
backgroundGradient	Gradient	outer
backgroundImage	String	Outer
backgroundTopCap	Number	Outer
backgroundLeftCap	Number	Outer
backgroundRepeat	Boolean	Outer
color	String	title, icon
shadowOffset	Object	title, icon
shadowColor	String	title, icon
font	Font	title, icon	For the icon, `font.fontFamily` is ignored and `font.fontSize` can be overrulled by `iconSize`
textAlign	String	title	Only when width is set
verticalAlign	String	title	Only when height is set
opacity	Number	outer
visible	Boolean	outer
bubbleParent	Boolean	outer

Public interface

Method	Description
applyProperties()	Main method for setting up and changing the button
show()	Shows button
hide()	Hides button
setIcon([icon], ]iconFont])	Changes the icon
getIcon()	Returns an `{ icon:, iconFont }` object
setTitle(title)	Changes the title
getTitle()	Returns the title
setTitleid(titleid)	Changes the titleid
getTitleid()	Returns the titleid
setStyle(style)	Applies the style
getStyle()	Returns the style name
addEventListener(event, callback)	Attaches event listener
removeEventListener(event, callback)	Removes event listener
fireEvent(event, dictionary)	Fires event on the button
id	Holds the `id` of the widget, so you have this in events

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.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 licensed under the Apache Public License (Version 2). Please see the LICENSE file for the full license.

RuudBurger / nl.fokkezb.button