Archived

This repository has been archived in favor of a new single repository located here.

Overview

Locale allows developers to create plug-in conditions and settings through the Locale Developer Platform. Interaction between Locale (host) and plug-ins (client) occurs via an Intent-based API. This repo contains an SDK that implements the host functionality defined by the Intent-based API. Although there are multiple ways to approach building a plug-in host, we recommend starting with this SDK layer.

API Reference

JavaDocs for the library are published here.

Compatibility

The SDK is compatible and optimized for Android API Level 9 and above. Note, however, consuming the SDK requires at least Android Gradle Plugin 1.3.0. (This is due to a manifest placeholder in the AAR's manifest.) For backwards compatibility, there are support-v4 versions of the Fragment and Loader classes in the SDK.

Download

Gradle

The library is published as an artifact to jCenter. To use the library, the jCenter repository and the artifact need to be added to your build script.

The build.gradle repositories section would look something like the following:

repositories {
    jcenter()
}

And the dependencies section would look something like this:

dependencies {
    compile group:'com.twofortyfouram', name:'android-plugin-host-sdk-for-locale', version:'[2.0.3,3.0['
}

Contributing

The Continuous Integration setup is using Firebase Test Lab. If forking this project, provide your own Firebase Test Lab service account and provide the necessary environment variables.

Creating a Host

The Locale host SDK offers a simplified way to implement an application that can host plug-ins. The host has three primary responsibilities with regards to plug-ins: 1. discovering plug-ins, 2. editing plug-in instances, and 3. executing plug-in instances.

A plug-in app is represented by Plugin. The data that the plug-in saved after editing is represented by PluginInstanceData.

Discover

The PluginRegistry scans for installed plug-ins, which are represented by Plugin. A host UI would most likely interact with the PluginRegistry through the PluginRegistryLoader or SupportPluginRegistryLoader.

Edit

The host's UI displays to the user the Plugins that were discovered, using Plugin.getActivityLabel() and Plugin.getActivityIcon() to get human-readable information about the plug-in.

To edit a Plugin, the host instantiates a subclass of AbstractPluginEditFragment or AbstractSupportPluginEditFragment. AbstractPluginEditFragment takes care of launching the plug-in's "edit" Activity, processing the Activity result, serializing the plug-in's Bundle into a persistent form, and delivering a callback to subclasses via handleSave(PluginInstanceData).

Execute

The host fires PluginInstanceData to a plug-in, via one of the two controller objects Condition or Setting.

PluginInstanceData has getters for getType() and getRegistryName(). Those two getters provide the keys necessary to look up the associated Plugin from the PluginRegistry, enabling the host to instantiate Condition or Setting.

History

• 1.0.0: Initial release
• 2.0.0: Update transitive dependency on plug-in-client-sdk-for-locale to a major new version. Although the host SDK APIs didn't change, the dependency change could break downstream clients hence a major new version.
• 2.0.1: Fix state management of AbstractPluginEditFragment and AbstractSupportPluginEditFragment. Fix PluginPackageScanner bug detected by lint.
• 2.0.2: Fix detection of changing plug-ins after initial scan.
• 2.0.3: Fix compatibility with AAPT2 in Android Gradle Plugin 3.0.0-alpha2.