Creating an Extension for Sparrow

First of all: Thanks for creating an extension for Sparrow!

As you might know, one of Sparrow's top priorities is to stay as lightweight and minimal as possible. At the same time, we don't want users to reinvent the wheel all the time — that's why we are dependent on folks like you, who provide components that can be used by our community. Thanks for taking the time to help us on this task!

To integrate well with the rest of Sparrow (and with other extensions), please make sure to follow these guidelines:

Best practices

Custom class prefix

Don't use the SP-prefix for your classes. Who knows, perhaps we want to integrate your class into a future Sparrow version, but want to change the interface — then we would break the code of anybody who is using your extension. We recommend the prefix SX for extension classes (like SXGauge), but you are free to use any other prefix if you prefer it.

Don't change the Sparrow source code

An extension should not make it necessary to change the source code of Sparrow. If you need to modify a Sparrow class, please try using Objective-C's categories instead.

Source code repository

If your extension consists of only a few files, we recommend using GitHub's Gist-feature to share the code. According to GitHub,

Gist is a simple way to share snippets and pastes with others. All gists are git repositories, so they are automatically versioned, forkable and usable as a git repository.

This is extremely convenient. Even if you don't care about VCS-Systems at all and haven't even heard of Git, you can create a minimal version-controlled version of your extension simply by pasting the code into their webpage. A zip-archive with the source code will be created automatically.

To create a gist, create one on the Gist Homepage. As an example, here is the Gist of the Gauge extension.

Of course, if your extension is too extensive, you can create a full-fledged Git repository or provide the links to any other hosting service or private homepage.

Creating a Wiki Page

When your extension is ready, please take the time to create a Wiki-page with all the links, a description and usage guidelines.

To create a new wiki-page, you have to register at the Sparrow Wiki. Create a user by clicking on “Login” in the bottom bar and then “Register”. As soon as you are logged in, you can create your extension-page.

Thankfully, this is very easy to do. Just paste the following address into your browser's address bar, replacing my_extension_name with … your extension's name! :-)

On the page that pops up, click on “Create this Page” (if this button is not visible, you are not logged in). Now, a template is displayed, showing the basic structure of your new page. Just replace the placeholders with your custom information, and you are ready to go!

  extensions/creating_an_extension.txt · Last modified: 2013/06/02 13:24 by daniel
Powered by DokuWiki