RubyGems - workarea - Versions diffs - 3.4.16 → 3.4.17 - Mend

workarea 3.4.16 → 3.4.17

Files changed (572) hide show

data/docs/source/articles/create-a-theme.html.md DELETED Viewed

@@ -1,134 +0,0 @@
----
-title: Create a Theme
-excerpt: Developing your own Workarea theme is similar in many ways to developing a plugin.
----
-# Create a theme
-Developing your own Workarea theme is similar in many ways to developing a plugin.
-Some additional tools are provided to expedite theme development and make it easy
-to customize the storefront.
-## Create a new theme
-To create a Workarea theme use the _rails plugin new_ command with the Workarea
-theme template which is part of the workarea-theme engine.
-``` bash
-rails plugin new /path/to/new-theme --full -m /path/to/theme-template.rb --skip-spring --skip-active-record --skip-action-cable
-```
-This template can be found in the [workarea-theme repository](https://github.com/workarea-commerce/workarea-theme) at [https://github.com/workarea-commerce/workarea-theme/docs/guides/source/theme_template.rb](https://github.com/workarea-commerce/workarea-theme/docs/guides/source/theme_template.rb).
-After creating the theme, edit the gemspec file to set relevant metadata.
-### Theme development workflow
-Once you've created your theme engine and edited the gemspec you can start
-developing your theme. Theme development relies heavily on overriding views,
-stylesheets, and javascripts from Workarea Storefront. To jump-start your theme
-development run the theme override generator to override all of the files you're
-likely to need in your theme.
-To use the theme override generator run
-```bash
-bin/rails generate workarea:theme_override
-```
-This will override every view file, along with most Sass and JS files from
-workarea-storefront. The generator also commits these overrides and stores the
-commit SHA in `lib/workarea/theme/override_commit`. This file is used by the
-Workarea `theme_cleanup` rake task and should not be deleted.
-Having overridden most of the files you will need to develop your theme, you are
-now ready to start implementing your designs. Should you need to override other
-files from Storefront, or another plugin, you should use the [Workarea override
-generator](https://developer.workarea.com/workarea-3/guides/overriding).
-Once you have implemented your theme you should run the Workarea `theme_cleanup` rake
-task. This will remove any files in `/app` that have not changed since you ran the
-theme_override generator. To execute `theme_cleanup` run:
-```bash
-bin/rails workarea:theme_cleanup
-```
-Be sure to check the files that have been removed, and test that your theme runs
-and looks correct before committing this change.
-Once your theme is cleaned up you're done, congratulations! Now head over to the
-[Workarea plugin documentation](https://developer.workarea.com/workarea-3/guides/plugins-overview)
-to learn how to release your theme for use!
-### Theme requirements
-In order for your theme to be registered correctly within the host application it
-must depend on workarea-theme and have the following include in your plugin's
-engine.rb file:
-```ruby
-  include Workarea::Theme
-```
-This is necessary for the `starter_store` generator to work.
-In addition your theme must:
-- Include a theme.rb initializer.
-- Allow the host application to configure the color scheme.
-- Allow the host application to configure fonts.
-The theme_template will take care of setting these things up for you, be sure to
-follow the instructions for creating a new Workarea theme to ensure your theme is
-configured properly.
-It is recommended that your theme's README include the following information:
-- Optimal image sizes.
-- Compatible Workarea plugins and dependencies.
-- Browser support, preferably supplemented with a browserlist file in the theme's
-    root directory.
-- Instructions for any additional configuration or features specific to your theme.
-### Theme plugin dependencies
-Your theme may include dependencies on other Workarea plugins. This allows you to
-ship a theme with support for popular functionality out of the box, and to benefit
-from pluginized UI components and functionality.
-To add support for another plugin, first add it to your theme's gemspec like this:
-```ruby
-s.add_dependency 'workarea-swatches', '1.0.0'
-```
-Next you will need to override the relevant files from the plugin to your theme.
-You should use the [workarea override generator](https://developer.workarea.com/workarea-3/guides/overriding) to do this.
-Once you have overridden all of the necessary files you can adjust styles, markup,
-and functionality as required to meet your requirements.
-_Note:_ dependencies of a theme cannot be removed when using
-the theme as a gem, so it is best to keep dependencies to a minimum. The only way
-to remove a theme's dependencies within a host application is to use the `starter_store`
-generator, then remove the unwanted dependency from the application gemfile along
-with any related app files (views, styles etc.).
-### Maintaining your theme
-A theme is like a baby, you spend a while making one, then you have a lifetime
-of taking care of it.
-Maintaining your theme means fixing bugs as they come in, and keeping your theme
-up to date with the latest versions of Workarea. If your theme is not kept up to
-date you will cause great pain and sadness for developers that have used your theme
-in their applications. You might prevent them from being able to take upgrades.
-#### Upgrading for minor-version compatibility
-Upgrading your theme for compatibility with Workarea is important. At a minimum
-all themes should be upgraded with the latest changes in each new minor version
-of Workarea.
-The Workarea upgrade tool will be very useful and allow you to
-upgrade your theme in the same way you upgrade a Workarea application.

data/docs/source/articles/css-architectural-overview.html.md DELETED Viewed

@@ -1,89 +0,0 @@
----
-title: CSS Architectural Overview
-excerpt: The main principals of the Workarea CSS architecture were modeled after OOCSS and ITCSS best practices. You will find that the architecture is layered. Each layer has a specific purpose and is naturally more specific than the layer it proceeds. This a
----
-# CSS Architectural Overview
-The main principals of the Workarea CSS architecture were modeled after OOCSS and ITCSS best practices. You will find that the architecture is layered. Each layer has a specific purpose and is naturally more specific than the layer it proceeds. This allows a developer to think about the purpose of the CSS he or she is writing before dropping it in a corresponding layer, keeping the application manifest direct and to the point.
-## _Cascading_ Style Sheets
-[Stylesheet manifests](add-stylesheets-through-a-manifest.html) take your referenced CSS files and produce a concatenated, production-ready file. It's important to note that the order of these files is honored during the concatenation process. This just means that the contents of the files at the top of your manifest will be output before those listed at the bottom of the manifest.
-A main pillar of the Workarea CSS architecture is to harness and reinforce the natural cascade of CSS. CSS files are parsed top-to-bottom and precedence is given to CSS rules that appear lower in the code, as seen in this very simple example:
-`.component { background: red; }
-.component { background: blue; }`
-When this code reaches the browser the component is blue, because of the cascade.
-Therefore, your most general CSS rules should be found at the top of the manifest, and your most specific CSS rules should be found at the bottom. By always keeping this in mind, you enable yourself to write scalable, purposeful and technically correct CSS.
-## Layers
-To reinforce the cascade of increasing specificity, the Workarea platform defines specific various CSS layers. All of the CSS files that you write should live in directories named after the file's intended layer. For example, if you create a component for the Storefront called `toggle-button`, that file should live within `workarea/storefront/components/_toggle_button.scss`. This files reference should then be added to the Components layer of the manifest.
-I've listed the main layers below. By "main layers" I mean they are the layers that define the core architecture. There are a few plugin-specific layers offered (which I'll cover in a bit), in addition to the following:
-1. The Settings Layer
-2. The Tools Layer
-3. The Generic Layer
-4. The Base Layer
-5. The Objects Layer
-6. The Typography Layer
-7. The Components Layer
-8. The Trumps Layer
-### The Settings Layer
-This layer contains variables which are meant to be globally available. They are considered safe for general use and you'll find them peppered throughout the proceeding Sass files.
-Each carry a `!default` flag, allowing Theme plugins or multi-site configuration to override their values, if necessary.
-### The Tools Layer
-This layer contains only functions and mixins. They're helpers that let you dry up your code or perform more complex calculations.
-### The Generic Layer
-This is the first layer where we start to see some CSS. The Generic Layer is the most global CSS you'll find in the project. We start off with including the [Normalize](https://necolas.github.io/normalize.css/) library, which we tweak the configuration of just a bit in our own reset.css file.
-Here is where we set up our global page box-sizing and whatever fonts we'll be using for the project.
-### The Base Layer
-Now that a sane foundation has been laid, we can begin to apply some default styling to element selectors.
-The biggest element we style is the `html` element (in `_page.scss`). Then we ask ourselves what should specific elements look like if we were to just drop them on a page, devoid of classes. This is where your default `table` element and `ul` element styling lives. Each file is grouped thematically, by usage. So the `_forms.scss` file contains default styles for `form`, `input`, and `textarea` tags, for example.
-### The Objects Layer
-Objects are probably the hardest part of the architecture to grasp. They are intended to be design-free classes and placeholder selectors that allow you to DRY up your codebase. An `inline-list` should remove the bullets of a list and make it's children display horizontally rather than vertically. A `button-reset` should remove all browser styling of a button, so that a component class can start applying design styles in a clear an direct manner.
-### The Typography Layer
-Here we find all of the text-based styles in the app. All headings are defined here. Utility classes to easily allow a developer to left, right, or center-justify some text are defined here. Links and paragraphs are defined here as well.
-### The Components Layer
-All of the styles leading up to this layer have ensured that our document looks just like a well formatted document. The Components layer takes that document and makes it into a real website. It provides each of the building blocks needed to achieve layout, the design, and the pleasurable user experience your customers will enjoy.
-### The Trumps Layer
-Lastly we have the Trumps layer. Trumps are the law. When their classes are applied to an element they are expected to react accordingly. There is no ambiguity in this layer. It contains styles that must be applied, at any cost. If you need to use the `!important` flag on a value, feel free, but you shouldn't have to, since these styles are naturally the most specific.
-## Plugin-Specific Layers
-In addition to the aforementioned layers, there are a few layers used only by Plugins.
-### The Theme Config Layer
-Theme Plugins are a special type of plugin who's primary purpose is to make the default Storefront look vastly different. These plugins make use of the Theme Config layer, which appears just before the Settings layer. Theme Plugins can override any Sass variable that carries a `!default` declaration which, out of the box, is every declared variable.
-### The Theme Layer
-Theme Plugins use this layer to further augment the styling of the system. The Theme layer appears directly after the Components layer, and right above the Trumps layer, to allow increased specificity beyond that of the Components layer.

data/docs/source/articles/customize-a-helper.html.md DELETED Viewed

@@ -1,91 +0,0 @@
----
-title: Customize a Helper
-excerpt: Workarea developers can use the following two-step procedure to add or change helper methods
----
-Customize a Helper
-======================================================================
-[Rails helpers](https://api.rubyonrails.org/v5.2.3/classes/ActionView/Helpers.html) are modules that define methods for use in views and controllers (helper methods).
-Occasionally, you may encounter the following use cases involving helper methods:
-* From a plugin, you need to define a new helper method
-* From a plugin or application, you need to re-define a helper method originally defined by Workarea
-The Rails engine architecture does not provide an extension mechanism to enable these use cases.
-However, Workarea developers can use the following two-step procedure to satisfy these requirements:
-1. Define or re-define the helper method (depending on use case)
-2. Add the helper module to the ancestors of either the Admin or Storefront application controller
-1\. (Re)Define the Helper Method
-----------------------------------------------------------------------
-For a new helper method (from a plugin), define a new helper and method.
-The following example defines a new helper method within the _Blogs_ plugin:
-```ruby
-# workarea-blog/app/helpers/workarea/storefront/blogs_helper.rb
-module Workarea
-  module Storefront
-    module BlogsHelper
-      def blog_posting_schema(entry)
-        # implementation of new helper method
-      end
-    end
-  end
-end
-```
-To redefine an existing method (from an app or a plugin), define a method with the same name within a new module.
-The following example re-defines a method from the _Blogs_ plugin from the _Boardgamez_ app:
-```ruby
-# boardgamez/app/helpers/workarea/storefront/blogs_helper.rb
-module Workarea
-  module Storefront
-    module BoardgamezBlogsHelper
-      def blog_posting_schema(entry)
-        # re-implementation of helper method
-      end
-    end
-  end
-end
-```
-2\. Add the Helper to an Application Controller
-----------------------------------------------------------------------
-In both cases above, a new module is defined.
-Add that module to the ancestors of either the Storefront or Admin application controller, depending on where you intend to use the helper method.
-Do this using the `.helper` class method on the controller.
-The following examples accomplish this in different ways, and both techniques are applicable to applications and plugins.
-The first [decorates](decoration.html) the chosen controller:
-```ruby
-# workarea-blog/app/controllers/workarea/storefront/application_controller.decorator
-module Workarea
-  decorate Storefront::ApplicationController, with: :blog do
-    decorated { helper Storefront::BlogsHelper }
-  end
-end
-```
-While the following example does the work in a configuration file:
-```ruby
-# boardgamez/config/application.rb
-module Boardgamez
-  class Application < Rails::Application
-    config.to_prepare do
-      Workarea::Storefront::ApplicationController.helper(
-        Workarea::Storefront::BoardgamezBlogsHelper
-      )
-    end
-  end
-end
-```