Will Browar

Making WordPress Users Feel at Home with Craft CMS

Will — Thu, 10 Oct 2024 07:28:00 -0400

Like most web developers I knew when I was starting my professional career, my first content-managed site was built on WordPress. I think if you ask most web developers who do content-driven websites (marketing sites, blogs, etc...) they all have at least one or two WordPress sites under their belt. When I started working at an ad agency in 2007 I switched to using Drupal for most things, then moved onto projects in Joomla, Statamic, Sitecore, Expression Engine, and a bunch of smaller—mostly proprietary—CMS platforms. Thanks to Andrew Welch’s introduction in 2014, I started using Craft CMS for all personal and client projects and I haven’t turned back since.

At least whenever I had the choice of the platform or when I could guide a client into the direction of which platform to use, we almost always wound up with Craft CMS being our choice. Over the years of being the senior web developer I had spent a lot of time discussing CMS platforms with clients and there were many times where we discussed the difference between WordPress and Craft CMS.

I tried to keep things objective because a lot of times clients were asking for what they were comfortable with in WordPress and they were biased coming into the conversation. A lot of times when we looked at what the client actually wanted their website to do it was easy to show how a Craft CMS site could feel familiar to a WordPress user while also letting us take advantage of the way Craft CMS gave us developers flexibility in content modeling and on the front-end.

With all of the WordPress versus WP Engine drama going on in the past few weeks, I've seen several folks asking for alternatives in case they feel like moving off of WordPress for their businesses or blogging platform. While to be completely honest with you I may not be up to date with all of the features in WordPress these days, but here are a few things that I’ve discussed with clients in the past.

Navigating the CMS

When you log into your Craft CMS site the first thing you see is the Dashboard. Just like WordPress, the Craft CMS Dashboard is customizable and each user can set which widgets they want to appear. There are some built-in widgets that come with the CMS and third-party plugins can also provide you with widgets to add to this page.

Next to the Dashboard widgets is the sidebar that follows you throughout the Control Panel. The links in the sidebar can change based on what kind of user role you have (admin users can see all of the links available), what features of the CMS you are using, and if you have any third-party plugins installed. The one you might use the most is the Entries link and that takes you to where most of your site’s content lives.

When you click on the name of your site at the top of the sidebar you will be taken to the homepage of your site. One thing you might notice is that the Admin Toolbar from WordPress isn’t there by default, but you can install a third-party plugin, called Admin Bar, that is similar to the Admin Toolbar in that you can navigate to a page on your website and use an Edit link to go directly to the edit page for that entry.

Posts, Pages, and Entries

In WordPress you have no doubt heard the terms Posts and Pages. Craft uses the term Entries to describe a piece of content, but Craft CMS content isn’t always treated as a single page in your website. An entry could be displayed as a page of content, or it could be a list of categories, a single article, a product, a menu item, etc... It’s up to you how you want to structure your content and Craft CMS gives you flexibility to build a simple blog with a section of blog post entries or a complex tree of product entries and product sub-pages.

On my personal blog, I have a section, called Article, where posts like this one live. I customized the entry list page to show me fields like the summary field so I can make sure I didn’t forget to write a summary for every article; and I hid the author column because it’s just me over here 😊

Menus

The Pages section of WordPress has another purpose in that in addition to letting you edit single pages it also can decide the structure of your pages and you can use that to build out a main navigation for the front end of your website. On the one hand, Craft doesn’t have something like this built in, but I think that’s actually a good thing. For one, how you edit content and how you structure menus can cause problems when they are tied closely together. In addition to that, there may be times where you need to link to a page in multiple places or in multiple menus on your website.

I like to manage menus via the tools built into Craft CMS, but for a very WordPress-like experience, there's another plugin I can recommend, simply called Navigation. It makes it easy to manage a main menu in addition to secondary menus like one you may find in the footer.

Publishing Entries

Similar to WordPress, Craft CMS gives you a bunch of options around publishing posts. You can schedule posts to go live on a specific date, you can change the slug of the entry (as part of the entry’s URL), and Craft CMS has a whole drafts and revisions workflow that lets you jump back and forth between previous versions of an article and future drafts that aren’t live yet. Craft CMS also automatically saves your work in drafts as you type so you don’t have to worry about a bad internet connection ruining a long session of writing.

You can use the Live Preview feature to see how your content will look before publishing, and you can create preview links that you can share unpublished drafts with collaborators.

Editing Entries

Probably my favorite thing about Craft CMS is how flexible the field setup is. If you are used to WordPress and doing everything in the old WYSIWYG text editor you can create that and use that for all of your content. The newly updated CKEditor first-party plugin not only works like a WYSIWYG-style text editor, but it comes with a bunch of new ways to pull in field blocks that you can create and repeat throughout your content.

For myself, I prefer to take those field blocks and use Craft CMS’s Matrix field, which essentially lets you add blocks and mix and match them in whatever order makes sense for your content. If you really need it, you could even nest matrix blocks into other matrix blocks, allowing you to handle some very complicated content needs.

For a simple blog I have a text block type (where I write everything in Markdown), an image block, subhead block, and a few specialty blocks for things like notes or fancy emojis. On the front end of my site, I create HTML and CSS components that take all of the fields from each block type and make them all look good no matter how you mix and match them.

Managing User Uploads (AKA Assets)

One of the biggest aha! moments that almost always happened for clients when we were discussing using Craft CMS for content management was around the way that images and other files are managed. I would show an asset page that shows you thumbnails of a bunch of images and I would show how you can upload an image while editing an entry or you can select an image from an existing pool of images, uploaded in the Assets section of Craft CMS.

What I would show is how you can have an image selected for a news post and that image would be used on a thumbnail for the news posts on the homepage, on the header of the news posts page, and in social media images shown on Facebook and other networks that showed link previews. This one image would use a focal point (a feature built into Craft CMS) and that would make it so this image would be cropped and still look great in all of these places. The thing that really knocked people’s socks off was that you can replace an image by uploading a new file in its place and that one image would be optimized and would be replaced in all of those places where it was being used.

Gone would be the days of re-uploading the same image multiple times into the Media Library then trying to figure out which one got used where.

I know things are different in WordPress now, but 10 years ago the idea that you didn't need to upload specific thumbnail and social media images into some bottomless Media Library was a huge win for authors. Nowadays Craft CMS’s asset organization is as comfortable as working within the filesystem on my computer (where you can select multiple files and drag them into subfolders to organize things).

SEO

Folks who use WordPress might be familiar with many SEO plugins, including one called Yoast SEO. While it takes a very different approach from Yoast, there is a very popular SEO plugin for Craft CMS, called SEOmatic. SEOmatic gives you sort of an onion of SEO layers where you can set global SEO settings (like the title of your site and a default SEO description), you can set a template for each entry section, or if you prefer to go page by page there’s a field you can add to your entries to manually write the SEO.

SEOmatic can pull SEO metadata from your content fields and image fields. You can also specify content types for each entry, so you can give search engines even more meta data to work with. For example you can say that an entry is a recipe and you can pass more information into SEOmatic to let Google know that it's more than just an article page and therefore it can add more content to its search results.

Theming, Templates, and the Front End

Here might be one of the biggest pain points for folks switching from WordPress to Craft CMS. Craft CMS purposely doesn’t manage themes. Just like you have flexibility on what fields you set up and how you structure your content, the idea is that you have full flexibility on the front end of your website, too. Which I can see where this seems like an issue, but in some WordPress themes you are tied to a specific content editor because this is what the theme needs in order to properly manage the content.

Instead of forcing you into a content authoring experience you don’t love, Craft CMS leaves it up to you to develop the front end but they give you a bunch of tools to make that easy.

Craft CMS uses the Twig templating language by default. If you’re a WordPress developer and you’ve used Timber, you already know how to use it. If you’ve used Shopify for a store in the past, or worked with HubSpot for mareketing, the syntax of Twig is very similar. You are basically doing everything in HTML until you need something from the CMS, and then from there you’re going from My static text to {{ entry.textField }}.
Craft CMS has a full routing setup so you can make pages that aren’t content managed. You can use this to create files that aren’t just HTML documents, which makes creating an RSS feed possible with just a Twig template.
For those who want to use Craft CMS to drive a separate, static front-end site you could use the built-in GraphQL setup to power a static site builder in whatever framework you want. All of your field data is included in the GraphQL output (based on what you allow in the GraphQL settings section).

At the ad agency, it was rare that we didn’t program the design from scratch and there were a few times where we wound up downloading HTML-based themes from websites like ThemeForest or Tailwind UI and we used them to create the front end. With most of the HTML structure already done, a lot of the work was swapping out headers for the page title and then matching up HTML with content fields in the CMS.

Forms

If you have a contact form on your site, Craft CMS is set up so you can create a form on your site front end through Twig, however, I’ve found third-party form plugins to be a good way to go if you want to create forms and manage their fields through the CMS. They also handle a lot of the work around displaying the form results and doing things like exporting submissions (for things like contests and newsletter signups).

I have the most experience with the Freeform and Formie plugins, but I think I would recommend looking through the Plugin Store to see which form tool fits what you need.

Ecommerce

The folks who create Craft CMS have created a few first-party plugins to help you sell stuff on your websites. WooCommerce users will feel at home with the Craft Commerce plugin. It lets you create products, provides the full checkout experience, and it gives you a ton of flexibility to display your products around your website.

The Shopify plugin can help you connect to an existing Shopify store and it will sync you products over from Shopify into your Craft CMS website so you can add them to the pages on your site.

Just like all the plugins mentioned above, it’s worth looking at the Plugin Store to see if Craft CMS can integrate with an existing system you already have in place.

Technical Requirements

I could go on and on about the feature of Craft CMS, but there are some prerequisite things you might also want to know about from a web development standpoint. Here are a few:

Just like WordPress, it’s built on PHP and MySQL (or PostgreSQL if you prefer).
Image transforms require some packages to the installed on your hosting server (but in my experience most hosting servers already have them installed).
You don’t need to use Docker for local development, but DDEV has a Craft CMS Quickstart that makes local development a fantastic experience.

For a full list of language and hosting requirements, see this page in the Craft CMS docs.

Hosting

There are some minimum hosting requirements for all Craft CMS sites, but depending in the size of your audience or if you use Craft CMS to run a business you may have some specific things you are looking for in a host.

If you are using a WordPress hosting solution already you might need to move to another service or at least to a plan that isn’t specific to WordPress installs.

I would personally avoid using any sort of shared hosting service, like GoDaddy, but using managed hosting is totally fine. Here are a few recommendations I’d consider if you are looking:

Craft Cloud – Craft CMS’s first-party hosting solution isn’t cheap, but it offers a bunch of features and you get the support from the team behind Craft CMS.
Servd – Servd is managed hosting that is designed for Craft CMS projects.
fortrabbit – fortrabbit is a great choice if you have Craft CMS and non-craft CMSs. They typically host sites built on Craft CMS, WordPress, and other PHP-based CMSs.
Linode/Akamai VPS – If you are comfortable doing your own DevOps work you can host Craft CMS sites on a cheaper VPS as long as it meets Craft CMS’s hosting requirements.

My blog is hosted on a $5/month Linode (recently purchased by Akamai) and I use Laravel Forge to manage things like SSL Certificates and the server config. I also use an S3-style bucket for image storage through Linode, which is $5/month. My hosting cost for this site is something around $300 per year.

I don’t have a big audience, but I use a caching plugin, called Blitz, to turn my site into a static site. This is what lets me get away with the $5/month hosting server and it also makes sure that if for some reason I had a spike in traffic the server could handle the load (no getting fireballed here).

Plugins, Modules, and PHP

I mentioned some plugins above and just like with a WordPress site you might find yourself using some third-party plugins in order to get your site to act and work like you need it to. I only use a handful of plugins on this site because they do things that—even as a developer—I’m glad to not have to do, but I would generally recommend only using the plugins you actually need.

If you have written plugins for WordPress sites in the past it shouldn’t be too hard to move over to the way Craft CMS works with project-specific modules and plugins. You can do things like create custom form handlers, extend Twig with your own logic and tags, and integrate your website with other APIs and services that you use.

For most folks, with the right mix of plugins you can get away with not touching PHP at all in the development of a Craft CMS site, with maybe the exception of changing configuration files to get the site running on a server.

Fin

If you’re considering jumping from WordPress to Craft CMS I hope this post gives you an idea as to how you can make that experience a little more relatable.

I didn’t touch on many other features and approaches you can use in a more advanced Craft CMS website. If you’re thinking of diving in, here is what I would recommend in order to get you started:

Check out CraftQuest if you like to learn from video courses. It covers some tips from getting started to advanced ways to optimize your project.
Poke around the Craft Documentation to find up-to-date installation instructions, details instructions for setting up fields and entries, and the full list of things you can do in your Twig templates.
Once you’ve gotten your site started, read some of the articles on NYStudio107 to find out how to optimize things and to deep dive into both Craft CMS and general web development topics.
Say “Hi” and get your questions answered in the Craft CMS Discord or on the Craft CMS StackExchange.

Happy Crafting!

💻

Guide 5: Don’t Write That Craft CMS Module!

Will — Sat, 21 Sep 2024 11:30:00 -0400

Sorry for the hyperbole. If you want to write that module, go right ahead.

This may come as a surprise, but as its author, a long time ago I stopped thinking about the Guide plugin as a place to write a traditional CMS Manual. This is still a fine use case for the plugin, but my theory since the Guide 3 days was that unless you are going through a proper training session where you walk them through page by page, clients and content authors are unlikely to take the time to read through every detail about their website in a book or wiki format.

Even when I wrote CMS manuals it was often a jumping off point. One quick paragraph about how to update news articles and where their related posts will show up, then a link off to /admin/entries/news-article to get them right into editing. The best place for those details you were sweating should be right on the News Article edit page itself. So putting documentation above the edit fields and in UI Elements—and now in slideouts—seems like a good way to make sure content authors feel comfortable with the edits they’re making.

Adding content to slideouts is a new feature in Guide 5.

Getting Plugged In

Putting documentation and useful authoring tips around the edit page is one thing, but sometimes clients ask for something more specific. Maybe you have a client that runs a news site and they have a pool of images that they are able to pull from that are organized in different folders in an asset volume. The client wants to make sure that they have alt text on all their images, across all of their folders in the asset volume. As the site’s developer, how do you approach that?

You could make a page on the front end and password protect it (or just hope that nobody comes across it). This way you could use Twig and use craft.assets.volume('newsArticlePhotos').all() to pull the images that are missing alt text and display them in a list.

But you're probably better off putting this into the CMS somewhere and that gets you into plugin or custom module territory. Say you go the module route and you do the following:

Create a new module PHP file.
Register it to the app.
Create a template route in the module file.
Create a Twig page to render at the route.
Extend the Craft CP template and follow along with all of the Twig blocks and variables available within that context.
Create a way to get CSS into the page, or use {% css %} tags to write CSS in your Twig document.
Write your asset queries and create your template from there.

If you’re experienced with PHP and with Yii modules this isn’t all that hard once you’ve got the hang of it, but then there are other concerns to think about:

Updating it on production means deploying a change to your website’s code base.
Locally you’re working with old data or you’re pulling down assets and the database from time to time (which is common in a lot of development environments).
Modules and plugins require maintenance. While uncommon within a major version of Craft CMS, changes in PHP and Craft CMS’s classes mean that you should keep track of updates and be prepared to make tweaks to your module as part of major updates to Craft CMS—including changes to Craft CMS’s underlying frameworks.

There’s a Plugin for That

I’m here today to convince you that using Guide is a better solution than both of those options above. Here are a few reasons why:

In Guide you are writing Twig code just like you could on your site’s front end. This includes Twig functions and tags provided by third-party plugins.
Guide comes with a CSS editor that uses nice-to-have features, like color pickers and basic autocompletion. There's also a JavaScript editor if you want to add some more advanced interaction to your guides.
When you make changes to guide content, CSS, and JavaScript, it’s happening on the server, meaning no build process or deployment is required.
If you want, you can use permissions to open up authoring of guides to clients and content authors.
There are no PHP classes to learn. If you want to add content to a widget, CP page, UI Element, or a slideout panel you can do that through the Guide Organizer in 2-3 simple steps.

In that example above—the one about the alt text checker—you could create a guide, use Twig to query for your assets, use a Guidetable component to lay out the data, and then use the Guide Organizer to add this checker to its own CP page, as well as a widget on the Dashboard, and as a slideout on the entry edit pages where you add these images.

The code for this entire thing looks like this:

{# Set the asset volume you would like to check for images in. #}
{% set volume = 'newsArticlePhotos' %}

{# Display a list of invalid images that are missing alt text. #}
{% cache %}
  {% set assets = craft.assets.volume(volume ?? null).hasAlt(false).kind('image').all() %}

  {% if assets|length %}
{% apply markdown('gfm') %}

These images are missing alt text.

{% endapply %}
    {% set rows = [] %}

    {% for asset in assets %}
      {% set cell1 %}{{ craft.guide.component('image', { modal: true, url: asset.url }) }}{% endset %}
      {% set cell2 %}{{ asset.title }}{% endset %}
      {% set cell3 %}{{ asset.filename }}{% endset %}
      {% set row = [cell1, cell2, cell3] %}
      {% set rows = rows|merge([row]) %}
    {% endfor %}

    {{ craft.guide.component('table', {
      headers: ['Preview', 'Title', 'File name'],
      rows,
    }) }}
  {% else %}
{% apply markdown('gfm') %}

All images in this volume have alt values!

{% endapply %}
  {% endif %}
{% endcache %}

When rendered in a slideout, this guide looks like this:

Clicking on an image will show the image in a modal so you can verify that you are looking at the right image. Clicking on the title of the image will take you to the edit page for the image asset.

If you have a lot of images, you could take this a little further. There’s a Snippet in Guide, titled Contact Sheet – Images, that you can use as a starting point. You can replace the code above with the Snippet’s Twig and CSS code. By default any image shown that has an empty alt text field is highlighted in fuchsia so it stands out.

Just like the first example, clicking on the image opens the full image in a lightbox and clicking on the title takes you to the edit page for the image asset.

If you wanted to, you could change the asset query to include only assets that had a blank alt field. Then your client could work through the images in the guide until they’ve emptied the list. Sort of like asset inbox zero!

Okay, Sometimes You Still Need a Plugin or Module

Using Guide to build out tools like the example above is a perfect use case for the plugin, but there are some things that Guide can’t—or shouldn’t—do. For example, Guide doesn’t provide a way to hook into PHP like you can in a module. This means making changes to the Craft CMS CP in Guide are based around things you can do with HTML/Twig, CSS, and JavaScript.

Guide also doesn't do anything to change your content or augment the content editing process. So doing things like trying to add form inputs to entry edit pages might cause some errors to occur in the content authoring process. In that case creating a custom module with a custom field in it might be the best way to go.

What you can do is use forms and controller actions in Twig to do some basic content editing within the scope of the controllers built into Craft CMS. If you are feeling really advanced, you could use JavaScript in Guide to call some of Craft CMS’s built-in JavaScript methods, like window.Craft.postActionRequest() and perform similar actions without using a page refresh.

Using Guide to Replace Other Plugins

Part of the reason I wanted to write this post was to help change the perception that Guide is just another wiki tool, but the thing that got me to write it is that I noticed that there’s been a big drop in plugins that are supported across both Craft CMS 4 and 5. Some folks have noticed that there have been plugins that have been marked as abandoned, but when you go to the Craft CMS Plugin Store and switch from Craft CMS version 4 to 5 you can also see that some plugins either have not yet been updated or perhaps the developer behind the plugin has decided to move on from its development (and didn't mark the plugin as abandoned yet).

I know from experience that updating and maintaining plugins takes time and on the flip side of that, upgrading a Craft CMS site from 3 to 4, or 4 to 5 can come to a halt when the plugins you use aren’t supported across both versions. Craft makes it easy to see which plugins are updated with their upgrade Utility, and in some cases you need to decide on whether or not you’ll replace a plugin or drop it from the site. My guess is that in this situation most Author Experience-focused plugins are easy to let go as they may be seen as nice-to-haves (Guide included!).

My goal with Guide is to reduce the amount of plugins and custom modules you need to maintain in a Craft CMS project. While I can’t promise anything in terms of long-term support, I can say that Guide PRO is popular enough that I plan on continuing to support it for the foreseeable future. I also feel like the plugin is finally at a point where its found its scope and while it might continue to improve over time, it’s unlikely that I’ll make big changes like the change from Guide 2 to 3. So while when Craft CMS and Guide major versions are updated my goal is that you will only need to make a few minor Twig updates to support new Twig features and CSS updates to match the control panel CSS—if any changes are needed at all.

So next time you’re looking at installing a new plugin or writing a module, try checking out Guide from the Plugin Store. And if you come up with a great use for Guide as a module, consider using Guide's built-in export utility to export out your guide and post it as a Gist or in the Guide Discussion section on GitHub.

📕

Guide 5 BTS: Slideouts, Vue v. Web Components, and Plugin Design

Will — Wed, 11 Sep 2024 12:30:00 -0400

The summer of 2021 resulted in two releases in the world of Craft CMS—one big one for me and one big one for everyone else! In July there was the release of Craft CMS 3.7 and about a month later I released version 3 of the Craft CMS plugin, Guide. Regarding the Guide release, I had been planning on its release for months, so I put out what I felt was a good GA release, but I had plenty of plans for improvements and features that I planned on working on soon after.

What was released in Craft CMS 3.7 was one of the best and worst features for my newly minted plugin.

Slidouts

Along with a bunch of other author-experience features, Craft CMS 3.7 introduced the slidout UI for making it easier for authors to make changes to related entries, image assets, and other related elements. You could double-click just about any entry element in the UI and it would open up a full editor in the slideout panel—letting you make changes to the entry, save them, and then when the slidout panel closed you’d be right back to the original entry you had begun with.

It was a really impressive feature and since one of the things I really wanted to promote in Guide 3 was the idea of putting important authoring information right on entry edit pages, having some sort of button in the sidebar that could open up related guides (content entries in the Guide plugin) in a slideout was an absolute no-brainer. I added slideouts to my backlog and planned on working on it for a 3.1 release.

It had been a little bit before I could make the time to work on the 3.1 branch and I remember having a little trouble figuring out how to work with the Craft.Slidout API at first. I found Leevi Graham’s excellent walkthrough on working with the Craft.CpScreenSlidout API and that helped me get a working prototype going. At least I could hack some of the way Guide moved content around the Craft CMS CP (Control Panel) to get guide content to appear on a Craft.Slideout panel. From there, that's where a bunch of problems became obvious around one of the basis on Guide’s architecture.

Relying Too Much on a Vue 3 Feature

The approach for Guide 3 came from what I was seeing in my own personal use of the Guide 2 plugin. The company I had worked for was still creating CMS guides (a lot of time we had a template and we brought it from site to site), but we were also doing lots of custom Craft CMS module work. Clients wanted a page in the CMS to keep track of things like image alt text or to have a widget on the Dashboard page that showed very specific data. Guide 2 let you do some of this and by Guide 3 I had re-engineered it so you could take one guide and spread it around several of the predefined locations in the CP, as well as on any page in the CP—and even on elements outside of the main #content area.

We were making custom alert banners and dropping buttons in the sidebar on element list pages. We'd do things that would make Brandon Kelly and the UI folks at Pixel & Tonic cry (probably), but these customizations were helpful for our clients and how they wanted to use their CMS.

All of this was driven by how Guide would let you put in any CP page URI (like seomatic/settings) and then any CSS selector you could find in the CMS’s HTML markup, and Guide would figure out how to get your page content to show up there.

Vue Teleport-Driven Development

This ability to move guides into various elements drove the main way that all guides were displayed on the page. While you may have seen a guide appear above the fields on an entry edit page, what was really happening is that Guide would render all of the guides at the bottom of the page from Twig, then use Vue 3’s Teleport component to take the guide content and throw it up to the correct element above. If you had some guides appear above the entry edit fields and then some guide content appear in another element, Guide would still render all of the guides at the bottom of the page, but I had mapped out all of the guides and where they were going and then I had Vue dispatch them upon mounting Vue.

I was pretty happy with this setup but there were a few thorns on that rose. For one, Vue Teleport required an element to be rendered at the point that Vue was mounted, or it would sort of say "hey, I want to teleport this thing to this element but the element doesn't exist yet... I guess we're done here...". At that point Vue would give up and your guide content wouldn't show up anywhere. I worked around this for some situations, but this was one of the bigger issues with trying to get guides into slideouts.

Making Messes in My Code Base

When I started the slideout prototype I had already started refactoring some things in my code base to migrate my Vue components from TypeScript with Vue’s Options API to using TypeScript and Vue’s Composition API. Anybody who has worked with both knows that the Options API with TypeScript wasn't nearly as straightforward as the Composition API approach. At one point I realized I had made a mess of things and that derailed things for a while. Some of it was my TypeScript implementation and some of it was me getting used to how to convert my existing code to Vue 3’s Composition API.

Also, rendering all guide content in Vue had another downside that I couldn't come up with an answer for. Vue likes it when Vue knows about everything it’s rendering. If done with coding guard rails in place you can get plain JavaScript to work with Vue, but it was really limiting with what you could do with JavaScript to customize guide content without completely breaking things. Craft has a couple of handy Twig tags, such as the {% js %} tag, that allow you to write custom JavaScript and while Guide would let you use them in your guide content (anything Craft CMS’s Twig could do you could do in Guide), but if you tried doing something like using vanilla JavaScript to sort rows in a table of data you'd be in trouble.

There were other problems with my implementation and I would create a branch, get stuck, and would scrap it for another attempt. I had thought about how to move forward within my code base for many months and finally came to the conclusion that some big rewrites would be needed.

Dropping Frameworks to Get (a Little Bit) Closer to HTML and Twig

Okay, fast forward to early 2024 when Craft 5 was entering beta. I had taken a break from the Guide problem and let that one sit on the back burner so I could show some love to my other two plugins, Admin Bar and Little Layout. Admin Bar had some of its own issues and the solution I went with for working with it across Twig and JavaScript SPA-like sites was to break it out into a standalone Web Component.

Little Layout also got the Web Component treatment as I converted the field and its settings from Vue 3 to using Web Components that wrapped around HTML elements that were rendered by Twig. The difference between waiting for DOM elements to be ready so you could vue.mount() an instance onto it versus registering a Web Component and having it automatically take care of kicking off when the custom element gets added onto the page was a big eye opener for me.

This is the thing that made Guide click for me and I got to thinking about how a refactor from Vue to Lit (my current Web Component framework of choice) might look.

Introducing Guide 5.0 (Beta)

This introductory post goes over the details around what’s new in Guide 5 at a high level.

What is new is that guides can now be shown in slideouts 🎉, and there are no hacks used to get them there. There's also a new guides list page that I hope will fix some of the confusion that the old Guide Organizer page created for some folks. I’ve re-written the entire UI side of things and even moved the documentation out of its own Nuxt-based docs website and I've put it right on the pages in Guide (you can also read them as markdown pages on GitHub if you prefer to read the docs that way).

More details around what has changed can be found on the plugin CHANGELOG on GitHub.

It Was a Good Idea at the Time

Guide 5 drops Tailwind and Vue 3 as dependencies. I don’t have a problem with either technology, but they no longer benefitted the project in the way I had hoped when I introduced them.

With Tailwind I had used it for a lot of the Vue component templates and I had offered a very small subset of Tailwind classes to guide authors as "Guide utility classes". It worked fine for my Vue work, but after thinking about it for a while I thought that it's not fair to offer Tailwind but to make customers do two things: they A. have to look up whether a class is available before using it, and B. they had to prefix everything with g- (so display: grid would be g-grid). I looked into ways of running guide content through some sort of Tailwind compiler, but I couldn’t find a good way to do that without a Node server or adding some pretty big dependencies to get things working in PHP.

Instead of using Tailwind I made it easier to write CSS for Guides by adding a code editor field that has some basic code completion and CSS syntax highlighting. For authors who just want to use Markdown I added a few more styles to cover common Markdown elements. For folks who do want to use CSS most of the default styles now come from Craft CMS itself and many of my overrides include CSS Custom Properties so it should be easy to override styles and spacing.

I think with all of the new features CSS has to offer, it is much easier to work with CSS directly. Features like :has() can be a huge help and I added a container to guide displays so you can use @container queries to make adjustments as guides appear in widgets and on full pages, alike.

Using the Platform

Regarding Vue, I was really invested in getting Vue Teleport to work and I thought at one point that if I needed to use Vue for some of it I may as well write everything in Vue. The problem with this is that if I wanted to do something with a native Craft CMS element, like form inputs, I either had to play a game of JavaScript tag between Vue and the native HTML components or I had to create my own components. I wound up creating Vue components that looked like the native text input and select components and they worked very similar by the time I was done.

The big problem, though, is that the version I created got out of date very quickly. To their credit, Pixel & Tonic have put a bunch of effort into making accessibility improvements and iterations on the design of the elements in the CP and my component clones weren’t getting any of it. By removing Vue’s rendering I wound up going back to using Craft CMS form elements (via their Twig macro) and now when you submit the form for something like editing a guide it's back to using a good old fashioned HTML form. Any reactive bits come in the form of adding event listeners and then maybe doing something within a Web Component and using slots to swap out content or visually hiding irrelevant input fields.

Because of the way Web Components are registered to the page and then initialized when they are added to the DOM, I got around the way I was using Vue Teleport to move guides around. In some cases guides are just rendered in place, but for guides that are added to places outside of the presets I am now using native JavaScript to take a handful of guide elements and then distributing them where they need to go. There's a Web Component that is just a wrapper around individual guide content that handles things like adding a menu when multiple guides are displayed in one spot. Otherwise guides are now just HTML rendered from Twig.

Some of the Guide Twig components use Web Components, too, but those are added by guide authors using Twig, and the Web Components just enhance their functionality. For example, the image component will just display an optimized version of the image if you just pass in an asset parameter. Because it’s transformed to a smaller size it can be hard to see the details in something like a screenshot, so now there’s an parameter in the component function to make it so the image can be clicked on and the original image can be displayed in a modal.

{# Adds an image from an uploaded asset and does an image transform to reduce the size and optimize it. #}
{{ craft.guide.component('image', {
    asset: craft.assets.filename('guide-widget.png').volume('guide').one()
}) }}

{# Adding the `modal` param wraps the output of this image in a web component that handles opening up the full size image URL in a modal when you click on it. #}
{{ craft.guide.component('image', {
    asset: craft.assets.filename('guide-widget.png').volume('guide').one(),
    modal: true
}) }}

The output is a tag with srcset used to handle multiple resolutions. If you add the modal option a Web Component wraps the element to add the modal functionality but it doesn't do anything to the image inside of it.

I really like this kind of thing. In working with Web Components for a third time now, I am starting to understand where Shadow DOM and Light DOM (non-shadow) have their own benefits. I also like the idea that I don’t have to worry about big framework shifts because Lit seems to be closely in tune with the web standards behind Web Components. Maybe someday these web components will simply follow web standards and I can remove Lit, but for now it includes a lot of great tools that makes working with Web Components very pleasant.

Customer Research-Driven Development

At one point all of the trouble with Guide’s source, and what looked like a big dip in sales, got me to think about how I wanted to proceed with the plugin. The trickiest thing is I have GitHub Issues and Discussions as my main point of getting feedback and while that helps show the holes, I wanted to know what people using the plugin actually thought and to know how they used it. In early 2024 I put out a survey in the form of a Google Form and while I got a few responses from that I also got some suggestions by folks via the Craft CMS Discord.

What I had learned was that Guide 3 was confusing. I had put together what I thought were clever redirects when you didn’t add certain settings, but other than in the docs somewhere, I hadn’t explained why you were getting redirected. From a UI design standpoint I tried to cram a lot of things into the Organizer page and doing things like trying to restrict the height and forcing page scrolling within page scrolling made the UI even harder to work with.

With Guide 5 I hope I have corrected a lot of that. Splitting up the Organizer so you now create and manage guides on one page, then having a separate page used to map out guides will hopefully help make things make more sense. I got rid of all of those redirects and even got rid of some settings being required in the first place.

Doing a little dogfooding, I also added my own Guide buttons around the pages in Guide where I thought documentation could be helpful. These buttons show the documentation in slideouts—of course 🎉

Guide 5 is Now Live

Guide 5 is now available and can be installed via composer or from the Craft CMS Plugin Store. The features above are available in the paid PRO edition, and a LITE edition is available for folks who just need a simple CMS Guide.

If you run into any bugs please add an issue to the Guide GitHub issue page. If you have questions or feature requests, please head over to the Guide GitHub Discussions page or drop my a line.

📓

Guide 5

Will — Tue, 10 Sep 2024 22:30:00 -0400

Guide 5 is here with support for its number-one requested feature: putting guides in Craft CMS slideouts! This release also brings a lot of quality-of-life features that have been suggested by the Craft CMS community. It has been re-structured to make it easier to manage guides and then distribute them around the Craft CMS CP (Control Panel).

Slideouts 🎉

Now when you are on an element edit page—for entries, assets, globals, categories, and users—you’ll see a new Guide button next to the Live Preview button. When clicked, this button will open up a slideout with all of the guides relevant for that element. This could contain how-tos, important authoring workflow steps, stats, a changelog, and other content-aware information—whatever you can think of writing in your guides. When you are done you can close the slideout panel and get right back to editing the element on the page.

Guide also comes with a new guide-button Twig component so you can put your own slideout button in any of your guides.

Markdown Rendering

In previous versions of Guide you could wrap text in a markdown Twig filter to render a few lines of text in Markdown at a time. In Guide 5 there is an option on every guide that lets you render the whole guide in Markdown. This can be great for pages of documentation and for content written by authors who prefer not to mess with HTML markup and Twig tags.

If you did want to drop in some HTML, Markdown leaves HTML tags as-is when rendering. Twig tags are also welcomed and they’ll be rendered on the page before Markdown processes the content—letting you do things like use {% for %} loops to fill out Markdown lists.

New Organization

The Guide home page is now called CMS Guide—for those who want all of their guides to appear in one place.

The new Guides page lets you manage the guides in your Craft CMS project. From here you can edit and delete guides, as well as preview guides to see what they'll look like in a slideout. Clicking on a guide title takes you into a standalone page in the CP with your guide content on it.

The re-designed Guide Organizer lets you enabled guides for Widgets, UI Elements, and lets you distribute guides on element edit pages or a specific URI (you could create a guide with some documentation around how you had set up your favorite SEO plugin and put it right on the plugin’s settings page).

Guide Components

Guide’s Twig components have all been modernized with a few additions and quality-of-life improvements:

Images can now be zoomed in by clicking on the image and showing the full-size image in a lightbox.
A new Details component lets you simplify your guides by hiding detailed instructions and documentation until your reader needs to see them.
The Table component is now a Twig component that lets you programmatically fill in table cells. Combining it with Twig’s {% set %} block lets you fill in tables with HTML so you can add image previews, links, and styles to your data.

CSS and JavaScript Customization

New fields can appear—based on your settings—in the Guide Editor that let you add custom CSS and JavaScript to your guides.

With all of the powerful tools CSS has to offer you can use things like :has() and Container Queries to make your guides fit—wherever they are added. Guide makes use of the CSS Custom Properties built into the Craft CMS and provides several CSS Custom Properties of its own—allowing you more customization in your guides.

The JavaScript field adds a callback onto the page that is fired whenever the guide is displayed. Using the Craft Code Editor field by nystudio107, you can author JavaScript in a code editor that has JavaScript-specific code highlighting, autocomplete, and multi-cursor editing.

Settling All Family Business

This release makes Guide a better plugin citizen. All static text can be translated into other languages, the source code has more-detailed documentation, and many issues and features requests have been incorporated.

Guide 5 is Alive

📘

Testing Craft CMS Fields with Guide UI Elements

Will — Sun, 31 Mar 2024 16:53:00 -0400

I just made some updates to the field plugin, Little Layout, to give it support for Craft 5. Of the plugins I release on the Craft Plugin Store, this one I test out the most because it affects author content, and bugs on a custom field can have some very unwanted results.

I like to dogfood my plugins for yet another touch point to make sure things are working as expected, so last year I put together a way to use Guide to test out all of the different ways you can output data from a Little Layout field into a Twig document. I used this setup when refactoring the front-end portion of the field, and when experimenting with new features.

With other developers working on updating their plugins for Craft 5, I thought this would be a good time to share, in case anybody else finds this setup useful.

Setting Thing Up

The first thing you'll need to get this working in your development environment is install Guide from the Plugin Store.

Next you'll need to change the edition of Guide from LITE to PRO. While I would really appreciate it if you'd buy a PRO license, this setup doesn't require you do pay anything, and I wouldn’t ask you to pay for it for just this purpose.

You can set Guide to the PRO edition, by hitting the Try button on the Guide Plugin Store page.

Once you've installed and activate the trail for Guide PRO, the button will change its label.

With Guide installed, visit the Guide Settings page to confirm that a Template Path and Asset Volume are set up. While you might not need these for your layout tests, they are required for Guides to work with images and Twig templates.

Field Settings

To test your field, you can create a new field in Craft’s Fields settings page. At this point you can set it up with whatever options you want to use as a default, or you could even create multiple fields from your field type. I will typically start with the default settings and then go through the process of updating each setting I want to test out, to also make sure I get the expected results for that field setting.

So I have created a Little Layout field, called Layout, and I’ve adjusted a few settings that I want to start from in my test layout.

Entry Types

Next up you’ll need to create an element or use an existing one where you don't mind editing the field layout. You can do this by adding an Element Type and a new Entry Section.

In this case, I created one called, Homepage.

Using the Field Layout field, I added my Layout field:

Next, click on the UI Elements tab and drag a Guide UI Element over to your field layout. I set it to span 50% width for both the field and the UI Element so I can see them both side-by-side.

When you are ready, click Save to confirm your field layout.

At this point you could go to that new entry type and create a new entry to see what your field layout looks like.

If you have any guides created in Guide, you'll see a select field that lets you pick a guide to use here. If not you’ll see a message indicating that there are no guides created yet.

Creating Your Field Test Guide

If you are new to Guide, the typical process for creating a guide goes something like this:

Click on the Guide link in the Craft CP sidebar menu.
If you aren’t already there, click on the Organizer submenu link.
Click on the + New Guide button to be taken to the Guide Editor.
Write your guide content and hit Save—taking you back to the Organizer.
Typically you can then use the Organizer to distribute this guide across the different CP pages, but we won’t need to do that today.

So making our way through that list, let’s start with the Guide Editor in step 3. Create the new guide, give it a Title and Slug and leave the Content Source as Code Editor for now.

This guide will go on an entry edit page, so in the code editor field we want to get data from the entry that we are currently editing. Guide lets you do this by using an element Twig variable that works just like using entry in a front-end Twig template.

So to get the current element of the entry edit page, you can add something like this to your guide code, then hit Save:

{{ element.layout }}

If we jump back to our entry edit page, we should now see the new guide appear in the Guide select field. Select that, hit the Save button, and then reload the page.

We should see our Guide UI Element populated with the current value of the field we are testing—it will probably show the field’s default value at this point.

In my case, an error is thrown. Guide captures errors so you can debug the issue back in your guide without throwing an error on the entire page.

The reason for this error is that the API for the Little Layout field doesn't return anything from the default field handle. I can add any of these properties to see what the value of my field would be.

When I set my guide content to display this:

Selected column: {{ element.layout.selectedColumns[0] }}

... I can see the selected Little Layout column on my entry edit page.

Fin

At this point you can go to town and update your guide to see all of the things your custom field can do. This is a good way to test things like the empty state of your field and what your field looks like when run through Twig filters. It’s a good way to check that your field doesn’t break when you develop new features for it or run content migrations (although unit tests are great for this, too).

While my main focus is on the Little Layout field, I have written custom fields for clients in custom modules for their site, so this sort of thing has been handy for me in that situation, too. If you wind up wanting to test a field across several different entry types or with different entry content, you could consider breaking this out into its own Guide page, or use the one guide in both contexts.

Hopefully this gives you some ideas and you find this helpful. If you do use it in this way, I’d love to hear more about it.

Epilogue: Using a Twig Template Across Craft Testing Environments

At one point, I wound up having to re-create my local plugin testing environment and that meant setting all of this up again. While Guide comes with a utility that lets you export guides out and then import them into another site that uses Guide, I wound up making a GitHub gist to store the template code I use to test Little Layout in Guide UI Elements.

In this gist, I made it easy to test different Little Layout fields by setting the field handle at the top:

{# Set the hande of the little layout field you want to test. #}
{% set fieldHandle = 'layout' %}

{# Set a variable to point to the field when used on the current element #}
{% set littleLayoutField = element[fieldHandle] %}

{# Use the new variable to test out the field’s API #}
{% set totalColumns = littleLayoutField.totalColumns %}
{% set totalRows = littleLayoutField.totalRows %}
{# ... more testing code ... #}

Setting up Guide to use this file follows this process:

Create a new Twig template and save it in the same directory you selected on the Guide Settings page (this is usually set to templates/_guide/ by default).
Open up your field testing guide from the Organizer.
Change the Content Source to Page Template. This will display the Template field.
Select your new Twig file from the list in the Template field.

At this point, Guide will now render the contents of that file, allowing you to make changes to the file and then see them appear in your UI Element. This can be helpful in keeping both developing the field and testing the field in your code editor.

🍱📘

CSS for Me, in 2023

Will — Thu, 04 Jan 2024 18:00:00 -0500

Jamstacked

In late 2019 the agency I worked for went all in on headless and Jamstack sites. At that time we explored ways to pair Craft CMS with front-end frameworks, like Gridsome, Gatsby, and Nuxt. I used my personal website, wbrowar.com, as my guinea pig, giving me a playground to connect all the puzzle pieces involved in creating a headless and static Jamstack website, such as:

Organizing the repos and CI/CD for the back-end and front-end source code.
Rendering a static front-end that can dynamically pull from the GraphQL API when using Craft’s Live Preview.
Working out incremental builds to reduce time taken during static generation.

I also used my site to explore using Tailwind CSS as the primary method for working with CSS. This worked great when paired with the Vue-based components in the Nuxt-based front-end I decided to go with.

2023 CSS Challenge

2023 has been an epic year for CSS features and web components seem to be all over the front-end zeitgeist right now. I keep reading about all of the new tools us front-end folks have at our disposal and I decided to refactor my personal site to give me a place to try them out. This got me thinking about how I'll do this with the Tailwind-based setup.

First off, Tailwind is not an either use it or don’t use it technology. What I like about Tailwind is that you could decide to style every part of a fully custom site with it, or simply use Tailwind for a few utility classes here and there—mixed in with the rest of your CSS. Yes, there is the part that includes the build step, but with my experience—and with build tools like Vite around—I'm not adverse to post processing my CSS.

But with this refactor, I decided that I wanted to go back to the days before I started using Tailwind, and even earlier in the days before I used SCSS for most of my projects. I wanted to see what I could come up with, architecting a front-end using modern CSS practices. While I'm not shooting for complete Vanilla CSS, I wanted to get back to thinking through a system instead of working within a framework.

Markup Templating

In my day job I use TypeScript, Vue.js, and REST/GraphQL APIs all day, so while that makes maintaining a Jamstack site within my wheelhouse, I no longer felt like I was getting the same level of new learning out of my Jamstack setup as I did back in 2020.

The back end of the site is built in Craft CMS and one of the things I like about Craft is that it’s focused on content management and it doesn't care about what you do on the front end. You can use Craft’s built-in routing and Twig templating setup, you can use the built-in GraphQL setup to feed a headless front end, or you can use something like the Element API plugin to expose your content via JSON API to a headless front end. As the developer, it’s your choice on whether or not you use a front-end framework, and if so, which framework you prefer (with a few caveats around things like working with Live Preview).

Nuxt is really great for static sites, and for a time I also looked into using Astro, but in this new refactor I wanted to get back to defining the markup I need, instead of working within a component-based framework. Part of this goes back to wanting to write CSS for my content and another side of it came from looking at what I need my site to do and what kind of content I was creating. I decided to go back to a non-headless site, built in Twig, with the use of the Craft plugin, Blitz, to handle static caching and cache invalidation.

JavaScript Framework is _undefined_

With my HTML markup approach decided, next up I wanted to think about how I’ll work with JavaScript for the places where it’s needed. Looking at my current needs, I really only used JavaScript for highlighting code blocks and some minor functionality around image carousels (which is an enhancement on a CSS scroll-snap-based carousel). Programming these couple of bits in vanilla JS wouldn’t be too much work, but rendering the whole page in something like Vue.js is probably overkill.

I like the general setup of Vue components, and in my recent Craft CMS plugin work I got some experience working in Lit to build out web components. So I decided to use web components where it made sense, then go to vanilla JS for more global interactions. SPOILER: So far I haven’t had the need for any global JavaScript and I wound up using just 4 web components for all of the JS on this site:

bokeh-box: a component used to generate bokeh-style bubbles for the background of the site.
bokeh-controls: a small set of buttons used to define the color scheme of the site and the color of the bokeh bubbles in the bokeh-box component.

code-highlight: a wrapper around a block that enables highlighting for a specific language, using highlight.js.

element-carousel: takes all of the child elements within the component and turns them into a CSS flex and scroll-snap carousel. The main JavaScript portion is in observing the element currently scrolled in the middle of the page, then indicating that with some dots at the bottom.

      My 2023 CSS Solution
I took some time to think about how I’d structure my CSS. This post by Dave Rupert was helpful in introducing me to other approaches and I wound up with a mixture of CUBE principles, organization like Vue’s Single File Component (SFC), and some inspiration from Tailwind.
The sections below describe the problems and areas of my current CSS solution.
            Keeping the CSS With the Twig Pieces
One of the features of SCSS that I’ve utilized a lot in the past was that you could break out CSS into a file structure that mirrored the structure of your templates, instead of creating one long CSS file, broken up with comments and other wayfinding tricks. Vue’s SFCs took this even further in that you could write the CSS relevant for a component directly within the component itself. 
The value in either approach is in the time saving of being able to open a template file and then work right within its corresponding CSS that is limited to just the scope that the template file is responsible for.
Since I'm working in Twig files, I don't have an easy way to store my CSS in the Twig template files then extract them into a cacheable .css files that can be served on my front-end. I know there is probably a solution here around using PHP or using something like Node to extract the CSS from the files in the filesystem, but the benefit of writing CSS into a Twig file isn’t worth adding a complicated setup into the mix.
I looked for ways to organize CSS natively, but the closest I could get was to use CSS @import, however, the action of importing happens in the browser, so that would A. lead to some performance woes, and B. wouldn’t work because my Twig templates are not stored in a directory that is exposed to my server’s web root.
There are lots of ways to concatenate and minify CSS with build tools, so at this point I decided that I'd use Vite to handle those tasks.
Vite comes with PostCSS, along with the postcss-import package, that lets you inline files imported via CSS @import. Vite also handles minification during the build step, so between the stock setup I would be all set. The only other package I might consider adding is Autoprefixer, but before doing that, I found that Vite 5 comes with Lightning CSS (included as an experimental feature).
            With a solution for bundling CSS in place, I looked at my Twig setup and came up with a structure for my CSS files. My templates directory looked something like this:
      templates
├── components
│   ├── article-body.twig
│   └── article-thumb.twig
├── includes
│   └── admin-bar.twig
├── layouts
│   └── global-layout.twig
├── macros
│   └── icons.twig
└── pages
    ├── about.twig
    ├── article.twig
    └── home.twig      My Twig structure could be defined like this:
components: self-contained, reusable files included via the Twig include or embed tags.
includes: one-off includes that don’t belong in any other directory.
layouts: page layouts that are extended by templates in the pages directory.
macros: Twig macros that are imported and used throughout the project.
pages: templates for a specific page or entry section.
Each of these files could require their own CSS, so my idea was to add a CSS file alongside the Twig template as needed. Here's what I wound up with in this first pass:
      templates
├── components
│   ├── article-body.css
│   ├── article-body.twig
│   ├── article-thumb.css
│   └── article-thumb.twig
├── includes
│   └── admin-bar.twig
├── layouts
│   ├── global-layout.css
│   └── global-layout.twig
├── macros
│   └── icons.twig
└── pages
    ├── about.css
    ├── about.twig
    ├── article.css
    ├── article.twig
    ├── home.css
    └── home.twig      The name of each CSS file matches the name of its corresponding Twig file.
In the root directory where all of my other front-end source files are stored I have a CSS file that imports all of these files so that these styles are bundled alongside all of the other global styles for the site. With the exception of some web component styles, all of my styles for the site live in one of these files:
      front-end
└── src
    ├── css
    │   └── reset.css
    └── wbrowar.css
templates
├── components
│   ├── article-body.css
│   ├── article-body.twig
│   ├── article-thumb.css
│   └── article-thumb.twig
├── includes
│   └── admin-bar.twig
├── layouts
│   ├── global-layout.css
│   └── global-layout.twig
├── macros
│   └── icons.twig
└── pages
    ├── about.css
    ├── about.twig
    ├── article.css
    ├── article.twig
    ├── home.css
    └── home.twig      When bundled, all of these files are imported and minimized, then served on the front end as wbrowar.css (along with a unique content hash for cache busting upon changes).
      CUBEish CSS, Nesting, and the Freedom of Cascade Layers
Early into my career in writing CSS I had latched on to the pattern of OOCSS. As I started working with teams of developers we gravitated towards BEM and eventually stayed there for a while. Our rule for writing CSS was if you were going to style something you’d use a class, and with BEM you’d be descriptive and you’d name everything in a way that was unique and described within the context the element is used.
So we'd wind up with markup that looked a lot like this:
      Home
About
Contact Us      In this case .main_menu was sort of a class that gave you context for which 
 element this was (amongst maybe a .footer_menu or a .secondary_menu). Then everything else gets prefixed with that context along with what the element is (in regards to how it will be used or styled), then any modifiers that describe something unique about the element.
In our minds, this was descriptive and it solved problems like clashing styles and being able to use ⌘+F to hunt for this style amongst all of our stylesheets in our _scss directory. Over time this also led to some other issues that made us less efficient:
Our BEM setup was based around very unique class names, but it also meant that we either had a lot of duplicate CSS code to cover common patterns in unique contexts, or it meant a rat king of selectors and modifiers everywhere the minute you moved something or tried to re-use CSS.
Naming took a while to get right. Some things are easy when there are only one of them on the page, but when you had common things, like headers, you have to do more to define them into sections like, .content_header, .sidebar_header, .news_card_header. Sometimes designers would make a decision after seeing something in the browser, so maybe the news cards got moved into the sidebar... Now you are either renaming a bunch of classes, or you have some no-longer-obvious element names.
As much as some folks may find a bunch of Tailwind classes hard to skim and quickly parse, reading BEM code—sometimes compiled via includes and partials—can also look like a wall of underscores and dashes amongst a lot of repetitive names. Indenting source code helps, but some extra mental processing time is required.
Gzipping CSS files is great when working with BEM, but when you don't have the ability to set that up where your static assets are served, you wind up with extra file bloat in both your CSS and in your template files.
Instead of following my old BEM rules, I’ve combined Cascade Layers, nesting, child selectors, and parts of CUBE CSS to come up with my new CSS setup.
To start, I’ve created a set of layers and I've imported all of my CSS files into their designated layers:
      @layer reset, admin-bar, globals, components, theme, layout, page;

/*
 * reset: normalize browser defaults, remove margins, set box-sizing: border-box on everything 
 * admin-bar: layers the styles that come with Admin Bar here so they can be overwritten later
 * globals: set project-specific HTML defaults and global classes
 * components: include styles specific to re-usable Twig components
 * theme: define custom properties for colors, fonts, animation, and spacing
 * layout: styles specific to the global page layout
 * page: page-specific styles
 */
 
@import './css/reset.css' layer(reset);

@import '../../templates/components/article-body.css' layer(components);
@import '../../templates/components/article-thumb.css' layer(components);

@import '../../templates/layouts/global-layout.css' layer(layout);

@import '../../templates/pages/about.css' layer(page);
@import '../../templates/pages/article.css' layer(page);
@import '../../templates/pages/home.css' layer(page);      Adding these layers make it so I don’t need to worry as much about clashing styles or using hyper-specific class naming. This lets me go back to using more global classes, like a .button class, knowing that I can overwrite it on the components or page layers later.
There is still the problem of selecting elements within the same layer, and that's where CUBE and child selectors come in. The things I took most from the CUBE  were the composition (C) and the block (B) principles, along with the visual benefit of grouping with brackets (as seen in the CUBE documentation).
Take a look at the markup for my About page for example:
      

      {# Intro text ... #}
      
      
        {# Links to external URLs ... #}
            The first thing you might notice are the bracket groupings here. When you look at the source code it makes it really easy to see where the different sections of code are. I set up sort of a framework for thinking about how these blocks work together with the elements on the page. Here’s a general outline for how I’ve organized this:
page is a root level starting point and it is the singular name of the folder that this Twig file lives in.
Where page describes the directory this file is in, about describes the file name. All of the styles in the about.css file are nested within .page.about.
Any child bracket, like [ content ], gets selected using a child selector, .page.about > .content. Then later, .page.about > .content > .grid. This is done via native CSS nesting.
.content-container and .prose are global classes that are defined on the globals cascade layer. Because the CSS in about.css is on the page layer, it’s a lot easier to overwrite properties defined on the globals layer.
The grid element contains a few  elements, so instead of naming those elements with a class like we would have in BEM, this setup makes me confident that I can set properties using this selector, .page.about > .content > .grid > a.
I haven’t done anything too complicated yet, but my goal is to limit the amount of child brackets to avoid nesting too much. If needed, I could break things out in to components, but so far that hasn’t been necessary.
Here’s what the full CSS for the About page looks like:
      .page.about {
  container-name: page-article;
  container-type: inline-size;

  & > .content {
    margin: 0 auto;
    padding-top: 100px;
    padding-bottom: 100px;
    max-width: 1024px;

    & h1 {
      font-family: var(--font-futura);
      font-size: 2rem;
      font-weight: var(--font-normal);
      color: var(--color-orange);
    }

    & > .grid {
      --svg-width: 1.5em;
      display: grid;
      grid-template-columns: var(--grid-template-columns, 1fr);
      align-items: center;
      gap: var(--xl);
      margin-top: 50px;
      font-size: 2em;

      & a {
        display: grid;
        grid-template-columns: max-content 1fr;
        align-items: center;
        gap: var(--md);
        text-decoration: none;
        color: var(--color-blue);
        transition: color var(--duration) ease-out;

        &:hover {
          color: var(--color-orange);
        }
      }

      @container page-article (width > 600px) {
        --grid-template-columns: 1fr 1fr;
      }
      @container page-article (width > 900px) {
        --grid-template-columns: 1fr 1fr 1fr 1fr;
      }
    }
  }
}      Global Styles and Custom Properties
My main CSS file, wbrowar.css, imports all of the CSS from my templates directories, and it also includes the CSS for the globals and themes layers. My globals layer contains commonly used classes, like an .article-grid class that is used to display article thumbnails across several pages. It also defines basic element styles, like the styles for 
 elements.
Because I use Markdown for a lot of the content in my site, the .prose class handles styling some commonly used HTML elements rendered by Markdown:
      .prose {
  & > * + *:not(hr) {
    margin-block-start: var(--md-rem);
  }

  & :is(blockquote, dd, dl, h1, h2, h3, h4, h5, h6, hr, p, li, pre) {
    max-width: var(--prose-max-width, 70ch);
    font-size: var(--prose-font-size, 1.25rem);
    line-height: var(--prose-line-height, 2);
    text-wrap: pretty;
    color: var(--prose-color, var(--color-black));

    & a {
      color: var(--color-orange);

      &:hover {
        color: var(--color-blue);
      }
    }
    & code {
      padding: 0.4em;
      background-color: color-mix(in srgb, var(--color-blue), transparent 50%);
      border-radius: 0.3em;
      font-family: monospace;
      font-size: 0.9em;
      user-select: all;
      color: var(--prose-code-color, var(--color-blue-800));

      @media (prefers-color-scheme: dark) {
        & {
          color: var(--prose-code-color, var(--color-blue-300));
        }
      }
    }
  }
  & :is(ol, ul) {
    & li {
      & + li {
      	margin-block-start: var(--sm-rem);
      }
      
      &::marker {
        color: var(--color-red);
      }
    }
  }

  @media (prefers-color-scheme: dark) {
    & {
      --prose-color: var(--color-gray-200);
    }
  }
}      The great things about the layer setup is that if I wanted to overwrite a  on a specific page, I won’t need to specify .prose in the selector, but instead I would follow the rules for the file I’m working in. I did include a few CSS Custom Properties here just in case I want to overwrite something and then use that variable to compute something else in all .prose elements.
            The name "prose" might seem familiar to someone who uses Tailwind CSS, and specifically the Tailwind Typography plugin. I’m sure other folks have used the term "prose" before Tailwind came along, but that’s where I first heard of the concept and the name for it.
I got a lot of inspiration for my theme layer from Tailwind CSS. Although I wound up not adding any utility classes (yet), I took a lot of naming from Tailwind.
      @layer theme {
  :root {
    /* Colors */
    --color-black: oklch(27.68% 0 0);

    --color-gray: oklch(57.51% 0 0);
    --color-gray-100: oklch(91.58% 0 0);
    --color-gray-200: oklch(82.3% 0 0);
    --color-gray-300: oklch(73.49% 0 0);
    --color-gray-400: oklch(66.06% 0 0);
    --color-gray-500: oklch(57.51% 0 0);
    --color-gray-600: oklch(48.37% 0 0);
    --color-gray-700: oklch(30.9% 0 0);
    --color-gray-800: oklch(27.68% 0 0);
    --color-gray-900: oklch(16% 0 0);

    /* OTHER COLORS ... */
  }
}      For starters I kept the concept of color shades. Part of this was a carry-over from the old Tailwind setup, but I also really appreciate the idea of limiting your color palette to a fixed number of shades. While I understand we could use color-mix() to automate shades now, I specifically like going through and defining each shade for myself (although automating it might be a good place to start).
      @layer theme {
  :root {
    /* Font families */
    --font-apple: system-ui, sans-serif;
    --font-avinir: 'Avinir Next', 'Avinir', Helvetica, Arial, sans-serif;
    --font-futura: Futura, 'Trebuchet MS', Arial, sans-serif;

    /* Font weight */
    --font-thin: 100;
    --font-extralight: 200;
    --font-light: 300;
    --font-normal: 400;
    --font-medium: 500;
    --font-semibold: 600;
    --font-bold: 700;
    --font-extrabold: 800;
    --font-black: 900;
  }
}      The fonts setup also comes from Tailwind, at least in the weights naming. I'm not opposed to using the numbers directly in my CSS properties, but the naming is just a tad easier for me to look at and immediately put an image in my head as to what name equates to which weight.
      @layer theme {
  :root {
    /* Border radius */
    --rounded-sm: .25rem;
  }
}      As time goes on I’ll add more things, like --rounded-sm, to define specific sizes of things I want to use throughout multiple contexts. Using -sm here is a bit of a risk in that it’s possible I won’t want to be limited to sm, md, and lg naming. When that happens I’ll judiciously employ find and replace where I have to 🤓
      @layer theme {
  :root {
    /* Animations */
    --duration: 0.3s;
  }

  @media (prefers-reduced-motion) {
    :root {
      --duration: 0.01ms;
    }
  }
}      The --duration property is a little different in that I'm using that as a base for animations everywhere. I shouldn't ever set a new value for it, but instead I should use something like transition-duration: calc(var(--duration) * 1.5). This way animations can be cut down to almost 0 when prefers-reduced-motion is turned on. I thought about doing something like this for opacity and prefers-reduced-transparency, but opacity isn't always set the same way and it changes more often that I handle prefers-reduced-transparency in the situation where it needs overriding.
      @layer theme {
  :root {
    /* Sizes for layout spacing */
    --xl: 32px;
    --lg: 24px;
    --md: 16px;
    --sm: 8px;
    --xs: 4px;

    --xl-em: 2em;
    --lg-em: 1.5em;
    --md-em: 1em;
    --sm-em: 025em;
    --xs-em: 0.25em;

    --xl-rem: 2rem;
    --lg-rem: 1.5rem;
    --md-rem: 1rem;
    --sm-rem: 0.5rem;
    --xs-rem: 0.25rem;
  }
}      In my opinion, one of the best uses of utility classes is to work with the 4px-based spacing system that Tailwind and other utility design systems tend to use. I didn’t bring over utility classes because so far I haven’t needed to, but I wanted to maintain some consistency in spacing for things like container padding and grid/flex gaps.
I picked up the idea of using really simple size naming from looking at the CSS found in the Craft CMS Control Panel (CP). While there are places where I use one-off values, these sizes are used for most of the padding and spacing across the site.
I added -em and -rem variants to each size so that I could get the same general spacing size at 100%, but to let those spaces change as the base font size changes.
      Fin
I’m still living with this new CSS setup, and I’m not sure this is scalable or the right approach for other types of projects, but so far I’ve achieved my goals of being able to write less CSS, to find CSS quickly when making changes, and to write CSS for the needs of my content.
Along the way I’ve made notes about other side effects that I feel like have occurred for me since making this transition:
This is the first time in maybe a decade or so where I’ve used things other than classes for CSS selectors (when I am creating the markup). I really like not naming everything, but I also wonder how much more work this will introduce during times where I move things around.
My biggest concerns are updates and maintainability—two of the main reasons why I started using Tailwind in the past. We'll see how nesting and using cascade layers works out when it comes time to update or remove sections. Because I am the only developer for my site, I’m not too worried, but I wonder how this sort of system holds up in a team setting.
Nesting with BEM led to a lot of extra CSS, but native CSS nesting (even when using & selectors) doesn’t add nearly as much extra file size, and a lot of the same benefits that I like are there.
I went all in on size container queries and it has been great. I’m not opposed to using viewport media queries, but I just didn’t wind up needing any. Things like clamp() and container queries made this possible.
I have a dark mode theme, but instead of defaulting to inverting all of the color shades, I went through and manually added prefers-color-scheme: dark queries as needed.
color-mix() is a CSS dream. It works so well and I think it will help in so many situations where you don’t have full control over the colors you’re working with (such as colors brought in from third-party libraries).
I wrapped all of the styles for Admin Bar in a layer so it’s easier to work with a custom cascade layer setup. I really hope UI libraries and other third-party packages start to do this. Imagine a company that provides a third-party form wrapping all of their CSS in a layer instead of using !important everywhere. In fact, @scope, cascade layers, and container queries makes me glad for all of the developers for marketing sites who currently cringe when getting a message saying "just drop this JavaScript tag onto the page".



Admin Bar for Everyone
Will — Sat, 25 Nov 2023 00:30:00 -0500
      
      Admin Bar was my first Craft CMS plugin—dating all the way back to 2015! I used Admin Bar to learn my way through plugin development on Craft 2. This was before there was a Plugin Store and before Composer and Packagist came into the mix.
The reason why I created Admin Bar was because the agency I worked for had just transitioned off from making all of our projects with Drupal 7 and we had started using Craft CMS 2 for our default CMS of choice. Craft provided a much better authoring experience on the CP side of things (for the way we approached websites), but it was missing the toolbar that we were used to in Drupal and on Wordpress sites. As a developer who also made content updates, those toolbars were super helpful, and it was always fun to show a client that you can find a page on your site that needs updating and then use the Edit link in the toolbar to jump right to the edit page.
So on my free time I put together Admin Bar and "released" it via updates to its GitHub repo.
      
      
      
      I wound up looking for more uses to expand Admin Bar so I added the Edit Link feature. This was more like an edit button for those thumbnails and summaries of news stories you might put on a news homepage.
Implementing Edit Links was trickier than the regular Admin Bar. For one, there would be multiple links on the page, which meant instead of loading a bunch of CSS and JavaScript multiple times, I had to find a way to load them once, find all of the edit links on the page, then get them to render. I eventually got this all working, but sometimes there were issues.
Around this time I had started using Vue.js on a lot of my projects. There seemed to be a wave of folks in the Craft world using Vue or similar frameworks to add interactivity to their pages, on top of their Twig-based sites. For the most part things still worked, but sometimes race conditions between my Edit Links code and Vue’s rendering would cause some issues.
      
      
      Along with Edit Links I also experimented with a concept, called Admin Bar Widgets. The idea here was that a plugin, like Guide, could inject some HTML into Admin Bar using a custom event on the PHP side of things. The HTML here could give you some info based on the current page you’re on.
I also tried setting up a widget that would find all of your Edit Links on the page and made it so you could click on the link to jump down to that section on the page.
I hadn’t heard of anybody really using the Admin Bar Widgets feature, and even in my own use I found that I’d run into some CSS issues due to the stylesheet on the page clashing with my widget CSS.
      THE Problem
So some of the features in Admin Bar had some issues, but they were all things that could be addressed with some CSS or a little extra JS work. The biggest issue that Admin Bar ran into was more about the shift into Jamstack, Headless, and static-cached sites.
On a Twig-based project, Admin Bar would use the session information in your browser to figure out if you are logged in and what permissions your account had. It would also rely on you passing in an entry argument, or it would try to use Craft’s built-in route matching to figure out what page you were on. Then it used all of your config options and plugin settings to customize the look and the links on the Admin Bar on the page.
At some point Admin Bar needs to get information from your CMS database and PHP files to render itself onto the page. In the world of headless sites, where your front-end may even be hosted on a completely different domain, this surfaced a whole bunch of problems.
I spent a lot of time thinking about this. Could you use GraphQL to render out the Admin Bar for the page, then use some JavaScript to pull that in and display it on the page? Could you hit a plugin controller that returns a blob of HTML, or at least the info you need to pass into Admin Bar on the front-end? How do I create something in the Admin Bar plugin that can do all of this securely? Maybe I could put together some lambda functions and service workers to help with this stuff?
Spoiler for the rest of this article: I don’t have answers to these questions, but I have come up with a way to get Admin Bar onto more projects.
      Admin Bar 4.0
My conclusion came down to deciding where the line would be for Admin Bar going forward. It’s not feasible for me to try to solve auth and rendering on static sites across all of the different server setups and front-end frameworks out there, but I could provide a way where if you can get through those barriers in your specific site setup, I can provide the front-end component that is a consistent experience across projects.
After spending some time learning some new front-end tricks I converted Admin Bar’s front-end to a standalone NPM package that can be used on Craft and non-Craft websites. I set up Admin Bar Component as a web component, built on Lit.
      
      The web component can be installed, using npm install admin-bar-component --save, and you can bundle it in with your existing JavaScript, or you can use a       
In my preview version of [articleSlug].vue I am importing the original component file, then as my

Will Browar

Making WordPress Users Feel at Home with Craft CMS

Navigating the CMS

Posts, Pages, and Entries

Menus

Publishing Entries

Editing Entries

Managing User Uploads (AKA Assets)

SEO

Theming, Templates, and the Front End

Forms

Ecommerce

Technical Requirements

Hosting

Plugins, Modules, and PHP

Fin

Guide 5: Don’t Write That Craft CMS Module!

Getting Plugged In

There’s a Plugin for That

Okay, Sometimes You Still Need a Plugin or Module

Using Guide to Replace Other Plugins

Guide 5 BTS: Slideouts, Vue v. Web Components, and Plugin Design

Slidouts

Relying Too Much on a Vue 3 Feature

Vue Teleport-Driven Development

Making Messes in My Code Base

Dropping Frameworks to Get (a Little Bit) Closer to HTML and Twig

Introducing Guide 5.0 (Beta)

It Was a Good Idea at the Time

Using the Platform

Customer Research-Driven Development

Guide 5 is Now Live

Guide 5

Slideouts 🎉

Markdown Rendering

New Organization

Guide Components

CSS and JavaScript Customization

Settling All Family Business

Guide 5 is Alive

Testing Craft CMS Fields with Guide UI Elements

Setting Thing Up

Field Settings

Entry Types

Creating Your Field Test Guide

Fin

Epilogue: Using a Twig Template Across Craft Testing Environments

CSS for Me, in 2023

Jamstacked

2023 CSS Challenge

Markup Templating

JavaScript Framework is _undefined_

My 2023 CSS Solution

Keeping the CSS With the Twig Pieces

CUBEish CSS, Nesting, and the Freedom of Cascade Layers

Admin Bar for Everyone

THE Problem

Admin Bar 4.0

Modern CSS for Old Markup

Fin

Craft CMS Live Preview with Nuxt.js

Secret Secrets

Setting up Nuxt.js

Talking to Craft

Pointing Craft to the Preview Site

Turning on Preview Mode in Nuxt.js

Build & Test

Keeping Live Preview Scroll Position

Fin

Guide 2

Features That Got the AX

Guide Editor

Guide Components

Guide Organizer

Guide Templates

Other Improvements

Improved Guide Widgets

Multiple Guides on Edit Pages

Better Rebranding Options

Iframe Docs