Module of the Month: Break out the SilverWare

As a developer, I love building projects that empower clients and give them the tools they need to take full control of their presence on the web. But as a freelancer, the time cost of responding to ad hoc requests and performing manual changes to sites stacks up.

In an effort to alleviate this back in the SilverStripe 2.4 days, I made heavy use of the SilverStripe widgets module. Originally intended for a single sidebar only, I extended this concept to both left and right sidebars, lower content, and page footer areas available on every page of the site. Although a little clunky, it afforded the client great flexibility in terms of controlling their page layout.

But then I thought, what if we could model the entire page layout from small, reusable components? Rather than hammering every site into the same approach with four widget areas, a tree of components could offer the ultimate in flexibility and code reuse for building sites. 

Enter SilverWare: a component framework for SilverStripe 4.

Widgets on steroids

In development for over two years, SilverWare takes the standard SilverStripe approach of templates and layouts for each page type and abstracts this concept into a model that can be manipulated using the CMS.

Folders appear in the site tree which hold a series of template and layout objects, and a section in site settings allows the developer to define which template and layout to use for certain page types.

By default, SilverWare creates a 'Main' template, and both 'Main' and 'Home' layouts, allowing you to define the appearance of regular pages and also the home page.  

SilverWare uses custom YAML fixture files to create the object model when SilverStripe builds the database, which also allows templates and layouts to be committed to source code control and built upon deployment to a server.

SilverWare components are created using the CMS site tree, just like pages

Everything in SilverWare is a component – even the responsive grid itself. Templates and layouts are built from a series of sections which are then further divided into rows and columns. Each column contains a number of child components to suit basically any purpose or functionality required.

Out of the box, SilverWare uses Bootstrap 4 for the frontend theme. However, it is possible to use other frameworks as the grid model is built as an abstraction layer.

Plug and play

From the start, SilverWare was designed to be highly modular and flexible. A basic installation provides a series of components for:

• Layout
• Content
• Media
• Navigation

To extend SilverWare further, there are currently over 40 other repositories available on Github and Packagist, including everything from blogs and carousels, to news archives and social networking integration. Adding a new feature is as easy as adding the required module using Composer and building the database.

And writing your own components is easy. Each component extends a class known as BaseComponent, and by writing your own subclass and template for each component, you’ll be able to add your own custom components to templates and layouts in no time.

Components can be rearranged using drag-and-drop. Even preview is supported.

Frontend requirements for SilverWare components are typically bundled using Webpack. You can inform SilverWare of the required bundles by adding a couple of lines to YAML config. In development mode, SilverWare will load all required bundles individually but for production deployments, it expects only two bundles (CSS and JavaScript) in the theme.

The default SilverWare installation and theme provides built-in Webpack configuration to help with compiling your bundle files and preparing them for deployment.

With great power...

I know what you might be thinking “but I don’t want clients messing around with the entire template and layout!” But there's no cause for concern. SilverWare makes use of the built-in SilverStripe permissions system so that you can lock down template and layout modification to only certain users.

In fact, clients will most often be making changes to what is known as a 'panel'. A panel is similar to a widget area and they can be added into sidebars, footers, or any other area you specify in the template or layout. Each panel can be defined as either the default for all pages, or customised for a series of pages as specified by the user.

A SilverWare panel in action. The sidebar contains a CarouselComponent.

Any subclass of BaseComponent can be added to a panel and is defined separately. You might imagine one page that has a YouTube video in the sidebar, or another that has a tag cloud and a list of recent blog posts. Perhaps another page has a carousel of slides after the content.

All of this is possible out-of-the-box with SilverWare without touching a single line of code.

Getting started with SilverWare

The best way to get started with SilverWare is creating a project using the silverware/app package:

composer create-project silverware/app /path/to/app

This will download everything you need to get underway.

After Composer finishes installing dependencies, a series of questions will be asked by the SilverWare installer via the console to configure your app.

For development, you will also need to create a .env file in the project root to define database credentials. An example file is included with the repository.

The project also includes the silverware/theme package by default. This is the default SilverWare theme based on Bootstrap 4 and includes everything necessary for Webpack bundling and hot module reloading for local development.

To install the dependencies for theme development, you’ll need to open a console in the theme folder and use either NPM or Yarn to install:

yarn install

To start the local development server for hot module reloading, you can enter:

yarn start

You may need to modify the webpack.server.js file to change the development host name and port along with any https certificates that may be in use for the host.

Summing up

SilverWare's a powerful and flexible tool for handling layout on sites that utilise individual pages in the site tree. The entire site can be built without writing a single line of code, and off-the-shelf components have been designed for maximum reuse and extensibility to cover a wide gamut of common functionality.

If you need a SilverWare component for a certain use case, chances are it's already been released. If that's not the case, it's easy to write your own components which can be added to any column or panel in your layout. Why not give it a try and see if it can be of benefit for your next project?

Is SilverWare for everybody? Perhaps not. Many developers prefer to have fine-grained control over individual theme and template files and may not be fond of the idea of too much flexibility being available to CMS users.

In addition, while SilverWare works really well for traditional content-based sites built from a series of pages, a different approach may be needed for single-page apps or apps which use frontend component frameworks such as React or Vue.js.

Check out the SilverWare Component Framework.

Want to get involved in the SilverStripe community?

Get acquainted with the SilverStripe developer community on Slack.