343 lines
14 KiB
Markdown
343 lines
14 KiB
Markdown
---
|
|
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.
|
|
|