<commit_before>h2. Tutorial: A Customization Extension

This guide contains a tutorial for the development of an extension to customize the appearance of the standard Spree installation. After reading this guide you should learn:

* How to build a "site" extension to customize the look of your store
* How to include custom stylesheets, javascript, or images
* How to deactivate the "site" extension

endprologue.

h3. Creating the Site Extension

WARNING. You must "understand the difference":boot_modes.html between running Spree as a gem and running it as a Rails application. Certain instructions below depend on how you are running Spree.

h4. Site Extension with Spree Application

First, to generate the extension, run the following to create an extension by the name of 'site'.

<shell>
script/generate extension site
</shell>

This command will create many files in the vendor/extensions/site/ directory that looks similar to a generic rails application.

h4. Site Extension with Spree Gem Install

A site extension exists upon creation of an application using the Spree gem.

<shell>
ls vendor/extensions
</shell>

h3. Add a Custom Stylesheet

This part of the tutorial explains how to add a custom stylesheet to spree to change the look of your site.

h4. Create the custom stylesheet

WARNING. Spree uses SASS and Compass, a CSS framework that includes Blueprint. We recommend you become familiar with SASS. However, you may continue this tutorial without the knowlege of SASS.

h5. SASS

To create a stylesheet with SASS, complete the following:

<shell>
mkdir -p public/stylesheets/sass
</shell>

Inside this directory, create a file named +site.sass+.  Edit +site.sass+ to contain the following:
<code>
body
  :background #99CC99
</code>

h5. CSS

To create a stylesheet without SASS, complete the following:

<shell>
mkdir public/stylesheets
</shell>

Inside this directory, create a file named +site.css+. Edit +site.css+ to contain the following:
<code>
body {
  background: #99CC99;
}
</code>

h4. Add the stylesheet to the default layout

Now you'll tell Spree to include the custom stylesheet in the default layout by overriding the stylesheets preference.

h5. SASS

If you created a +site.sass+ file, edit the +SITE_EXTENSION_DIR/site_extension.rb+ file to change the existing +activate+ method to the following:
<code>
def activate
  AppConfiguration.class_eval do
    preference :stylesheets, :string, :default => 'compiled/screen,compiled/site'
  end
end
</code>

h5. CSS

If you created a +site.css+ file, edit the +SITE_EXTENSION_DIR/site_extension.rb+ file to change the existing +activate+ method to the following:
<code>
def activate
  AppConfiguration.class_eval do
    preference :stylesheets, :string, :default => 'compiled/screen,stylesheets/site'
  end
end
</code>

h4. Restart server

When any extension +public/*+ files are modified, a server restart is required to copy the files over to the main app +public/+ directory.

Restart the server with the +script/server+, +touch tmp/restart.txt+, etc. command.

h4. Results

After the server has restarted, refresh your browser to verify the background colour changes have taken effect.

!images/customize1.png(Custom CSS Part 1)!

h4. Another Iteration

Complete the following steps to perform another iteration of style changes:

h5. SASS

Apply the following patch on +site.sass+:
 
<code>
  body
   :background #99CC99
+ body.two-col div#wrapper
+   :background-image none
+   :background #FFF<commit_msg>Specifying stylesheets/ in the path for site CSS file is an error because stylesheets is already the default folder.<commit_after>h2. Tutorial: A Customization Extension

This guide contains a tutorial for the development of an extension to customize the appearance of the standard Spree installation. After reading this guide you should learn:

* How to build a "site" extension to customize the look of your store
* How to include custom stylesheets, javascript, or images
* How to deactivate the "site" extension

endprologue.

h3. Creating the Site Extension

WARNING. You must "understand the difference":boot_modes.html between running Spree as a gem and running it as a Rails application. Certain instructions below depend on how you are running Spree.

h4. Site Extension with Spree Application

First, to generate the extension, run the following to create an extension by the name of 'site'.

<shell>
script/generate extension site
</shell>

This command will create many files in the vendor/extensions/site/ directory that looks similar to a generic rails application.

h4. Site Extension with Spree Gem Install

A site extension exists upon creation of an application using the Spree gem.

<shell>
ls vendor/extensions
</shell>

h3. Add a Custom Stylesheet

This part of the tutorial explains how to add a custom stylesheet to spree to change the look of your site.

h4. Create the custom stylesheet

WARNING. Spree uses SASS and Compass, a CSS framework that includes Blueprint. We recommend you become familiar with SASS. However, you may continue this tutorial without the knowlege of SASS.

h5. SASS

To create a stylesheet with SASS, complete the following:

<shell>
mkdir -p public/stylesheets/sass
</shell>

Inside this directory, create a file named +site.sass+.  Edit +site.sass+ to contain the following:
<code>
body
  :background #99CC99
</code>

h5. CSS

To create a stylesheet without SASS, complete the following:

<shell>
mkdir public/stylesheets
</shell>

Inside this directory, create a file named +site.css+. Edit +site.css+ to contain the following:
<code>
body {
  background: #99CC99;
}
</code>

h4. Add the stylesheet to the default layout

Now you'll tell Spree to include the custom stylesheet in the default layout by overriding the stylesheets preference.

h5. SASS

If you created a +site.sass+ file, edit the +SITE_EXTENSION_DIR/site_extension.rb+ file to change the existing +activate+ method to the following:
<code>
def activate
  AppConfiguration.class_eval do
    preference :stylesheets, :string, :default => 'compiled/screen,compiled/site'
  end
end
</code>

h5. CSS

If you created a +site.css+ file, edit the +SITE_EXTENSION_DIR/site_extension.rb+ file to change the existing +activate+ method to the following:
<code>
def activate
  AppConfiguration.class_eval do
    preference :stylesheets, :string, :default => 'compiled/screen,site'
  end
end
</code>

h4. Restart server

When any extension +public/*+ files are modified, a server restart is required to copy the files over to the main app +public/+ directory.

Restart the server with the +script/server+, +touch tmp/restart.txt+, etc. command.

h4. Results

After the server has restarted, refresh your browser to verify the background colour changes have taken effect.

!images/customize1.png(Custom CSS Part 1)!

h4. Another Iteration

Complete the following steps to perform another iteration of style changes:

h5. SASS

Apply the following patch on +site.sass+:
 
<code>
  body
   :background #99CC99
+ body.two-col div#wrapper
+   :background-image none
+   :background #FFF
{'fraction_non_alphanumeric': 0.06425646095184297, 'fraction_numerical': 0.00819093348397119, 'mean_word_length': 4.447692307692308, 'pattern_counts': {'":': 2, '<': 37, '<?xml version=': 0, '>': 41, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5516555', 'n_tokens_mistral': 2029, 'n_tokens_neox': 1949, 'n_words': 975}