IDEA: ID CSS Plugin to replace Custom CSS usage by Creative Services

[acketon]

A CSS/stylesheet/asset loading plugin for WP for use by site designers

Description

The existing Custom CSS plugin is used by both clients and internal Interactive Design staff to customize BU sites. However over the years we've had issues with CSS as part of a custom design that a client has paid for being fragile by loading it into sites via the same Custom CSS plugin that the client has access to make changes as well.

Another big problem is that the CSS only exists in that site database where Custom CSS Plugin stores it. We generally don't have good copies within Interactive Design.

Instead, let's build a new plugin and store the CSS for each of these projects in Github as we do other theme files. After adding this plugin, the existing Custom CSS plugin would only be used by Clients themselves or minor/temporary "hacks" to fix something on the site.

Goals

• Make sure we can isolate ID-built CSS sites
• Make it trackable in Github
• Make it deployable!

Enqueue order

The load order would be:

1. Theme Stylesheets / JS
2. ID Custom CSS Plugin Stylesheets & JS
3. Existing Custom CSS Plugin Stylesheet.

Requirements - MVP

• The plugin should only be able to be turned on by super admin/id admin only
• The plugin should have a notice that usage is only intended for BU Interactive Design
• There should be a way to organize assets for each site:
  • /assets/<asset-group-name>/css-dev/
  • /assets/<asset-group-name>/js-dev/
  • /assets/<asset-group-name>/js/
  • /assets/<asset-group-name>/<asset-group-name>.css
  • /assets/ceid/ceid-dev.css
  • /assets/ceid/js/ceid-dev.js
  • /assets/ceid/vendor/some-slideshow-library.js
  • /assets/butoday/story-name/css-dev/
  • /assets/ceid/releases/ceid-1.2.2.css
  • /assets/ceid/releases/ceid-1.2.2.js
• Branching workflow for when multiple changes need to go out at the same time, such as an issue of Bostonia or a WordPress upgrade change branch. Also, we need a changelog workflow, and someone to be responsible for releases on projects with multiple designers at the same time.
  • Have at least 2 Plugin owners that would be responsible for managing releases and responsible for ensuring releases don't revert styles on other projects.
  • Strict Changelog documentation.
• Responsive Foundation should be used as the frontend library, and added as a dependency. Import burf-tools/tools-grunt into the main Sass file so all variables, mixins, etc. are available to designers/devs. https://github.com/bu-ist/r-static-starter/blob/master/css-dev/style.scss
• Plugin settings allow the admin to select from the stylesheets in the css folder.
• The plugin enqueues the selected stylesheet(s) for the entire site.
• A way to enable a fast workflow for designers to test stylesheets and javascript in their sandbox. User story: as a designer, I want to be able to FTP my changes to my stylesheets up to my sandbox, just like I would with a custom theme.
• Grunt Workflow:
  • Grunt Watch: generates my-asset-dev.css or my-asset-dev.js
  • Grunt Release: generates my-asset-<version>.css or my-asset-<version>.js based on the version number set in package.json
• Plugin in Production environment does not show my-asset-dev.css files. Only the generated files from a /release/.
• There should be a versioning workflow: as an Ashley, I need to be able to bust the browser cache when a Responsi update goes out so I can guarantee all sites are showing the updated CSS.
• Folders for versioning (workflow, not a dev item)
• Metaboxes work with Gutenberg sites as well as classic editor sites
• SEAN, WEIGH IN HERE: Metaboxes are built with cmb2
• The plugin can be deployed from Github directly and work as expected; no build processes are required for the plugin to work, and all assets are compiled and committed.
• Build Process: Grunt for now.
• Are custom build processes allowed? No. Write a custom theme instead.

Requirements - Long Term

• The ability to select multiple custom stylesheets per site is supported.
• The ability to add custom JavaScript, using the same pattern as above: js-dev/SITENAMEHERE, compiled to js/SITENAMEHERE.js
• Multiple JS files should also be supported.
• Some method of enqueuing scripts from the CDN http://www.bu.edu/cdn/scripts/
  • An array in the root of the plugin of CDN Assets and their paths that will always be available as a asset in the asset dropdown in an asset group.
• The ability to choose whether a stylesheet or JS file is sitewide or by post type or page template.
• The ability to choose a stylesheet or JS file to attach on a page by page basis via a metabox on the page or something similar.
• Network-level reporting: a way to see which sites are using this plugin AND have assets enqueued or in use at the network level. User story: as an Ashley, I need to know which sites are actually using Custom CSS or JavaScript during a WordPress upgrade, not just what sites have the plugin enabled.
• Site-level reporting: a way to see which pages have a custom CSS or JS attached to them. User story: as an Ashley, I need to know which pages are using Custom CSS or JavaScript during a WordPress upgrade in one place.

Advantages:

Only we can add stylesheets or custom JS files, it is version controlled AND deployed to production like other work we do. All custom css is stored in one repo so we can have a build process that shares base mixins, etc. (hoping this makes it easier to update/fix/improve/manage)

Downsides:

One repo might make working/launching multiple custom css sites at the same time slightly tricky… you could have a branch for site A and a branch for site B both in progress at the same time. But that should be manageable?

[ashleykolodziej]

I think this makes complete sense. Since the CSS will be in separate files and partials at the end of the day, designers who are working on sites shouldn’t collide much. And since stylesheets won’t appear until they are selected on a site, we should be able to deploy changes at any time.

I love this idea and execution - clean, easy to manage, straightforward. Let’s do it!

[ashleykolodziej]

One thing to add - this new plugin should be compatible with BOTH Responsive 2x and 3x. 1x is a nice to have, but optional in my eyes. After this plugin is complete, I’d like to audit our custom CSS sites and move them over to this plugin.

As far as Sass goes, I’d like to consider putting this on Gulp. We have an existing Gulp setup that runs the same as Grunt with the same commands on child starter, but I haven’t had bandwidth to train people on the switch. We need to do it, though. This would kick me to formalize it and get the team updated in a manageable way.

For Sass folder structure, I would like to see a css-dev folder with a folder for each site underneath. Each folder should contain a site-name.scss at minimum. Partials are optional. A starter file could import burf-tools, which gives access to Foundation mixins and variables without the bloat.

@sr4136 @acketon - thoughts on naming conventions? Does site-name.scss work? Perhaps we can also put a link to the URL of the intended site for that CSS to be used on in a comment at the top of the starter file. One challenge here will be keeping track of which site (maybe sites?) are using which style sheet, in the case of updates. Let’s say we use one stylesheet on multiple sites - can we run a wp-cli command to find out what sites are using a particular stylesheet using this structure?

Also, will we need a cache busting mechanism, similar to grunt version in child themes?

[ashleykolodziej]

For documentation purposes: the workflow is that a designer will need to work on this plugin to build a custom CSS site. To preview their changes, they will need to upload the plugin files to their sandbox. Then, just like a theme, to preview on either staging or live, the plugin will have to be deployed.

Do we want to enforce a release system on deploys for this plugin? This would guarantee cache busting happens, and may be safer since the plugin will eventually grow to affect many sites. The downside is an extra step before deploying.

[acketon]

For documentation purposes: the workflow is that a designer will need to work on this plugin to build a custom CSS site. To preview their changes, they will need to upload the plugin files to their sandbox. Then, just like a theme, to preview on either staging or live, the plugin will have to be deployed.

Do we want to enforce a release system on deploys for this plugin? This would guarantee cache busting happens, and may be safer since the plugin will eventually grow to affect many sites. The downside is an extra step before deploying.

actually one of the thoughts I outlined above in the last bullet was having a sort of "develop" mode that would let a designer load a stylesheet (or js file) from any url. This would let them bypass having to deploy the plugin to see changes on staging or even prod while the project is being worked on.

We could display a warning in the admin that this plugin is in "develop mode" and needs to be changed to "production" mode when development is finished. (Meaning move the CSS/JS into the plugin and enqueue from those files)

This could take the form of some UI:
[ ] Production Mode [ X ] Develop Mode
Choose Asset: [ Dropdown to select registered asset file ] or [ Text field: url to asset file ]
Choose Asset: [ Dropdown to select registered asset file ] or [ Text field: url to asset file ]
Choose Asset: [ Dropdown to select registered asset file ] or [ Text field: url to asset file ]
[ button: Add Another Asset ]

[ashleykolodziej]

I totally missed that piece!

I'm a little wary of introducing a place where you can upload the CSS to any URL and have it live on production - a risk that introduces is that the mode never gets switched properly on site launch, and then one day we clean out the webteam/projects folder without thinking, and that CSS disappears right off the site with no one making the connection until we get a ticket for it. (I know there's a warning for this, but I still don't like it. In theory, someone could clean out webteam at any time.) It seems to me like a sandbox or id-presents would be sufficient for testing/presentations while in development, but without the risk and question of "well, where do I put my files now?" that always comes up with these sites. It also brings a custom CSS site more in line with the theme development process for our new designers. I kind of like the idea of this "baby step" being more in line with our typical process, so they aren't surprised about deploys and things like that.

We still have the Custom CSS editor for emergency fixes, too. We do that all the time with themes, and that would serve the purpose of an emergency fix.

Alternately... what if we just selected a different stylesheet on staging for those who need to do a redesign of an existing Custom CSS site? I have Faculty of Computing and Data Sciences in mind. I designed the original, Corin then starts a phase 2 stylesheet that goes with a re-launch of their content. Live has my stylesheet selected, staging has hers selected. It launches, everything updates at the right time, and we're good. No risk of accidentally uploading the wrong stylesheet to the wrong place or overwriting everything.

[acketon]

Alternately... what if we just selected a different stylesheet on staging for those who need to do a redesign of an existing Custom CSS site? I have Faculty of Computing and Data Sciences in mind. I designed the original, Corin then starts a phase 2 stylesheet that goes with a re-launch of their content. Live has my stylesheet selected, staging has hers selected. It launches, everything updates at the right time, and we're good. No risk of accidentally uploading the wrong stylesheet to the wrong place or overwriting everything.

I think that works!

[ashleykolodziej]

I think we've got our direction then. I can finalize a requirements checklist based on these notes!

[acketon]

New requirement from 5/13/21:

Need some sort of reporting dashboard:

List all sites and/or pages that custom assets (css, js, etc) are being enqueued on so that a superadmin can look in the Network Admin settings and perform testing during WP upgrades.

[ashleykolodziej]

@jdub233 brought up some great points to me in Slack just now about some features that are coming up in WordPress 5.8 that may overlap with what we're planning here, so I've asked him to add them here so they don't get lost as we refine and clarify some of these items :)

[jdub233]

There are new Gutenberg features that will become available in 5.8 that (if I'm understanding correctly) provide user-overridable custom css through core features. They are defined in a new theme.json file, there is some information here:

https://make.wordpress.org/themes/2020/10/01/gutenberg-9-1-new-json-structure-for-fse-theme-json-files/

I was able to catch some of a workshop that demonstrated the css variables, I think it may not be restricted just to block based themes. It looks very SASS like.

It may be worth looking into these new features. We may be better off concentrating on getting to 5.8 than writing new code that may be parallel to upcoming core features.

[jdub233]

Here's more information on "Universal" themes, which aims to bring the the newer "FSE" features to classic themes in addition to newer block based themes (so that they work on both hence "Universal"):

https://make.wordpress.org/themes/2021/05/10/friday-may-14th-at-14utc/

[ashleykolodziej]

Okay - I definitely understand full site editing more clearly now. I think there's a lot of overlap here, and it's also going to REALLY change how Responsi is doing color palettes and typeface choices. Definitely should be integrated into 3x. I also think this makes some super compelling arguments for avoiding custom CSS projects on the ID side in the future, and moving towards a "start with a theme if at all possible" approach.

I think what this won't replace is the use case of "I'm a designer, and I want to do a hyper fancy one time only thing for an editorial article" - think projects like this: http://www.bu.edu/bostonia/summer14/leaf-out/

The full site CSS will also give me a short term stopgap to track existing custom CSS sites during WordPress upgrades in one place. So I think as written, we probably will need this plugin for a while, because I'm not sure how to solve the problem of dealing with our untracked existing custom CSS sites otherwise. But what this says to me is we should be preparing to move our small budget websites away from this workflow in the very near future, because we'll have better tools for that soon.

This also means I should start looking at what FSE might look like in Responsive 3 :D

[acketon]

Mockup of ID Assets plugin Admin page, showing how a user can add an asset to the site and enqueue it sitewide, by post type, or by page template.

Asset Group is what I've decided for now to call a set of custom css/js/etc for a specific "project" or "site". An ID Admin selects the Asset Group. ( think this should be limited to 1 set per site) Then they can see a list of assets provided by that group and enqueue any of them that they would like to. Assets can be enqueued multiple times. Enqueue order (important for JS/css) is set by the order of the asset boxes.

[acketon]

We need to think a bit more about the workflow for Editorial Articles. I'm not sure if working on the story on a sandbox where you could FTP the plugin up is realistic. These are usually worked on in production.

Maybe the designer still works on it on their sandbox but then attaches the CSS to the post on production temporarily via the tracking snippets plugin?

[ashleykolodziej]

@acketon Look at this gem I found hanging out in https://github.com/bu-ist/responsive-framework-1x/issues/94:
https://docs.google.com/document/d/1Ni5WeM9Q9sy6aAflIEPsbq-7vlk8Vdj9-7GWpTQkzSk/edit?usp=sharing

Is there anything in there that helps with the editorial workflow aspect?

One idea I thought was interesting was including CSS as a dependency of a repo. I don't know that that would help with the editorial workflow, but maybe there's something to that in helping with the pull request/deploy process.