[Docs] Move and update the documentation on creating compass extensions.

doc-src/content/tutorials/extensions.markdown

@@ -0,0 +1,342 @@
+---
+title: Creating Compass Extensions
+layout: tutorial
+classnames:
+  - tutorial
+---
+Compass Extensions
+==================
+
+Compass, at its heart, is a framework upon which sass-based stylesheet frameworks
+are built. It provides the tools for building, installing and using reusable
+stylesheets that provide anything from full-fledged layout frameworks to designs
+for widgets or even full page designs. All using the power of sass to keep the
+semantic meaning of the html pages clear and free of design details.
+
+This document describes the compass extension toolset so that you can build
+your own compass extension.
+
+Basic Extension Layout
+----------------------
+
+<pre>
+<strong>my_extension</strong>
+|
+|- <strong>stylesheets</strong> (this directory will be on the sass load path)
+|  |
+|  |- my_extension (not technically required, but it's good to scope imports by the name of the extension)
+|  |  |
+|  |  |- _module_one.sass (this file would be imported using <code>@import my_extension/module_one.sass</code>)
+|  |  |- _module_two.sass (this file would be imported using <code>@import my_extension/module_two.sass</code>)
+|  |  |- ...
+|  |
+|  |- _my_extension.sass (This file will import the entire extension using <code>@import my_extension.sass</code>)
+|
+|- <strong>templates</strong> (this is where templates/patterns go)
+|  |
+|  |- <strong>project</strong> (this should be provided if you'd like people to be able to base their project on the extension)
+|  |  |
+|  |  |- <strong>manifest.rb</strong> (this file should declare the contents of the template)
+|  |  |- screen.sass (this would be the main stylesheet, importing from your extension and demonstrating its use)
+|  |  |- print.sass (this file would set up basic print styles)
+|  |  |- ie.sass (if you want, you can provide custom styles for IE)
+|  |
+|  |- some_pattern
+|     |
+|     |- <strong>manifest.rb</strong>
+|     |- some.sass (some sass is probably in order, always import from the extension library as much as possible)
+|     |- some_script.js (yes, you can provide javascript code)
+|     |- some_image.png (and images)
+|     |- some_content.html.haml (and even html and haml)
+|     |- some_other_file.txt (and other arbitrary files)
+|
+|- <strong>lib</strong> (optional ruby code)
+   |
+   |- <strong>my_extension.rb</strong> (this code can register your framework if you deviate from conventions and require sass extensions, etc.)
+   |
+   |- my_extension
+      |
+      |- sass_extensions.rb (this is the standard location to place sass functions)
+</pre>
+
+Names in <strong>bold</strong> are part of the extension naming convention.
+
+Generating an Extension
+-----------------------
+
+If you want a leg up to get started working on your extension,
+you can use compass to generate an extension with the following command:
+
+    compass create my_extension --using compass/extension 
+
+This will create a few basic files and folders to get you started.
+
+Advanced Layout Options
+-----------------------
+
+### Library File Location
+
+The extension library file referenced above as `my_extension/lib/my_extension.rb`
+can actually be stored at any of the following three locations:
+
+1. `my_extension/compass_init.rb`
+2. `my_extension/lib/my_extension.rb`
+3. `my_extension/my_extension.rb`
+
+The first of those locations found (in the above order) will be loaded.
+The compass_init.rb file takes priority, so that extensions that want to work
+differently as compass extensions than they do as normal ruby libraries,
+have a way of targeting compass.
+
+### Stylesheet and Template Locations
+
+If you'd like to store your stylesheets and/or templates in a non-standard location within your extension,
+you must provide a library file and register the extension explicitly like so:
+
+    base_directory  = File.join(File.dirname(__FILE__), '..')
+    stylesheets_dir = File.join(base_directory, 'my', 'stylesheets')
+    templates_dir   = File.join(base_directory, 'my', 'templates')
+    Compass::Frameworks.register('my_extension', :stylesheets_directory => stylesheets_dir, :templates_directory => templates_dir)
+
+If you're following the standard naming convention, but the stylesheet and
+template directories are not at the top level, you can just do this instead:
+
+    # path from the library file to where you're keeping your compass stuff.
+    base_directory  = File.join(File.dirname(__FILE__), '..', 'compass')
+    Compass::Frameworks.register('my_extension', :path => base_directory)
+
+Conventions to Follow
+---------------------
+
+The following are not required, but are standards that your framework
+should attempt to adhere to unless there's a good reason not to do so.
+
+1. Have a single import for your framework.
+2. Break up your framework into modules so that people can import just smaller
+   pieces for faster load times when they're not using everything.
+3. Use partials (files starting with an underscore) for stylesheets that are meant
+   to be imported. If you do not Sass will generate css
+   files for your libaries in some configurations.
+4. Provide a project template. If you do not, your project should only be
+   providing widgets or page designs, etc.
+
+Building a Template (a.k.a. Pattern)
+====================================
+
+Manifest Files
+--------------
+
+The manifest file declares the template contents and tells compass information
+about the files in the template.
+
+### An Example Manifest File
+
+    description "My awesome compass plugin."
+
+    stylesheet 'screen.sass', :media => 'screen, projection'
+    stylesheet 'partials/_base.sass'
+    stylesheet 'print.sass',  :media => 'print'
+    stylesheet 'ie.sass',     :media => 'screen, projection', :condition => "lt IE 8"
+
+    image 'grid.png'
+    javascript 'script.js'
+
+    html 'welcome.html.haml', :erb => true
+    file 'README'
+
+    help %Q{
+    This is a message that users will see if they type
+
+      compass help my_extension
+
+    You can use it to help them learn how to use your extension.
+    }
+
+    welcome_message %Q{
+    This is a message that users will see after they install this pattern.
+    Use this to tell users what to do next.
+    }
+
+
+You may also see some real manifest files here:
+
+* [blueprint](http://github.com/chriseppstein/compass/blob/master/frameworks/blueprint/templates/project/manifest.rb)
+* [compass-css-lightbox](http://github.com/ericam/compass-css-lightbox/blob/master/templates/project/manifest.rb)
+
+### Manifest Declarations
+
+There are five kinds of manifest declarations:
+
+1. `stylesheet` - Declares a sass file.
+2. `image` - Declares an image.
+3. `javascript` - Declares a javascript file.
+4. `html` - Declares an html file.
+5. `file` - Declares a random file.
+
+All declarations take the path to the file as their first argument. Note that the
+normal slash `/` can and should be used in a manifest. Compass will take care of
+the cross platform issues. The path to the file will be reproduced in the user's
+project, so please keep that in mind when creating folders. The location where
+files are going to be installed is dictated by the user's project configuration,
+however, a template can place things into subdirectories relative to those locations.
+
+Common options:
+
+* `:erb` - When set to true, the file will be processed via the ERB templating language.
+  See the "Advanced Manifests" section below for more details.
+* `:to` - The location where the file should be installed relative to the
+  type-specific location.
+* `:like` - Most often used with a `file` declaration, this option allows you to
+  install into the location of another manifest type (and also :css). E.g. :like => :css
+
+Stylesheet options:
+
+* `:media` - this is used as a hint to the user about the media attribute of the
+  stylesheet link tag.
+* `:condition` - this is used to hint the user that a conditional comment should be
+  used to import the stylesheet with the given condition.
+
+HTML files:
+
+You can provide html as haml or as plain html. If you provide haml, the haml will be
+converted to html when it is installed, unless the project allows haml files.
+Providing html files is usually done to demonstrate how to use a more complicated
+design and to get the user started off with working product.
+
+### Advanced Manifests and Templates
+
+* ERB Processing - This can be used to customize the contents of the file in an
+  extension template. The template will be processed in the context of a
+  TemplateContext instance, which gives you access to the full project configuration
+  information as well as the command line options. Since it's unlikely many templates
+  will need this functionality, I leave it as an exercise of the user to figure it out
+  and if they can't to contact the compass-devs mailing list for assistance.
+* `no_configuration_file!` - calling this method within the manifest will tell
+  the installer to skip the creation of a configuration file.
+* `skip_compilation!` - calling this method within the manifest will tell the
+  installer to skip compilation of sass files to css.
+
+Distributing Extensions as Ruby Gems
+------------------------------------
+
+How to build and distribute ruby gems is outside the scope of this document.
+But delivering an extension as a ruby gem makes it easier to manage software
+dependencies, install, and uninstall.
+
+Tips for Developing Extensions
+------------------------------
+
+* If you're developing a simple extension, you may find it convenient to place
+  your extension within an existing compass project in the extension folder.
+* Never specify an extension in your imports as this can cause issue when the
+  syntax of a file changes.
+
+Packaging an Extension as a RubyGem
+-----------------------------------
+
+You do not _have_ to make your extension a ruby gem. But if you do, you get some benefits you would not have otherwise:
+
+* Releases
+* Versions
+* A standard way of asking your users what release they are using.
+* Better integration with ruby-based projects via tools like
+  [Bundler](http://gembundler.com/).
+
+### Creating a Gem
+
+Before you begin, please ensure you have gem version `1.3.6` or greater. `gem -v` will tell you the currently installed version.
+
+1. Define your gemspec file at the top of your extension. Here's [an example of
+   one](http://github.com/ericam/compass-css-lightbox/blob/master/css-lightbox.gemspec).
+   The gemspec should have the same name as your gem.
+2. Build a gem: `gem build my_extension.gemspec`. This will build your gem file and
+   add the current version to the name. E.g. `my_extension-0.0.1.gem`
+3. Test your gem by installing it locally: `gem install my_extension-0.0.1.gem`
+
+### Releasing a Gem
+
+The ruby community is nice and will host your gem files for free. To release your gem:
+
+    gem push my_extension-0.0.1.gem
+
+Your ruby gem will be hosted on [rubygems.org](http://rubygems.org/).
+Please familiarize yourself with [their documentation](http://rubygems.org/pages/gem_docs).
+
+Installing Extensions
+=====================
+
+How extensions are installed varies according to the decisions you make about
+how you are packaging and releasing your gem. There will be a standard approach
+in a future release, but until then, it is suggested that you provide your users
+with succinct installation instructions.
+
+Installing Extensions Released as RubyGems
+------------------------------------------
+
+When creating a new project:
+
+    sudo gem install my_extension
+    compass create my_project -r my_extension --using my_extension
+
+The `-r` option is annoying and will not be needed in a future version of compass.
+But for now, it tells compass to find and load the extension from the local
+rubygems repository.
+
+To install via rubygems into an existing project:
+
+    gem install my_extension
+    # edit the project configuration file and add:
+    require 'my_extension'
+    compass install my_extension
+
+Or if you have other patterns besides the project pattern:
+
+    compass install my_extension/pattern
+
+Installing Ad-hoc Extensions
+----------------------------
+
+Ad-hoc extensions are any set of files and folders following the basic conventions
+described above. They could be installed via a zip file or by checking the code out
+from source control. Ad-hoc extensions will be automatically found in the extensions
+directory of a project and registered for import without needing a `require` statement
+in the compass configuration file.
+
+Currently, ad-hoc extensions can only be installed into the extensions directory
+of an existing compass project. This will be fixed in a future release of compass.
+Until then, you may need to instruct your users to create a bare project to get started:
+
+    compass create my_project --bare
+
+This will create a project directory, a sass directory (with no sass files) and a configuration file.
+
+The standard location for extensions is `project_root/extensions` for stand-alone
+projects and `project_root/vendor/plugins/compass_extensions` for rails projects.
+Additionally, the user may customize their extensions directory by setting
+`extensions_dir` in their compass configuration file.
+
+To install into an existing project, simply place the extension into a project's
+extension directory. This could be done via a git clone or by extracting an archive.
+The name of the directory it creates should be the name of the extension. The project
+will now have access to the extension.
+
+Verifying that an Extension is Installed Correctly
+--------------------------------------------------
+
+The user can verify that they have access to your extension by typing:
+
+    compass help
+
+And they should see the framework in the list of available frameworks.
+Alternatively, if you've provided a `help` message in the manifest, then
+the user can type:
+
+    compass help my_extension
+    - or -
+    compass help my_extension/pattern_name
+
+*Note:* The user might need to provide the `-r` option to help in order for compass to
+find a gem-based extension before a project exists. This is not needed for
+extensions installed into the extensions directory, or if the project is already
+required in the current directory's project configuration.
+