workarea 3.4.12

data/docs/source/articles/commerce-model.html.md

@@ -0,0 +1,164 @@
+---
+title: Commerce Model
+excerpt: The following diagram is a model of commerce from Workarea's perspective.
+---
+
+Commerce Model
+======================================================================
+
+The following diagram is a model of _commerce_ from Workarea's perspective.
+In this model, Workarea receives _catalog data_ as input and returns _order data_ as output.
+Activity within Workarea is represented as a cycle of actions, some of which are completed by _administrators_ within the _Admin_; the rest by _shoppers_ within the _Storefront_.
+
+(
+Keep in mind this model is an abstraction of the Workarea system.
+In practice, catalog and order data are not the only input/output, and actions within the system are non-linear and asynchronous.
+)
+
+![Commerce Model](../images/commerce-model.png)
+
+
+Code Mappings
+----------------------------------------------------------------------
+
+Use this illustration of Workarea to improve your mental model of the system.
+Keep this representation of Workarea in mind when reading Workarea code and documentation.
+
+To help you in this regard, the following sections map the actions from the diagram to relevant _models_, _view models_, and _services_ within the base Workarea platform.
+(These object types are those used to write to and read from the primary data store.)
+
+Each section provides a command which you can run from the root of your application to list the pathnames of the relevant files within your version of Workarea.
+
+
+### Admins Manage Catalog
+
+```bash
+echo "
+$(bundle show workarea-core)/app/models/workarea/catalog/product.rb
+$(bundle show workarea-core)/app/models/workarea/catalog/variant.rb
+$(bundle show workarea-core)/app/models/workarea/catalog/product_image.rb
+$(bundle show workarea-core)/app/models/workarea/pricing/sku.rb
+$(bundle show workarea-core)/app/models/workarea/pricing/price.rb
+$(bundle show workarea-core)/app/models/workarea/inventory/sku.rb
+$(bundle show workarea-core)/app/models/workarea/shipping/sku.rb
+$(bundle show workarea-core)/app/services/workarea/copy_product.rb
+$(bundle show workarea-core)/app/models/workarea/shipping/service.rb
+$(bundle show workarea-core)/app/models/workarea/shipping/rate.rb
+$(bundle show workarea-core)/app/models/workarea/tax/category.rb
+$(bundle show workarea-core)/app/models/workarea/tax/rate.rb
+"
+```
+
+
+### Admins Merchandise Store
+
+```bash
+echo "
+$(bundle show workarea-core)/app/models/workarea/release.rb
+$(bundle show workarea-core)/app/models/workarea/release/changeset.rb
+$(bundle show workarea-core)/app/models/workarea/catalog/category.rb
+$(bundle show workarea-core)/app/models/workarea/product_rule.rb
+$(bundle show workarea-core)/app/models/workarea/search/settings.rb
+$(bundle show workarea-core)/app/models/workarea/search/customization.rb
+$(bundle show workarea-core)/app/models/workarea/content.rb
+$(bundle show workarea-core)/app/models/workarea/content/page.rb
+$(bundle show workarea-core)/app/models/workarea/content/block.rb
+$(bundle show workarea-core)/app/models/workarea/content/asset.rb
+$(bundle show workarea-core)/app/models/workarea/navigation/redirect.rb
+$(bundle show workarea-core)/app/models/workarea/navigation/taxon.rb
+$(bundle show workarea-core)/app/models/workarea/navigation/menu.rb
+$(bundle show workarea-core)/app/models/workarea/recommendation/settings.rb
+$(bundle show workarea-core)/app/models/workarea/pricing/discount.rb
+"
+```
+
+
+### Shoppers Search & Browse Products
+
+```bash
+echo "
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/category_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/search_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/search_suggestion_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/page_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/content_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/menu_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/recommendations_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/product_view_model.rb
+"
+```
+
+### Shoppers View Products
+
+```bash
+echo "
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/product_view_model.rb
+"
+```
+
+
+### Shoppers Create & Manage Carts
+
+```bash
+echo "
+$(bundle show workarea-core)/app/models/workarea/order.rb
+$(bundle show workarea-core)/app/models/workarea/order/item.rb
+$(bundle show workarea-core)/app/models/workarea/pricing.rb
+$(bundle show workarea-core)/app/models/workarea/price_adjustment.rb
+$(bundle show workarea-core)/app/models/workarea/pricing/calculator.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/cart_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/cart_item_view_model.rb
+"
+```
+
+### Shoppers Place Orders
+
+```bash
+echo "
+$(bundle show workarea-core)/app/models/workarea/checkout.rb
+$(bundle show workarea-core)/app/models/workarea/checkout/steps/base.rb
+$(bundle show workarea-core)/app/models/workarea/payment.rb
+$(bundle show workarea-core)/app/models/workarea/payment/transaction.rb
+$(bundle show workarea-core)/app/models/workarea/inventory.rb
+$(bundle show workarea-core)/app/models/workarea/inventory/transaction.rb
+$(bundle show workarea-core)/app/models/workarea/inventory/transaction_item.rb
+$(bundle show workarea-core)/app/models/workarea/shipping.rb
+$(bundle show workarea-core)/app/models/workarea/shipping/service_selection.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/order_view_model.rb
+$(bundle show workarea-storefront)/app/view_models/workarea/storefront/order_item_view_model.rb
+$(bundle show workarea-core)/app/models/workarea/pricing/discount/redemption.rb
+$(bundle show workarea-core)/app/services/workarea/create_fulfillment.rb
+"
+```
+
+
+### Admins Manage Orders
+
+```bash
+echo "
+$(bundle show workarea-core)/app/models/workarea/fulfillment.rb
+$(bundle show workarea-core)/app/models/workarea/fulfillment/item.rb
+$(bundle show workarea-core)/app/models/workarea/fulfillment/event.rb
+$(bundle show workarea-core)/app/models/workarea/fulfillment/package.rb
+$(bundle show workarea-core)/app/models/workarea/pricing/override.rb
+$(bundle show workarea-core)/app/models/workarea/pricing/request.rb
+$(bundle show workarea-core)/app/models/workarea/payment/refund.rb
+$(bundle show workarea-core)/app/services/workarea/cancel_order.rb
+$(bundle show workarea-core)/app/services/workarea/copy_order.rb
+"
+```
+
+
+### Admins View Insights & Reports
+
+```bash
+echo "
+$(bundle show workarea-core)/app/models/workarea/metrics/by_day.rb
+$(bundle show workarea-core)/app/models/workarea/metrics/by_week.rb
+$(bundle show workarea-core)/app/models/workarea/insights/base.rb
+$(bundle show workarea-admin)/app/view_models/workarea/admin/insight_view_model.rb
+$(bundle show workarea-admin)/app/view_models/workarea/admin/reports/insights_view_model.rb
+$(bundle show workarea-core)/app/models/workarea/reports/export.rb
+$(bundle show workarea-core)/app/services/workarea/export_report.rb
+"
+```

data/docs/source/articles/configuration-for-hosting.html.md

@@ -0,0 +1,106 @@
+---
+title: Configuration for Hosting
+excerpt: How to configure Workarea for hosting in practice.
+---
+
+# Configuration for Hosting
+
+Here's what you'll need to configure Workarea for hosting. It'll outline commonly set configurations and why. To learn more about Workarea infrastructure configuration, check out the code here: [https://github.com/workarea-commerce/workarea/tree/master/core/lib/workarea/configuration](https://github.com/workarea-commerce/workarea/tree/master/core/lib/workarea/configuration).
+
+## Application
+
+### Web
+
+Workarea ships with a [default Puma configuration](https://github.com/workarea-commerce/workarea/blob/master/core/lib/workarea/configuration/puma.rb) out-of-the-box. If you want to configure this, remove the custom Workarea config from your `config/puma.rb`. Workarea will respect the following Puma environment variables if set:
+
+| Name | Default | Notes |
+|---|---|---|
+| `PORT` | `3000` | - |
+| `RAILS_MAX_THREADS` | `5` | - |
+| `RAILS_ENV` | `development` | - |
+| `WEB_CONCURRENCY` | | - |
+
+### Sidekiq
+
+Workarea will automatically configure Sidekiq based on the other Workarea configuration (like Redis).
+
+| Name | Default | Notes |
+|---|---|---|
+| `WORKAREA_SIDEKIQ_CONCURRENCY` | Dynamic | Based on number of processes |
+| `WORKAREA_SIDEKIQ_DEFAULT_TIMEOUT` | `5` |
+
+_Note:_ Workarea will not try to configure Sidekiq if `config/sidekiq.yml` or `config/sidekiq.yml.erb` are present.
+
+## Databases
+
+### MongoDB
+
+Workarea automatically configures Mongoid for you with the recommended settings. No further action is required. However, settings provided in `config/mongoid.yml` will override the default Workarea configuration. Doing this is discouraged.
+
+Workarea uses two different instances of `Mongoid::Client`, one for primary application use, and one specifically for metrics collection. This is done to allow sharding metrics/reporting from standard application use.
+
+| Name | Default | Notes |
+|---|---|---|
+| `WORKAREA_MONGOID_HOST_0` | `localhost:27017` | increment `0` for each host |
+| `WORKAREA_MONGOID_OPTIONS` | `{}` | JSON-serialized [options for Mongoid](https://docs.mongodb.com/mongoid/current/tutorials/mongoid-installation/#anatomy-of-a-mongoid-config) |
+| `WORKAREA_MONGOID_METRICS_HOST_0` | `localhost:27017` | increment `0` for each host |
+| `WORKAREA_MONGOID_METRICS_OPTIONS` | `{}` | JSON-serialized [options for Mongoid](https://docs.mongodb.com/mongoid/current/tutorials/mongoid-installation/#anatomy-of-a-mongoid-config) |
+
+You can configure hosts using `WORKAREA_MONGOID_HOST_*` environment variables. You can add as many hosts as desired, just be sure to end the environment variable names with digits, e.g. `WORKAREA_MONGOID_HOST_0`, `WORKAREA_MONGOID_HOST_1`, `WORKAREA_MONGOID_HOST_2`, etc.
+
+### Elasticsearch
+
+You can set an arbitrary number of Elasticsearch hosts for Workarea to use, or simply specify one (perhaps behind a load balancer).
+
+| Name | Default | Notes |
+|---|---|---|
+| `WORKAREA_ELASTICSEARCH_URL_0` | `localhost:9200` | increment `0` for each host |
+| `WORKAREA_ELASTICSEARCH_URL` | `localhost:9200` | used if the digit-trailing vars are blank |
+
+You can configure hosts using `WORKAREA_ELASTICSEARCH_URL_*` environment variables. You can add as many hosts as desired, just be sure to end the environment variable names with digits, e.g. `WORKAREA_ELASTICSEARCH_URL_0`, `WORKAREA_ELASTICSEARCH_URL_1`, `WORKAREA_ELASTICSEARCH_URL_2`, etc.
+
+### Redis
+
+While only one instance of Redis is _required_ to run Workarea, you can run two for distributing load. The first would be for persistent data like the Sidekiq queue or recommendations. The second is for ephemeral data like cache.
+
+| Name | Default | Notes |
+|---|---|---|
+| `WORKAREA_REDIS_HOST` | `localhost` | host for persistent Redis |
+| `WORKAREA_REDIS_PORT` | `6379` | port for persistent Redis |
+| `WORKAREA_REDIS_DB` | `0` | database for persistent Redis |
+| `WORKAREA_REDIS_CACHE_HOST` | `localhost` | host for ephemeral Redis |
+| `WORKAREA_REDIS_CACHE_PORT` | `6379` | port for ephemeral Redis |
+| `WORKAREA_REDIS_CACHE_DB` | `0` | database for ephemeral Redis |
+
+## Miscellaneous
+
+### Assets
+
+You'll need at least one S3 bucket setup to run Workarea. An optional second (called the "integration" bucket in the code) can be configured for integrating with other systems, like flat-file exports, image imports, etc.
+
+| Name | Default | Notes |
+|---|---|---|
+| `WORKAREA_S3_REGION` | `us-east-1` | - |
+| `WORKAREA_S3_ACCESS_KEY_ID` | | if this is blank _and_ the secret access key is blank, Workarea will use the IAM profile |
+| `WORKAREA_S3_SECRET_ACCESS_KEY` | | if this is blank _and_ the access key ID is blank, Workarea will use the IAM profile |
+| `WORKAREA_S3_BUCKET_NAME` | | - |
+| `WORKAREA_S3_INTEGRATION_REGION` | | (optional) |
+| `WORKAREA_S3_INTEGRATION_ACCESS_KEY_ID` | | (optional) |
+| `WORKAREA_S3_INTEGRATION_SECRET_ACCESS_KEY` | | (optional) |
+| `WORKAREA_S3_INTEGRATION_BUCKET_NAME` | | (optional) |
+
+### Asset Host
+
+Workarea ships with support for the asset host as an environment variable. This sets the Rails configurations to this value.
+
+| Name | Default | Notes |
+|---|---|---|
+| `WORKAREA_ASSET_HOST` | | set this to your CDN |
+
+### Logstash
+
+Workarea depends on the [logstasher gem](https://github.com/shadabahmed/logstasher) to provide [Logstash](https://www.elastic.co/products/logstash) support out-of-the-box. This will only be enabled if the environment variable is set.
+
+| Name | Default | Notes |
+|---|---|---|
+| `WORKAREA_LOGSTASH` | | set this to `true` to enable `logstasher` |

data/docs/source/articles/configuration.html.md

@@ -0,0 +1,406 @@
+---
+title: Configuration
+excerpt: Every Workarea application has Ruby and JavaScript configurations, which consist of customizable named values that provide designed extension points for the application and its installed plugins. Configuration, as an extension technique, is the proces
+---
+
+# Configuration
+
+Every Workarea application has Ruby and JavaScript configurations, which consist of customizable named values that provide designed extension points for the application and its installed plugins. <dfn>Configuration</dfn>, as an extension technique, is the process of customizing configuration keys, known informally as <dfn>configs</dfn>, and their values.
+
+Configuration allows _developers_ to customize an application beyond the capabilities of administrators. Because configs are _designed_ extension points, configuration is less expensive than other extension techniques, which require developers to extend the platform beyond its original design.
+
+## Configuration Objects
+
+Ruby and JavaScript configuration objects provide access to the current configuration of the application and allow developers to change the configuration.
+
+### Ruby Configuration Object
+
+Use `Workarea.config` to access the current Ruby configuration. The configuration object is hash-like (composed of keys and values) and also provides an accessor method for each key. This configuration object is actually a member of the Rails configuration, which is covered in more detail below.
+
+The following example, which I ran in a Rails console, lists all the configs for my sample application.
+
+```ruby
+puts Workarea.config.keys.sort
+# activity_excluded_types
+# activity_size_on_dashboard
+# address_attributes
+# admin_break_points
+# admin_max_most_visited
+# admin_max_recently_visited
+# admin_session_timeout
+# admin_visit_excluded_paths
+# allowed_login_attempts
+# analytics_timezone
+# asset_store
+# asset_types
+# blog_entries_on_index
+# bulk_action_expiration
+# cache_expirations
+# cart_recommendations_count
+# category_summary_product_count
+# checkout_expiration
+# checkout_steps
+# clothing_swatch_size
+# ... (truncated)
+# user_activity_display_size
+```
+
+The config object contains _all_ platform configs, including those added as extensions by installed plugins.
+
+The next example examines the values of several keys, demonstrating the varying complexity of configuration values.
+
+```ruby
+Workarea.config.blog_entries_on_index
+# => 4
+
+Workarea.config.max_admin_bookmarks
+# => 10
+
+Workarea.config.product_templates
+# => [:test_product, :package, :family, :clothing]
+
+Workarea.config.shipping_origin
+# => {:country=>"US", :state=>"PA", :city=>"Philadelphia", :zip=>"19106"}
+
+Workarea.config.pricing_calculators
+# => #<Workarea::SwappableList:0x007f508b94d670 @source=["Workarea::Pricing::Calculators::ItemCalculator", "Workarea::Pricing::Calculators::CustomizationsCalculator", "Workarea::Pricing::Calculators::DiscountCalculator", "Workarea::Pricing::Calculators::TaxCalculator"]>
+
+Workarea.config.elasticsearch_mappings.storefront
+# => {:category=>{:properties=>{:query=>{:type=>"percolator"}}}, :storefront=>{:dynamic_templates=>[{:facets=>{:path_match=>"facets.*", :mapping=>{:type=>"keyword"}}}, {:numeric=>{:path_match=>"numeric.*", :mapping=>{:type=>"float"}}}, {:keywords=>{:path_match=>"keywords.*", :mapping=>{:type=>"keyword"}}}, {:sorts=>{:path_match=>"sorts.*", :mapping=>{:type=>"float"}}}, {:content=>{:path_match=>"content.*", :mapping=>{:type=>"text", :analyzer=>"text_analyzer"}}}, {:cache=>{:path_match=>"cache.*", :mapping=>{:index=>false}}}], :properties=>{:id=>{:type=>"keyword"}, :type=>{:type=>"keyword"}, :slug=>{:type=>"keyword"}, :suggestion_content=>{:type=>"string", :analyzer=>"text_analyzer"}, "facets.category_id"=>{:type=>"keyword"}, "facets.on_sale"=>{:type=>"keyword"}}}}
+```
+
+The Ruby configuration is also exposed through the _Settings_ dashboard in the Admin (_/admin/dashboards/settings_).
+
+![Current configuration shown in Admin Settings](images/current-configuration-shown-in-admin-settings.png)
+
+### JavaScript Configuration Object
+
+Use `WORKAREA.config` to access the current JavaScript configuration.
+
+The following example, which I ran in a browser console, lists all the configs for my sample application in lexicographical order.
+
+```js
+console.log(Object.keys(WORKAREA.config).sort().join('\n'))
+// categorizedAutocompleteFields
+// contentBlocks
+// contentEditorForms
+// dashboardCharts
+// date
+// datepickerFields
+// datetimepicker
+// deletionForms
+// dropzones
+// formSubmittingControls
+// forms
+// helpLookupButtons
+// imageFileExtensions
+// messages
+// productImagesSortable
+// recommendationsSortables
+// remoteSelects
+// storefrontBreakPoints
+// tooltipster
+// validationErrorAnalyticsThrottle
+// wysiwygs
+```
+
+The config object contains _all_ platform configs relevant to the current page, including those added as extensions by installed plugins. The configuration object is specific to the current UI (e.g. Admin, Storefront), since each UI has its own JavaScript manifests, which load different JavaScript config files.
+
+### Accessing the Ruby Configuration in JavaScript
+
+The Admin and Storefront configuration files, _workarea-admin/app/assets/javascripts/workarea/admin/config.js.erb_ and _workarea-storefront/app/assets/javascripts/workarea/storefront/config.js.erb_, are processed by ERB during compilation, providing access to the application's Ruby configuration.
+
+The following example demonstrates how responsive break points sizes are read from a Ruby config in order to write them to a JavaScript config.
+
+```js
+<%# workarea-storefront/app/assets/javascripts/workarea/storefront/config.js.erb %>
+
+<%# ... %>
+
+WORKAREA.config.storefrontBreakPoints = {
+    sizes: {
+        <% Workarea.config.storefront_break_points.each do |name, size| %>
+            '<%= name %>': <%= size %>,
+        <% end %>
+    },
+
+    ie9Matches: [
+        'small',
+        'medium',
+        'wide'
+    ]
+};
+
+<%# ... %>
+```
+
+The same values are therefore accessible through Ruby and JavaScript.
+
+```ruby
+# Storefront break points in Ruby
+
+Workarea.config.storefront_break_points
+# => {:small=>320, :medium=>760, :wide=>960, :x_wide=>1160}
+```
+
+```js
+// Storefront break points in JavaScript
+
+console.log(JSON.stringify(WORKAREA.config.storefrontBreakPoints.sizes))
+// => {"small":320,"medium":760,"wide":960,"x_wide":1160}
+```
+
+## Configuring an App in Ruby
+
+To configure an app in Ruby, modify config values or add config keys from within an initializer or an environment-specific configuration file. It is also possible to modify the configuration temporarily, which is useful for testing (see below).
+
+### Initializers & Environment Files
+
+Write Workarea configuration code anywhere you would write Rails configuration code, most likely within an initializer or an environment-specific config file. The boilerplate for a Workarea application includes the following initializer.
+
+```ruby
+# config/initializers/workarea.rb
+
+Workarea.configure do |config|
+  # Basic site info
+  config.site_name = 'Board Game Supercenter'
+  config.host = 'board-game-supercenter.dev'
+  config.email_to = 'customerservice@board-game-supercenter.dev'
+  config.email_from = 'noreply@board-game-supercenter.dev'
+end
+```
+
+The `Workarea.configure` method yields the Workarea configuration object to its block, providing a convenient interface for bulk configuration. Application developers typically write their configuration code within this block.
+
+Rails also provides environment-specific files, such as _config/environments/development.rb_ and _config/environments/production.rb_. Write environment-specific configuration code within the appropriate environment file.
+
+The plugins I looked at are less consistent than applications in where they write their configuration code. When writing configuration code within a plugin, I recommend using initializers that describe the type of configuration, such as _config/initializers/seeds.rb_ and _config/initializers/assets.rb_. Or, for small plugins, use a single generic initializer, such as _config/initializers/workarea.rb_.
+
+Some existing plugins write configuration code in the _engine.rb_ file, within inline intializers. Avoid that technique in new plugins—such initializers run _after_ the application's initializers, making it more difficult for an application to override values specified in the plugin.
+
+### Modifying Values
+
+Within your initializer, modify existing configuration values as needed by assigning a new value or manipulating the existing value, as shown in the following examples.
+
+```ruby
+Workarea.config.blog_entries_on_index = 5
+
+Workarea.config.seeds.push('Workarea::SharesSeeds')
+
+Workarea.config.seeds << 'Workarea::ReviewSeeds'
+
+Workarea.configure do |config|
+  config.jump_to_navigation.merge!('Reviews' => :reviews_path)
+end
+
+Workarea.config.seeds.insert_after('Workarea::ProductsSeeds', 'Workarea::PackageProductSeeds')
+
+Workarea.configure do |config|
+  config.product_templates += %i(package family)
+end
+
+Workarea.config.product_templates << :clothing
+
+Workarea.configure do |config|
+  config.storefront_search_middleware.swap(
+    'Workarea::Search::StorefrontSearch::Template',
+    'Workarea::Search::StorefrontSearch::TemplateWithContent'
+  )
+end
+
+Workarea.config.clothing_swatch_size ||= '44x'
+
+Workarea.config.product_copy_default_attributes ||= {}
+Workarea.config.product_copy_default_attributes.merge!(
+  total_reviews: 0,
+  average_rating: nil
+)
+```
+
+### Adding Keys
+
+A plugin may add new configuration keys to provide applications with extension points for the functionality provided by the plugin. To add a new key, simply assign a value to it.
+
+```ruby
+Workarea.config.and_now_for_something_completely_different = 'Anthologies are cool'
+```
+
+### Temporary Configuration (Testing)
+
+In the context of tests, it can be useful to change a config temporarily, perhaps for the duration of a single test or assertion. Use `Workarea.with_config` with a block to set or modify a config for the duration of the block. The following test case demonstrates this concept.
+
+```ruby
+# workarea-core-3.1.0/test/queries/workarea/search/pagination_test.rb
+require 'test_helper'
+
+module Workarea
+  module Search
+    class PaginationTest < TestCase
+      # ...
+
+      def test_from
+        Workarea.with_config do |config|
+          config.per_page = 30
+          assert_equal(0, Paginate.new(page: 1).from)
+        end
+
+        Workarea.with_config do |config|
+          config.per_page = 15
+          assert_equal(15, Paginate.new(page: 2).from)
+        end
+
+        Workarea.with_config do |config|
+          config.per_page = 45
+          assert_equal(90, Paginate.new(page: 3).from)
+        end
+      end
+
+      def test_size
+        Workarea.with_config do |config|
+          config.per_page = 30
+
+          search = Paginate.new(page: 2)
+          assert_equal(30, search.size)
+        end
+      end
+    end
+  end
+end
+```
+
+## Configuring an App in JavaScript
+
+To configure an app in JavaScript, modify config values or add config keys from within a JavaScript config file and [append](appending.html) the config file to an append point within the relevant manifest to include it on the page. <sup><a href="#notes" id="note-1-context">[1]</a></sup>
+
+The following examples for the fictional store <cite>Board Game Supercenter</cite> demonstrate appending an application-specific JavaScript config file in the Storefront.
+
+```js
+// board_game_supercenter/app/assets/javascripts/workarea/storefront/board_game_supercenter/config.js
+
+WORKAREA.config.messages.delay = 5000;
+```
+
+
+```js
+# board_game_supercenter/config/initializers/appends.rb
+
+Workarea.append_javascripts(
+  'storefront.config',
+  'workarea/storefront/board_game_supercenter/config'
+)
+```
+
+Similarly, the following examples append an Admin config file for the fictional <cite>Workarea Loyalty</cite> plugin.
+
+```js
+// workarea-loyalty/app/assets/javascripts/workarea/admin/loyalty/config.js
+
+WORKAREA.config.loyaltyBadges = {
+    events: ['hover']
+}
+```
+
+
+```ruby
+# workarea-loyalty/config/initializers/appends.rb
+
+Workarea.append_javascripts(
+  'admin.config',
+  'workarea/admin/loyalty/config'
+)
+```
+
+If you need access to the Ruby config object within your JavaScript config file, use a file ending in _.js.erb_ instead. See example above.
+
+## Rails Configuration
+
+You should also be familiar with [configuring your Rails application](http://guides.rubyonrails.org/configuring.html), since Workarea depends on several Rails configuration values.
+
+Use `Rails.application.config` or `Rails.configuration` to access the Rails configuration object. The Ruby configuration for Workarea is actually a member of the Rails configuration.
+
+```ruby
+Workarea.config == Rails.application.config.workarea
+# => true
+
+Workarea.config == Rails.configuration.workarea
+# => true
+```
+
+However, Workarea makes use of additional Rails configs that live outside the Workarea-specific configuration. Two important examples are the application time zone and locales, each covered below.
+
+### Configuring the Application Time Zone
+
+[Since Workarea 3.2.0](workarea-3-2-0.html#uses-rails-time-zone-to-display-all-dates-times), you must configure a time zone for the admin side of your Workarea application. Set `config.time_zone` in your Rails general configuration in `config/application.rb`.
+
+```ruby
+# config/application.rb
+
+module YourApp
+  class Application < Rails::Application
+    # ...
+    config.time_zone = 'Eastern Time (US & Canada)'
+    # ...
+  end
+end
+```
+
+Rails provides a command to list the time zones it recognizes, which is demonstrated in the following shell session:
+
+```bash
+$ bin/rails -T time
+rails time:zones[country_or_offset] # List all time zones, list by two-letter country code (`rails time:zones[US]`), or list by UTC offset (`rails time:zones[-8]`)
+$ bin/rails time:zones
+
+* UTC -11:00 *
+American Samoa
+International Date Line West
+Midway Island
+
+… more …
+
+* UTC +13:00 *
+Nuku'alofa
+Samoa
+Tokelau Is.
+
+$ bin/rails time:zones[US]
+
+* UTC -10:00 *
+America/Adak
+Hawaii
+
+… more …
+
+* UTC -05:00 *
+America/Detroit
+America/Indiana/Marengo
+America/Indiana/Petersburg
+America/Indiana/Vevay
+America/Indiana/Vincennes
+America/Indiana/Winamac
+America/Kentucky/Louisville
+America/Kentucky/Monticello
+Eastern Time (US & Canada)
+Indiana (East)
+
+$ bin/rails time:zones[-5]
+
+* UTC -05:00 *
+Bogota
+Eastern Time (US & Canada)
+Indiana (East)
+Lima
+Quito
+
+$
+```
+
+### Configuring Locales
+
+Other important Rails configurations are the _available locales_, _default locale_, and _locale fallbacks_. All of Workarea's user interfaces are internationalized and therefore depend on these values.
+
+Review the [Configure Locales](configure-locales.html) guide for coverage of this topic.
+
+## Notes
+
+[1] Alternatively, if you are working in an application that is [overriding](overriding.html) the relevant manifest, you can require the config file within your manifest override.