Skip to content

Custom Parameters Guide

Jump to bottom
Bryan Irace edited this page May 15, 2015 · 1 revision

XExtensionItem provides a way for extension developers to make it easy for applications to pass custom metadata to your share extension.

To give an example, the Tumblr share extension accepts custom parameters that allow applications to optionally specify:

  • Which type of post should be created
  • What the post’s custom URL path should be (e.g. the “pancakes” in http://bryan.io/post/116820149416/pancakes)
  • A Tumblr API consumer key (we use this to provide attribution, linking back to your application from the created post)

Adding custom parameters to XExtensionItem

To add custom parameters to XExtensionItem, simply follow these steps:

  • Fork the XExtensionItem repository

  • Create a new directory under XExtensionItem/Custom, e.g. XExtensionItem/Custom/Tumblr

  • Create a new class in this directory that conforms to XExtensionItemCustomParameters, e.g. XExtensionItemTumblrParameters

    • To conform to this protocol, your class will need to be serializable to and deserializable from an NSDictionary. XExtensionItemTypeSafeDictionaryValues is a helper class that makes it easier to implement initWithDictionary: in a type-safe fashion.

Your class will look something like this:

@interface XExtensionItemYourServiceParameters <XExtensionItemCustomParameters>

@property (nonatomic) NSString *someCustomParameter;

@end
  • Add a new subspec to the Podspec, e.g. XExtensionItem/Tumblr. By default, all custom parameter classes are imported by applications that use XExtensionItem, but these subspecs allow application developers to pick and choose if they’d prefer to only import some.
{
  "name": "YourService",
  "source_files": "XExtensionItem/Custom/YourService/*.{h,m}",
  "dependencies": {
    "XExtensionItem/Core": []
  }
}
  • Update the module map. This is conceptually similar to subspecs but intended for developers who use the framework directly (e.g. via Carthage), rather than through CocoaPods.
// Exclude your custom file from the “core” module
exclude header "XExtensionItemYourServiceParameters.h"

// Add a new module for your custom file
explicit module YourService {
  header "XExtensionItemYourServiceParameters.h"
}

Add an integration guide

In addition to adding custom parameters, it can be helpful to document exactly how your extension consumes the attachments and generic parameters that are built-in to XExtensionItem. Here’s an integration guide example for Tumblr.

If you write up a guide for your extension, please create an issue and we’ll be happy to add it.

Consuming custom parameters in your share extension

The custom parameters are stored in an XExtensionItem instance’s userInfo dictionary. Since your custom parameters class has an initializer that takes a dictionary, it’s easy to get your custom parameter values out of an extension item:

@implemention YourExtensionViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    for (NSExtensionItem *inputItem in self.extensionContext.inputItems) {
        XExtensionItem *extensionItem = 
            [[XExtensionItem alloc] initWithExtensionItem:inputItem];

        XExtensionItemYourServiceParameters *yourCustomParameters = 
            [[XExtensionItemYourServiceParameters alloc] initWithDictionary:
             extensionItem.userInfo];

        NSString *someCustomParameter = yourCustomParameters.someCustomParameter;
    }
}

@end
Clone this wiki locally