cssSweet

Version: 4.0.1-rc1

Author: YJ Tso (@sepiariver) on Twitter

cssSweet is a suite of tools for processing (S)CSS. It comes with several output modifiers to modify CSS values, and a plugin that concatenates and processes (S)CSS from specified Chunks and outputs to a minified CSS file. version 2+ also concatenates and minifies JS with a 2nd plugin.

The documentation site is here:

http://sepiariver.github.io/cssSweet

as well as here:

http://rtfm.modx.com/extras/revo/csssweet (this one needs updating)

Example Use Cases

• Use system or context settings to store primary colors in a site’s color scheme, then process all other color values relative to these, so you can shift the entire color theme by modifying a few settings.
• Use in conjunction with ClientConfig to give site owners a nice UI to manage CSS styles–but only the ones you expose, and only in the manner you choose!
• Author MODX “themes” that are customizable by the end user.
• Use other MODX tags & placeholders in your CSS–limitless possibilities! Utilize “dynamic CSS” without the performance penalty, because the plugin writes the static CSS file on the Manager Clear Cache and Chunk Save actions, not per request.
• Manage your Sass, CSS, and JS development workflow right from inside the MODX Manager.
• Add a code editor like Ace, and you can use MODX as your IDE for front-end development.

NOTE: please see section below on potentially breaking changes when upgrading, especially from cssSweet version 1.x.

Usage

Installation

You can install cssSweet via the MODX Extras Installer. Or you can download it from the MODX Extras Repo or from the _packages directory. Upload the package to the packages subdirectory of your MODX install’s core directory, and use the “Search Locally for Packages” feature in the Extras Installer to find and install the package.

CSS Sweetness

Once installed, you’ll have a default Chunk in the “cssSweet” category. If you edit that Chunk and click the “Manage” » “Clear Cache” main menu item, a CSS file will be generated for you at [[++assets_path]]components/csssweet/custom_css.min.css

Note: it’s highly recommended to create new Chunks with unique names. As of version 2.x, the cssSweet package has been configured to not update an existing Chunk with the same name, but I haven’t tested that thoroughly yet. I’d hate for it to fail in your production environment.

Reference the generated CSS file in your template, like this <link rel="stylesheet" href="[[++assets_path]]components/csssweet/custom_css.min.css"> and you’ll be good to go.

Customization

In the Plugin properties, you can set the names of Chunks that you wish to process and include, in a comma-separated list. (As of version 2, this is required for the plugin to do anything.)

IMPORTANT NOTES:

1. Put your customized properties into a new property set, so that they won’t be overwritten on upgrade. In this case, ensure the Events are triggered using your custom property sets. Check the “System Events” tab in the Plugin Edit View.
2. Make sure to enable the checkbox at the bottom of the “Properties” tab, that says “Pre-process tags in Property Values” if you are using MODX placeholders like [[++assets_path]].

You can include static Chunks that reference files–even minified files. You can also customize the filesystem location to which to write the output file. Chunks will be included in the order which they appear in the comma-separated list. As of version 2, cssSweet will parse any SCSS syntax in your Chunks, and log error messages generated by the scssphp processor class.

Events

You can optionally enable the OnChunkFormSave Event in the Plugin events tab. (As of version 2, this event is enabled by default.)

Doing so will speed up your process immensely, as a new output file will be generated each time you save a Chunk that is in the list of Chunks you’ve set.

“Dev” Mode

As of version 4, the dedicated “dev mode” properties have been removed, and the dev_mode Plugin property is a textfield rather than boolean. By entering a (string) namespace, the plugin will use the properties prefixed with {$namespace}_, allowing you to process a different set of Chunks, output to a different file, or override any Plugin property.

This allows for multiple workflows and output files. You can use it to build moderately-sized bundles of assets for performance or build a different output file for different Contexts.

Potentially Breaking Changes (especially when upgrading from version 1.x)

The utmost care has been taken to ensure that upgrades of cssSweet are as safe as possible. However, there are a few scenarios that could potentially break an existing site, especially when you upgrade cssSweet from version 1 to version 2+. Hopefully the following points will help you avoid those:

1. The default property set. I haven’t found a way to update the saveCustomCss plugin without overwriting the default property set. If you’ve customized the default property set, I recommend moving your custom properties to a custom property set.
2. Some property keys have changed. Most notably, custom_css_chunk is now custom_scss_chunks to more accurately describe the plugin’s actions. Ensure that after upgrading, your CSS Chunk names are listed in the new property, rather than the old one. I figured a major version upgrade is the most opportune time to change property keys.
3. The sample Chunk has a different name. This served 2 purposes: to demonstrate the scss syntax compatibility, and prevent overwriting the default Chunk on upgrade, because some users (including myself) erroneously customized the default Chunk without changing its name. As with any MODX Extra that installs Chunks, it’s highly recommended that you create new Chunks or rename the sample Chunk. That said, the cssSweet 2.x packages have been authored to not overwrite existing Chunks (with the help of @TheBoxer ‘s GitPackageManagement component), but I’ve tested this minimally.
4. The default output filename has changed. In an effort to prevent overwriting your existing compiled CSS before you’ve had a chance to set the properties correctly, I’ve changed the default CSS output filename. However, if by sheer chance, you had previously customized your output filename to custom_css.min.css, then the saveCustomCss plugin will overwrite it by default! In this (probably rare) case, *make sure* to setup the plugin properties correctly before executing the plugin.
5. “Pre-process tags in Property Values.” This checkbox gets disabled on upgrades. If you’re using MODX placeholder tags in your properties, then be sure to enable this again.
6. In version 4, the “dev_mode” property keys have been removed from the default property set. They’re no longer relevant, unless you set the dev_mode property to the namespace “dev”, but you can set the namespace to whatever you want.

Thanks

A lot of time, research and consideration was put into which libraries should be included in this package, for the minification functions. I whole-heartedly support these fine developers and their open-source projects. Please extend your thanks to these folks, if you find cssSsweet useful (or even if you don’t :P)

[@leafo/scssphp] (https://github.com/leafo/scssphp)

[@tedious/Jshrink] (https://github.com/tedious/JShrink)