Version: 5.3.0-beta1
Author: YJ Tso @sepiariver
cssSweet is a suite of tools for processing (S)CSS. It comes with several output modifiers to manipulate 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.
Find out more about cssSweet here
as well as on the documentation site:
https://docs.modx.org/current/en/extras/csssweet (this one needs updating)
Thank you to contributors: @matdave and the MODX team
- 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. 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 from cssSweet version 1.x.
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.
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_url]]components/csssweet/custom_css.min.css">
and you'll be good to go.
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:
- 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.
- 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.
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.
As of version 4.1, you can also enable the custom ClientConfig_ConfigChange event, if you have the ClientConfig Extra installed.
As of version 5.1, an un-tested—and at this time unsupported—feature exists whereby you can enable the OnDocFormSave event, at which point saving a Resource with contentType = text/css will trigger the Plugin to execute. You still need to configure a Chunk where you include the content of the css Resources via a Snippet of some kind.
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.
cssSweet installs with a suite of utility Snippets to manipulate style declarations. See the files in the Snippets folder for more detailed usage examples. As of version 5.x, the Snippets use ozdemirburak/iris for color manipulation.
- csssweet.convert: Convert color values to any other supported format.
- csssweet.extract: Extract channel values, from any supported format.
- csssweet.lighten: Lighten or darken a color value, in any supported format.
- csssweet.modval: Modifies the numeric value in a string.
- csssweet.prefix: Naively adds vendor prefixes to a string.
- csssweet.saturate: Saturate or desaturate a color value, in any supported format.
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.
Version 5.x changes the behaviour of the included Snippets significantly. The new Snippets install with new names, so your existing implementation should continue to work, but it's worth experimenting with the new Snippets to see how the output compares. There should be no drastic, breaking effects.
If you have a legacy installation, upgrading from version 1 to a later version, the following points should help you avoid any major issues:
- The default property set. It's an established pattern that updating an Element in MODX also updates its default property set. If you've customized the default property set of the cssSweet Plugins, you must move your custom properties to a custom property set, in order to preserve them.
- Some property keys have changed. Most notably,
custom_css_chunkis nowcustom_scss_chunksto 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. - 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 this remains minimally tested.
- 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. - "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. In version 5.x this should be preserved on upgrade.
- 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_modeproperty to the namespace "dev", but you can set the namespace to whatever you want.
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)
