Sheets

Build Status

Sheets is a way to manage stylesheets and scripts from your existing page tree. With Sheets, you'll create new types of pages: JavascriptPage and StylesheetPage.

Pages of these types are Sheets.

Configuration

Sheets have an option to output paths with a cache parameter which will create a digest of the rendered content.

By setting Radiant::Config['sheets.use_cache_param?] to true the paths output from the <r:stylesheet> and <r:javascript> tags will appear like

/css/styles.css?bc4150d023d3255136db671d61ac93f2
/js/scripts.js?d6c5855a62cf32a4dadbc2831f0f295f

where the parameter is created from the rendered content of the sheet.

Without this set, the paths will be:

/css/styles.css
/js/scripts.js

and the pages will not be rendered to generate the path.

Features

The basic features:

  • provide a separate interface for editing CSS and Javascript content
  • set a longer expire time for Sheet content with sheet_cache_timeout (similar to the typical cache_timeout set for pages)
  • hide the JavascriptPage and StylesheetPage nodes from the standard Page index view
  • provide Radius tags to output content as it is, as a link to content, and as an HTML element containing the content
  • append a timestamp to sheet content URLs so that the cache need not be cleared with the same frequency for updates to typical pages

Differences with other solutions and the benefit of using Sheets

Some standard site templates provided by Radiant include stylesheet content in a typical page. This requires a custom layout merely to set the content type, and displays content unintended for editing by typical users. This makes for a cluttered page index view and cluttered layout index view.

A popular solution to these problems is the SNS extension. SNS separates the editing interfaces for these types of content, but the problem is that it makes too much of a separation. With SNS, stylesheet and javascript content is stored in a separate table and is generated by models completely unrelated to the Page model. This means that other extensions are required to do extra work to provide features and Radius tags to SNS content, and as a result many extensions do not do this work. This situation makes for a confusing introduction to Radiant for new users and developers alike.

You can get around this SNS limitation by using the SNS Page Hook extension but even this solution will lead to unpredictable results because it merely copies modules from the Page model to the TextAsset model and tricks the included methods into believing they are operating on a Page. But this is not a good long-term solution.

Sheets keeps this content in the same location as all other content: Pages. Doing it this way allows any chosen URL or Page slug to be protected properly with newly created pages. Even more importantly, this allows user and developer expectations about the behavior of Radius tags to make sense. With Sheets, extensions which add Radius tags to the Page model add them to stylesheets and javascripts too; there is no extra work to be done.

Not only does it do all this, but the standard Page model provides a headers method which Sheets overrides to alter the mime-type for the returned content. Sheets uses the built-in ways to serve content, rather than generating yet another way to serve content like SNS.

Thanks

Special thanks goes to Chris Parrish for creating the SNS extension in the first place. And thanks to Dane Harrigan for some early bug checking.

Built by Saturn Flyer