Add configuration guide #1607

mamhoff · 2016-11-23T12:14:32Z

This commit adds a very high-level guide to some of the ways
it's possible to customize Solidus:

Configuration options
Overriding templates
Changing assets
Installing extensions
Custom service classes
Monkey-Patching Solidus
Run a private fork

While we like some of these methods better than others, I think it's
important for beginners to understand their options.

tvdeyen

Great work! Added some notes below, though

tvdeyen · 2016-11-23T13:03:23Z

guides/configuration.md

+
+When you first setup a Rails app with Solidus installed, you will want to customize its looks and behaviour to fit your company's needs. Solidus can be customized in six ways:
+
+* Configuration options


Is it possible to link these?

tvdeyen · 2016-11-23T13:04:20Z

guides/configuration.md

+
+You will most probably use at least methods 1-4, and most shops we know also use some combination of the last three.
+
+As Solidus is an Engine, much of what the [Spree Guide on using Engines](http:https://guides.rubyonrails.org/engines.html) explains applies directly to Solidus.


~~Spree~~ Guide on using Engines

Rails Guide on using Engines

tvdeyen · 2016-11-23T13:07:24Z

guides/configuration.md

+
+## Configuration options
+
+Since Solidus is a [Rails Engine](http:https://guides.rubyonrails.org/engines.html), much of its behaviour can be customized through the Solidus initializer. After you have run the `rails g spree:install` generator, this initializer will live in `config/initializers/spree.rb`. Open this file, and have a look at the first block (comments left out):


Maybe explaining the spree vs. solidus incidence in the introductory section would be helpful to understand the differing file names especially for the unaware.

tvdeyen · 2016-11-23T13:10:03Z

guides/configuration.md

+
+Of course, it the template you wish to modify references other template files, you can override those, too. For example, the product list references a shared partial `app/views/spree/shared/_products.html.erb` - you can find it [here](https://github.com/solidusio/solidus/blob/master/frontend/app/views/spree/shared/_products.html.erb) and also override it in your host app.
+
+When you override a view from a Gem, there is the possibility of difficulties when upgrading, because Controller code within the Gem might have changed, such as for example the name of an instance variable. Be careful when upgrading, and always read `CHANGELOG.md`.


Maybe mark this as side note or tip

tvdeyen · 2016-11-23T13:11:01Z

guides/configuration.md

+
+### In the backend
+
+We do not recommend overriding the admin backend in the same way, since some of the extensions you might be running (see below) depend on them having the HTML structure present in the version of Solidus they were built for. If you need to add custom functionality to Solidus' backend, we recommend using the `Deface` gem. Find it [here](https://github.com/spree/deface). Overriding backend views with Deface is tricky - be sure to have good tests!


Do we recommend the usage of Deface?

tvdeyen · 2016-11-23T13:14:50Z

guides/configuration.md

+
+The Solidus configuration object from above has some getters and setters for classes as extension points. After evaluating whether you need to go down this route, take some time to study the standard implementation for the class you want to modify, and subclass or re-implement it. The service class extension points can be found [here](https://github.com/solidusio/solidus/blob/master/core/app/models/spree/app_configuration.rb#L277-L383).
+
+These extension points can alter Solidus' behaviour quite drastically. If you make mistakes when implementing them, your store will break. Good luck!


Nah, this is too harsh. I think we can just remove this line

tvdeyen · 2016-11-23T13:16:26Z

guides/configuration.md

+For example, if you want to add a method to the `Spree::Order` model, you would have a file called `app/models/spree/order_decorator.rb` with the following contents:
+
+```
+module Spree


It's not necessary to use the Spree module namespace and can even lead to strange issues.

Maybe just use none or module YourStore

tvdeyen · 2016-11-23T13:17:00Z

guides/configuration.md

+ end
+end
+
+Spree::Order.prepend Spree::OrderDecorator


Great usage of Module.prepend

"No more class_eval" 👌

tvdeyen · 2016-11-23T13:17:34Z

guides/configuration.md

+Spree::Order.prepend Spree::OrderDecorator
+```
+
+This creates a new module called `Spree::OrderDecorator` and will insert its methods so early in the method lookup chain that the decorator's methods overwrite the original order class's methods.


I think you don't need to explain Module.prepend here. Maybe link to a good article?

tvdeyen · 2016-11-23T13:17:56Z

guides/configuration.md

+
+From now on, every order, when asked for its total, will return the string "One Million Dollars". This particular decorator would, by the way, definitely break a large part of Solidus' functionality as `Spree::Order#total` is expected to return a `BigDecimal`, not a `String`.
+
+If you do this kind of thing, be very careful and test your new functionality very well. If you do upgrades, read extra carefully about changes in Solidus' core classes.


Also mark this as "tip" or "side note"?

tvdeyen

Very nice!

Not mandatory, but syntax highlighting would be 🍨

tvdeyen · 2016-11-24T17:39:38Z

guides/configuration.md

+
+If you do this kind of thing, be very careful and test your new functionality very well. If you do upgrades, read extra carefully about changes in Solidus' core classes.
+
+## Run a private fork (and submit us a Pull Request!)


Could you please remove the call for pull requests? This is a little bit too "loud" ;)

This breaks the link at the top, as well.

This commit adds a very high-level guide to some of the ways it's possible to customize Solidus: * Configuration options * Overriding templates * Changing assets * Installing extensions * Custom service classes * Monkey-Patching Solidus * Run a private fork While we like some of these methods better than others, I think it's important for beginners to understand their options.

tvdeyen

This is now 💯 🎯

jhawthorn

Great!

tvdeyen reviewed Nov 23, 2016

View reviewed changes

mamhoff force-pushed the add-config-guide branch from 0f9ea3b to 6563204 Compare November 23, 2016 20:00

tvdeyen approved these changes Nov 24, 2016

View reviewed changes

tvdeyen requested changes Nov 24, 2016

View reviewed changes

mamhoff force-pushed the add-config-guide branch from 6563204 to af608df Compare November 25, 2016 13:15

tvdeyen approved these changes Nov 25, 2016

View reviewed changes

jhawthorn approved these changes Nov 25, 2016

View reviewed changes

jhawthorn merged commit 33ee15e into solidusio:master Nov 25, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add configuration guide #1607

Add configuration guide #1607

mamhoff commented Nov 23, 2016

tvdeyen left a comment

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen Nov 23, 2016

tvdeyen left a comment

tvdeyen Nov 24, 2016

cbrunsdon Nov 25, 2016

tvdeyen left a comment

jhawthorn left a comment


		When you first setup a Rails app with Solidus installed, you will want to customize its looks and behaviour to fit your company's needs. Solidus can be customized in six ways:

		* Configuration options


		You will most probably use at least methods 1-4, and most shops we know also use some combination of the last three.

		As Solidus is an Engine, much of what the [Spree Guide on using Engines](http:https://guides.rubyonrails.org/engines.html) explains applies directly to Solidus.


		## Configuration options

		Since Solidus is a [Rails Engine](http:https://guides.rubyonrails.org/engines.html), much of its behaviour can be customized through the Solidus initializer. After you have run the `rails g spree:install` generator, this initializer will live in `config/initializers/spree.rb`. Open this file, and have a look at the first block (comments left out):


		Of course, it the template you wish to modify references other template files, you can override those, too. For example, the product list references a shared partial `app/views/spree/shared/_products.html.erb` - you can find it [here](https://github.com/solidusio/solidus/blob/master/frontend/app/views/spree/shared/_products.html.erb) and also override it in your host app.

		When you override a view from a Gem, there is the possibility of difficulties when upgrading, because Controller code within the Gem might have changed, such as for example the name of an instance variable. Be careful when upgrading, and always read `CHANGELOG.md`.


		### In the backend

		We do not recommend overriding the admin backend in the same way, since some of the extensions you might be running (see below) depend on them having the HTML structure present in the version of Solidus they were built for. If you need to add custom functionality to Solidus' backend, we recommend using the `Deface` gem. Find it [here](https://github.com/spree/deface). Overriding backend views with Deface is tricky - be sure to have good tests!


		The Solidus configuration object from above has some getters and setters for classes as extension points. After evaluating whether you need to go down this route, take some time to study the standard implementation for the class you want to modify, and subclass or re-implement it. The service class extension points can be found [here](https://github.com/solidusio/solidus/blob/master/core/app/models/spree/app_configuration.rb#L277-L383).

		These extension points can alter Solidus' behaviour quite drastically. If you make mistakes when implementing them, your store will break. Good luck!


		From now on, every order, when asked for its total, will return the string "One Million Dollars". This particular decorator would, by the way, definitely break a large part of Solidus' functionality as `Spree::Order#total` is expected to return a `BigDecimal`, not a `String`.

		If you do this kind of thing, be very careful and test your new functionality very well. If you do upgrades, read extra carefully about changes in Solidus' core classes.


		If you do this kind of thing, be very careful and test your new functionality very well. If you do upgrades, read extra carefully about changes in Solidus' core classes.

		## Run a private fork (and submit us a Pull Request!)

Add configuration guide #1607

Add configuration guide #1607

Conversation

mamhoff commented Nov 23, 2016

tvdeyen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tvdeyen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tvdeyen left a comment

Choose a reason for hiding this comment

jhawthorn left a comment

Choose a reason for hiding this comment