Add a guide for upgrading themes to use the asset pipeline

1 files changed, 69 insertions, 0 deletions

diff --git a/doc/THEME-ASSETS-UPGRADE.md b/doc/THEME-ASSETS-UPGRADE.md
new file mode 100644
index 000000000..66a1e95f4
--- /dev/null
+++ b/doc/THEME-ASSETS-UPGRADE.md
@@ -0,0 +1,69 @@
+This document has notes on switching your Alaveteli theme to use
+the Rails asset pipeline.
+
+Firstly, add the following to your `lib/alavetelitheme.rb`, in
+order to add the subdirectories of your theme's `assets`
+directory to `config.assets.path`:
+
+    # Prepend the asset directories in this theme to the asset path:
+    ['stylesheets', 'images', 'javascripts'].each do |asset_type|
+        theme_asset_path = File.join(File.dirname(__FILE__),
+                                     '..',
+                                     'assets',
+                                     asset_type)
+        Rails.application.config.assets.paths.unshift theme_asset_path
+    end
+
+In the root of your theme, create these directories:
+
+    assets
+     \ images
+     \ stylesheets
+     \ javascripts
+
+i.e. `assets` is at the same level as `lib` and `locale-theme`.
+
+Move any image files from `public/images` to `assets/images`.
+Now change any references to those images with a literal `<img>`
+tag to use `image_tag` instead.  For example, instead of:
+
+    <img src="/images/helpmeinvestigate.png" alt="" class="rss">
+
+... you should have:
+
+    image_tag('helpmeinvestigate.png', :alt => "", :class => "rss")
+
+You should similarly move your stylesheets into
+`assets/stylesheets`.  If a stylesheet refers to images, you
+should rename the `.css` file to `.css.scss`, and change `url`
+to the sass-rails `image-url` helper.  e.g. instead of:
+
+    background-image: url(../images/mysociety.png);
+
+... you should have:
+
+    background-image: image-url('mysociety.png');
+
+If your only stylesheet is called `custom.css`, as in the
+example theme, you shouldn't need to make any other changes to
+the CSS.  If you have added additional stylesheets
+(e.g. `extra.css`), then you'll need to both:
+
+1. add them to
+`lib/views/general/_stylesheet_includes.html.erb`, for example
+with:
+
+    <%= stylesheet_link_tag "extra" %>
+
+2. add the following in `lib/alavetelitheme.rb`:
+
+    config.assets.precompile.push 'extra.css'
+
+Any custom Javascript should be moved to `assets/javascripts` in
+your theme directory, and, simlarly to the additional CSS, it
+should be mentioned in `lib/alavetelitheme.rb` with:
+
+    config.assets.precompile.push 'fancy-effects.js'
+
+You should be left with nothing in the `public` directory after
+making these changes, except possibly custom error pages.