Add Stylesheets through a Manifest
Stylesheet manifests are the preferred solution for adding stylesheets to and removing stylesheets from a Workarea application. The Workarea Admin and Storefront each include a single manifest named 'application', which is introduced in the Stylesheets overview. This guide covers the manifest in detail.
If you're new to Ruby on Rails and the concept of asset manifests, check out the following guides to get you started.
Customizing a Manifest
To add and remove stylesheets through a manifest, you need to have a copy of the manifest in your app. If you're working in a new application, start by overriding the manifest file you want to customize. You can override a manifest in the same way as any other stylesheet. When overriding, note that the manifest file ends with the extensions .scss.erb
. I'll explain the reason for that in the following sections which look at the application manifest in detail.
Now that you have a copy of the manifest in your app, edit it to taste. The follow sections explain how Workarea manifests differ from default Rails manifests and what is included out of the box.
Application Manifest
The application manifest contains a mixture of Sass @import
statements and ERB blocks, hence the need for the .erb
file extension mentioned above. The manifest is designed as as such to support the Workarea plugin system and to load some assets conditionally, as you'll see shortly. "Zoomed out", it looks something like this:
workarea-storefront/app/assets/stylesheets/workarea/storefront/application.scss.erb:
<%= "@import 'workarea/core/feature_test_helper';" if Rails.env.test? %>
<%= append_stylesheets('storefront.feature_test_helpers') %>
<%= append_stylesheets('storefront.theme_config') %>
@import // settings
<%= append_stylesheets('storefront.settings') %>
@import // tools
<%= append_stylesheets('storefront.tools') %>
@import // generic
<%= append_stylesheets('storefront.generic') %>
@import // base
<%= append_stylesheets('storefront.base') %>
@import // objects
<%= append_stylesheets('storefront.objects') %>
@import // typography
<%= append_stylesheets('storefront.typography') %>
@import // dependencies
<%= append_stylesheets('storefront.dependencies') %>
@import // components
<%= append_stylesheets('storefront.components') %>
<%= append_stylesheets('storefront.theme') %>
@import // trumps
<%= append_stylesheets('storefront.trumps') %>
Now let's zoom in on each of the manifest sections.
Feature Test Helper
<%= "@import 'workarea/core/feature_test_helper';" if Rails.env.test? %>
<%= append_stylesheets('storefront.feature_test_helpers') %>
The feature test helper includes styles that make automated testing easier. Plugins are also able to add their own feature test helpers as needed.
Theme Config
The Theme Config Layer is used by Theme Plugins to reset any Sass variable declared within the Storefront.
<%= append_stylesheets('storefront.theme_config') %>
Settings
The Settings Layer contains globally available Sass variables that any other layer may make use of.
@import 'workarea/storefront/settings/colors';
@import 'workarea/storefront/settings/typography';
@import 'workarea/storefront/settings/breakpoints';
@import 'workarea/storefront/settings/global';
@import 'workarea/storefront/settings/grid';
@import 'workarea/storefront/settings/z_indexes';
<%= append_stylesheets('storefront.settings') %>
Tools
The Tools Layer contains globally available, configurable Sass functions and mixins that any of the following layers may make use of.
@import 'workarea/storefront/tools/center';
@import 'workarea/storefront/tools/focus_ring';
@import 'workarea/storefront/tools/respond_to';
@import 'workarea/storefront/tools/svg';
<%= append_stylesheets('storefront.tools') %>
Generic
The Generic Layer contains the Normalize library, a Workarea-focused global Normalize reset file, and other top-level stylings.
@import 'normalize-rails';
@import 'workarea/storefront/generic/reset';
@import 'workarea/storefront/generic/box_sizing';
@import 'workarea/storefront/generic/fonts';
<%= append_stylesheets('storefront.generic') %>
Base
The Base Layer contains basic element styling.
@import 'workarea/storefront/base/page';
@import 'workarea/storefront/base/images';
@import 'workarea/storefront/base/forms';
@import 'workarea/storefront/base/tables';
@import 'workarea/storefront/base/lists';
<%= append_stylesheets('storefront.base') %>
Objects
The Objects Layer contains reusable, design-free abstractions that help DRY up code found in the Components layer. There are a few specific reset-like abstractions here. They're used to reset specific element styling on an as-needed basis.
@import 'workarea/storefront/objects/inline_list';
@import 'workarea/storefront/objects/list_reset';
@import 'workarea/storefront/objects/text_field_reset';
@import 'workarea/storefront/objects/button_reset';
@import 'workarea/storefront/objects/content_wrapper';
@import 'workarea/storefront/objects/content_preview_visibility';
<%= append_stylesheets('storefront.objects') %>
Typography
The Typography Layer focuses on global typography throughout the application.
@import 'workarea/storefront/typography/align';
@import 'workarea/storefront/typography/headings';
@import 'workarea/storefront/typography/links';
@import 'workarea/storefront/typography/text';
<%= append_stylesheets('storefront.typography') %>
Dependencies
The Dependencies Layer allows Plugins to inject 3rd Party Library CSS into the application, if necessary.
@import 'avalanche';
@import 'jquery_ui/storefront/ui_autocomplete';
@import 'jquery_ui/storefront/ui_dialog';
@import 'jquery_ui/storefront/ui_helper_hidden_accessible';
@import 'jquery_ui/storefront/ui_menu';
@import 'jquery_ui/storefront/ui_state_focus';
@import 'jquery_ui/storefront/ui_widget_overlay';
<%= append_stylesheets('storefront.dependencies') %>
Components
The Components Layer contains all of the main UI building block styling for the application.
@import 'workarea/storefront/components/button';
@import 'workarea/storefront/components/hero_content_block';
@import 'workarea/storefront/components/loading';
@import 'workarea/storefront/components/message';
@import 'workarea/storefront/components/mobile_nav';
@import 'workarea/storefront/components/primary_nav';
@import 'workarea/storefront/components/product_details';
@import 'workarea/storefront/components/page_header';
@import 'workarea/storefront/components/product_list';
@import 'workarea/storefront/components/product_summary';
@import 'workarea/storefront/components/button_property';
@import 'workarea/storefront/components/inline_form';
@import 'workarea/storefront/components/property';
@import 'workarea/storefront/components/value';
@import 'workarea/storefront/components/payment_icon';
@import 'workarea/storefront/components/table';
@import 'workarea/storefront/components/data_card';
@import 'workarea/storefront/components/style_guide';
@import 'workarea/storefront/components/breadcrumbs';
@import 'workarea/storefront/components/cart';
@import 'workarea/storefront/components/category_summary_content_block';
@import 'workarea/storefront/components/checkout_addresses';
@import 'workarea/storefront/components/checkout_payment';
@import 'workarea/storefront/components/checkout_shipping';
@import 'workarea/storefront/components/checkout_step_summary';
@import 'workarea/storefront/components/email_signup';
@import 'workarea/storefront/components/html_content_block';
@import 'workarea/storefront/components/order_help_menu';
@import 'workarea/storefront/components/order_summary';
@import 'workarea/storefront/components/page_content';
@import 'workarea/storefront/components/page_footer';
@import 'workarea/storefront/components/page_container';
@import 'workarea/storefront/components/page_messages';
@import 'workarea/storefront/components/personalized_recommendations_content_block';
@import 'workarea/storefront/components/product_detail_container';
@import 'workarea/storefront/components/product_prices';
@import 'workarea/storefront/components/recent_views';
@import 'workarea/storefront/components/result_filters';
@import 'workarea/storefront/components/text_content_block';
@import 'workarea/storefront/components/search_no_results';
@import 'workarea/storefront/components/secondary_nav';
@import 'workarea/storefront/components/text_box';
@import 'workarea/storefront/components/text_button';
@import 'workarea/storefront/components/video_content_block';
@import 'workarea/storefront/components/view';
@import 'workarea/storefront/components/checkout_progress';
@import 'workarea/storefront/components/search_results';
@import 'workarea/storefront/components/taxonomy_content_block';
@import 'workarea/storefront/components/image_group_content_block';
@import 'workarea/storefront/components/image_and_text_content_block';
@import 'workarea/storefront/components/video_and_text_content_block';
@import 'workarea/storefront/components/product_list_content_block';
@import 'workarea/storefront/components/image_content_block';
@import 'workarea/storefront/components/button_content_block';
@import 'workarea/storefront/components/quote_content_block';
@import 'workarea/storefront/components/divider_content_block';
@import 'workarea/storefront/components/social_networks_content_block';
@import 'workarea/storefront/components/mobile_filters';
@import 'workarea/storefront/components/admin_toolbar';
@import 'workarea/storefront/components/content_block';
@import 'workarea/storefront/components/pagination';
@import 'workarea/storefront/components/svg_icon';
<%= append_stylesheets('storefront.components') %>
Theme
The Theme Layer contains is used by Theme Plugins to override the CSS declared within the Components layer.
<%= append_stylesheets('storefront.theme') %>
Trumps
The Trumps Layer contains code that is considered definitive. The values of the properties found in these files should override any previously declared property in any other layer.
@import 'workarea/storefront/trumps/break_word';
@import 'workarea/storefront/trumps/clearfix';
@import 'workarea/storefront/trumps/hidden';
@import 'workarea/storefront/trumps/hidden_if_js_enabled';
@import 'workarea/storefront/trumps/image_replacement';
@import 'workarea/storefront/trumps/truncate';
@import 'workarea/storefront/trumps/visually_hidden';
@import 'workarea/storefront/trumps/visible';
<%= append_stylesheets('storefront.trumps') %>
Adding and Removing stylesheets
Oh yeah, I guess this guide was supposed to be about adding and removing stylesheets through a manifest. Well, now that you know how the manifests are structured, adding and removing files is as easy as adding and removing the relevant @import
statements.
If the asset you want to include has been packaged as a gem, first add the gem to your Gemfile and then @import
the asset in your manifest using the path to the asset within the gem. If the asset is not available as a gem, simply download the asset and copy it to your application's vendor/assets/stylesheets
directory and reference it from there.
Refer to Appending for advice on managing plugin stylesheets in your manifests.
Help Us Improve this Doc
Was this helpful? Open a GitHub issue to report a problem with this doc, suggest an improvement, or otherwise provide feedback. Thanks!