I'm a little worried that XExtensionItemSource is a little bit confusing/difficult to use for newcomers. Normal users might not be familiar with what a "placeholder item" is or why it's here.

It seems confusing that you can initialize an XExtensionItemSource with an attachments array or use the registerItemProvidingBlock: method and what the difference is between those things. And how are people supposed to understand how attributedContentText ties into those things? I worry that you have to be an expert in how UIActivityItemSource/NSExtensionItem/NSItemProvider work in order to use this API.

Compare that to UIActivityViewController, which (in the simple case) is easy as can be - literally just pass it whatever object you want. I wonder if we should be trying to offer a slightly higher-level API that abstracts away a few of these things. Particularly the placeholder item, the attachments array, and the attributedContentText/attributedTitle properties. I think that attributedTitle and subject are fundamentally the same concept and could be easily merged (since the activities that use subject never use attributedTitle)

Working on ideas for alternatives.

Mutability should be avoided. A great way to provide an easy-to-use object creation API is by using the builder pattern.

Unfortunately, many Objective-C developers seem adverse to using builders. As such, the first version of this library includes the XExtensionItemMutableParameters subclass, which allows one to create an XExtensionItemParameters instance without using its initializer (which takes a large number of arguments).

I'd prefer a builder but want this library to be as approachable as possible. The introduction of a builder class means XExtensionItemMutableParameters would be deleted altogether, and XExtensionItemParameters's large initializer would be made private. The only way to get an instance would be to use the builder object and then call build at the end.

https://github.com/tumblr/XExtensionItem/issues/32

Rewriting the README to incorporate all of the API changes. I’d absolutely love your feedback on how we can make this more comprehensive yet as approachable and clear as possible.

Some links may be broken until the Carthage PR is merged; I’ll handle that once it’s in.

There’s also a link to a wiki page which I’ve yet to write. This’ll happen tomorrow.

@arix @mattbischoff @prendio2 @padraigk

Adds hooks for providing alternative items, subjects, and thumbnail images on a per-activity type basis. Addresses the following tickets:

• https://github.com/tumblr/XExtensionItem/issues/33
• https://github.com/tumblr/XExtensionItem/issues/35

I’m going to punt on updating the README for now since I want to do a bigger pass at rewriting it for 1.0.

Other requests which have been broken out into separate issues:

• https://github.com/tumblr/XExtensionItem/issues/40
• https://github.com/tumblr/XExtensionItem/issues/41

https://github.com/tumblr/XExtensionItem/issues/42

Diverge from the traditional pod lib create project structure in order to add first class framework support.

• XExtensionItem.xcodeproj in the root directory now has a framework target and the tests target.
• Example/XExtensionItemExample.xcworkspace contains a sample application and share extension, and pulls XExtensionItem in as a development pod

Also fixes a bug in XExtensionItem.m and updates the unit tests such that they will fail if it returns.

To test

• Verify that the framework target builds without any warnings or errors, and that tests all pass
• Verify that the sample application and share extension function as expected
• Verify that a sample project is able to consume XExtensionItem via Carthage
  • Clone the CarthageTest project locally (it won’t build until the following steps are completed)
  • brew install carthage
  • From the CarthageTest directory, run carthage update
  • Follow these instructions from the Carthage README
  • Verify that CarthageTest builds properly

Provide hooks for giving specific items to specific activities, instead of simply passing the same fully-populated NSExtensionItem everywhere (e.g. to send different representations to Twitter, Facebook, Mail.app, etc.)

I can think of three different ways to register alternative items off the top of my head (these methods would all be on XExtensionItemSource:

@implementation XExtensionItemSource

...

// Simplest – just provide a value that should be used in place of the default `NSExtensionItem` if a specific activity is picked
- (void)registerItem:(id)item forActivityType:(NSString *)activityType;

// More complex – provide a block that returns a value, to avoid necessarily creating values for activities that may never be selected
- (void)registerItemProvider:(void (^)())itemProvider forActivityType:(NSString *)activityType;

// Most flexible – provide an object that determines what item should be returned for an activity type

@property (nonatomic) id <XExtensionItemProvider> alternativeItemProvider;

@end

@protocol XExtensionItemProvider

- (id)itemForActivityType:(NSString *)activityType;

@end

Usage would look something like:

[itemSource registerItem:twitterLengthSummaryString forActivityType: UIActivityTypePostToTwitter];

[itemSource registerItemProvider:^{
    // Lazily compute the Twitter-specific summary
    return twitterLengthSummaryString;
} forActivityType: UIActivityTypePostToTwitter];

@implementation MyAppCustomActivityItemProvider <XExtensionItemProvider>

- (id)itemForActivityType:(NSString *)activityType {
    if (activityType == UIActivityTypePostToTwitter) {
        return self.twitterLengthSummaryString;
    }

    // Returning `nil` would mean the activity/extension gets the default `NSItemProvider` instead of something special
    return nil;
}

@end

itemSource.alternativeItemProvider = [[MyAppCustomActivityItemProvider alloc] init];

I feel like @arix will have opinions on this one.

Related: https://github.com/tumblr/XExtensionItem/issues/49

We should be able to lazily provide items that don’t match the placeholder’s type, in order to e.g. provide a GIF if the message activity is selected. This requires using our function to calculate the item’s type rather than the type identifier that was provided when the item source was initialized.

The only other place where self.typeIdentifier was being used was in the UIActivityItemSource protocol’s activityViewController:dataTypeIdentifierForActivityType: method, but that seemed to be causing a problem due to the mismatch. I’ve removed it and everything seems to work fine.

Totally possible that I’m overlooking something here – please take a look through and let me know if you think this is necessary for some reason.

Talk with @chrismaddern to make sure we’re on the same page with regards to which parameters apps should use to attribute themselves.

Here’s what we have so far: https://github.com/tumblr/XExtensionItem/blob/master/XExtensionItem/XExtensionItemSourceApplication.h

As per @prendio – allow a default subject to be provided rather than explicitly registering subjects for individual activity types using the registerSubject:forActivityType: method added in this pull request.

(This isn’t particularly pressing since there isn’t public API for extensions to read this value, and only Mail and Messages support subjects out of the built-in activities (which only change once a year, at most), but we only just realized that the latter does yesterday, so who knows what else we could potentially be missing?)

A couple of options:

• Use the attributedTitle value if it exists and a subject was not explicitly registered for a given activity type
• Add a @property (nonatomic, copy) NSString *defaultSubject; property
• Document that calling registerSubject:forActivityType: with a nil activity type will register it as the default. I think I like this one the best.

Thoughts?

:rage::rage::rage::rage::rage::rage::rage::rage::rage::rage::rage:

Thanks to @prendio2 for catching this one. While some system activities do know how to consume NSExtensionItem input, others like Mail and Messages do not. Passing an NSExtensionItem to these doesn’t result in any data making its way through.

Unfortunately I don’t know a better way to handle this other than to deduce (via trial and error) which activities can support extension item input, and pass the placeholder object to the ones that can’t.

This PR to add more UIActivityItemSource hooks makes these changes a lot easier to swallow, in my opinion, even though this still sucks. I definitely need to radar this.

CC: @mattbischoff @arix

Is two Xcode projects confusing? @twigz seems to think so. The arguments I can remember him making:

1. It’s not the default from pod lib create
2. If you’re working on the library in the normal code → test your code in the sample app workflow, it’s more difficult to run the unit tests.

:warning: Preliminary thoughts! Please take this with a grain of salt as I haven’t thought about it for long enough to feel like I have my head fully wrapped around it. :warning:

To try and determine what modifications we may want/need to make to XExtensionItem in the short term, I think it’s worthwhile to consider how we’d want the library to function if we only needed to support iOS 9.

XExtensionItem for iOS 8 has two goals:

• Support multiple attachments (obviated by iOS 9)
• Support metadata parameters (still useful on iOS 9)

Therefore, XExtensionItem usage on iOS 9 only could look something like the following:

// Application

// `XExtensionItem` no longer wraps your attachments, instead it’s just an additional metadata object
[[UIActivityViewController alloc] initWithActivityItems:
 @[@"Apple homepage", [NSURL URLWithString:@"http://apple.com"], xExtensionItemSource] 
                                  applicationActivities:nil]

// Extension

// Rather than treat *every* item as something that can be wrapped by an `XExtensionItem`, just specifically look to see if one was passed in
for (NSExtensionItem *item in self.extensionContext.inputItems) {
    if ([XExtensionItem isXExtensionItem:item]) {
        XExtensionItem *xExtensionItem = [[XExtensionItem alloc] initWithExtensionItem:item];
        // Access tags, app attribution, custom application parameters, etc.
    }
    else {
        // Process regular, non-XExtensionItem item
    }
}

Ideally, we’d release what we currently have (let’s call it 1.0) and add a section to the README documenting how we envision the library changing in order to eventually better support iOS 9 exclusively. Then at some point we cut a new release for developers who only support 9 (let’s call this 2.0), and those who continue to support 8 can just use the older version.

But the problem here is interoperability. An application that uses XExtensionItem 1.0 (e.g. provides a single XExtensionItem instance as their lone activity item) wouldn’t be compatible with an extension that uses 2.0 (I need to think about it a little more but I think an app that uses 2.0 will still work just fine with an extension that uses 1.0).

How can we resolve this? It seems as though modifying the extension-facing API to support both types of input is the most future-proof course of action. Otherwise, we’d have to either:

• Go iOS 9 only and not be useful to anyone who needs to support iOS 8 for a while still (bad option, almost no one will use this)
• Forget about changing the library in the future to better mesh with how activity items work in a post-iOS 9 world (makes this library very useful in the short term but more annoying to use than it needs to be post-iOS 9)

@mattbischoff @prendio2 @AriX

The more I think about this, the more I think we would actually want to be able to key titles off of activity types, if we’re going to use them as the subject that the UIActivityItemSource provides. I realized this by sharing from the Tumblr app to the Tumblr extension and realizing that our subjects written specifically for email don’t translate well to quote posts or link posts, where we consume the title field in our extension.

You can return an NSData instance but there’s no way to specify a type identifier that differs from the one that the XExtensionItemSource was initialized with.

It would just pass a single item through rather than providing any of the benefits, but at least would make it easier for apps that still support iOS 7 to simply drop XExtensionItem in.

Add this back to the .travis.yml file:

- pod lib lint --quick

Once this command actually looks for JSON podspecs (https://github.com/CocoaPods/CocoaPods/issues/3477)