README

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.

Contents

• Background
• Requirements
• Installation
• Configuration
• Usage
• Components
• Issues
• To-Do
• Contribution
• Attribution
• Maintainers
• License

Background

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.

Requirements

• SilverStripe Framework v4
• SilverStripe CMS v4
• SilverWare Theme

Installation

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

Configuration

As SilverWare is based upon SilverStripe, all configuration is performed using YAML configuration files.

Usage

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

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

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

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.

Page Types

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.

Components

SilverWare ships with the following components ready for use:

• AreaComponent
• ContentComponent
• CopyrightComponent
• DeveloperComponent
• FeatureComponent
• HeadingComponent
• ImageComponent
• ListComponent
• MediaComponent
• PageComponent
• ScrollToTopButton
• TableComponent
• TagCloudComponent
• TaglineComponent
• TileComponent
• TitleComponent
• ToggleComponent
• VirtualComponent

AreaComponent

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.

ContentComponent

Allows you to embed a block of rich-text content, edited using HTMLEditorField.

CopyrightComponent

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.

DeveloperComponent

Adds a developer attribution message, usually in the footer of the site. Supports linking to a page or URL for the site developer.

FeatureComponent

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.

HeadingComponent

Adds a regular H1-H6 heading with text of your choice. Also supports selection of a font icon to display with the heading.

ImageComponent

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.

ListComponent

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.

MediaComponent

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.

PageComponent

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.

ScrollToTopButton

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.

TableComponent

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.

TagCloudComponent

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.

TaglineComponent

Shows the tagline for the site as a heading. The tagline is defined through site settings.

TileComponent

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.

TitleComponent

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.

ToggleComponent

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.

VirtualComponent

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.

Issues

Please use the GitHub issue tracker for bug reports and feature requests.

To-Do

• Tests
• Documentation

Contribution

Your contributions are gladly welcomed to help make this project better. Please see contributing for more information.

Attribution

• 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.

Maintainers

Colin Tucker	Praxis Interactive

License

BSD-3-Clause © Praxis Interactive.