Creating an Extension for Starling

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

As you might know, one of Starling's top priorities is to stay as lightweight and simple as possible. At the same time, we don't want users to reinvent the wheel all the time — that's why we are depending 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 Starling (and with other extensions), please make sure to follow these guidelines:

Best practices

Don't change the Starling Source Code

An extension should not make it necessary to change the source code of Starling. If it requires users to modify their copy of Starling, it will suddenly become very difficult for them to upgrade when a new Starling version comes out.

I know that this is sometimes difficult, or maybe even impossible. Feel free to post a question in the Forum if you need guidance on this task.

Package names

If you put your extension into the package “starling.extensions”, users will have all their Starling extensions neatly collected in one directory.

That's not compulsory, though. It might make sense to put some extensions into a unique root package.

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 rather 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. If possible, make sure to include a sample image that shows what it looks like.

To create a new wiki-page, you have to register at the Starling 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! :-)

http://wiki.starling-framework.org/extensions/my_extension_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: 2012/04/05 16:12 by daniel
 
Powered by DokuWiki