Hey! Keep up to date with the project through its beta and public launch by following @getsparks.

GetSparks.org News

Guide #3: Making Sparks

Contributing code and being recognized for awesome and useful code: It's what we love about being open-source developers. Learn how to make and distribute your own sparks.

Note: This is a fairly wordy document, but it will clearly explain how a spark is structured, how to build one, and how to submit it. If you think we've missed something, let us know!

How Contributing Works

GetSparks.org is entirely backed by external repositories. That means we do not host your projects. Your project can live happily on your GitHub or BitBucket account, or personal git or mercurial server. When you register a spark at GetSparks, you simply point us to your repository.

That's awesome for a few different reasons:

  1. All your cool open-source projects can remain in one place.
  2. You'll get the fun of wikis, issue trackers, and watchers automatically if you use GitHub or BitBucket.
  3. You aren't forced to use some antiquated versioning system in order to contribute. GetSparks can easily support new VCSs over time.
  4. We don't have to worry about bandwidth issues.

After that, you register new versions of your spark on GetSparks by pointing us towards a tag in your repository. That is, if you create tag '1.0.0' in your repo, just add a '1.0.0' version to your project in GetSparks. In a few minutes, it'll be available to the world.

What A Spark Looks Like

For now, a Spark is simply a CodeIgniter package that is nested inside the sparks/ directory. So when they are installed, sparks look like: 

/sparks
..../example-spark
......../1.0.0

Another spark that might do something more advanced, might have configs, helpers, libraries, and models. We'll call this 'other-spark', which might look like: 

/sparks
..../example-spark
......../1.0.0
............/config
............/libraries
..../other-spark
......../2.1.0
............/config
............/libraries
............/helpers
............/models

When you create a spark project on github or bitbucket, all you have to do is set up the root of your project to look like: 

......../config
......../libraries
......../helpers
......../models

We'll take care of the rest. Name your project appropriately − You might want to register the spark before creating a github project since GetSparks project names must be unique.

Writing A Test Spark

In this section we'll go through creating a very basic spark that pulls tweets from Twitter for a given user. If you haven't already, set up the spark system in your application: Setting Up.

  1. Create a directory inside your sparks folder named 'birdseed'. Inside that, create a directory named '0.0.1', which is the version of this spark. This exact structure (sparkname/version) is created automatically when people install your spark.
  2. Inside '0.0.1', create a 'config' folder and a 'helpers' folder.
  3. Create files named 'birdseed.php' and 'autoload.php' inside 0.0.1/config. Note that you should generally name your config files the same as your spark.
  4. Inside 0.0.1/config/birdseed.php, place this, and save the file: 
    <?php

# The base URL for API calls to twitter
$config['twitter_api_base_url'] = 'http://api.twitter.com/1/';
  5. Inside 0.0.1/config/autoload.php, place this, and save the file: 
    <?php

# Load the birdseed config when the spark is loaded
$autoload['config'] = array('birdseed');

# Load the birdseed helper when the spark is loaded
$autoload['helper'] = array('birdseed');

    Note: Autoloading components of your spark is optional, but we do it here to make this tutorial more simple. Generally, you should only autoload what you need to maintain the overall speediness of CodeIgniter.

  6. Create the file '0.0.1/helpers/birdseed_helper.php'. Inside it, place this, and save: 
    <?php

/**
 * This function grabs a user's tweets from twitter. It's not a
 *  bad idea to cache the output of this call!
 * @param  string $username The Twitter username to grab
 * @param  int    $n        The number of tweets to pull down
 * @return array            An array of tweets
*/
function birdseed_fetch($username, $n = 10)
{
    $base_url = config_item('twitter_api_base_url');
    $call_url = $base_url
                . 'statuses/user_timeline.json?screen_name='
                . $username
                . '&count='
                . $n;

    $tweets = json_decode(file_get_contents($call_url));

    if($tweets === FALSE)
    {
        # We didn't get a valid response back. Maybe the innerwebs are down.
        return array();
    }

    return $tweets;
}
  7. Inside 0.0.1/spark.info, place this, and save the file: 
    # This is the spark-sdk specification. It's in a magical format called YAML.
#  Use this format while developing your own sparks!

# This is the spark name. This should be the registered name of the spark.
# It is here for informational purposes only.
name: birdseed

# This is the current version of this spark. All sparks should be in
#  x.x.x format. Validation will fail otherwise.
version: 0.0.1

# This is the version of CodeIgniter this spark is compatible up to. It should
#  be in x.x.x format
compatibility: 2.0.2

# There are no dependencies now, but when there are, uncomment below.
#dependencies:
#  some-spark-1: 1.0.0
#  some-other-spark-2: 1.0.0

    This is your 'spark.info' file, which is required with every new spark. It tells the spark processor about your spark, and most importantly, supplies version information. Versions must always be in x.x.x format! Read more about spec formats here.

  8. Now you're ready to try your new spark. From somewhere inside your CodeIgniter Application, try: 
    $this->load->spark('birdseed/0.0.1');

# Grab _kennyk_'s tweets
$tweets = birdseed_fetch('_kennyk_', 5);
print_r($tweets);

    You could then try something like this in your view:

    <?php

    # Load the spark and get some tweets
    $this->load->spark('birdseed/0.0.1');
    $tweets = birdseed_fetch('_kennyk_', 5);

?>
...
<ul>
    <?php foreach($tweets as $tweet): ?>
        <li><?php echo $tweet->text; ?></li>
    <?php endforeach; ?>
</ul>
  9. Did that work alright? Cool! If not, let us know!

Contributing

So now you have a spark that works, and you want to contribute it to the rest of the CodeIgniter world. Awesome! We're going to assume here that:

  1. You have an account at GitHub or BitBucket, or you run your own publicly-accessible git or mercurial server. If you don't have one of these, go get one and join the open-source world!

  2. You know how to set up a project in your repository.

  3. You know what a "Clone URL" is, and how to get a publicly-readable clone URL from your repository.

Here's what you need to do:

  1. If you haven't already, copy your spark's files (everything inside birdseed/0.0.1) into your project directory.

  2. Spark SDK: It is not required, but good practice to validate your spark before submitting it to the repository. You can do this by installing the 'spark-sdk' spark, available here. This is almost the exact validator that GetSparks.org uses.

  3. Optionally, you may add a readme file at the root of your spark. Readme files are expected to be in markdown format. This readme will be parsed and posted with your spark when it goes live.

  4. Push the files to your repository via: 
    $ hg add .
$ hg commit -m "My sweet new spark - first commit"
$ hg push
    or 
    $ git add .
$ git commit -m "My sweet new spark - first commit"
$ git push
  5. Create and push a new tag. This should be something sane, like a version number. 
    $ hg tag '0.0.1'
$ hg commit -m "My neato releaso ;)"
$ hg push
    Or 
    $ git tag '0.0.1'
$ git push --tags

  6. If you don't already have an account as GetSparks.org, get one and log in.

  7. Head over the spark contribution page, fill out the details, and create your entry. Remember, for "Clone URL," use the publicly-accessible one. On GitHub, this is called your "Read Only" clone URL.

  8. You should now be on your project's page. You'll notice a form that says "Add a New Version." This is where you enter the tag that you created in step 3. Enter "0.0.1" and click "Create from Tag"

    Your spark entry will be created, but marked as "unverified". Over the next few minutes, the GetSparks daemons will check out and validate your spark.

  9. If your spark looks fine, it'll be marked as verified. If there was some sort of error (like an invalid clone URL), the version will be removed and you'll receive an automated email explaining why. At this point, you should try to fix the errors and re-register your tag on GetSparks.

  10. Once your spark has been verified, version information and a download-able zip will appear on the page. If you have the spark-manager installed in one of your applications, you can open up a terminal and navigate to a new project. Try: $ php tools\spark install [your-spark-name] Did it work? Sweet! Go tell your friends. If not, and you think these directions are faulty in some way, let us know!

Best Practices

  1. Naming: Naming your spark so that it won't conflict with a user's existing libraries or sparks is a something you should absolutely do. This is especially important because of PHP's lack of namespacing in earlier, but still support versions (<5.3).

    If your spark involves a model that deals with users, you might be inclined to naming the class 'User'. Instead, prefix the name of the class with the name of the spark: Something like 'Birdseed_user'. Keep in mind, we stick to CodeIgniter's class and file naming conventions.

    Also: GetSparks currently only accepts letters, numbers, and underscores in spark names. If your spark only contains a single library, it might be an idea to name your library after the spark to keep things clear for the end user:

  2. Documentation: Put your spark's documentation in a Readme file at the root of your spark. The GetSparks.org spark daemon will pull down any readme file at the root of your spark, and try to parse it as markdown. This means it's compatible with GitHub and BitBucket's Readme format too.

    Writing your spark documentation this way will allow you to update your code and docs all in one place: your repo. How easy is that?

  3. Vendor Files: If you're writing a spark that uses third-party libraries, and you need a place to store them, just place them in a folder named 'vendor' inside your spark. Including those files via require_once etc, should be done by your spark intelligently.

  4. Autoloading: The spark system allows you to autoload anything you need in config/autoload.php (including sparks). This can make things handy for the end-user, but don't forget one of the major philosophies of CodeIgniter: Only include what you need.

Tips for Advanced Users

  1. When working on a spark that you have as a project in github, it may be much easier to manage if you set up a symbolic link in the sparks directory to point to the spark project path.