Skip to content
This repository
Fetching contributors…

Cannot retrieve contributors at this time

file 366 lines (327 sloc) 11.757 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
<?php $this->load->view('global/_new_header.php', array('title' => 'Writing Your Own')); ?>

<h2>Guide #3: Making Sparks</h2>

<p>
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.
</p>

<p>
<strong>Note:</strong> 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,
<a href="mailto:<?php echo config_item('support_email'); ?>">let us know!</a>
</p>
<h3>How Contributing Works</h3>

<p>
GetSparks.org is <strong>entirely backed by external repositories.</strong>
That means we do not host your projects. Your project can live happily on your
<a href="http://github.com" target="_blank">GitHub</a> or <a href="http://bitbucket.com" target="_blank">BitBucket</a> account, or personal git or mercurial server. When you
register a spark at GetSparks, you simply point us to your repository.
</p>

<p>
That's awesome for a few different reasons:
</p>

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

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

<h3>What A Spark Looks Like</h3>

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

<p>
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:
</p>

<pre>
/sparks
..../example-spark
......../config
......../libraries
..../other-spark
......../config
......../libraries
......../helpers
......../models
</pre>

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

<pre>
......../config
......../libraries
......../helpers
......../models
</pre>

<p>
We'll take care of the rest. Name your project appropriately &minus; You
might want to register the spark before creating a github project since
GetSparks project names must be unique.
</p>

<h3>Writing A Test Spark</h3>

<p>
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: <a href="<?php echo base_url() . 'set-up'; ?>">Setting Up</a>.
</p>

<ol>
<li>Create a directory inside your sparks folder named 'birdseed'.</li>
<li>
Inside birdseed, create a 'config' folder, and also, create a
'helpers' folder.
</li>
<li>
Create a file named 'birdseed.php' and 'autoload.php' inside birdseed/config. Note that
you should generally name your config files the same as your spark.
</li>
<li>
Inside birdseed/config/birdseed.php, place this, and save the file:
<pre>
&lt;?php

# The base URL for API calls to twitter
$config['twitter_api_base_url'] = 'http://api.twitter.com/1/';
</pre>
</li>
<li>
Inside birdseed/config/autoload.php, place this, and save the file:
<pre>
&lt;?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');
</pre>
<p>
<strong>Note:</strong> 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.
</p>
</li>
<li>
Create the file 'helpers/birdseed_helper.php'. Inside it, place this, and
save:
<pre>
&lt;?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.xml?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 FALSE;
}

$return = array();

foreach($tweets->user->tweets as $tweet)
{
$return[] = $tweet;
}

return $tweets;
}
</pre>
</li>
<li>
Now you're ready to try your new spark. From somewhere inside your
CodeIgniter Application, try:
<pre>
$this->load->spark('birdseed');

# Grab _kennyk_'s tweets
$tweets = birdeseed_fetch('_kennyk_', 5);
print_r($tweets);
</pre>
</li>
<li>
Did that work alright? Cool! If not, <a href="mailto:<?php echo config_item('support_email'); ?>">let us know!</a>
</li>
</ol>

<h3>Contributing</h3>

<p>
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:
</p>

<ol>
<li>
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!
</li>
<li>
You know how to set up a project in your repository.
</li>
<li>
You know what a "Clone URL" is, and how to get a publicly-readable
clone URL from your repository.
</li>
</ol>

<p>Here's what you need to do:</p>

<ol>
<li>
<p>
If you haven't already, copy your spark's files into your project
directory.
</p>
</li>
<li>
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.
</li>
<li>
Push the files to your repository via:
<code>
$ hg push
</code>
or
<code>
$ git push
</code>
</li>
<li>
Create and push a new tag. This should be something sane, like a version number.
<pre>
$ hg tag '1.0'
$ hg add .
$ hg commit -m "My neato releaso ;)"
$ hg push
</pre>
Or
<pre>
$ git tag '1.0'
$ git push --tags
</pre>
</li>
<li>
<p>
If you don't already have an account as GetSparks.org,
<a href="<?php echo base_url(); ?>register">get one</a> and log in.
</p>
</li>
<li>
<p>
Head over the <a href="<?php echo base_url(); ?>packages/add">spark contribution page</a>, fill out the details, and
create your entry. <strong>Remember</strong>, for "Clone URL," use the
publicly-accessible one. On GitHub, this is called your "Read Only" clone
URL.
</p>
</li>
<li>
<p>
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 "1.0" and click "Create from Tag"
</p>
<p>
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.
</p>
</li>
<li>
<p>
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.
</p>
</li>
<li>
<p>
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 your project.
Try:
<code>
$ php tools\spark install [your-spark-name]
</code>
Did it work? Sweet! Go tell your friends. If not, and you think these
directions are faulty in some way, <a href="mailto:<?php echo config_item('support_email'); ?>">let us know!</a>.
</p>
</li>
</ol>


<h3>Best Practices</h3>

<ol>
<li>
<p>
<strong>Naming:</strong> 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).
</p>
<p>
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.
</p>
</li>
<li>
<p>
<strong>Documentation:</strong> 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.
</p>
<p>
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?
</p>
</li>
<li>
<p>
<strong>Vendor Files:</strong> 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
file via require_once etc, should be done by your spark intelligently.
</p>
</li>
<li>
<p>
<strong>Autoloading:</strong> The spark system allows you to autoload
anything you need in config/autoload.php. 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.
</p>
</li>
</ol>

<h3>Tips for Advanced Users</h3>

<ol>
<li>
<p>
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.
</p>
</li>

</ol>

<?php $this->load->view('global/_new_footer.php'); ?>
Something went wrong with that request. Please try again.