Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

its/it's trip; sentence flow; putting a camel in javascript

  • Loading branch information...
commit 026d76c68ed3a1eb7b8bb843e0d72dc68d03bf0a 1 parent 60cc5e5
@randomecho randomecho authored
View
44 source/asset_customization.textile
@@ -1,6 +1,6 @@
h2. Asset Customization
-This guide covers how Spree manages it's javascript, stylesheet and image assets and how you can extend and customize them including:
+This guide covers how Spree manages its JavaScript, stylesheet and image assets and how you can extend and customize them including:
* Understanding Spree's use of the Rails asset pipeline
* Managing application specific assets
@@ -13,9 +13,9 @@ endprologue.
h3. Spree's Asset Pipeline
-With the release of 3.1 Rails now supports powerful asset management features and Spree fully leverages these features to futher extend and simplify it's customization potential. Using asset customization techniques outlined below you be able to adapt all the javascript, stylesheets and images contained in Spree to easily provide a fully custom experience.
+With the release of 3.1 Rails now supports powerful asset management features and Spree fully leverages these features to further extend and simplify its customization potential. Using asset customization techniques outlined below you be able to adapt all the JavaScript, stylesheets and images contained in Spree to easily provide a fully custom experience.
-All Spree generated (or upgraded) applications include an <tt>app/assets</tt> directory (as is standard for all Rails 3.1 apps). We've taken this one step further by subdividing each top level asset directory (images, javascripts, stylesheets) into store and admin directories, this is designed to keep assets from the front end (store) and back end (admin) from conflicting with each other.
+All Spree generated (or upgraded) applications include an <tt>app/assets</tt> directory (as is standard for all Rails 3.1 apps). We've taken this one step further by subdividing each top level asset directory (images, JavaScript files, stylesheets) into store and admin directories. This is designed to keep assets from the front end (store) and back end (admin) from conflicting with each other.
A typical assets directory for a Spree application will look like:
@@ -35,12 +35,12 @@ A typical assets directory for a Spree application will look like:
| |-- admin
| |-- all.css</pre>
-Spree also generates four top level manifests (all.css & all.js, see above) that require all the core extension's and site specific stylesheets / javascripts.
+Spree also generates four top level manifests (all.css & all.js, see above) that require all the core extension's and site specific stylesheets / JavaScript files.
h4. How core extensions (engines) manage assets
-All core engines have been updated to provide four asset manifests that are responsible for bundling up all the javascripts and stylesheets required for that engine.
+All core engines have been updated to provide four asset manifests that are responsible for bundling up all the JavaScript files and stylesheets required for that engine.
For example, spree_core provides the following manifests:
@@ -66,15 +66,15 @@ These core (engine specific) manifests are included by default by the relevant a
//= require admin/spree_promo
//= require_tree .</css>
-External javascript libraries, stylesheets and images have also be relocated into vendor/assets (again Rails 3.1 standard approach), and all core extensions no longer have public directories.
+External JavaScript libraries, stylesheets and images have also be relocated into vendor/assets (again Rails 3.1 standard approach), and all core extensions no longer have public directories.
h3. Managing your application's assets
-All of your application's assets should be stored in the appropriate <tt>app/assets</tt>, <tt>lib/assets</tt> or <tt>vendor/assets</tt> sub-directory. All javascript and stylesheet files in <tt>app/assets</tt> sub-directories will be automatically included by the relevant all.(js|css) manifests.
+All of your application's assets should be stored in the appropriate <tt>app/assets</tt>, <tt>lib/assets</tt> or <tt>vendor/assets</tt> sub-directory. All JavaScript and stylesheet files in <tt>app/assets</tt> sub-directories will be automatically included by the relevant all.(js|css) manifests.
-Javascript & stylesheet files in <tt>lib/assets</tt> or <tt>vendor/assets</tt> sub-directories should be manually required in the appropriate all.(js|css) manifests.
+JavaScript & stylesheet files in <tt>lib/assets</tt> or <tt>vendor/assets</tt> sub-directories should be manually required in the appropriate all.(js|css) manifests.
INFO: Images will be served in development mode, or compiled into the public directory automatically in production mode.
@@ -91,13 +91,13 @@ For an example of an extension using a generator to install assets and migration
h3. Overriding Spree's core assets
-Overriding or replacing any of Spree's internal assets is even easier than before, it's recommended to attempt to replace as little as possible in a given javascript or stylesheet file to help ease future upgrade work required.
+Overriding or replacing any of Spree's internal assets is even easier than before. It's recommended to attempt to replace as little as possible in a given JavaScript or stylesheet file to help ease future upgrade work required.
The methods listed below will work for both applications, extensions and themes with one noticeable difference: Extension & theme asset files will not be automatically included (see above for instructions on how to include asset files from your extensions / themes).
-h4. Overriding individual css styles
+h4. Overriding individual CSS styles
-Say for example you want to replace the following, css snippet:
+Say for example you want to replace the following CSS snippet:
<css>
/* app/assets/stylesheets/store/screen.css */
@@ -120,17 +120,17 @@ div#footer {
The <tt>store/all.css</tt> manifest will automatically include <tt>foo.css</tt> and it will actually include both definitions with the one from <tt>foo.css</tt> being included last, hence it will be the rule applied.
-h4. Overriding entire css files
+h4. Overriding entire CSS files
To replace an entire stylesheet as provided by Spree you simply need to create a file with the same name and save it to the corresponding path within your application's or extension's <tt>app/assets/stylesheets</tt> directory.
-For example to replace <tt>store/all.css</tt> you would save the replacement to <tt>your_app/app/assets/stylesheets/store/all.css</tt>.
+For example, to replace <tt>store/all.css</tt> you would save the replacement to <tt>your_app/app/assets/stylesheets/store/all.css</tt>.
NOTE: This same method can be used to override stylesheets provided by third-party extensions.
-h4. Overriding individual javascript functions
+h4. Overriding individual JavaScript functions
-A similar approach can be used for javascript functions, for example if you wanted to override the <tt>show_variant_images</tt> method:
+A similar approach can be used for JavaScript functions. For example, if you wanted to override the <tt>show_variant_images</tt> method:
<javascript>
// app/assets/javascripts/store/product.js
@@ -153,7 +153,7 @@ A similar approach can be used for javascript functions, for example if you want
}
</javascript>
-Again, just create a new javascript file inside <tt>your_app/app/assets/stylesheets/store</tt> and include the new method definition:
+Again, just create a new JavaScript file inside <tt>your_app/app/assets/stylesheets/store</tt> and include the new method definition:
<javascript filename="app/assets/javascripts/store/foo.js">
// app/assets/javascripts/store/foo.js
@@ -163,19 +163,19 @@ Again, just create a new javascript file inside <tt>your_app/app/assets/styleshe
}
</javascript>
-The resulting <tt>store/all.js</tt> would include both methods, with the later being one executed on request.
+The resulting <tt>store/all.js</tt> would include both methods, with the latter being the one executed on request.
-h4. Overriding entire javascript files
+h4. Overriding entire JavaScript files
-To replace an entire javascript file as provided by Spree you simply need to create a file with the same name and save it to the corresponding path within your application's or extension's <tt>app/assets/javascripts</tt> directory.
+To replace an entire JavaScript file as provided by Spree you simply need to create a file with the same name and save it to the corresponding path within your application's or extension's <tt>app/assets/javascripts</tt> directory.
-For example to replace <tt>store/all.js</tt> you would save the replacement to <tt>your_app/app/assets/javascripts/store/all.js</tt>.
+For example, to replace <tt>store/all.js</tt> you would save the replacement to <tt>your_app/app/assets/javascripts/store/all.js</tt>.
-NOTE: This same method can be used to override javascript files provided by third-party extensions.
+NOTE: This same method can be used to override JavaScript files provided by third-party extensions.
h4. Overriding images
-Finally images can be replaced by substituting the required file into the same path within your application or extension as the file you would like to replace.
+Finally, images can be replaced by substituting the required file into the same path within your application or extension as the file you would like to replace.
For example, to replace the Spree logo you would simply copy your logo to: <tt>your_app/app/assets/images/admin/bg/spree_50.png</tt>.
View
63 source/creating_extensions.textile
@@ -17,17 +17,17 @@ There are a few basic steps to know when it comes to creating your own extension
h4. Integrated vs. Standalone
-Extensions can be created in their own standalone directory (like the ones shared on Github) or they can be created within your Rails application. We refer to the extensions that sit in an existing Rails application as "integrated" extensions.
+Extensions can be created in their own standalone directory (like the ones shared on GitHub) or they can be created within your Rails application. We refer to the extensions that sit in an existing Rails application as "integrated" extensions.
-Integrated extensions are usesful during the active development phase of your store. Instead of switching projects all of the time you can just make little tweaks to your extension inside of your store repo. Generally you would only do this if you intended to one day share the extension with someone else (or reuse it elsewhere in a private project.)
+Integrated extensions are useful during the active development phase of your store. Instead of switching projects all of the time you can just make little tweaks to your extension inside of your store repo. Generally you would only do this if you intended to one day share the extension with someone else (or reuse it elsewhere in a private project.)
-INFO: The distinction between standlone and integrated extensions is not very important. The instructions for this guide can be assumed to apply to both cases (unless stated otherwise.)
+INFO: The distinction between standalone and integrated extensions is not very important. The instructions for this guide can be assumed to apply to both cases (unless stated otherwise.)
NOTE: You may want to consider the integrated approach if the extension is potentially useful on another project but you don't want to make the extension publicly available for others to use.
h4. Creating
-You can create a new extension using the +spree+ command. This requires that you have a gem version of Spree installed that is version 0.70.0 or greater. Once you've navigated the directory in which you wish to create the extension, you can create a new extension by typing the following in your console:
+You can create a new extension using the +spree+ command. This requires that you have a gem version of Spree installed that is version 0.70.0 or greater. Once you've navigated to the directory in which you wish to create the extension, you can create a new extension by typing the following in your console:
<shell>
$ spree extension foofah
@@ -107,13 +107,13 @@ h3. Sharing Your Extension
h4. Publishing Your Source
-The first order of business is to get your extension on "Github":http://github.com where everybody can see it. Most importantly, you will want to allow others to have access to the source code. Github provides a convenient (and free) place to store your source code along with the ability to track issues and accept code patches.
+The first order of business is to get your extension on "GitHub":http://github.com where everybody can see it. Most importantly, you will want to allow others to have access to the source code. GitHub provides a convenient (and free) place to store your source code along with the ability to track issues and accept code patches.
-INFO: It is convention to use the +spree-+ naming convention for your Github repository and +spree_+ for your gem name. So for example, if you are creating a "foofah" extension the Github project would be named +spree-foofah+ and the gem would be +spree_foofah+.
+INFO: It is convention to use the +spree-+ naming convention for your GitHub repository and +spree_+ for your gem name. So for example, if you are creating a "foofah" extension the GitHub project would be named +spree-foofah+ and the gem would be +spree_foofah+.
h4. Publishing Your Gem
-If your extension is ready to be released into the wild you can publish it as a gem on "RubyGems.org":http://rubygems.org. Assuming you used the extension generator to build your extension, its already a gem and ready to be published. You'll just want to edit a few details in your gemspec file before you proceed.
+If your extension is ready to be released into the wild you can publish it as a gem on "RubyGems.org":http://rubygems.org. Assuming you used the extension generator to build your extension, it's already a gem and ready to be published. You'll just want to edit a few details in your gemspec file before you proceed.
<ruby>
s.name = 'foofah'
@@ -138,7 +138,7 @@ Spree is moving at a rapid pace with the code constantly evolving as new release
h4. Versionfile Basics
-+Versionfile+ is a plain text file which keeps information about which version of Spree an extension is compatible with. It was inspired by the +Gemfile+ used by bundler. Lets take a look at a sample +Versionfile+.
++Versionfile+ is a plain text file which keeps information about which version of Spree an extension is compatible with. It was inspired by the +Gemfile+ used by bundler. Let's take a look at a sample +Versionfile+.
<ruby>
"0.50.x" => { :branch => "master" }
@@ -149,15 +149,15 @@ The above +Versionfile+ is saying that if you are using Spree version "0.50.x" t
You should note that we are dealing with two different concepts of "version" here. One is the version of Spree supported and the other is the version of the extension.
-INFO: All Spree extensions should have a version. This version number has nothing to do with what version of Spree is supported. It is listed purely as a convenient way to refer to an extension. For example "I'm having a problem with spree_active_shipping 1.0.1"
+INFO: All Spree extensions should have a version. This version number has nothing to do with what version of Spree is supported. It is listed purely as a convenient way to refer to an extension. For example, "I'm having a problem with spree_active_shipping 1.0.1"
h4. Syntax
-A +Versionfile+ can have any number of lines. It is recommended that you put the latest Spree releases at the top. The very first thing a line should is the Spree version it is supporting. Next within curly braces how to get extension supporting the specified Spree version is mentioned.
+A +Versionfile+ can have any number of lines. It is recommended that you put the latest Spree releases at the top. The very first thing a line should include is the Spree version it is supporting. Next, within curly braces, how to get the extension supporting the specified Spree version.
-There are four different ways of specifying an extension's compatibilty information.
+There are four different ways of specifying an extension's compatibility information.
-NOTE: All four variations for identifying extension compatibility can be mapped to more than one Spree version. In other words, its entirely possible that the same version of an extension can be compatible with multiple versions of Spree.
+NOTE: All four variations for identifying extension compatibility can be mapped to more than one Spree version. In other words, it's entirely possible that the same version of an extension can be compatible with multiple versions of Spree.
*Gem Version*
@@ -165,7 +165,7 @@ NOTE: All four variations for identifying extension compatibility can be mapped
"0.30.x" => { :version => "1.2" }
</ruby>
-Above case is saying that if you are using Spree version "0.30.x" then use extension as a gem and the version of gem you should be using is "1.2".
+In the above case, if you are using Spree version "0.30.x" then use the extension as a gem and the version of gem you should be using is "1.2".
Gem versions are considered "stable." They will show up in the extension registry as such.
@@ -175,7 +175,7 @@ Gem versions are considered "stable." They will show up in the extension regist
"0.30.x" => { :branch => "0-30-stable" }
</ruby>
-Above case is telling that if you are using Spree version "0.30.x" then use branch named "0-30-stable". Notice that when you suggesting to use "branch" then "version" should not be specified.
+In the above example, if you are using Spree version "0.30.x" then use the branch named "0-30-stable". Notice that when you suggest the "branch" the "version" should not be specified.
Versions identified by Git branch are considered "unstable" or "edge." They will be identified as such in the extension registry.
@@ -185,7 +185,7 @@ Versions identified by Git branch are considered "unstable" or "edge." They wil
"0.30.x" => { :tag => "v0.30", :version => '1.1' }
</ruby>
-Above case is suggesting that if you are using Spree version "0.30.x" then use tag named "v0.30". The version information indicates that the author of the extension is calling that release as version "1.1".
+In this example, if you are using Spree version "0.30.x" then use the tag named "v0.30". The version information indicates that the author of the extension is calling that release as version "1.1".
Versions identified by tags are considered "stable." They will show up in the extension registry as such. This is also a nice alternative to having to release an extension as an actual gem.
@@ -195,7 +195,7 @@ Versions identified by tags are considered "stable." They will show up in the e
"0.30.x" => { :ref => "4aedfg", :version => '1.2' }
</ruby>
-Above case is suggesting that if you are using Spree version "0.30.x" then use ref named "4aedfg" . The version information indicates that the author of the extension is calling that release as version "1.2"
+In the above case, if you are using Spree version "0.30.x" then use ref named "4aedfg" . The version information indicates that the author of the extension is calling that release as version "1.2"
Versions identified by a Git SHA are considered "stable." They will show up in the extension registry as such. This is also a nice alternative to having to release an extension as an actual gem.
@@ -203,11 +203,11 @@ Versions identified by a Git SHA are considered "stable." They will show up in
#"0.30.x" => { :ref => "4aedfg", :version => '1.2' }
</ruby>
-Above case is indicating how you can comment out a line. A line beginning with hash "#" is treated as comment.
+The last example indicates how you can comment out a line. A line beginning with a hash "#" is treated as a comment.
h4. Using the Versionfile
-+Versionfile+ has no impact on the actual ability of an extension to work with Spree. It is simply a declaration by the extension author that a certain version of the extension is known to work with a particular version(s) of Spree. Its also possible that an extension version might be compatible with versions of Spree not listed. If you discover this to be the case please send a pull request to the extension author so they can update their +Versionfile+.
++Versionfile+ has no impact on the actual ability of an extension to work with Spree. It is simply a declaration by the extension author that a certain version of the extension is known to work with a particular version(s) of Spree. It's also possible that an extension version might be compatible with versions of Spree not listed. If you discover this to be the case please send a pull request to the extension author so they can update their +Versionfile+.
There is a crawler which crawls the +Versionfile+ of all the registered extensions once every day. So any changes you make to your extension's +Versionfile+ should be captured within 24 hours.
@@ -217,13 +217,13 @@ After the +Versionfile+ info has been processed you will see it listed in the "E
h4. Troubleshooting
-While parsing the lines gathered from +Versionfile+ if a line is invalid then that line is skipped. So make sure that entries in +Versionfile+ are valid. Soon we would be releasing a tool that can verify the +Versionfile+ and provide instant feedback if something is not right.
+While parsing the lines gathered from +Versionfile+ if a line is invalid then that line is skipped. So make sure that entries in +Versionfile+ are valid. We'll soon be releasing a tool that can verify the +Versionfile+ and provide instant feedback if something is not right.
h3. Testing Against a Release Candidate
The Spree core team will often announce a so-called "release candidate":http://en.wikipedia.org/wiki/Software_release_life_cycle#Release_candidate shortly before an official release. This is to allow Spree developers to test their sites and extensions against the upcoming release code.
-In order to test your extension against the release candidate you will need to first update your gemspec file. Lets look at how we would update the "spree_social":http://github.com/spree/spree_social gem to use the new 0.60.0.rc1 version of Spree. We'll need to modify +spree_social.gemspec+ as follows:
+In order to test your extension against the release candidate you will need to first update your gemspec file. Let's look at how we would update the "spree_social":http://github.com/spree/spree_social gem to use the new 0.60.0.rc1 version of Spree. We'll need to modify +spree_social.gemspec+ as follows:
<ruby>
Gem::Specification.new do |s|
@@ -240,13 +240,13 @@ You'll also want to update your +Gemfile+ that belongs to the Spree application
gem 'spree', '0.60.0.rc1'
</ruby>
-Next, you'll need to update the dependencies locally using bundler and commit the resulting +Gemfile.lock+ to your source code respository.
+Next, you'll need to update the dependencies locally using bundler and commit the resulting +Gemfile.lock+ to your source code repository.
<shell>
$ bundle update spree_social
</shell>
-Now its time to fire up Spree and make sure everything is working properly. Assuming everything looks good you'll also want to update the +Versionfile+ associated with your extension so that people can use the new and improved version.
+Now it's time to fire up Spree and make sure everything is working properly. Assuming everything looks good you'll also want to update the +Versionfile+ associated with your extension so that people can use the new and improved version.
In our example we're adding support for a new 0.60.0RC1 release candidate which is equivalent to 0.60.x in the extension directory.
@@ -255,22 +255,22 @@ In our example we're adding support for a new 0.60.0RC1 release candidate which
"0.50.x" => { :tag => "v1.0.2", :version => "1.0.2" }
</ruby>
-If we're not 100% sure the extension will support the release candidate (or if its a work in progress) we could reference the "edge" branch (ie. master) in the +Versionfile+ instead.
+If we're not 100% sure the extension will support the release candidate (or if it's a work in progress) we could reference the "edge" branch (i.e. master) in the +Versionfile+ instead.
<ruby>
"0.60.x" => { :branch => "master" }
"0.50.x" => { :tag => "v1.0.2", :version => "1.0.2" }
</ruby>
-INFO: Using a branch in the +Versionfile+ designates the gem as a "development release" which is possibly unstable and subject to change. Once things are stable you can point ot a specific Git SHA or tag so that people can rely on the extension not changing in a production release.
+INFO: Using a branch in the +Versionfile+ designates the gem as a "development release" which is possibly unstable and subject to change. Once things are stable you can point to a specific Git SHA or tag so that people can rely on the extension not changing in a production release.
h3. Extension Tutorial
-This tutorial assumes a basic familiarity with Spree extensions. For more detailed information on how extensions, please see the previous sections. The tutorial will, however, walk you through a complete example touching on all of the major aspects of an extension so if you like to learn through "step by step" instructions you may want to start here.
+This tutorial assumes a basic familiarity with Spree extensions. For more detailed information on how to use extensions, please see the previous sections. This tutorial will, however, walk you through a complete example touching on all of the major aspects of an extension. If you like to learn through "step by step" instructions you may want to start here.
h4. Getting Started
-Let’s start by building a simple extension. Suppose we want the ability to mark certain products as part of a promotion. We’d like to add an admin interface for marking certain items as being part of the promotion. We’d also like to highlight these products in our store view. This is a great example of how an extension can be used to build on the solid Spree foundation. Well be adding our own custom models, views, controllers, routes and locales via the new extension.
+Let’s start by building a simple extension. Suppose we want the ability to mark certain products as part of a promotion. We’d like to add an admin interface for marking certain items as being part of the promotion. We’d also like to highlight these products in our store view. This is a great example of how an extension can be used to build on the solid Spree foundation. We'll be adding our own custom models, views, controllers, routes and locales via the new extension.
We're going to assume you already have a functioning Spree application. If you have not yet achieved this you should read the "Getting Started Guide":getting_started.html first.
@@ -316,7 +316,7 @@ This creates a +spree_flag_promotions+ directory with several additional files a
h4. Creating a Resource
-Lets create a new +PromotedItem+ resource for our extension. Since Spree let us take advantage of normal Rails generators we can do this pretty easily.
+Let's create a new +PromotedItem+ resource for our extension. Since Spree lets us take advantage of normal Rails generators we can do this pretty easily.
First we'll make sure we have a test app created.
@@ -413,7 +413,7 @@ Please see the "View Customization":view_customization.html pages for details.
h4. Internationalization (I18n)
-Spree extensions can also provide their own locales/translations. If you're adding additional view text and you wish to support multiple locales, or if you are interested in sharing your extension with others, its a good idea to enable your extension with the i18n features of Spree.
+Spree extensions can also provide their own locales/translations. If you're adding additional view text and you wish to support multiple locales, or if you are interested in sharing your extension with others, it's a good idea to enable your extension with the i18n features of Spree.
In order to properly display the "Promoted Items" tab we'll need to provide an English localization in the +config/locales/en.yml+ file.
@@ -460,6 +460,7 @@ In order to configure these preferences within the extension, we must first inst
</ruby>
Now this preference can be accessed using *Spree::FlagPromotions::Config*
+
<ruby>
Spree::FlagPromotions::Config[:show_flags] = false
Spree::FlagPromotions::Config[:show_flags] #=> false
@@ -469,7 +470,7 @@ INFO: Please refer to the "Preferences":preferences.html#site_wide_preferences g
h4. Adding the Extension to Your Application
-Lets now add the extension to our application. We'll create a simple Spree application for this purpose just to illustrate how its done.
+Let's now add the extension to our application. We'll create a simple Spree application for this purpose just to illustrate how it's done.
We'll start by creating a new Rails app
@@ -487,13 +488,13 @@ gem 'spree_flag_promotions', :path => '../spree_flag_promotions'
</ruby>
-NOTE: This is a relative path to the 'spree_flag_promotions' directory. You could also refer to a git location or any other convention that is acceptable to bundler. See the "bundler site":http://gembundler.com for more details on bundler.
+NOTE: This is a relative path to the 'spree_flag_promotions' directory. You could also refer to a Git location or any other convention that is acceptable to bundler. See the "bundler site":http://gembundler.com for more details.
<shell>
$ bundle install
</shell>
-Now that the extension is setup its time to install (and then run) the migrations.
+Now that the extension is setup it's time to install (and then run) the migrations.
<shell>
$ rake railties:install:migrations
View
15 source/customization.textile
@@ -9,14 +9,13 @@ For more detailed information and a step-by-step tutorial on creating extensions
endprologue.
-h3. Managing Customizations
+h3. Managing Customizations
-Spree supports three methods for managing and organizing your customizations, while they all support exactly the same options for customization they differ in terms of re-usability. So before you get started you need to decide what sort of customizations you are going to make:
+Spree supports three methods for managing and organizing your customizations. While they all support exactly the same options for customization they differ in terms of re-usability. So before you get started you need to decide what sort of customizations you are going to make.
h4. Application Specific
-Application specific customizations are the most common type of customization applied to Spree, it's generally used by developers and designers to tweak Spree's behaviour or appearance to match a particular business's operating procedures, branding, or provide a unique feature.
-
+Application specific customizations are the most common type of customization applied to Spree. It's generally used by developers and designers to tweak Spree's behaviour or appearance to match a particular business's operating procedures, branding, or provide a unique feature.
All application specific customizations are stored within the host application where Spree is installed (please see the Installation section of the "Getting Started with Spree":getting_started.html guide, for how to setup the host application). Application customizations are not generally shared or re-used in anyway.
@@ -30,21 +29,21 @@ Visit the "Extension Registry":http://spreecommerce.com/extensions to get an ide
h4. Theme
-Themes are designed to overhaul the entire look and feel of a Spree store (or it's administration system). Themes are distributed in exactly the same manner as extensions, but don't generally include logic customizations.
+Themes are designed to overhaul the entire look and feel of a Spree store (or its administration system). Themes are distributed in exactly the same manner as extensions, but don't generally include logic customizations.
INFO: For more implementation details on Extensions and Themes please refer to the "Extensions & Themes":extensions.html guide.
h3. Customization Options
-Once you've decided how you're going to manage your customizations, you then need to choose the correct option to achieve the desired changes:
+Once you've decided how you're going to manage your customizations, you then need to choose the correct option to achieve the desired changes.
h4. View Customizations
-Allows you to change and/or extend the look and feel of a Spree store (and it's administration system). For details see the "View Customization":view_customization.html guide.
+Allows you to change and/or extend the look and feel of a Spree store (and its administration system). For details see the "View Customization":view_customization.html guide.
h4. Asset Customizations
-Allows changing the static assets provided by Spree, this includes Stylesheets, Javascripts and Images. For details see the "Asset Customization":asset_customization.html guide.
+Allows changing the static assets provided by Spree, this includes stylesheets, JavaScript files and images. For details see the "Asset Customization":asset_customization.html guide.
h4. Logic Customizations
View
11 source/extensions.textile
@@ -8,13 +8,14 @@ After this guide you should understand:
* The differences between extensions and themes
* How to install a third party extension
* How to install a third party theme
+
endprologue.
h3. The Basics
-Spree uses two terms: **extensions** and **themes** when referring to discrete packages of code (ruby, stylesheets, javascripts, etc), but the technical differences between the two are neglible:
+Spree uses two terms: **extensions** and **themes** when referring to discrete packages of code (ruby, stylesheets, JavaScript files, etc), but the technical differences between the two are negligible:
-* **Extensions** refer to discrete packages of code that provide new functionality to a Spree application, while extensions may affect the appearance of a Spree application they generally only provide additional interfaces to enable users to interact with the new functionality provided.
+* **Extensions** refer to discrete packages of code that provide new functionality to a Spree application. While extensions may affect the appearance of a Spree application they generally only provide additional interfaces to enable users to interact with the new functionality provided.
* **Themes** are discrete packages of code that **only** affect the appearance of a Spree application (and generally only the front-end store). Themes do not generally include any logic customizations.
@@ -62,7 +63,7 @@ Please see the "Source Code Guide":source_code.html for a more in-depth discussi
h3. Using Extensions
-Now that we've discussed some of the rationale behind extensions, its time to get started using them. You may also want to refer to the "Creating Extensions":creating_extensions.html guide for a tutorial that will walk you through a detailed example of creating and publishing your own extension.
+Now that we've discussed some of the rationale behind extensions, it's time to get started using them. You may also want to refer to the "Creating Extensions":creating_extensions.html guide for a tutorial that will walk you through a detailed example of creating and publishing your own extension.
h4. Installing an Extension or Theme
@@ -70,7 +71,7 @@ Since extensions/themes are created as engines in Rails, using them is as simple
WARNING: The dependencies should be specified in a specific order. Always specify +spree+, followed by the various spree extensions and then the required theme(s) at the very end of +Gemfile+. This is to ensure the proper classes are defined for extensions, and also so Deface Overrides are loaded in the proper order.
-WARNING: Prior to Spree 0.30.0 extensions were not managed as gems. They were typically installed from the command line using +script/extension install+. They were then added to the git repository of the application itself and deployed on the server. This is no longer supported. You must convert your old extension into a gem in order to use it in Spree.
+WARNING: Prior to Spree 0.30.0 extensions were not managed as gems. They were typically installed from the command line using +script/extension install+. They were then added to the Git repository of the application itself and deployed on the server. This is no longer supported. You must convert your old extension into a gem in order to use it in Spree.
h5. Modifying Your +Gemfile+
@@ -96,7 +97,7 @@ NOTE: Using the +path+ directive is an excellent option when actively developing
h5. Selecting the correct extension / theme version
-As Spree releases new versions the underlying code can change and this necessitates extensions and themes to be updated to account for the changes in Spree. To help match the correct version of an extension / theme with the Spree version you should refer to the <tt>Versionfile</tt>, normally located in the root of the engines git repository.
+As Spree releases new versions the underlying code can change and this necessitates extensions and themes to be updated to account for the changes in Spree. To help match the correct version of an extension / theme with the Spree version you should refer to the <tt>Versionfile</tt>, normally located in the root of the engine's Git repository.
The "Spree Extension Registry":http://spreecommerce.com/extensions also presents the contents of an engine's Versionfile, and suggests the correct line to add your Gemfile when you click on the "Install" link beside the relevant Spree version number.
View
14 source/logic_customization.textile
@@ -1,6 +1,6 @@
h2. Logic Customization
-This guide explains the how to customize the internal Spree code to meet your exact business requirements:
+This guide explains how to customize the internal Spree code to meet your exact business requirements including:
* Extending and overriding existing Spree models and controllers
* Changing the output from an existing Spree controller action
@@ -16,7 +16,7 @@ All of Spree's business logic (models, controllers, helpers, etc) can easily be
Standard practice for including such changes in your application or extension is to create a file within the relevant *app/models* or *app/controllers* directory with the original class name with **_decorator** appended.
-NOTE: To activate your decorators you need to include the follow code in your *lib/spree_site.rb* or *lib/extension_name.rb* file:
+NOTE: To activate your decorators you need to include the following code in your *lib/spree_site.rb* or *lib/extension_name.rb* file:
<ruby>
Dir.glob(File.join(File.dirname(__FILE__), "../app/**/*_decorator*.rb")) do |c|
@@ -76,9 +76,9 @@ The *respond_override* method is used to customize the response from any action,
{ :result => lambda { ... response ... } } }
</ruby>
-* *:action_name* - Can be any existing action within a controller (i.e. :update, :create, :new), provided that action is using respond_with to define it's response.
+* *:action_name* - Can be any existing action within a controller (i.e. :update, :create, :new), provided that action is using respond_with to define its response.
* *:format* - The format of the request, (i.e. :html, :json, :js, etc). All Spree controllers have a class level *respond_to* method call that defines which formats the controller's actions will respond to.
-* *:result* - Two possible results are available on any given response, :success or :failure. :success being the default for most actions, however actions that change or create models will have a :failure response if validation fails for the model being updated.
+* *:result* - Two possible results are available on any given response, :success or :failure. :success being the default for most actions. However, actions that change or create models will have a :failure response if validation fails for the model being updated.
* *lambda* - The lambda passed contains the actual code to create the desired custom response (i.e. render or redirect_to). A lambda must be passed to ensure the code is evaluated at the correct time.
h4. Example Usage
@@ -101,12 +101,12 @@ Or if you wanted to redirect on the failure to create in Admin::ProductsControll
h4. Caveats
-* If an action does not use *respond_with* to define it's response the *respond_override* will not work.
+* If an action does not use *respond_with* to define its response the *respond_override* will not work.
* Some actions contain several *respond_with* calls so any *respond_override* defined on it will be executed for any of the *respond_with* instances, so it's important to check the model state / logic within the lambda passed to prevent overriding all possible responses with the same override.
h3. Product Images
-Spree uses Thoughtbot's "paperclip":https://github.com/thoughtbot/paperclip gem to manage images for products. All the normal paperclip options are available on the Image class. If you want to modify the default spree product and thumbnail image sizes, simply create an image_decorator.rb file in your app model directory, and override the attachment sizes:
+Spree uses Thoughtbot's "paperclip":https://github.com/thoughtbot/paperclip gem to manage images for products. All the normal paperclip options are available on the Image class. If you want to modify the default Spree product and thumbnail image sizes, simply create an image_decorator.rb file in your app model directory, and override the attachment sizes:
<ruby>
Spree::Image.class_eval do
@@ -124,5 +124,5 @@ You may also add additional image sizes for use in your templates (:micro for sh
h4. Image resizing option syntax
Default behavior is to resize the image and maintain aspect ratio (i.e. the :product version of a 480×400 image will be 240×200). Some commonly used options are:
- * trailing #, image will be centrally cropped, ensuring the requested dimensions.
+ * trailing #, image will be centrally cropped, ensuring the requested dimensions
* trailing >, image will only be modified if it is currently larger than the requested dimensions. (i.e. the :small thumb for a 100×100 original image will be unchanged)
View
30 source/view_customization.textile
@@ -1,6 +1,6 @@
h2. View Customization
-View customization allows you to extend or replace any view within a Spree store and this guide explains the options available, including:
+View customization allows you to extend or replace any view within a Spree store. This guide explains the options available, including:
* Using Deface for view customization
* Replacing entire view templates
@@ -64,14 +64,14 @@ Deface applies an __action__ to element(s) matching the supplied CSS selector. T
Deface currently supports the following actions:
* <tt>:remove</tt> - Removes all elements that match the supplied selector
-* <tt>:replace</tt> - Replaces all elements that match the supplied selector, with the content supplied.
+* <tt>:replace</tt> - Replaces all elements that match the supplied selector, with the content supplied
* <tt>:insert_after</tt> - Inserts content supplied after all elements that match the supplied selector
* <tt>:insert_before</tt> - Inserts content supplied before all elements that match the supplied selector
-* <tt>:insert_top</tt> - Inserts content supplied inside all elements that match the supplied selector, as the first child.
-* <tt>:insert_bottom</tt> - Inserts content supplied inside all elements that match the supplied selector, as the last child.
-* <tt>:set_attributes</tt> - Sets (or adds) attributes to all elements that match the supplied selector, expects :attributes option to be passed.
+* <tt>:insert_top</tt> - Inserts content supplied inside all elements that match the supplied selector, as the first child
+* <tt>:insert_bottom</tt> - Inserts content supplied inside all elements that match the supplied selector, as the last child
+* <tt>:set_attributes</tt> - Sets (or adds) attributes to all elements that match the supplied selector, expects :attributes option to be passed
-NOTE: Not all actions are applicable to all elements, for example <tt>:insert_top</tt> and <tt>:insert_bottom</tt> expects a parent element with children.
+NOTE: Not all actions are applicable to all elements. For example, <tt>:insert_top</tt> and <tt>:insert_bottom</tt> expects a parent element with children.
h4. Supplying content
@@ -87,9 +87,9 @@ h4. Targeting elements
While Deface allows you to use a large subset of CSS3 style selectors (as provided by Nokogiri), the majority of Spree's views have been updated to include a custom HTML attribute (<tt>data-hook</tt>), which is designed to provide consistent targets for your overrides to use.
-As Spree views are changed over coming versions, the original html elements maybe edited or be removed. We will endeavour to ensure that data-hook / id combination will remain consistent within any single view file (where possible), thus making your overrides more robust and upgrade proof.
+As Spree views are changed over coming versions, the original HTML elements maybe edited or be removed. We will endeavour to ensure that data-hook / id combination will remain consistent within any single view file (where possible), thus making your overrides more robust and upgrade proof.
-For example spree/products/show.html.erb looks as follows:
+For example, spree/products/show.html.erb looks as follows:
<ruby>
<div data-hook="product_show" itemscope itemtype="http://schema.org/Product">
@@ -146,7 +146,7 @@ As you can see from the example above the <tt>data-hook</tt> can be present in a
* On elements with an <tt>id</tt> attribute the <tt>data-hook</tt> attribute does **not** normally contain a value.
* Occasionally on elements with an <tt>id</tt> attribute the <tt>data-hook</tt> will contain a value different from the elements id. This is generally to support migration from the old 0.60.x style of hooks, where the old hook names were converted into <tt>data-hook</tt> versions.
-The suggested way to target an element is to use the <tt>data-hook</tt> attribute wherever possible, here are a few examples based on **products/show.html.erb** above:
+The suggested way to target an element is to use the <tt>data-hook</tt> attribute wherever possible. Here are a few examples based on **products/show.html.erb** above:
<ruby>
:replace => "[data-hook='product_show']"
@@ -203,7 +203,7 @@ h4. View upgrade protection
To ensure upgrading between versions of Spree is as painless as possible, Deface supports an <tt>:original</tt> option that can contain a string of the original content that's being replaced. When Deface is applying the override it will ensure that the current source matches the value supplied and will output to the Rails application log if they are different.
-These warnings are good indicator that you need to review the source and ensure your replacement is adequately replacing all the functionality provided by Spree, this will help reduce unexpected issues after upgrades.
+These warnings are a good indicator that you need to review the source and ensure your replacement is adequately replacing all the functionality provided by Spree. This will help reduce unexpected issues after upgrades.
Once you've reviewed the new source you can update the <tt>:original</tt> value to new source to clear the warning.
@@ -217,23 +217,23 @@ NOTE: Using this method will ensure your overrides are compatible with future th
h4. More information on Deface
-For more information and sample overrides please refer to it's "README":https://github.com/railsdog/deface file on Github.
+For more information and sample overrides please refer to its "README":https://github.com/railsdog/deface file on GitHub.
You can also see how Deface internals work, and test selectors using the "Deface Test Harness":http://deface.heroku.com application.
h3. Template Replacements
-Sometimes the customization required to a view are so substantial that using a Deface override seems impractical, Spree also supports the duplication of views within an application or extension that will completely replace the file of the same name in Spree.
+Sometimes the customization required to a view are so substantial that using a Deface override seems impractical. Spree also supports the duplication of views within an application or extension that will completely replace the file of the same name in Spree.
-To override any of Sprees default views including those for the admin interface, simply create a file with the same filename in your app/views directory.
+To override any of Spree's default views including those for the admin interface, simply create a file with the same filename in your app/views directory.
For example, to override the main layout, create the file YOUR_SITE_OR_EXTENSION/app/views/spree/layouts/spree_application.html.erb
-INFO: It's important to ensure you copy the correct version of a view into your application or extension, as copying a mismatched version could lead to hard to debug issues. We suggest using <tt>bundle show spree</tt> to get location of the Spree code your actually running and then copying the relevant file from there.
+INFO: It's important to ensure you copy the correct version of a view into your application or extension, as copying a mismatched version could lead to hard to debug issues. We suggest using <tt>bundle show spree</tt> to get the location of the Spree code you're actually running and then copying the relevant file from there.
h4. Drawbacks of template replacements
Whenever you copy an entire view into your extension or application you are adding a significant maintenance overhead to your application when it comes to upgrading to newer versions of Spree. When upgrading between versions you need to compare each template that's been replaced to ensure to replicate any changes from the newer Spree version in your locally copied version.
-To this end we strongly suggest you use Deface to achieve the desired customizations wherever possible.
+To this end we strongly suggest you use Deface to achieve the desired customizations wherever possible.
Please sign in to comment.
Something went wrong with that request. Please try again.