SilverWare is a component framework for SilverStripe v4 which allows you to build entire page templates and layouts from small, reusable, configurable and extensible components. SilverWare and its associated modules provide a number of components for you to use in your apps out-of-the-box, however it's easy to extend the SilverWare model and build your own components too.
- Background
- Requirements
- Installation
- Configuration
- Usage
- Components
- Issues
- To-Do
- Contribution
- Attribution
- Maintainers
- License
Most web applications consist of a series of small, reusable "blocks" that perform a particular function. Many of these are hard-coded by the developer, and often tightly-coupled to the underlying theme and/or scripts that drive the site.
One approach that affords more flexibility for both the developer and the end-user is to use "widgets". Often an area of the site such as the sidebar is designated as a "widget area", and the end-user is given the freedom to add and remove widgets from this area at will.
SilverWare goes a step further. In SilverWare, the entire page template and layout is built from reusable blocks similar to widgets, which are known as components. SilverWare builds upon the existing SilverStripe notion of page templates and layouts, and abstracts these concepts into a rich component data model which can be manipulated using the CMS.
Installation of SilverWare is via Composer. We recommend getting started with the SilverWare App repository, which will install everything you need to get underway.
$ composer create-project silverware/app my-app-path
If you'd prefer to install the SilverWare component framework without the app installer, you can instead use a regular require command via Composer:
$ composer require silverware/silverware
You will also need to use Yarn (or NPM) to install the theme dependencies:
$ cd themes/silverware-theme
$ yarn install
Once your theme dependencies are installed, execute the following to start the webpack development server:
$ yarn start
The theme should now compile with hot module reloading enabled, allowing the browser to automatically reload and update your styles as you make changes to the theme SASS.
To prepare your theme for production, execute the following:
$ yarn build
As SilverWare is based upon SilverStripe, all configuration is performed using YAML configuration files.
Upon building your SilverWare app, you will find a series of folders within your CMS site tree:
- Templates
- Layouts
- Panels
These are hidden from display on the public site, and are used to create your page templates, layouts, and panels (more on those in a moment). SilverWare exploits the built-in hierarchy features of SilverStripe to define a particular structure for your components.
You may think of templates and layouts in exactly the same fashion as SilverStripe convention dictates. Each page may have a template and a layout, the template wrapping around the layout for a particular page type.
Templates generally consist of a series of sections, rows and columns, with a LayoutSection component
informing SilverWare where the layout is to be rendered.
Layouts also consist of sections, rows and columns, with a series of components added to columns in order
to provide any type of functionality you require. Typically, a PageComponent will be added to a layout, in
order to render the actual template of the page itself.
Panels work in conjunction with an AreaComponent. Say you want two different page types to use the same
template and layout, but one page type has a different sidebar. Within the layout, you could add an
AreaComponent called "Sidebar". This component simply acts as a marker to inform SilverWare that
certain pages will display different content in this area.
You could now add a Panel called "Contact Sidebar". Select the areas this panel will display on
(e.g. "Sidebar"), and then select which pages this panel will appear on (e.g. "Contact Us"). Now, add your
components as children to this panel. Your "Contact Us" page will now show these components in its sidebar.
Panels can also be added by CMS users as children of regular pages within the site tree. In this case, the panel will display for the selected area on the parent page and all of its child pages. Note that the CMS user must have permission to create SilverWare components.
SilverWare needs to know which template and layout to render for each particular page type. By default, the SilverWare app installer creates a "Main" template and layout, and a "Home" layout just for the home page.
You can configure templates and layouts for pages in two places:
- site configuration
- page settings tab
Under the SilverWare tab in site configuration, you will find the "Page Types" tab. This tab allows you to define the default template and layout for each particular page type. To define a new page type, click the "Add Page Type" button, then select the type of page, the template, and the layout.
You may also override the template and/or layout on a page-by-page basis. Click on the page in the site tree you wish to modify, then click the "Settings" tab, and select the template and/or layout in the "Appearance" section.
SilverWare ships with the following components ready for use:
AreaComponentContentComponentCopyrightComponentDeveloperComponentFeatureComponentHeadingComponentImageComponentListComponentMediaComponentPageComponentScrollToTopButtonTableComponentTagCloudComponentTaglineComponentTileComponentTitleComponentToggleComponentVirtualComponent
Defines an area within a template or layout where a Panel can
appear, for example, a sidebar. This allows different types of pages on the
site to have different components shown for this area.
Allows you to embed a block of rich-text content, edited using HTMLEditorField.
Adds a standard copyright message, usually in the footer of the site. Supports a single year, or range of years, and showing the current year automatically. Can also link to a page or URL with more copyright information, and a page or URL for the entity named in the copyright message.
Adds a developer attribution message, usually in the footer of the site. Supports linking to a page or URL for the site developer.
Allows the user to select a page to feature in a block. The component will
show the title and a summary of the featured page, and also an image if the
page has one defined. Both the image and summary can be overridden by the
FeatureComponent itself.
Adds a regular H1-H6 heading with text of your choice. Also supports selection of a font icon to display with the heading.
Allows the user to add a responsive image with optional caption to the template or layout. The image can be selected from the existing asset images, or uploaded through the component. The component can be configured to resize the image using a variety of methods.
Renders a list of items with optional pagination. The ListComponent can render items
from any implementor of ListSource on the site. For example, a list source could be a blog, a
news archive, or an image gallery. Once the list source is defined, you can then
specify how many items to display, whether to paginate or not, standard or reversed
sort order, and whether or not to show only items with images.
Embeds media from a URL, such as a YouTube video, Flickr photo, or Twitter tweet.
MediaComponent uses Embed to access the media URL and
obtain information from the remote service. This data is subsequently stored within the
component, preventing excess remote calls.
For more information about the types of media which MediaComponent supports, see the
Embed documentation.
Renders the template for the current page. A PageComponent is usually added to a
layout, and informs SilverWare where it should render the template for the current
page. It is analogous to the $Layout tag used in regular SilverStripe templates.
Adds a "scroll to top" button that when clicked returns the user to the top of the page. The button is hidden by default when the user is at the top of the page, and appears when the user begins to scroll down. It can be customised by choosing a font icon, and also has fields for defining the show offset, opacity offset and scroll duration.
Renders a series of child components in a table layout, consisting of rows and columns.
By default, TableComponent makes use of the Bootstrap v4 flexbox layout grid, allowing
you to define viewport-specific column spans for child components.
Shows an interactive tag cloud with tags obtained from an implementor of TagSource.
The cloud is rendered as an HTML5 canvas (supported by most modern browsers), and
can be rotated by the user using the mouse or touch gestures. The component has
configurable text and outline colors, along with zoom, rotation, and font size options.
Weighted tags are also supported.
Shows the tagline for the site as a heading. The tagline is defined through site settings.
Renders a list of items as a series of "tiles". TileComponent is very similar to
a ListComponent, and allows you to specify a ListSource for the items to display.
The tiles are rendered using CSS + flexbox (similar to the Bootstrap grid), adjusting to
each device accordingly.
Shows the title of the current page. This component is useful when you need to show
the page title in a separate row or column from the actual page template itself.
If you need to hide the page title in the template (so that two titles are not shown),
select the "Hide title of page" option in your PageComponent. This adds the class
page-title-hidden which can be used in your site styles.
Allows you to embed a block of rich-text content, edited using HTMLEditorField, with
the visibility of the content toggleable via clicking on the header of the component.
Can be started open or closed.
Acts as a proxy for another component, allowing you to display a component in multiple locations without needing to create the component again. The virtual component may use a custom title, style ID and style classes, but will otherwise render an exact copy of the source component.
Please use the GitHub issue tracker for bug reports and feature requests.
- Tests
- Documentation
Your contributions are gladly welcomed to help make this project better. Please see contributing for more information.
- Logo icon designed by Freepik from www.flaticon.com and released under a Creative Commons BY 3.0 license.
- Fugue icons designed by Yusuke Kamiyamane and released under a Creative Commons BY 3.0 license.
- Makes use of Font Awesome by Dave Gandy.
- Makes use of Bootstrap by the Bootstrap Authors and Twitter, Inc.
- Makes use of TagCanvas by Graham Breach.
- Makes use of Embed by Oscar Otero.
- Makes use of webpack and webpack dev server by Tobias Koppers, Kees Kluskens, and many more.
 |
 |
|---|---|
| Colin Tucker | Praxis Interactive |
BSD-3-Clause © Praxis Interactive.