Contributing new Adium plugin?

[Peter Schmitt]

Hi all,

TL;DR: I'd like to contribute a new plugin, what do I do?

About a year ago I wrote an Adium plugin for Quicksilver that provides Adium contacts to the catalog and allows "open chat" actions on them. To make it work I had to fix some bugs in Adium as well as add some features. Those patches were then released as part of Adium 1.5 so now I'd like to publish the Quicksilver plugin as well. I've attached the files so you can take a look.

What are the steps required to get a plugin repository as part of the Quicksilver github project? And how does the plugin show up in the official plugin list?

Cheers,

Peter

PS: I noticed that there seems to be code for another Adium plugin in Quicksilver - not sure if that one is still active and would conflict with my contribution?

[Rob McBroom]

On Oct 17, 2012, at 4:16 PM, Peter Schmitt <ara...@gmail.com> wrote:

TL;DR: I'd like to contribute a new plugin, what do I do?

We love to hear that. I assume you know about the plug-in dev reference? If not you’ve done pretty well on your own.

http://projects.skurfer.com/QuicksilverPlug-inReference.mdown

About a year ago I wrote an Adium plugin for Quicksilver that provides Adium contacts to the catalog and allows "open chat" actions on them.

Hey, me too! :-) https://github.com/skurfer/Adium-qsplugin

To make it work I had to fix some bugs in Adium as well as add some features.

I wonder if you had the same problem I did. I described it in great detail (to absolutely no one, it seems) on the forums.

http://forums.cocoaforge.com/viewtopic.php?f=13&t=23929

That road-block was the reason I never finished/released mine. I noticed in the Adium release notes that there were some AppleScript related fixes. It seemed like they might be relevant to my issue, but I wasn’t sure and I never got around to testing with my plug-in. Anyway, it looks like you “cheated” and just used AppleScript. I was obviously trying to avoid that. :-)

Those patches were then released as part of Adium 1.5 so now I'd like to publish the Quicksilver plugin as well. I've attached the files so you can take a look.

Thanks. The main things would be

  * Take a look at the cleanup section in the plug-in ref. That’ll bring your plug-in in line with the current standard. http://projects.skurfer.com/QuicksilverPlug-inReference.mdown#plugin_cleanup_and_modernization

  * The original iChat and Adium plug-ins were implemented as “chat mediators”, which meant they provided the same functionality and users could specify which app should handle those tasks (under Handlers in the prefs). I think we should stick to that convention. Unfortunately, we don’t have the source for the Chat Support plug-in which defined the QSChatMediator protocol. But since it mostly just passes work off to other plug-ins, I think I can probably recreate it using clues from the old ones. I’ll hopefully be able to work on that tomorrow. If I do that, would you be willing to rework your plug-in to use the chat mediator protocol?

  * Since your plug-in has a different bundle ID vs. the original, it won’t replace old versions on people’s systems. You can either change the bundle ID to match, or specify that this plug-in makes the other obsolete. Details on that are in the reference under QSRequirements.

What are the steps required to get a plugin repository as part of the Quicksilver github project? And how does the plugin show up in the official plugin list?

The primary repo for most plug-ins is owned by the Quicksilver organization and individual devs fork them to make changes. But that’s not required. Some devs keep the main repo under their account. It’s up to you. I guess all we ask is that you keep it available so we can get the source if you ever abandon it.

As for getting listed in the app, just let us know when you think it’s ready and we’ll take a look. If we agree, we’ll publish it on qsapp.com.

PS: I noticed that there seems to be code for another Adium plugin in Quicksilver - not sure if that one is still active and would conflict with my contribution?

I’d call that dead, though it may have value in that it demonstrates how to set up a chat mediator.

Let us know if you have any questions.

-- 
Rob McBroom
<http://www.skurfer.com/>

[Patrick Robertson]

Great to hear of a new plugin, thanks Peter!

Just a few things to add to what Rob's said, although most of it is documented in the reference Rob linked to.

* In order to get a plugin published on QSApp.com, it must have some decent documentation. See here for more info: http://projects.skurfer.com/QuicksilverPlug-inReference.mdown#documentation_and_bltrversion

* Since the plugin only works with Adium 1.5+, it's probably worth adding a 'requirement' in the .plist so the plugin will only load for people who have Adium 1.5+

See the 'bundles (array)' subheading at http://projects.skurfer.com/QuicksilverPlug-inReference.mdown#qsrequirements

Other than that, the plugin looks great. Here's to hoping Rob can master a new Chat Support plugin/mediator and we can work on things from there!

(For an idea on what that means, take a look at the Mail Support plugin: https://github.com/quicksilver/elements.support.mail-qsplugin )

[Peter Schmitt]

Hi all,

thanks a lot for the feedback!

I wonder if you had the same problem I did. I described it in great detail (to absolutely no one, it seems) on the forums.

Looks like we had the same problems. :)

 

Anyway, it looks like you “cheated” and just used AppleScript. I was obviously trying to avoid that. :-)

Yes, those fixes to Adium's AppleScript were my doing. And while AppleScript is admittedly downright weird ObjectiveC isn't my favourite language either so I ended up going with the first thing that worked.

 

  * Take a look at the cleanup section in the plug-in ref. That’ll bring your plug-in in line with the current standard. http://projects.skurfer.com/QuicksilverPlug-inReference.mdown#plugin_cleanup_and_modernization

I've completed most of these steps, however the first one still mystifies me. What "Configuration" folder? And (probably because the folder is missing) I don't have a configuration "QSPlugin". This might be due to the fact that despite lots of attempts I never got the QSPlugin template to work. IIRC from the stuff I did a year ago things got complicated because the template structure in XCode changed with version 4.3 or so and I'm running 4.4. For example the directory "~/Library/Developer/Xcode/Templates/Application Plug-in" doesn't exist on my machine.

 

If I do that [reworking the mediator protocol], would you be willing to rework your plug-in to use the chat mediator protocol?

I can certainly look into it. I assume it supports the basic "add contact to catalog" and "open chat" functionality (besides other things)? Might take a while though since I'm often short on time. :)

 

It’s up to you. I guess all we ask is that you keep it available so we can get the source if you ever abandon it.

In that case would you mind if I put it up with svn on code.google.com? I know Subversion is a bit old fashioned but it's what I'm used to. :) Otherwise I'll make do with git although I'll have to figure out the details.

 

* Since the plugin only works with Adium 1.5+, it's probably worth adding a 'requirement' in the .plist so the plugin will only load for people who have Adium 1.5+

See the 'bundles (array)' subheading at http://projects.skurfer.com/QuicksilverPlug-inReference.mdown#qsrequirements

Thanks, that's useful!

Once I've resolved the couple questions above I'll push the updated plugin to a source repository and we can move it along from there.

Peter

[Rob McBroom]

On Oct 21, 2012, at 5:51 PM, Peter Schmitt <ara...@gmail.com> wrote:

Anyway, it looks like you “cheated” and just used AppleScript. I was obviously trying to avoid that. :-)

Yes, those fixes to Adium's AppleScript were my doing. And while AppleScript is admittedly downright weird ObjectiveC isn't my favourite language either so I ended up going with the first thing that worked.

OK. I still want to revisit it and see if it’s now possible to send a message to a contact (as opposed to an existing chat).

  * Take a look at the cleanup section in the plug-in ref. That’ll bring your plug-in in line with the current standard. http://projects.skurfer.com/QuicksilverPlug-inReference.mdown#plugin_cleanup_and_modernization

I've completed most of these steps, however the first one still mystifies me. What "Configuration" folder?

Sorry, I suppose that’s mostly aimed at cleaning up old plug-ins and not necessarily setting up new ones. :-) This should be more helpful:

1. Build Quicksilver (if you haven't recently) to create things in `/tmp/QS`

2. Right-click your project and add files

3. Choose `/tmp/QS/Configuration`

4. Don't copy items, do create groups for added folders, and don't add to the target

5. Select “Configuration” in the project and open the File Inspector on the right (⌥⌘1)

6. Change the path to “Absolute”

7. Click the tiny icon that looks like a window next to the path

8. Do nothing but click “Choose” to point it to the same folder. The path should now actually be absolute (without all the references to `..`)

9. Select the project in the Project Navigator then go to the project’s “Info” tab. Under Configurations, you should see “Debug” and “Release”. The project under each should be based on “Debug” or “Release” respectively, and the target under each should be based on “QSPlugIn”.

10. Go through the build settings for both the project and the target. As a general rule, nothing should be in bold except “Product Name”. Select anything that’s bold and hit Delete.

IIRC from the stuff I did a year ago things got complicated because the template structure in XCode changed with version 4.3 or so and I'm running 4.4. For example the directory "~/Library/Developer/Xcode/Templates/Application Plug-in" doesn't exist on my machine.

I’ve made a new template for Xcode 4 since then, but I don’t know if it’s worth starting over at this point.

 

If I do that [reworking the mediator protocol], would you be willing to rework your plug-in to use the chat mediator protocol?

I can certainly look into it. I assume it supports the basic "add contact to catalog" and "open chat" functionality (besides other things)? Might take a while though since I'm often short on time. :)

I’ve started it. https://github.com/quicksilver/ChatSupport-qsplugin

You’ll need to implement all the methods under `@protocol QSChatMediator`, but as I work on the Messages plug-in, this will likely change, so I wouldn’t dig into it yet.

It’s up to you. I guess all we ask is that you keep it available so we can get the source if you ever abandon it.

In that case would you mind if I put it up with svn on code.google.com?

Like I said, it’s up to you. The main problem I see with that is that you’ll be on your own. Other devs are less likely to collaborate that way.

I know Subversion is a bit old fashioned but it's what I'm used to. :) Otherwise I'll make do with git although I'll have to figure out the details.

I used to use Subversion. I don’t miss it at all. If you’re just waiting for a good excuse to mess with Git, maybe this is it. :-)

[Peter Schmitt]

1. Build Quicksilver (if you haven't recently) to create things in `/tmp/QS`

2. Right-click your project and add files

3. Choose `/tmp/QS/Configuration`

4. Don't copy items, do create groups for added folders, and don't add to the target

5. Select “Configuration” in the project and open the File Inspector on the right (⌥⌘1)

6. Change the path to “Absolute”

7. Click the tiny icon that looks like a window next to the path

8. Do nothing but click “Choose” to point it to the same folder. The path should now actually be absolute (without all the references to `..`)

9. Select the project in the Project Navigator then go to the project’s “Info” tab. Under Configurations, you should see “Debug” and “Release”. The project under each should be based on “Debug” or “Release” respectively, and the target under each should be based on “QSPlugIn”.

10. Go through the build settings for both the project and the target. As a general rule, nothing should be in bold except “Product Name”. Select anything that’s bold and hit Delete.

I've finished these steps but now my project refuses to build - it apparently can't find the QS headers anymore: "/tmp/QS/Configuration/Quicksilver.pch:3:9: 'QSFoundation/QSFoundation.h' file not found"

I'm a bit stumped right now (all the paths look fine, QSFoundation is present at /tmp/QS/build/Debug/QSFoundation.framework/Headers/QSFoundation.h), I'll take another look later this week. If you want to help debug I put the project's current state into an attachment.

 

I used to use Subversion. I don’t miss it at all. If you’re just waiting for a good excuse to mess with Git, maybe this is it. :-)

Fair enough, I'll take a stab at it. :)

Peter

[Patrick Robertson]

You're right, the fiddling with project settings is a bit of an art, that we've grown used to over the years ;-)

I've downloaded your .zip and made the appropriate changes. It builds for me up until the AS compile phase (I don't have Adium on my system), so it should be find for you.

As Rob suggested, from now on we recommend just using his XCode template, but it's not worth you doing this now.

It looked like you've missed out steps 2 and 3 on Rob's list - once the configuration files are imported into the project things become so much easier :)

[Rob McBroom]

On Oct 22, 2012, at 11:31 PM, Peter Schmitt <ara...@gmail.com> wrote:

I've finished these steps but now my project refuses to build - it apparently can't find the QS headers anymore: "/tmp/QS/Configuration/Quicksilver.pch:3:9: 'QSFoundation/QSFoundation.h' file not found"

I don’t know why, but some plug-ins need the frameworks in the project and some don’t. Often, this error can be fixed by adding the QSFoundation framework to the project. Now, this can be a real pain to do correctly and usually involves altering the project in a text editor (instead of Xcode), so let’s not go down that road unless we have to. It sounds like maybe Patrick found another way. (I haven’t downloaded the zips.)

Other things I forgot to mention:

Feel free to take any and all code from my version of the plug-in. Most of it probably needs to wait until the QSChatMediator protocol is finalized, but I think the Adium and Messages plug-ins will have a few application specific features, such as what to show when you right-arrow into the application, and the action I created that lets you select Aduim in the first pane, then set your status.

[Rob McBroom]

On Oct 22, 2012, at 9:54 AM, Rob McBroom <mailin...@skurfer.com> wrote:

I’ve started it. https://github.com/quicksilver/ChatSupport-qsplugin

You’ll need to implement all the methods under `@protocol QSChatMediator`, but as I work on the Messages plug-in, this will likely change, so I wouldn’t dig into it yet.

OK, I think the protocol is getting to a point where it won’t change that much if you want to start developing against it.

You’ll need to add QSChatMediator.h to your project. We should be consistent across plug-ins so it will work when other devs pull down the repo, so here’s how I’d set it up.

In the parent directory where you have your Adium plug-in, put the Chat Support plug-in in ChatSupport:

    git clone g...@github.com:quicksilver/ChatSupport-qsplugin.git ChatSupport

In the Adium plug-in’s project, add files and choose `../ChatSupport/Chat Support/QSChatMediator.h`. Don’t copy it into the project. Make sure in the file inspector that it’s set to “Relative to Project”.

As for code, I think the important methods to implement for now are

- (BOOL)sendItem:(QSObject *)item toAccounts:(NSArray *)accounts;

- (BOOL)accountIsAvailable:(NSString *)accountID;

- (BOOL)contactIsAvailable:(QSObject *)contact;

The last two will eventually be used to determine which actions show up for a particular contact/account.

We have the advantage that no working plug-ins are using this protocol right now, so if you see anything you think we should change, let me know.

[Peter Schmitt]

Hi again - and apologies for the long absence. My life got a bit more interesting and I had to take a break from random coding. :)

It took me a couple hours of digging but I managed to get the plugin to build (the supplied "fixed" Adium.zip unfortunately ran into exactly the same trouble as I did before). The solution: In XCode choose "File" menu -> "Project Settings..." -> "Build" tab -> "Derived Data Location" -> "Advanced..." -> choose "Legacy".

Next time (hopefully not two months from now) I'll upload this to git and then look into the mediator protocol. :)

Peter

[Patrick Robertson]

Thanks for the follow up Peter,

We completely understands how things are in the real world, it's just good to see people helping out :)

We'll try and include 'the solution' you mentioned in the plugin documentation so hopefully it won't happen again.

Good luck, and let us know if you're stuck on the mediator protocol!

[Peter Schmitt]

Thanks, hope my findings will be able to benefit others! :)

I'm still learning git but you can find the plugin source on github now: https://github.com/Aragos/qsadium

Do you think it's worth listing the plugin yet or should that wait until it is integrated with the mediator protocol?

[Rob McBroom]

On Dec 24, 2012, at 4:42 AM, Peter Schmitt <ara...@gmail.com> wrote:

> I'm still learning git but you can find the plugin source on github now: https://github.com/Aragos/qsadium

Nice. Let us know if you have any questions on that.

> Do you think it's worth listing the plugin yet or should that wait until it is integrated with the mediator protocol?

It should probably implement the mediator stuff. You can find a mostly working implementation for the Messages plug-in.

https://github.com/quicksilver/Messages-qsplugin/blob/master/QSiChatMediator.m

I haven’t figured out a lot of that code. You should probably just concentrate on the three methods I mentioned.

[Jonathan Levi]

Dropped you an email, but just in case - does anyone have a built version of this Messages plugin that I could try out? I wasn't able to build it (I'm not a developer)