Will Browar

Hello, Admin Bar PRO

Will — Fri, 20 Dec 2024 18:39:00 -0500

Last year I rewrote part of the Craft CMS plugin, Admin Bar, to solve some major CSS clashing issues and to make it easier to use the toolbar portion of Admin Bar across headless front-end frameworks. I published this blog post that outlined the problem and my solution and in writing that post I did a short retrospective on where the plugin began. I mentioned a feature, called Admin Bar Widgets, that never took off due to it relying on getting other plugin developers to add hooks and templates to their plugins.

I’ve always liked the idea around the feature, but that implementation wasn’t right. On top of asking developers to add and maintain something in their plugins, there remained the issue of CSS from your front-end templates overriding the widget CSS and making a mess of them.

As we’re coming up on 10 years of Admin Bar being available as a free Craft CMS plugin, I’ve decided to introduce a PRO edition that brings back Admin Bar Widgets in—what I think—is the right way to do it. Read on to find out more.

Admin Bar Widgets 2.0

Admin Bar Widgets integrate Craft CMS and other Craft CMS plugins to display links and statuses related to the current page you are on in your Craft CMS site. For example, there’s an SEOmatic widget that shows you the meta information for the current page, and another widget that tells you how many times the page has been visited—as collected by the View Count plugin.

Just like everything else Admin Bar, widgets are all about flexibility. Widgets are all opt-in by default, so you can head over to the Admin Bar Plugin Settings page on an environment that lets you make admin changes. From there you’ll see a new section, called Admin Bar Widgets:

If you haven’t picked up the PRO edition yet, this section will be disabled but you’ll still be able to see what widgets will be available to your site. If a widget is an integration for a Craft CMS plugin, it would show up in the list of available widgets when the plugin is both installed and enabled for your project.

If Admin Bar supports a plugin that you don’t have installed on your site, it will appear in a list of available widgets in the right-hand column.

Enabling a widget and then hitting the Save button will update the Admin Bar in the Preview section at the top of the page. The Preview area will try to find an entry on your site that has a URI and it will use that entry to show you what the Admin Bar would look like on that entry’s page. A random entry is loaded every time the Settings page loads to show a variety of Admin Bar scenarios.

Now your enabled widgets will appear and you can get a feel for how they will work on your site. Here is a rundown of all of the widgets that will be available at the launch of Admin Bar PRO:

New Entry

The New Entry widget is a quick way to create a new entry. The logged-in content author will see a list of entry sections that they have permission to create, and by clicking on one of the links they will be brought back into the CMS and onto the New Entry edit page for that entry type.

Guide

The Guide widget displays a list of guides that have been assigned to that entry in the Guide Organizer. Clicking on one of these links will bring you to the page for that guide in the Control Panel.

Below the list of guides, there is a link to the CMS Guide page in the Guide Control Panel section.

SEOmatic

The SEOmatic widget shows you a preview of SEO meta data for the current page. This shows these SEO values for the entry:

The schema.org Main Entity
og:image
Page Title
Page Description
Canonical URL

Sites

The Sites widget shows you the current Craft CMS Site. If the page you are on is propagated to other Sites, a menu will appear with links to that page on all related sites.

This can be an easy way to jump between your project’s Sites.

Blitz

The Blitz widget shows the Blitz cache status for the current page you are on. If the page is cached, clicking on the status will show the date and time the page was cached.

View Count

The View Count widget displays the amount of times the current page has been viewed—as collected by View Count.

All of these widgets have a default view that’s meant to keep them compact on the Admin Bar toolbar. There's also another setting on the Admin Bar Settings page that enables more verbose labels that show the title of the widget.

Editions

The core of Admin Bar will continue to live on in the free LITE edition. The PRO edition will be focused mostly on the Admin Bar Widgets feature and integrations with third-party plugins.

The PRO edition will be introduced at $19 and you can upgrade to it on the Craft CMS Plugin Store. Moving back down to the LITE edition can be done at any time.

Technical Details

What is different about Admin Bar where it makes sense to re-introduce the Admin Bar Widgets feature?

Aside from managing integrations from within Admin Bar now, the biggest change is how Admin Bar Widgets utilize the Shadow DOM in Admin Bar Component to isolate them from the CSS on your front-end templates. While the widgets are themeable via Admin Bar’s CSS Custom Properties, you should no longer see your CSS making a big impact on the rest of the widgets’ content.

When Updates Happen

Speaking of integrations, Admin Bar PRO is based around working well with third-party plugins, so it’s important that when a plugin gets updated it will not break Admin Bar or any other portion of your site’s front-end. Admin Bar Widgets will check plugins for their installed version and use that info to decide which version of its widget should be shown.

If a plugin is updated to a major SEMVER version (for example, from 1.0.0 to 2.0.0), the widget that requires it is then disabled by default. Once Admin Bar has been tested with the new version then an update to Admin Bar will re-enable the updated plugin’s widget.

Anchoring Widgets Along the Bleeding Edge

Admin Bar Widgets use a feature that was recently added to the Admin Bar Component, utilizing HTML popovers and CSS anchor positioning. As of this writing, popover support is widely available across evergreen browsers, however, anchor positioning support is limited to Chrome and Chromium-based browsers.

So in Google Chrome, when you use the SEOmatic widget you should see something like this:

In browser that don’t yet support anchor positioning, the popover will be displayed in the center of the screen and a mask will blur out the page behind it. So in Safari or Firefox, you may see the SEOmatic widget look like this:

Once anchor positioning support is brought to these browsers the affected widgets will automatically change their behavior to match the first screenshot.

There’s More to Come

More widgets are planned for future releases, and I’d love to hear from other plugin developers who would like to integrate Admin Bar with their plugin. If you have an idea for a new widget, please start a new post on the Admin Bar GitHub Discussions page or contact me.

Thanks to everyone who has enjoyed the last 10 years of Admin Bar and I hope the next 10 have just gotten much more useful for you and your clients.

🥃

Craftentries Podcast: Episode 19

Will — Fri, 29 Nov 2024 20:54:00 -0500

You can probably tell from listening that I was excited to join Thomas on the latest episode of the Craftentries Podcast. It was a lot of fun talking with him and I really appreciate him carrying the torch from the Craft CMS community podcasts of the past.

We talked about my experience as a web developer and then it turned into an impromptu review of the 2024 Dot One event in Toronto.

Dot One Toronto 2024 Photos

Will — Wed, 30 Oct 2024 07:30:00 -0400

Thank You for Using Guide

Will — Tue, 29 Oct 2024 17:00:00 -0400

I’ve been working on this plugin for Craft CMS since 2017, called Guide. The idea behind the plugin is to make it easy to add pages and other custom things to the CMS Control Panel without needing to use PHP or write your own plugin. The whole thing started as a way to replace printed CMS user manuals that we used to hand out to clients during training meetings, so the logo for the plugin was meant to look like a little notebook.

Over the years I’ve looked for ways to make the plugin unique and to maybe add a little joy for its users. When I released version 3 in 2021 I included a little easter egg for the developer installing the plugin:

When you used the CMS to install the plugin you were redirected to a page where I had this 3D-animated notebook slide in from the left side. Once the camera slides over the book for the first time, the cover would pop open and reveal a page inside with a thank you message on the inside sheet. From there an animation plays on an endless loop until you click a button to take you to the settings page.

In order to make this animation happen I used Blender to create the 3D model of the logo and then exported that out into a format that lets me display it into the browser. Since I already had this 3D model created, I rendered it out and used it in things like the header on the plugin store page:

As I was recently updating the Guide plugin to version 5 I decided to keep this animation and the 3D logo around in the plugin and I moved it out of this easter egg screen and into a place where more folks might see it. While I was making changes to update the animation I got this idea...

The folks behind Craft CMS put on single-day and multi-day conferences and I was planning on attending the one closest to me, Dot One Toronto 2024. I thought it would be cool to have something to give to the folks who have helped me promote my plugin, or to just hand out to anybody who wants some extra SWAG.

What I wound up creating took some of the things I’ve learned in 3D printing and woodworking and I think it came out pretty cool.

Design

My original idea for this project was to buy a handful of Field Notes, print a 3D cover that was maybe 1mm thick and glue it onto the cover of the Field Notes top cover. I sort of played around with this idea with a 3D print I whipped up and realized that it would feel uneven having a plastic cover on just the front. Another issue is printing such a thin sheet isn't a good idea since it can warp or break easily.

I looked at my 3D model and decided to thicken up the front cover and use my printer’s multi-color print feature to make the white part of the logo stand out a little more. I wanted to essentially create a hard cover notebook out of the Field Notes by printing a back and front and when you open it up it would look just like it does in the animation.

I placed an order for a bunch of Field Notes to get the size right and to start testing this out.

For reference, I landed on 89mm x 140mm x 3.5mm

I got the dimensions of a Field Notes book and used that to create a 3D model of that size to use as a reference.

It took me a few tries to get the thickness right as when you look at a Field Notes they are not exactly a rectangle. The depth is higher at the side near the staples and while you can squash that down, I didn't want to mess with the notebook itself to make this piece work. So after some trial and error I got the size from the thickest portion and moved on from there.

With these 3D-printed notebook stand ins I started to think about how to model up the cover and how it might work if I glued it onto the Field Notes books. What I realized is that this original design wouldn't work. If you look at the binding of a hard-cover book you’ll see that it’s a little more complicated than just two sheets of cardboard stuck together—that there are places where the cover needs to contract to allow the book to open up.

I tried thinking about ways to make this work with 3D-printed parts and couldn’t come up with a good way that didn’t leave a weird gap or that made it feel natural to open and close the book. Looking online, some folks have created 3D models with hinges and ways to do something similar to how a hardcover book works, but they require books that are thicker than Field Notes.

I decided to scrap the idea of 3D printing the hard covers and I picked up some cardboard to think of some other ideas.

One of the ideas I had was to wrap the Field Notes notebook in U-shaped 3D print where it would sort of act as a protective case around the notebook. I used some tape to hold down the top and bottom and tested this out with one of the 3D-printed stand ins.

I cut a notch out of the back side of the cardboard to make it so you could push the notebook out when it’s inside. With that I had a good idea where to take it from here.

3D Modeling

One of the things I have learned in 3D printing is that there are some tricks you can use to make things look cooler. I didn’t want to sand or paint these pieces and I thought it was important that the letters in the logo were crisp and readable and that they fit together nicely. The best way I know to achieve this is to design your model to lay down onto the bottom layer of the 3D print—right on the printing plate.

I modeled out the first version in several parts based on how I wanted it to look and how I planned on assembling it. Thinking about things like printing supports and how to glue it together helped me decide on portions of the design.

I used the Field Notes stand in piece as a guide and built around that, giving me the right width and the thickness for things like these little sides that were meant to look like paper.

For the white letters that spelled out the word, GUIDE, I used the shape of the letters and the picture icon to cut out the shape on the top cover and I added a small kerf to make sure I had some room to slide them together once they were printed.

Build plates for each part of the print. Top row, left to right: Field Notes stand in, GUIDE letters, "paper" sides. Bottom row: top and bottom covers, parts inlayed into GUIDE letters.

This screenshot is from below since the GUIDE letters are facing down so they can be printed directly on the build plate.

One of the earlier versions of the top and bottom pieces.

I wanted to test out the fit of the cover first, so that's where I started printing.

The fit of the letters and the top cover worked out great so I printed the rest of the pieces to see how they would fit together.

As I did a dry run I noticed that the depth wasn’t a great fit. I made a few iterations on the top portion to make it big enough so you could easily slide a Field Notes notebook in without too much resistance, but tight enough to hold a Field Notes in place without it falling out.

The top cover had the top face and then it also included the spine portion in sort of an L shape. One of the ways I could have put this together was to make the width of the bottom cover thinner to fit the thickness of the spine, then glue that bottom piece to the bottom of the spine. My concern there was that it might be hard to do this accurately and it might make a gluey mess.

One of the tricks I have learned in woodworking is that for a really strong hold, and to give you more control over how pieces fit together, you can use a little cutout, called a rabbet, that sort of acts like a groove to rest one piece into another. So instead of making the back cover less wide, I made the spine piece less tall by about 1mm, then I added a groove onto the back cover and offset it to the same height as the original spine piece. In a dry run this worked out great.

With the functionality working nicely, I spent the next few days dialing in the aesthetics. I tweaked the height of the GUIDE text to make it feel like the right height (mostly pushing it out more until it seemed tall enough).

I showed this to my wife to get her feedback. She had a great idea to add a little gap between the inner wall of the spine and the edge of the Field Notes book, giving you a little more room to slip your fingers behind the back edge of the notebook to help slide it out. I tweaked the height and width of everything slightly and added a few millimeters to the spine area on the bottom cover—everywhere except where the notch is. This change not only helped with the gap for your finger, but it also gave me more surface area to use when gluing the top and bottom parts together.

At this stage, I had a working prototype and I was ready to begin production.

Material Change

I ordered the Field Notes notebooks first because they were a prerequisite for the design, and while waiting for them to arrive I also ordered 3D-printing filament. I already had some white PLA in stock (Bambu PLA Basic), and while I liked the Cyan color that I used for the prototype (also Bambu PLA Basic), I wanted to see if I could find a filament that matched the Guide logo color. Because my printer is a Bambu P1P I wanted to find one of their filaments, however, they didn’t have anything closer to the color, in a material I was comfortable using for the project.

I like using PLA for this kind of thing because it's easy to print and I have the most experience with it over other materials. I found a filament on Prusa’s store, in a color called Chalky Blue, however, it was a PETG material. I know that PETG can be a little more finicky and dialing in the temperature was important, however, PETG can be stronger than PLA and I know a lot of folks who print only using PETG when they can. So I placed an order and waited for it to arrive.

I had to re-spool the Prusa PETG to fit within my Bambu AMS. I used a drill, a bar from a dumbbell, and lots of patience to move the chalky blue filament to an AMS compatible spool.

I added the chalky blue PETG to my printer as a custom filament and set it up according to the heat ratings as written on the filament box. My first print with it was close but had some issues filling in some of the gaps on smaller areas. This affected the G and the U the most.

After spending some time dialing in the right temperatures and slowing down the speed of my printer, I finally got to a point where I thought it was good enough to start printing the final pieces.

Production

I made an inventory list of all of the pieces that need to be printed, so I can keep track of how many I needed. In a project this small it wasn’t too hard to keep track, but I did it out of habit.

I started off with the parts printed in white first. The little "paper" side walls were easy enough to print in one sheet. The GUIDE letters were also pretty straightforward to print, and I did those in only a couple of batches.

Even the supports for the GUIDE letters looked cool.

As everybody with a 3D printer knows, failed prints happen. At one point the printer head popped off from a print that wasn’t sticking correctly to the bed.

Next up were the parts inlayed into the GUIDE layer. This included the inside of the picture icon and the inner area on the letter D.

I cleaned up these prints and got them ready to glue into the GUIDE letter pieces. I followed this order because I knew that I had to have the GUIDE letters completed before I could glue them into the top cover. Then the paper sides and the bottom cover would be glued on last.

Over the course of the next few days I had printed out the rest of the top and bottom pieces. The bottom pieces were no problem, but some of the top pieces still had issues with small gaps. Everything was flat, but sometimes there were holes missing and I wouldn’t find out there was an issue until I pulled the piece off of the plate (this is sort of the downside to printing face down).

My goal was to hand out 10 of these, so I made a couple extras—just in case. I eventually got 12 tops that I liked and moved onto the next step.

I used some things around my workshop to get the GUIDE letters to stay in place when gluing them into the top cover. I wanted to make sure these were fully cured before I started gluing the top and bottom pieces together.

These metal blocks are called 1-2-3 blocks and the are just heavy enough to provide some weight without bending the top pieces.

I used one of these tool cases to distribute out a 15lb weight and I stacked the glued pieces into two layers.

Once the tops were all set, I began gluing the rest of it together in batches. I used woodworking clamps to hold things together in two spots where I thought they needed them the most. These quick clamps are perfect in that they aren’t too strong and the pads that touch the 3D printed parts didn't leave any marks.

I gave everything a good 24 hours to cure and then started inspecting them, making fixes, and cleaning them up where I felt like it was needed.

Fin

This project was sort of a good way to use all of the things I’ve learned about 3D printing so far. I didn’t feel like I had run into any major, unforeseen issues at any point. Most of the refinements were based on having the final thing in hand and taking some time to get a feel for what works and doesn’t work.

The only thing I would try to do better next time is work on figuring out a cleaner way to glue the 3D parts together. I used a two-part epoxy and I was sometimes more worried about the epoxy hardening before I used it that sometimes I put on too much and had to come back and clean it up later. Just like a woodworking project, each one has one or two minor things that make it not perfect, but I'm okay with that.

I’ve been doing a lot of promoting for the Guide plugin in Discord, Mastodon, and on my blog and doing that sort of thing doesn’t feel natural for me to do, so putting my energy into a little thank you piece felt like a good change of pace.

📘

Slow-Toasted Pumpkin Seeds

Will — Sat, 12 Oct 2024 21:40:00 -0400

As a kid we always cut into our pumpkins, separated the gunk, washed the seeds, salted them and threw them in the toaster oven on high for 15 minutes and that’s how we toasted pumpkins seeds. Sometimes they would burn, sometimes they would cook the outer shell and then the inner seed was still raw. We still loved them.

Around the time my wife and I moved in together I wanted to share pumpkin seeds with her and I found this recipe online for slow-toasted seeds and I thought I would give it a shot. Over the years I've tinkered with the method and at this point I think I've got it down to a science. If you can take the time, give it a try and let me know if it was worth the wait.

Preparation

Cut a hole into your pupkin and pull all of the seeds from the inside. I like to keep the seeds from each pumpkin separate to make it easier to cook them later. Clean off all of the excess flesh, and use a strainer to wash the seeds, then place them in a container with a lid (a take-out soup container works well). Pour enough water into the container to cover the seeds twice. If you’d like, add about 1 tablespoon of salt for each cup of seeds. Close the lid and leave them overnight.

If the water is orange like this give it another rinse. Rinsing them through a colander helps if you’re finding little bits of pumpkin sticking to the seeds.

The next day, strain the seeds through a strainer to get off as much excess watar as possible. Take a cookie sheet and spread the seeds out to one, flat layer and leave them out to dry (this can take several hours, but using a salad spinner, a fan, or dehydrator can help speed this along).

After letting the pumpkin seeds dry, move them to a small bowl and toss them in olive oil. About a teaspoon of oil for every cup of seeds should do.

Adding Flavor

Add a flavoring of your choice. Some that have worked well in the past:

Cayenne pepper + sugar (applied at the 60 minute turn)
Sweet chili sauce + Pappy's Hottest Ride hot sauce
Tonkatsu Sauce + brown sugar (applied at the 60 minute turn)
Sweet Baby Ray’s BBQ sauce (or something with a similar texture) mixed into a little olive oil
Worcestershire Sauce
Cinnamon + Maple Syrup (put it on at the 60 minute turn and cook until seeds are crispy)

How much seasoning you use is completely to taste and since the amount you get from each pumpkin can vary, it’s hard to pinpoint exactly how much to use.

Strain seeds to remove excess oil and flavoring, then place seeds onto baking sheet.

Toasting Time

Preheat the oven to 250°F (121.11°C) and bake for 80 minutes (breaking them up and stirring them around every 20 min). If you are using sugar or something similar, add it to the last 20 minutes so it doesn’t burn.

Before taking the seeds out, check to see if they are crunchy (sometimes the bigger seeds take longer). When cooked to your preference, let them cool down on baking sheet and store in a container or ziploc bag.

You can use a regular oven for this or a toaster oven, but make sure you can set the temperature to 250°F.

Fin

Every year I make at least one batch of the cayenne pepper + sugar seeds and then depending on how many other pumpkins we have I’ll experiment with different flavors. Usually I try to use different sauces or rubs that we have laying around and sometimes they are hits and sometimes we have misses. Generally I shoot for a combo of heat and sweetness and sometimes simplicity is where it’s at.

If you wind up using this method, please let me know what spices you wound up liking (or even which ones you think should be avoided). Enjoy!

Bonus Tip

Okay, so while we’re talking pumpkins I have another thing to suggest. I learned this during a pumpkin carving contest from a friend who is an artist.

A lot of folks cut a hole in the top of their pumpkin, grab the stem and pull off the top like a lid. It gives you good access to put a candle or a light inside, but as the pumpkin gets older and softer, or if you don’t cut it perfectly, you might see some light peaking out in a way that might not fit the rest of your design. A few years ago I learned that you could get a cleaner look by cutting the hole in the bottom of the pumpkin instead.

The hole in the bottom makes it easy to get all the seeds and gunk out and if you use a candle or LED tea light you now have a little base to put it on, then you put the shell of the pumpkin over the base.

The big hole is at the bottom of the pumpkin and the little hole is the size of a light socket.

I also learned to ditch the candles and instead put a light bulb inside your pumpkin! If you have an outlet within reach of where you display your jack-o-lanterns you can pick up an outdoor light socket and feed that into your pumpkin with an LED at the end of it. I usually cut a hole somewhere in the back of the pumpkin, place the socket into the hole, then go up through the big hole in the bottom of the pumpkin to screw the bulb in.

If you want to go for a really cool look you can find standard-size LED bulbs that have a built-in flame effect. Since we do multiple pumpkins per year, I picked up this outdoor work light string and took off the little cages. We use the flame-effect bulbs for the inside of the pumpkins and then I also picked up some ultraviolet bulbs to flood the background behind the pumpkins.

Happy pumpkining and enjoy the slow-cooked seeds!

🎃

Update 2024

This year I made a batch of Cayenne Pepper + Sugar seeds and a batch of Curry Madras (from a local spice shop, Stuart’s Spices.com. A. During this cook, the house smelled amazing. B. I went back to using the big oven to spread the seeds out better and I think it helped bring out the toasted flavor a bit more than last year’s in the toaster oven.

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.

📕

Apple Hearing

Will — Mon, 16 Sep 2024 21:00:00 -0400

Anybody who knew me when I was a teenager knew that I played drums at church, went to band practice every week, and on any given Friday or Saturday night went out to either see a band play or would be on stage myself. My mom—who was a musician herself—always stressed that earplugs were important and your hearing was something you can't get back once it's gone.

Dumb teenager me doing dumb things, I often kept a few pairs of earplugs in my stick bag but almost never put them on when I was playing. On top of that, the problem with being a band full of poor teenagers is that things like extra speakers and in-ear monitors weren't something we'd invest our part-time paychecks on. So if you’re the drummer and you want to hear the vocals and whatever the guitar is playing you’d put the main speaker and amps behind the kit and listen to them from there. You're also sitting at one of the loudest instruments in the band that has a huge dynamic range between the bass and all the cymbals.

Anyway, somewhere in my 20s I started noticing that I had a hard time hearing in my right ear. I went to the doctor and got my ears cleaned and checked out. While I was having a few issues with hearing a few different sounds it wasn’t bad enough to diagnose me as hard-of-hearing or anywhere worse than that. But I knew that something was off.

Now that I'm 40 I know for sure that my early drumming days did some serious damage. I often find myself having a hard time hearing people in crowded areas where a lot of talking is going on and I find myself asking people to repeat what they said from time to time.

It’s all my fault and while the ship has sailed I have found that being a remote employee has really helped me deal with it at work (because every conversation can be turned up with a volume knob). Elsewhere I find myself using headphones a lot to consume media and for basic hearing protection. I keep a pair of over-the-ear monitors at my drum kit for when I play at home, I have a pair of noise cancelling, over-the-ear headphones for when I mow the lawn or do anything in the wood shop, a pair of headphones for solo watching TV (which is also about not disturbing everyone in the house), and as of the last couple months I've started doing the thing I learned on ATP where you can wear AirPods Pros at concerts to kill off sounds above a certain decibel range.

AirPods Pros as Hearing Aids

At its 2024 iPhone event, Apple announced a software update coming to all AirPods Pros (2nd generation) that turn them into clinical-grade hearing aids. I can’t wait for this to roll out officially because A. I already have a pair of AirPods Pro that will work with this feature so it's just a software upgrade for me, and B. at this point I always have my AirPods Pros on me anyway.

My understanding of the feature is that you use an iPhone on iOS 18 to do a hearing test, then it helps you create a profile that syncs to all of your Apple devices. This means my iPhone, iPad, Mac, and Apple TV would all use this hearing profile to make audio sound better for me. Then as part of the AirPods themselves I can essentially put them in a hearing aid mode where it not only pumps noise from around me into the earbuds but it'll use that profile to help enhance the right sounds that work better for my ears.

While I don’t love being in this situation to begin with, at least I hope this new AirPods feature will help me out a little bit.

🎧

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

📘

Frostapalooza Photo Roundup

Will — Fri, 23 Aug 2024 17:30:00 -0400

I wasn’t the only person shooting photos at Frostapalooza and a week later I'm starting to see tons of great photos and videos from the show pop up! The best place to get an idea what it felt like to be at this show can be found in the Frostapalooza! Google Photos album.

A special shout out to Anne-Laure Gaté—who I think is in the photo above—for nailing some really incredible closeups.

I also noticed Brian Kordell was shooting a lot of video from the crowd and has posted a bunch of shorts and videos on his YouTube channel, (including this clip of one of my favorite tunes of the night, Sledgehammer).

Over the past few days I’ve seen a few blog posts popping up that share some really nice insight on what it was like to participate in the show:

Adactio: Journal—Frostapalooza by Jeremy Keith
Frostapalooza in photos and videos by Brad Frost
Frostapalooza by Chris Coyier (about 40% of the way down the page is a video of a very sweet jam between Chris and Jeremy from the pre-show get together)
Vibe Check №34 - Dave Rupert

Finally, while I believe it’s currently in editing, there is a multi-camera video that is definitely worth looking forward to. I got to see a behind-the-scenes look at the process to capturing all of the clips from all of the cameras placed around the venue and it’s an amazing, yet complicated setup that got all the best angles of the night.

Photographing Frostapalooza

Will — Tue, 20 Aug 2024 07:00:00 -0400

Frostapalooza was an amazing night! If you haven’t heard of it, Brad Frost turned 40 this year and he invited 40 of his friends, family, and fellow web development-related folks down to put on a charity concert in Pittsburgh. It was a bunch of folks from around the US (and from across the pond) who were coming into town and playing together for the first time.

I had heard about it on episode 601 of the Shop Talk Show and bought my ticket right away. Putting together all of these people who’s books and blogs I’ve been reading, and podcasts I’ve listened to for almost two decades, in one place, only a few hours away, was an incredible thing. I can’t remember anything else like this in the web development community and I don’t know the next time something this big will happen again.

Having spent some time photographing events for The A Cappella Blog I thought it might be fun to bring my camera gear down to capture this event for posterity. From my experience I know that some bands have rules around when and how you can shoot their shows, as well as venues sometimes have rules around where you can go to take photos or what you can and cannot include in your photos. So I reached out to Brad via email asking if it would be okay to bring my gear down and if I could have access to places like the backstage and the balconies. While I thought that worst case I would just go to the show and enjoy it as part of the audience, I was surprised and thrilled to get an enthusiastic “YES!” in response.

With that I made it a goal to capture some of the fun moments of the night and to get at least one good shot of each person performing. I'm happy with how the photos turned out and throughout this page you’ll see some of my favorite shots from the night—along with a few photos from the night before.

Preparing for the Gig

Before heading down to Pittsburgh I put together a solid set of lenses and gear (backup batteries, memory cards, lens cleaning kits, etc...) as well as a few backup items that I wasn’t sure I'd need, like battery-powered LEDs and a tripod.

It’s been a while since I've shot photos during an event like this so I wanted to do a little YouTube research on concert photography and I picked up on a couple of tricks and camera settings that I tried throughout the event. One of them was around metering modes and using spot metering. When I've shot events like this in the past I usually will leave metering on the matrix metering mode (in Nikon parlance), but this can sometimes lead to lots of extra noise and an increased auto-ISO from the huge differences between stage lights and the dark background behind the performers.

I moved the metering selector to one of my camera’s function buttons so I could quickly swap between matrix metering and spot metering. My other function button was set to focus modes and throughout the entire show I wound up switching both of these settings frequently as I moved around the venue and changed lenses.

Another tip I got was to use Manual mode and set the aperture wide open, set the camera to auto-ISO, and the shutter speed to 1/200 or 1/250. I've done something like this for past shows, but I would try to stick to a shutter speed of 1/160 or something slower to get more light in. I moved my setting to 1/250 for almost the whole show and I'm glad I did. Details like hair moving, drum sticks swinging, and other movement were mostly frozen and I think it made a huge difference in some shots. The tradeoff for this was higher ISO and more noise, but I think spot metering helped keep that down where it could.

Finally, I capped the auto-ISO at either 8000 or 6400 throughout the night. There are a few shots where this was an issue and the noise is very obvious, but for the most part exposures were where I wanted them to be and those that were underexposed still got enough detail to balance things out.

Fin

I came to this show as a fan of the web developers that I've learned from and that have made a huge impact on my career and how I approach my work. But for one weekend these folks weren’t developers talking shop; they were musicians and a group of people looking to celebrate being together and to share their talents with the crowd. Brad and all of the folks I met were kind and welcoming throughout the entire weekend and Brad answered all of my questions that came up along the way—making it really easy to just show up and go with the flow.

One thing that’s not to be overlooked is that this whole event was for the benefit of two different charities, Project Healthy Minds and NextStep Pittsburgh. Right before hitting the road one of my friends was managing a mental health crisis in his life, so that made this event hit home even more for me. Please take care of each other and—as Brad started off the concert—we all need to take some time to notice the negative and get it out.

To Brad and all of the other folks I met this weekend, thank you and keep rocking!

🍄🎸

Gamifying Vacation

Will — Thu, 08 Aug 2024 17:25:00 -0400

I recently went on a vacation with my family that took us across the globe. It was exciting for all of us but my kids, in particular, were absolutely stoked. It would mean a lot of new things for them, including seeing the sights, eating new foods, and interacting with new people. While these are all the reasons why I wanted to go on this trip, I can see why my kids might have a little anxiety about getting catapulted way outside of their comfort zone.

We—a family from north-eastern USA—were traveling to Malaysia, Singapore, and Japan, and while my kids are familiar with Malaysian and Japanese food, we knew that there would be a few foods we wanted them to experience, we wanted them to get to know the language and the cultures, and we wanted them to be motivated to be in their best behavior.

Tag Ceremonies

During summer break our kids go to a summer camp that has a reward system for kids that show kindness and maturity or push themselves out of their comfort zones. They give kids a lanyard with a keyring on it at the beginning of the summer and as the kids earn their rewards they are presented with a colorful keyring tag that has a unique label and an illustration for each reward. For example, the kids will get tags for their first time swimming, hitting the target in archery, and doing the ropes course. They also have tags for behaviors, like sharing, being honest, and winning competitions. The tags are presented to the kids in a weekly “Tag Ceremony” put on by the counselors.

My kids are proud when they receive a tag. It motivates them to do their best to receive more tags and they are psyched to let us know what new tags they've earned each week.

A week or so before our trip, my kids were sharing with us the news about the tags they just received and I just threw the idea out there to my kids that wouldn’t it be fun to get a tag for trying durian or sushi on the trip? They both got excited about the idea and I told them that—no promises but—I would look for some tags I could write on during the plane ride and we’d come up with some that they could earn.

Right on, Write-on Tags

With just a few days to spare I went with the quickest route to getting some blank tags that would work for our purpose. I wound up placing an order for a box of translucent tags on Amazon. To be honest, I went with the translucent color because I thought it would look cool, but I think the white or one of the other colors would have worked better. The problem with the translucent background is it made a stack of tags on a keyring harder to read.

These tags were a little smaller than the tags the kids get from camp, but they were very similar in shape and size. We found a couple of key rings around the house that fit the tiny holes in the tags. I would up using a fine-point Sharpie and wrote on the tags by hand—sloppy handwriting be damned.

To organize myself ahead of time I came up with a list of all of the rewards that could be earned on the trip. I used Affinity Publisher to whip together a page that I could print out, cut in half, then put in my kid’s travel backpacks. This page would outline what is required to earn a particular tag as both a reminder to myself and to help make sure the kids knew the rules up front.

I have two kids so I made two sets of each tag, and I doubled up on a couple of the tags I thought the kids could earn more than once, like the Spicy Adventurer tag.

The blank tags came in a little ziplock bag so after I wrote up all the tags I put them all in that bag and put it in my travel bag.

Throughout the vacation I would give the kids a heads up, like letting them know we’ll be going to a seafood restaurant and they had a good chance of getting a shrimp or crab tag. At the end of the day for each day of our vacation we did our own tag ceremony and I presented the kids with their new tags.

The Ultimate Reward

My kids each have a hand-me-down iPad that we brought on the trip to give them something to do on the long flights. Kids being kids, instead of looking for fun ways to entertain themselves in our homestays and hotels they constantly asked to play games on their iPads whenever we seemed to have a moment of downtime. Instead of constantly telling them “no”, I eventually told them that if they can go the rest of the trip—outside of plane rides—without turning on their iPads I would give them a special, golden tag as a reward.

I can’t say I expected anything to come out of this, but it worked (with some really minor exceptions that we let go by). For the most part they stayed off their devices without us having to tell them. The only thing they used their iPads for were to take videos and photos, and that was something we encouraged them to do.

So anyway, we got back home and now I needed to come up with whatever this golden tag would look like 🤔

I used Fusion 360 to create a blank tag. To do this I measured the current tags (at 5mm x 3mm) and measured the distance from the keyring hole from the edge. In Fusion I put together a sketch and modeled out the based of the tag, added a border, and room for the keyring hole.

Fusion 360 lets you add text, but the slicer software I use for my 3D printer, Bambu Slicer, also lets you add text to a model. It was simpler to create the tags as blank in Fusion, bring the STL file from that into the slicer, add the text to one of the tiles, then duplicate that one tile to modify the text from there.

I created an iPad Dust Collector tag and let the printer do its thing. I used Prusa’s awesomely named Oh My Gold PLA filament with Bambu’s default print settings (along with the PLA profile I added to the slicer for the non-Bambu PLA).

While I had done most of the work anyway, I put a couple of colors on my AMS and created tags with my kids names on them just for fun. The slicer lets you start with one color and then swap out the color at a certain layer, so I picked the layer after the base was printed in gold to start the color for the text and the border.

Fin

I uploaded the model for the blank tags onto Prusa’s Printables website. There are other similar tags on the website, but if you have a 3D printer and wanted to follow along my process here, the model is free to use.

My kids didn’t earn all of the available tags but they earned most of them and they truly tried their best. I’m so damn proud of them for trying different foods (and actually liking them!), for sticking with us on some long hikes, and for learning some words in the local language and speaking them to strangers (like telling the cook ”thank you“ in Malay on the way out of a restaurant).

I don’t know that we'll use this whole tag setup on future trips, but my kids are at the right age right now where this got them excited for this one vacation and it added a lot to the memories for them and for me.

🏝️

Embracing Noise

Will — Wed, 19 Jun 2024 22:54:00 -0400

I was looking back at some photos from a past vacation—one where I rented a Nikon D500 to bring along with me—and I noticed that I had taken some photos set to really high ISO numbers. For example, this photo of these lanterns was shot with an ISO just over 17000!

This is a screenshot of a crop of the original photo, so there’s a little more in the frame than shown here.

Unless it's very specific for the look of the photo, I typically set the ISO to use AUTO-ISO, which essentially lets the camera decide what ISO setting is best for the shot. Nikon lets you set a base setting and a maximum setting, however, for the D500 I don't think I had set it to a specific maximum ISO, because in my library I saw shots that went all the way up to 40000.

When I got my current camera, the Nikon Z 7ii, I had left on a lot of the noise reduction settings (that blur out the noise in camera) and I had set the maximum AUTO-ISO for each of my three user settings to go no higher than 2000 or 4000.

I've noticed that when taking photos in situations where I'd expect the ISO to go way up that one of two things happen. Either the noise reduction does its thing and the image looks a little blurry, or if in a situation where I'm shooting Aperture Priority (where the shutter speed is automatically set to work with a fixed aperture setting) the shutter speed goes so low that the image is blurry or at least some detail is lost.

Wherever possible I've been trying to avoid any noticeable noise, but looking at my past vacation photos I think letting there be noise was the reason why I got a decent shot in the first place.

As I've heard from other photographers, you can use technology to remove noise and you can spend all day tweaking exposure, but removing motion blur is a much tricker thing to do later on.

So I decided to take my one user setting that I typically use to take photos of my kids or other moving subjects and I cranked the maximum AUTO-ISO to 25000 and turned off the in-camera noise reduction, then took a few random shots around the house.

This photo is also zoomed in and cropped from a portrait orientation.

In this low-light shot of my cat you can see a lot of noise, but also things like her whiskers or the fur on her ears aren't blurry from movement. I might continue to tweak these settings, but I'm leaning towards keeping this look. Over the next couple of weeks I'll focus more on low-light shooting to see how well this pans out. I’ll bet some photos in otherwise decent light don’t change, but I'll also keep an eye on that too. For now I’m willing to embrace the noise.

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.

🍱📘

Wall-Mounted Standby

Will — Sun, 28 Jan 2024 09:51:00 -0500

In 2023, Apple introduced a feature to their MagSafe-compatible iPhones, called Standby. This feature lets you use the widgets from your apps when your phone is:

Magnetically attached to a MagSafe charger or plugged in with a charging cable
The phone is positioned upwards and in the horizontal position
The device’s Lock Screen is on

I currently have 2 MagSafe stands by TwelveSouth that I use on a nightstand while I sleep and on my desk while I'm working. With these stands in places here are some ways I typically use Standby:

On my nightstand I display a digital clock alongside either the weather widget, a charging widget, or my calendar (via Fantastical).
While I'm working I typically leave my phone on the World Clock, showing points that represent the timezones of some of the international teammates I work with.
In both places, I’ll turn on the Now Playing screen for audio books and podcasts that I listen to (usually air playing to speakers or AirPods Pros).

I really love how simple this feature is to use and now I want to put MagSafe stands all around my house. After upgrading my nightstand MagSafe stand to the HiRise 3 Deluxe, I gave the Forté I was previously using to my wife, which—replacing her MagSafe charger—left us with an extra MagSafe puck to spare.

Finding a Use Case

My first thought was to pick up another Forté and find a place to put it in the kitchen, but then—as part of a customer journey—marketing for a different brand had another idea in mind.

I got a marketing email by a company I bought iPhone stands and AirTag cases from, Elevation Lab, for a new product that lets you pin an AirTag to your kids or a piece of luggage. While I'm not in the market for that, it got me to visit their website and check it out. While I was there, I came across something they call, MagBase.

MagBase is essentially a little silicon holder for a MagSafe puck that is meant to live on your desk or another flat surface. It’s designed so you can pick up your phone by sliding it off the magnet, but just as easily, you can pick up both your phone and your MagSafe puck to do things like check your email or respond to messages.

I like that the MagBase is very minimal, and even though it’s designed to sit on a flat surface it gave me an idea on how I can solve a very minor problem, while also giving me another place to use Standby.

A few years ago I put together this little couch-side shelf, and above that I mounted a shelf for more vertical space. Last year, I unmounted the shelf for a few minutes to add a headphone hook to it. I use this shelf while watching TV or playing video games and I usually place things like my iPad and AirPods Pro case on it.

As far as my phone goes, I usually put that on the arm of the couch because I had no other particular place to put it. This extra MagSafe puck helped me find a new place for it, and it looked cool to boot.

The headphone hook sits in the middle of the shelf, so when sitting on the couch there is some room on the wall to the left and to the right of the headphones. The space to the right seemed like a really good place to put a MagSafe puck. Before ordering a MagBase I thought that maybe I would 3D print my own MagSafe mount. After taking a look at some of the 3D printing model sites I found that the idea of mounting a MagSafe puck on the wall wasn't a new idea, and there were several free, really nice models to choose from.

One thing the MagBase had going for it, though, was that it also comes with a USB-C extender. This would be important because the 1-meter distance from the nearest outlet to the place I wanted to mount the MagSafe puck was too short. That got me to go for the MagBase, so I placed an order and it showed up a couple of days later.

I thought for a little bit about how I would run the MagSafe cable around the shelf. I didn't want to drape the cable over the shelf, but if I added a little gap between the shelf and the wall I could run the cable behind the shelf. This wasn’t really my favorite option, so I unmounted the shelf and brought it down to the workshop to see if I could come up with something else.

Channeling a Solution

I took a look at where the shelf mounting hardware fits into the shelf and noticed that the area I routed out for the mounting hardware gave me about 5mm to work with. With the cable plugged into the wall on the left side, I could have ran the cable from the left mount to the right, leaving the cable just under the shelf.

Maybe it was where I was standing, but something else came to mind. Did you know that the width of the kerf on a table saw blade is exactly the same thickness as a MagSafe cable? At least this is true for the blade that came with my DeWalt table saw.

I moved the table saw fence close enough that the blade lined up with the routed area for the mounting hardware. I raised the blade to just about 3-4mm, picked up one side of the shelf, and did a plunge cut from one side of the mounting hardware slot to the other.

I did a quick test of the cable to find that it was a perfect fit!

I realized I had to create an exit point for the cable on both sides, so I grabbed a chisel and diagonally cut out a notch for the cable on both sides.

While doing a dry run with the cable, I also realized that I would need to let some of the cable sit within the routed out area that the bottom of the mounting hardware sits. The problem with this is that a lot of the stability for the shelf is based around clamping down on that area and I didn't want to crush the MagSafe cable to get this to work.

I found a washer big enough to fill up that area and found that if I stack up two washers it was just about as high as the MagSafe cable. I used some hot glue to attach the washers tougher, then onto the shelf. I didn’t really need to do this but this would make it so that when I'm mounting the shelf the washers wouldn’t move around and fall out of place.

After another quick test I was all set with routing the cable from one end of the shelf to the other.

The final step was to re-mount the shelf and then attach the MagBase to the wall. I took one more pass at running the cable through the channel I just made. I made it as flush as I could and made sure the MagSafe puck was the right distance from the shelf to where I wanted to put it.

Fin

This is a DIY situation I really like being in. This is the 4th time I’ve iterated on this shelf area and each time it becomes more useful for my needs. I also like that everything in this project is reversible. As with all technology, a new things comes along every few years and sometimes things just break. If I decide I no longer want the MagSafe puck in this spot, I can unmount it and remove it from the shelf, leaving only the channel and the notch cut out, but hidden in the back of the shelf. Removing the washers should be pretty easy, too.

As I was going through these pictures on my laptop, I placed my phone up on the wall, put on a podcast, and got to enjoy this new setup right away.

🖼️

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".



Unboxing the Birdfy Nest
Will — Wed, 06 Dec 2023 12:30:00 -0500
            Intro
Earlier this year I built two bird houses and put cameras in them as gifts for family members. At the end of that post I mentioned that the company I bough the cameras from, Netvue, invited me into their testing program to give feedback on a product, called Birdfy Nest. I received my Nest a couple of weeks ago and I set it up in my back yard. I wanted to write this post as sort of an unboxing and to show some detailed photos of what to expect from the Birdfy Nest.
      Unboxing
      
      On first impression, the box the Nest ships in was a little heavier than I expected, but it turns out there's a lot in the box. The retail box for the nest fits nicely into its shipping box, then inside the retail box there is the Nest birdhouse and a series of little boxes for the solar panel and the mounting accessories. There were also a couple of other cardboard boxes used to protect the gap between the top of the birdhouse and the vented roof, as well as the outer camera.
      
      
      One thing I really appreciated was that they included a ribbon as sort of a temporary handle to help you pull all of this out of the box, instead of having to turn the box upside down and hoping things don't go all over the place.
The box also comes with two instruction booklets. One is an installation guide that walks you through the installation options and how to use the gear that comes with the Nest. The other booklet is the user manual and it includes things like the parts list and some other standard user manual info. One of the things I really liked is that the manuals included information around how to change the predator guard (the doorway with the hole that the bird enters the box) and they give some suggestions on good places to mount the Nest.
      Setup
      The first thing the instructions tell you to do is to charge the camera unit up. The Nest comes with a USB-A-to-USB-C cable so as long as you have a cell phone charging brick around you’re all set (no need to pull the solar panel out just yet). To access the camera unit you can pull down the main door from the side of the Nest.
      
      
      If you want, you can plug the charging cable right into the camera unit, or you can unplug the cables going into it and slide the whole camera unit out of the Nest.
      
      The camera is split into three parts: the inside camera (shown here), an outside camera, and the box that stores the camera battery and the WiFi transmitter.
      With the camera charging, the next step is to set up the outer camera. In order to do this there's a piece of tape you need to remove, then there's a cover that you need to slide off. The instructions make this clear with some really helpful illustrations.
      
      For someone with big fingers, installing the outer camera was a tiny bit tricky. The first step is to turn the camera 180 degrees so the lens is facing the front entrance of the birdhouse. There are guide hole that make this easy to do, but the tricky part is that there are four screws that need to be lined up and screwed into the wooden side. There are pre-drilled holes there already but I found my self having a hard time keeping the screws from falling into the hole used for the camera wire. The screws rolled right out, but it took me a few extra attempts to get it right.
Once the outer camera is fastened to the side you can slip the cover back on. Another neat trick is that you can tilt the camera down. To do this you can pull the camera forward a bit, rotate it, then let it snap into place. I tilted it down a notch to point the lens right at the entrance hole.
      
      Mounting Accessories
The three accessory boxes were split up like this:
      Wall and pole mounting hardware and extra predator guards
      
      This box included a mixed bag of an accessories. In this box you’ll find the a charging cable you can use the first time you set up the camera. There's also a screwdriver you can use to mount the Nest and install the outer camera.
The Nest also comes with two alternate predator guards. One has a hole that is larger than the standard one and the other has a hole that is smaller. The smaller hole provides more protection from predators, but it means only smaller birds can fit comfortably through the hole and reside in your Nest. I chose to keep the standard guard on, but I may consider moving to the larger hole to attract larger birds in the future. The user manual shows you how you can access and then replace the guard.
One of the most important pieces in this box is a mounting plate. This plate attaches to another mounting piece on the back of the Nest. You can choose to screw the mounting plate directly onto a flat surface, using the screws included in this box. There is a paper template that you can use to help mark where the screw holes will go.
If you want to mount your Nest onto a pole there are two smaller hose clamps and two that are slightly larger. You can unscrew the clamp all the way and feed it into the mounting plate, then tighten it around the pole you are mounting it to.
Finally, there is a third options, using the tree-mounting strap found in another box.
      Tree-mounting strap
      
      You can feed the tree-mounting strap through the mounting plate, wrap it around a tree or a larger post, then tighten it up and lock it into place.
I really like all of the mounting options. I planned on mounting my Nest to a pole, but I’m going to keep the other accessories around so in case I need to move the Nest someday I’ll have the flexibility to try one of the other mounting options.
      Solar panel
      
      The solar panel is an awesome accessory. It saves you from having to remove the camera to charge it up—disturbing the birds residing in your birdhouse. It comes with two mounting options. There’s a screw-on wall mount that can be rotated to face the sun. The solar panel has a really long USB-C cable that means you can mount the birdhouse where you'd like and then mount the solar panel in an area where you'll get optimal sunlight.
The other option is a posable mount that screws into the ¼ inch standard mount on the back of the solar panel. This mount can be bent and wrapped around a pole or a fencepost. Just note that the posable mount can be found in a different box than the solar panel.
      Installation
To mount my Nest onto a pole I fed two of the smaller hose clamps into the mounting plate. I also used the posable mount and attached that to the solar panel so I can mount that onto the same pole.
      
      Before putting the mount on the pole I checked the orientation with the mount on the back of the Nest.
      
      I see that Netvue just announced a poll that would work in this situation, but I had picked this pole up at a local garden center. I also picked up a squirrel baffle, just like I did for my bird feeder. Finally, I 3D-printed the topper to keep rain out of the top of the pole.
      
      
      I added the solar panel in a way where I could hide it when you look straight on, but I might move this again after seeing how much sun we get over the next couple of weeks.
      
      
      Software
I had already gotten familiar with the Netvue app from my previous experience with the Birdfy Cameras I purchased. Recently Netvue came out with a new app that’s dedicated to their Birdfy line of cameras. It seems more focused on sharing the story of the birds that reside in your Nest, as well as using AI features to help you identify the birds that visit your Nest.
The setup process is quite painless and I had the app connected to my camera in just a couple of minutes. The only thing I haven’t tried yet is the bird recognition AI feature, but I’ll likely turn that on in the spring, when we have some more traffic around the Nest. Within my first week of setting up the camera I had already had a visitor (my guess is it was maybe a House Sparrow).
      
      One of the features that stood out to me is that when your camera detects motion and captures a clip, the app gives you the option to "Collect" the bird in the clip. When you hit the "Collect" button, it saves the clip and tags it with the species of the bird. My kids—who are huge fans of Pokémon—really like this feature and the idea of building out a collection of the birds around our house.
      Fin
The folks behind the Birdfy Nest really went all out to design this birdhouse. When I was doing research for my homemade birdhouses a lot of features that were suggested by other makers included things like adding a screen at the bottom, adding ventilation, adding notches below the entrance hole to help birds climb out, using a specific diameter for the predator guard and entrance hole, having a door that opens up so you can clean it every year, etc...
When I was building the birdhouses I did some of these things, but I didn't get around to adding all of these features (specifically the mesh screen). This birdhouse just comes with all of those things built into it. I can’t think of anything I would have done differently, feature wise.
There is something to be said for learning how, and then building your own birdhouse, but for most folks I think this is the way to go.
      
      
      The Birdfy Nest is currently on pre-order at the Netvue Birdfy website and—as of this writing—there’s even a special Christmas edition that’s on sale.      🪺  


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