search

MattMcFarland / com.mattmcfarland.fontawesome

Font Awesome meets Appcelerator Titanium Alloy
GNU General Public License v2.0
78 stars 23 forks source link

readme

MattMcFarland/com.mattmcfarland.fontawesome API Documentation

Font Awesome Ti.Widget 1.7.3

OMG! It's the Offical Font Awesome 4.7.0 by Dave Gandy for Titanium Alloy!

This is a widget for the Appcelerator Alloy MVC framework which provides easy implementation of the Offical Font Awesome icons found at fontawesome.io.

Before you submit an issue, be sure to check out the FAQ section.

Overview

Features

Working Example

Imgur

Quick Start

"dependencies": {
    "com.mattmcfarland.fontawesome":"1.7.3"
}

Alloy

<Alloy>
    <Window title="Tab 1">
        <Label icon="fa-car">I am Window 1</Label>
        <Widget id="fa" src="https://github.com/MattMcFarland/com.mattmcfarland.fontawesome/raw/master/com.mattmcfarland.fontawesome"/>
    </Window>
</Alloy>

That's it. You simply add your Icons in a very similar way we do it with HTML 5.

<Label icon="fa-glass"></Label>

Titanium

    var fa = Alloy.createWidget("com.mattmcfarland.fontawesome");
    win.add(fa);

Using Titanium API with Javascript to add icons on the fly:

$.fa.add(MyLabel,'fa-star');

Documentation

As of version 1.1.1, Font Awesome Ti.Widget code is heavily documented. If you are planning on using additional functionality or customization please review the docs at http://mattmcfarland.github.io/com.mattmcfarland.fontawesome

Working with the widget

Click here to review the methods / properties for the widget.

Creating your own Icons

Click here to review the icons.js object.

Customization

As of version 1.2.0, customization has been implemented. You may use a different font-based icon character map with different widgets. For example, you could use glyphicons or different versions of fontawesome

Enabling debugMode

When customizing the Font Awesome Ti.Widget API, it is recommended to enable debugMode:

    $.fa.debugMode = true;

Using "iconPosition" property

By default we "prepend" any text/title value with the icon but you might want to "append" the icon instead.

XML:

<Label icon="fa-search" text="Search" id="searchLabel" />

TSS:

"#searchLabel": {
    font : {
        iconPosition : "append", // Default value is "prepend"
    }
}

Using custom icons

To add your very icon character map from a font-file:

  1. Copy your fontfile into your assets/fonts directory.

  2. Make sure the name of the font file and the system name of the font file match.

    • For IOS - Titanium SDK looks for the system name of the font file
    • For ANDROID and MOBILE WEB - Titanium SDK looks for the file name without the ext (.ttf)
    • This is why FontAwesome.ttf is the same as FontAwesome, the system name is FontAwesome, file name is FontAwesome.

For more information, checkout the Titanium SDK documentation regarding adding fonts: http://docs.appcelerator.com/titanium/3.0/#!/guide/Custom_Fonts

  1. Follow the same example found in /com.mattmcfarland.fontawesome/lib/icons.js to create the same font array map.

You MUST use the "fa-" prefix. You could do something like fa-myfont-star if you wish.

  1. Place your custom icons.js file in /assets/lib/ and use require to assign them to any widget.

  2. Apply your custom fonts to a widget instance like so:

    $.fa.icons = require('new_icons');

Extended Methods

Once you add an instance of the widget to a view, you may use the API methods to add/remove/change icons.

For more information please review the docs: http://mattmcfarland.github.io/com.mattmcfarland.fontawesome

Methodology

Knowledge is Power...

The widget was designed so at a very basic level it works right out of the box. Meaning, all you have to do is add a proper icon property to any view and it works. But not in all cases, so the purpose of this section is to explain how it works so you can have a better understanding and control over the widget and how it operates.

Once you create a Font Awesome Ti.Widget it immediately parses the view it is added to for other Ti.UI.View objects. The scope of this query is limited to the widget's siblings and it/their children views (and grand children and so on).

As of version 1.2.0, you can disable the initial parser by adding the property instaParse to false (eg: <Widget instaParse = "false" ...), then use the refresh method to parse when you are ready.

The Font Awesome Ti.Widget then applies icons to every instance of a Ti.UI.View object that has an icon property with a fa- prefix. Because MobileWeb, Android, and IOS handle View objects (such as Label, Button, Row, etc) differently, you may have to create blank labels just for icons for optimal compatibility.

Additional methods such as add, remove, change are available for use with a widget instance so you can have additional control. Refer to the documentation for the comments in widget.js for more information.

FAQ

Q: Where does it place the icon?

A: If you add it to a Label with text, it appears before the text. If you want to put it after the text, or anywhere else, you can simply just add it as a seperate label like so: <Label icon = "fa-users"/>

Q: Where is the reference guide/cheat sheet for these icons?

A: You can find a complete list of all icons and their names at fontawesome.io/icons

Q: Are there any compatibility issues?

A: Android requires putting the icon inside the app's asset folder, and Mobileweb does not allow for text+icon sharing.

Q: Why can't I see icons in my Listview/Tableview?

A: Currently, this widget does not work well with auto-generated content, such as Listview, TableView and alike. While setting the icon property does not work, the combination of setting the text property to the unicode character and the fontFamily to FontAwesome does work:

XML:

<!-- breaks in listview -->
<Label icon="fa-search"></Label>

<!-- still works in listview -->
<Label class="search-icon"></Label>

TSS:

".search-icon": {
    text : "\uf002",
    font : {
        fontFamily : "FontAwesome",
    }
}

Q: What if I'm using icon for something else?

A: FontAwesome Widget will only pay attention to the icon property value using the fa- prefix.

Q: What to do if I can't get it to work?

A: Please use the issues tab on the right, this way we can publically fix your issue and hopefully fix it for others who may run into the same problem in the future.

Q: Do I need to put it inside every <View> tag??

A: The widget will automatically parse its siblings/children for icon properties with fa- prefix. For optimum efficiency, you should only apply the widget to these areas.

Q: Who made these Awesome Icons???

A: The Icons themselves were created by Dave Gandy, the Font in which they populate is under the SIL OFL 1.1 License. It's free for commercial use!

Q: I've seen another FontAwesome on Titanium's Marketplace for $5, is this the same?

A: Not the same at all, the other one is using an older version of Font Awesome, has a few proprietary fonts mixed in, and was made for Titanium, not Alloy.

License

Font Awesome

Created by Dave Gandy

FontAwesome.ttf is licensed under SIL OFL 1.1

Titanium Alloy Widget

Created by Matt McFarland and Licensed under GPL

Changelog

Version 1.7.3

Version 1.7.2

Version 1.7.1

Version 1.7.0

Version 1.6.1

Version 1.6.0

Version 1.5.1

Version 1.5.0

Version 1.4.1

Version 1.4.0

Version 1.3.0

Version 1.2.0

Version 1.1.1

Version 1.1.0

Version 1.0.1-3

Version 1.0.0