h1. About Pupu

"Pupu":http://github.com/botanicus/pupu is a framework-agnostic plugin system for assets like JS/CSS frameworks and its plugins, icon sets etc. You can "search GitHub":http://github.com/search?type=Repositories&language=&q=pupu&repo=&langOverride=&x=9&y=24&start_value=1 for more examples. It provides CLI interface for searching, installing and updating pupus from GitHub and it also provides a helper for including static files from pupu into your HTML page. Both CLI and helper can handle dependencies.

CLI example:

<pre>
pupu install botanicus/autocompleter
~ Downloading botanicus/autocompleter
~ Downloading dependency botanicus/mootools
</pre>

h1. Why I wrote it

In my apps the root/ stuff always get bloated and messy when I have all javascripts in root/javascripts, all stylesheets in root/stylesheets etc. It's nearly imposible to remove some stuff related with let's say some mootools plugin. It has it's own javascripts, stylesheets, few images + code which is required for initialization. And of course it is really bad idea to put your own code to directory with such things as javascript framework is.

Another thing which really annoyed me was the bloody <code>js_include_tag</code> and <code>css_include_tag</code>. There are so stupid that they do not throw exception when the JS or CSS file do not exists! So you are surprised why you fancy script do not work and then you realized that it's not correctly included at all!

h1. CLI interface

If you are storing your media files in different directory than in @public@ or @media@ or if you want to use submodules strategy, you will need some "setup":http://wiki.github.com/botanicus/pupu/setup. *In case you are using defaults, everything should just work out of the box.*

<pre>
# list all available pupus
pupu search

# search for pupu matching mootools in its name (you can use regexp)
pupu search mootools

# install autocompleter and its dependencies from my github repo
pupu install botanicus/autocompleter

# or uninstall, it's the same
pupu uninstall autocompleter

# list all installed pupus
pupu list
</pre>

h1. Runtime Setup

Command-line interface doesn't require any setup, runtime needs some.

At the moment "Rango":http://github.com/botanicus/rango, "Merb":http://github.com/merb/merb and Rails are supported directly. If you are using one of these frameworks, just use @require "pupu/adapters/rango"@ in your environment file.

Rango actually will have stack generator in "upcoming version 0.2":http://wiki.github.com/botanicus/rango/roadmap, so then you can just run @rango create stack my_blog@ and it will work with Pupu out of the box.

If your framework isn't supported, just:

<pre>
require "myframework"
require "pupu"
require "pupu/helpers"

Pupu.root = MyFramework.root
Pupu.media_root = File.join(MyFramework.root, "media") # you don't have to set it if you are using public or media
MyFrameworkHelpersModule.send(:include, Pupu::Helpers)
</pre>

And it should work. Check existing "Rango":http://github.com/botanicus/pupu/blob/master/lib/pupu/adapters/rango.rb, "Merb":http://github.com/botanicus/pupu/blob/master/lib/pupu/adapters/merb.rb resp. "Rails":http://github.com/botanicus/pupu/blob/master/lib/pupu/adapters/rails.rb adapter for inspiration.

h1. Helpers

In your views you can include all the plugin-related files this way:

<pre>
pupu :autocompleter
</pre>

If pupu has optional arguments, you can specify them, it will modify its behaviour (including extra files etc).

<pre>
# this will include not just basic autocompleter files, but script for local requests too
pupu :autocompleter, type: "local"
</pre>

There is some helpers for getting path to pupu's files:

<pre>
Plugin[:autocompleter].image("spinner.gif")
</pre>

h1. Initializers

Initializers are the only part of pupu which are not stored in <code>root/pupu</code>, but are copyied to <code>[media_root]/javascripts/initializers</code> resp. <code>[media_root]/stylesheets/initializers</code>. In contrary to files in <code>[media_root]/pupu</code>, initializers are intended for user editing.

Example from "botanicus/flash":http://github.com/botanicus/pupu-flash: "flash.js":http://github.com/botanicus/pupu-flash/blob/master/initializers/flash.js, "flash.css":http://github.com/botanicus/pupu-flash/blob/master/initializers/flash.css

h1. Links

- "Wiki":http://wiki.github.com/botanicus/pupu
- "Source Code":http://github.com/botanicus/pupu
- "API Documentation":http://rdoc.info/projects/botanicus/pupu
- Examples: "Rango":http://github.com/botanicus/pupu/tree/master/examples/rango, "Merb":http://github.com/botanicus/pupu/tree/master/examples/merb and "Rails":http://github.com/botanicus/pupu/tree/master/examples/rails