Home plugins

Creating home plugins

You know how to write small pieces of code, and you want to extend the Appsi home screen with something you'd like to have in there?

You are in luck today!

All new are home screen plugins. The home screen is a new page in Appsi that you can use to add something you like. Examples are custom toggle buttons, custom buttons that start or open something specific, missed call count, unread message count or your own profile photo. You could also create a weather plugin, upcoming appointment plugin, or anything that fits in one of the defined fields. And in case you ask nicely, I might also add a field of the type you'd like to use.

Appsi and the plugins include a few as well, and an example project is available on github. You can download the Home Plugins sample project from Google play to test it yourself.

For the most up to date information, always refer to the Github project.

How hard is it?

All you need is a jar file with the service you'll need to extend (right here). You'll need to declare this service in the AndroidManifest.xml of your project and set the proper intent filter. That's all!

Show me the code

You can dive into the code right here.

Here's some highlights of the code.

/**
 * This is called when Appsi needs to update a specific field. Fill the
 * bundle with the values that need to be displayed
 * @param builder
 * @param fieldId
 */

@Override
protected void updateBundleForField(FieldValues.Builder builder, int fieldId, int reason) {
    switch (fieldId) {
        case FIELD_DOWNLOADS:
            createDownloadsValues(builder);
            break;
        case FIELD_USER_PROFILE:
            createUserProfileValues(builder);
            break;
        case FIELD_TOGGLE_SAMPLE:
            createToggleValues(builder);
            break;
        case FIELD_MISSED_CALLS_COUNT:
            createMissedCallCountValues(builder);
            break;
        case FIELD_TETHERING_INFO:
            createWifiFields(builder);
            break;
        default:
            mDashClockHomeExtensions.get(fieldId).onUpdateData(builder);
    }
}

/**
 * Called when the service is created to setup the field you are using. Do not do complex computations
 * here. Simply register your fields.
 */
@Override
protected void onRegisterFields(FieldsBuilder builder) {

    builder.registerField(
        FIELD_DOWNLOADS, 
        HomeServiceContract.FieldsResponse.DISPLAY_TYPE_SIMPLE, 
        R.string.downloads, 
        R.drawable.ic_plugin_downloads, null);

    builder.registerField(
        FIELD_MISSED_CALLS_COUNT, 
        HomeServiceContract.FieldsResponse.DISPLAY_TYPE_MISSED_COUNT, 
        R.string.calls, 
        R.drawable.ic_logo_missed_calls, 
        null, 
        CallLog.CONTENT_URI.toString());

    builder.registerField(
        FIELD_USER_PROFILE, 
        HomeServiceContract.FieldsResponse.DISPLAY_PROFILE_IMAGE_STYLE,
        R.string.profile_image, 
        R.drawable.ic_logo_profile, 
        null);

    builder.registerField(
        FIELD_TETHERING_INFO, 
        HomeServiceContract.FieldsResponse.DISPLAY_TYPE_DASHCLOCK,
        R.string.wifi_info, 
        R.drawable.ic_plugin_tethering, null);

    int count = mDashClockHomeExtensions.size();
    for (int i = 0; i < count; i++) {
        int key = mDashClockHomeExtensions.keyAt(i);
        mDashClockHomeExtensions.get(key).onInitialize(builder);
    }
}

These are the two key functions to implement.

The first call, updateBundleForField, is called when Appsi wants new values for a field. All you need to do is fill the bundle with the proper values.

There are five types of fields:

DISPLAY_TYPE_SIMPLE, this is a normal looking field with a text and an image.
DISPLAY_PROFILE_IMAGE_STYLE, room for a photo and multiline text.
DISPLAY_TYPE_TOGGLE_STYLE, use this if you want to create a toggle button.
DISPLAY_TYPE_MISSED_COUNT, like simple but shows an additional number on the right.
DISPLAY_TYPE_DASHCLOCK, easiest for porting DashClock Extensions.

You use these to register your plugin in Appsi. It gives Appsi some basic information and tells it it's dependencies. Then when the method updateBundleForFields is called, you need to use the builder to update the field values. These values include:

The text in the field
The (left) image in the field
The amount to display for DISPLAY_TYPE_MISSED_COUNT fields
The color and the alpha state for fields with type DISPLAY_TYPE_MISSED_COUNT
A pending intent to call when the field is tapped

For a full overview see checkout the sample project on Github.

By Nick Martens

AppsiHomePlugins-b2.apk

(19k)

Nick Martens,

Aug 27, 2013, 1:58 AM

v.3

javadocs.zip

(44k)

Nick Martens,

Aug 29, 2013, 5:27 AM

v.2

Comments

	Search this site