emGee Software Solutions Custom Database Applications

Share this

Lullabot

Strategy, Design, Development | Lullabot
Updated: 1 week 17 hours ago

Lullabot at DrupalCon Seattle

Wed, 11/28/2018 - 12:54

We're excited to announce that 14 Lullabots will be speaking at DrupalCon Seattle! From presentations to panel discussions, we're looking forward to sharing insights and good conversation with our fellow Drupalers. Get ready for mass Starbucks consumption and the following Lullabot sessions. And yes, we will be hosting a party in case you're wondering. Stay tuned for more details!

AMP (Accelerated Mobile Pages) Re-Imagined

Karen Stevenson, Director of Technology

Karen will talk about the challenges of the original Drupal AMP architecture, changes in the new branch, and some big goals for the future of the project.

Autopsy of Vulnerabilities

Zequi Vázquez, Developer

Zequi will explore Drupal Core vulnerabilities, SA-CORE-2014-005 and SA-CORE-2018-7600, by discussing the logic behind them, why they present a big risk to a Drupal site, and how the patches work to prevent a successful exploitation.

Design a Decoupled Application - An Architecture Guide Based Upon the Drupal Admin UI

Sally Young, Senior Technical Architect (with Matthew Grill, Senior JavaScript Engineer at Acquia & Daniel Wehner, Senior Drupal Developer at Chapter Three)

Discussing common problems and best practices of decoupled Drupal has surpassed the question of whether or not to decouple. Sally, Matthew, and Daniel will talk about why the Drupal Admin UI team went with a fully decoupled approach as well as common approaches to routing, fetching data, managing state with autosave and some level of extensibility.

Drupal Admin UI

Sally Young, Senior Technical Architect (with Lauri Eskola, Software Engineer in OCTO at Acquia; Matthew Grill, Senior JavaScript Engineer at Acquia; & Daniel Wehner, Senior Drupal Developer at Chapter Three)

The Admin UI & JavaScript Modernisation initiative is planning a re-imagined content authoring and site administration experience in Drupal built on modern JavaScript foundations. This session will provide the latest updates and a discussion on what is currently in the works in hopes of getting your valuable feedback.

Enterprise Content Inventories

Greg Dunlap, Senior Digital Strategist

Greg will take you on a tour of the set of tools we use at Lullabot to create predictable and repeatable content inventories and audits for large-scale enterprise websites. You will leave with a powerful toolkit and a deeper understanding of how you use them and why.

Front-end Web Performance Clinic 2019

Mike Herchel, Senior Front-end Developer

If you're annoyed by slow websites, Mike will take you on a deep dive into modern web performance. During this session, you will learn how to identify and fix performance bottlenecks in your website and web app.

How DevOps Strengthens Team Building

Matt Westgate, CEO & Co-founder

Your DevOps practice is not sustainable if you haven't implemented its culture first. Matt will take you through research conducted on highly effective teams to better understand the importance of culture and give you three steps you can take to create a cultural shift in your DevOps practice. 

How to Hire and Fire Your Employer

April Sides, Developer

Life is too short to work for an employer with whom you do not share common values or fits your needs. April will give you tips and insights on how to evaluate your employer and know when it's time to fire them. She'll also talk about how to evaluate a potential employer and prepare for an interview in a way that helps you find the right match.

Layout Builder in the Real World

Karen Stevenson, Director of TechnologyMike Herchel, Senior Front-end DeveloperWes Ruvalcaba, Senior Front-end Developer, & Ellie Fanning, Head of Marketing

Karen, Mike, Wes, and team built a soon-to-be-launched Drupal 8 version of Lullabot.com as Layout Builder was rolling out in core. With the goal of giving our non-technical Head of Marketing total control of the site, lessons were learned and successes achieved. Find out what those were and also learn about the new contrib module Views Layout they created.

The Imaginary Band of Drupal Rock Stars

Matthew Tift, Senior Developer

The words "rockstar" and "rock star" show up around 500 times on Drupal.org. Matthew explores how the language we use in the Drupal community affects behavior and how to negotiate these concepts in a skillful and friendly manner.

Using Personas as an Inclusive Design Tool

Helena McCabe, Senior Front-end Developer (with Carie Fisher, Sr. Accessibility Instructor and Dev at Deque)

Helena and Carie will examine how web accessibility affects different personas within the disability community and how you can make your digital efforts more inclusive with these valuable insights.

Diversity & Inclusion: Building a Stronger Drupal Community

Marc Drummond, Senior Front-end Developer Greg Dunlap, Senior Digital Strategist (with Fatima Sarah Khalid, Mentor at Drupal Diversity & Inclusion Contribution Team; Tara King, Project lead at Drupal Diversity & Inclusion Contribution Team; & Alanna Burke, Drupal Engineer at Kanopi Studios)

Open source has the potential to transform society, but Drupal does not currently represent the diversity of the world around us. These members of the Drupal Diversity & Inclusion (DDI) group will discuss the state of Drupal diversity, why it's important, and updates on their efforts.

Why Will JSON:API Go into Core?

Mateu Aguiló Bosch, Senior Developer (with Wim Leers, Principal Software Engineer in OCTO at Acquia & Gabe Sullice, Sr. Software Engineer, Acquia Drupal Acceleration Team at Acquia)

Mateu and his fellow API-first Initiative maintainers will share updates and goals, lessons and challenges, and discuss why they're pushing for inclusion into Drupal core. They give candy to those who participate in the conversation as an added bonus!

Personalization for the Perplexed

Jeff Eaton, Senior Digital Strategist

Personalization has become quite the buzzword, but the reality in the trenches rarely lives up to the promise of well-polished vendor demos. Eaton will help preserve your sanity by guiding you through the steps you should take before launching a personalization initiative or purchasing a shiny new product. 

Also, from our sister company, Drupalize.Me, don't miss this session presented by Joe Shindelar:

Gatsby & Drupal

Joe will discuss how Gatsby and Drupal work together to build decoupled applications, why Gatsby is great for static sites, and how to handle private content, and other personalization within a decoupled application. Find out what possibilities exist and how you can get started.

Photo by Timothy Eberly on Unsplash

Categories: Drupal CMS

Project Management with GitHub: v2

Wed, 11/28/2018 - 10:02

At Lullabot, we’ve been using GitHub, as well as other project management systems for many years now. We first wrote about managing projects with GitHub back in 2012 when it was still a bit fresh. Many of those guidelines we set forth still apply, but GitHub itself has changed quite a bit since then. One of our favorite additions has been the Projects tab, which gives any repository the ability to organize issues onto boards with columns and provides some basic workflow transitions for tickets. This article will go over one of the ways we’ve been using GitHub Projects for our clients, and set forth some more guidelines that might be useful for your next project.

First, let’s go over a few key components that we’re using for our project organization. Each of these will be explained in more detail below.

  1. Project boards
  2. Epics
  3. Issues
  4. Labels
Project boards

A project board is a collection of issues being worked on during a given time. This time period is typically what is being worked on currently, or coming up in the future. Boards have columns which represent the state of a given issue, such as “To Do”, “Doing”, “Done”, etc.

For our purposes, we’ve created two main project boards:

  1. Epics Board
  2. Development Board
Epics Board

ex: https://github.com/Lullabot/PM-template/projects/1

The purpose of this Project board is to track the Epics, which can be seen as the "parent" issues of a set of related issues. More on Epics below. This gives team members a birds-eye view of high-level features or bodies of work. For example, you might see something like “Menu System” or “Homepage” on this board and can quickly see that “Menu System” is currently in “Development”, while the “Homepage” is currently in “Discovery”.

The “Epics” board has four main columns. (Each column is sorted with highest priority issues at the top and lower priority issues at the bottom.) The four columns:

  • Upcoming - tracks work that is coming up, and not yet defined.
  • Discovery - tracks work that is in the discovery phase being defined.
  • Development - tracks work that is currently in development.
  • Done - tracks work that is complete. An Epic is considered complete when all of its issues are closed.
Development Board

ex: https://github.com/Lullabot/PM-template/projects/2

The purpose of the Development board is to track the issues which are actionable by developers. This is the day-to-day work of the team and the columns here are typically associated with some state of progression through the board. Issues on this board are things like “Install module X”, “Build Recent Posts View”, and “Theme Social Sharing Component”.

This board has six main columns:

  • To do - issues that are ready to be worked on - developers can assign themselves as needed.
  • In progress - indicates that an issue is being worked on.
  • Peer Review - issue has a pull request and is ready for, or under review by a peer.
  • QA - indicates that peer review is passed and is ready for the PM or QA lead for testing.
  • Stakeholder review - stakeholder should review this issue for final approval before closing.
  • Done - work that is complete.
Epics

An Epic is an issue that can be considered the "parent" issue of a body of work. It will have the "Epic" label on it for identification as an Epic, and a label that corresponds to the name of the Epic (such as "Menu"). Epics list the various issues that comprise the tasks needed to accomplish a body of work. This provides a quick overview of the work in one spot. It's proven very useful when gardening the issue queue or providing stakeholders with an overall status of the body of work.

For instance:

Homepage [Epic]

  • Tasks

    • #4 Build Recent Posts View
    • #5 Theme Social Sharing Component

The Epic should also have any other relevant links. Some typical links you may find in an Epic:

  • Designs
  • Wiki entry
  • Dependencies
  • Architecture documentation
  • Phases
Phases

Depending on timelines and the amount of work, some Epics may require multiple Phases. These Phases are split up into their own Epics and labeled with the particular Phase of the project (like “Phase 1” and “Phase 2”). A Phase typically encompasses a releasable state of work, or generally something that is not going to be broken but may not have all of the desired functionality built. You might build out a menu in Phase 1, and translate that menu in Phase 2.

For instance:

  • Menu Phase 1

    • Labels: [Menu] [Epic] [Phase 1]
    • Tasks
    • Labels: [Menu] [Phase 1]
  • Menu Phase 2

    • Labels: [Menu] [Epic] [Phase 2]
    • Tasks
    • Labels: [Menu] [Phase 2]
  • Menu Phase 3

    • Labels: [Menu] [Epic] [Phase 3]
    • Tasks
    • Labels: [Menu] [Phase 3]

Issues within Phase 3 (for example) will have the main epic as a label "Menu" as well as the phase, "Phase 3", for sorting and identification purposes.

Issues

Issues are the main objects within GitHub that provide the means of describing work, and communicating around that work. At the lowest level, they provide a description, comments, assignees, labels, projects (a means of placing an issue on a project board) and milestones (or a means of grouping issues by release target date).

Many times these issues are directly linked to from a pull request that addresses the issue. By mentioning the issue with a pound(#) sign, GitHub will automatically create a link out of the text and add a metadata item on the issue deep linking to the pull request. This is relevant as a means of tracking what changes are being made with the original request which then can be used to get to the source of the request.

For our purposes, we have two "types" of issues: Epics or Tasks. As described above, Epics have the "Epic" label, while all others have a label for the Epic to which it belongs. If an issue does not have a value in the "Project" field, then it does not show up on a project board and is considered to be in the Backlog and not ready for work.

Labels

Labels are a means of having a taxonomy for issues.

We have 4 main uses for Labels currently:

  1. Epic - this indicates the issue is an Epic and will house information related to the body of work.
  2. [name of epic] (ex: Menu) - indicates that this is a task that is related to the Menu epic. If combined with the Epic label, it is the Menu Epic.
  3. [phase] (ex: Phase 1) - indicates this is part of a particular phase of work. if there is no phase label, it's considered to be a part of Phase 1.
  4. bug - indicates that this task is a defect that was found and separated from the issue in which it was identified.
  5. Blocked - Indicates this issue is blocked by something. The Blocker should be called out in the issue description.
  6. Blocker - indicates that this issue is blocking something.
  7. front-end - indicates that an issue has the underlying back-end work completed and is ready for a front-end developer to begin working on it.

There are other labels that are used sometimes to indicate various meta, such as "enhancement", "design", or "Parking Lot". There are no set rules about how to use these sort of labels, and you can create them as you see fit if you think they are useful to the team. Though be warned, if you include too many labels they will become useless. Teams will generally only use labels if they are frictionless and helpful. The moment they become overwhelming, duplicative, or unclear, the team will generally abandon good label hygiene.

These are just some guidelines we consider when organizing a project with GitHub. The tools themselves are flexible and can take whatever form you choose. This is just one recommendation which is working pretty well for us one of our projects, but the biggest takeaway is that it’s versatile and can be adapted to whatever your situation may require.

How have you been organizing projects in GitHub? We’d love to hear about your experiences in the comments below!

Categories: Drupal CMS

Joanne Armitage on Feminist Algorave

Sun, 11/11/2018 - 07:30
In this episode, Matthew Tift talks with Dr. Joanne Armitage, a lecturer in digital media at the University of Leeds. Joanne performs regularly with ALGOBABEZ, the Orchestra For Females And Laptops (OFFAL), and other collaborators. She recently won the British Science Association’s Daphne Oram Award for Digital Innovation. In this episode, we discuss feminist algorave, her live coding workshops for women and non-binary people, narratives around failure, inclusion and diversity in technology communities, and more.
Categories: Drupal CMS

Usability Testing on a Tight Timeline

Thu, 10/18/2018 - 08:03

User-centered design systems that stand the test of time, require a level of research and testing to inform and validate ideas. As pressure to create leaner timelines mounts, how do we continue to deliver great work that requires our thoughtful due diligence―in particular, listening to user feedback?

Here are a few ways our design team has integrated testing into our design process without disrupting the overall project pace, while still receiving valuable feedback and instilling client confidence for a successful launch.

Conduct fewer tests, one is better than none

One way to incorporate usability testing into a tight timeline is to reduce the total number of tests per study. A study is a group of tests. Behind each study, there is a driving question for conducting the test (e.g. Will new students be able to register for new classes? Is the account creation process user-friendly?). It’s easy to think that we need a vast pool of tests in order to merit testing at all. This all-or-none mentality often leaves designers on tight timelines skipping the process altogether.

As a response to shorter project schedules, our design team has simplified our expectations around testing. Every individual user test has valuable feedback that can help improve the design. If one person that clearly matches our primary audience segment is having trouble with the search functionality, we take time to improve the design before spending time on a second test. And if a second test isn't a luxury we can afford, that single test held its value.

Jakob Nielson explains why you only need to test with five users per study in order to accurately reflect a large user base. He goes on to explain that as few as two users per study can still be valuable. We’ve found this rule to hold true. Even one test will likely improve the design process over skipping the testing experience altogether. If you can afford up to 5 tests, great! It’s likely that the bulk of your time will be spent getting set up for one test that will be replicated across users. Adding a handful more is sometimes not a big deal.

"For really low-overhead projects, it's often optimal to test as few as two users per study." - Jakob Nielsen, Ph.D.

Keep in mind that most of our usability tests at Lullabot are 30-minute video calls where we ask the user to complete a task, while we’re also gathering qualitative data. Nielson argues that qualitative interviews should be the majority of your testing style for highest quality feedback.

As we work to reduce the number of tests per study, we can reduce the total number of tests for the entire project. The success of this approach hinges on leveraging priority. Knowing when a test is needed is a call we make throughout the process as questions arise. Areas of the site that are designated as a higher priority during the initial design research process, naturally receive special attention. So go ahead, book fewer user tests and feel confident that you’re adding value, while also enjoying the time-saving benefits.

Iterate between individual tests

With each individual test, we learn a great deal and will likely have a key insight for design improvement. Consider iterating on the design immediately following each test. Once the design has improved, schedule another test if needed and repeat the process. By iterating between each test, we can focus on what was learned from each individual user, and truly take their feedback into consideration with a thoughtful improvement.

Another benefit of iterating between tests is that we’re able to create space in our day for continuing to produce design work. If we schedule multiple tests in one day, that day of productivity will be lost. Whereas scheduling one test in a day keeps the project momentum moving forward quickly without an interruption for usability testing.

Save time with sketch testing early in the process

Usability tests can be conducted with a variety of asset types. Examples of testable assets including: 

  • Paper sketch
  • Singular digital wireframe page or component
  • Digital wireframe prototype (no styles, multiple wireframes simulate interactivity or a multi-step experience)
  • High-fidelity digital prototype (styles added, simulates interactivity or a multi-step experience)
  • Singular high-fidelity page or component
  • HTML prototypes (wireframe or high-fidelity)
  • Existing sites
  • Navigational Tree

The best asset type for use in a test depends on the nature of the question you have. For example, testing the user-friendliness of a navigation interaction may prove ineffective with an asset as low fidelity as a paper sketch. Though testing the effectiveness of a headline or a certain order of content on the page would be great examples of ways to use paper sketches.

Leaning on paper sketches early helps to keep testing fast and light. The disposable nature encourages iteration and experimentation. There is an inclusive quality of paper, it invites participation from all levels of technical backgrounds. 

In addition to testing paper sketches, also consider tree testing as a way to quickly test things like navigation. No prototype, wireframe or design comp is needed to complete this test.

undefined Save time with boilerplate templates

Over the last few years, our design team has worked to compile templates and boilerplates for design processes wherever possible. When we need to conduct usability testing on a tight timeline, these starter documents can be especially helpful. For example, we have an email template ready to go for recruiting users and an interview script that reminds us to ask permission to record or remember to pull together highlights before closing the tab. These tools are simple, yet each little line item that we don’t have to reinvent adds up over the course of a project. We like to use Dropbox Paper Docs as a simple tool for text-based boilerplates. In fact, we use it for just about everything.

undefined Lean on scheduling tools that integrate with your calendar

Scheduling is a sneaky task that can easily add many hours to your usability testing timeline. Using email can quickly become a time leak, as cancellations and rescheduling become a manual process. Calendly is a tool we often use for scheduling. With a free account, you can add available times and simply send the link to choose a time to your users. You can even integrate Calendly with your Google Calendar so that the process is completely automated, all you need to do to is keep an eye on your calendar and show up to the interview. 

Other tools similar to Calendly undefined Ask for help from your client to recruit and schedule testers

Users are more likely to engage in a user test if they are being recruited by a friend or colleague. We have made it a habit to ask for help from clients in recruiting their users for testing. This helps users feel more comfortable being recruited by a familiar entity, and it allows our design team more time to focus on design work and creating the tests, rather than email correspondence. We provide the client with an email template that they can customize with their own voice, and a Calendly link to include in the email which will allow the user to schedule their own interview. 

Also, consider services like usertesting.com where you can gain access to a community that will participate in tests. This approach could potentially save a lot of time, especially if you can match people to your target audiences easily. There are many community testing sites where you can choose characteristics for the type of user you’d like to review the work. 

Summary

Go forth, book fewer tests, ask for help from your clients, lean on new design tools, test early with sketches and create time-saving boilerplates. Most importantly, continue creating thoughtful, research-informed design systems. 

Categories: Drupal CMS

Update on the Admin UI / JavaScript Modernization Initiative

Thu, 10/11/2018 - 11:46
Mike and Matt interview members of the Drupal 8 JavaScript modernization initiative to find out what's going on, and the current status.
Categories: Drupal CMS

Upcoming Changes to DrupalCons

Thu, 09/27/2018 - 12:00
Mike and Matt talk with the Drupal Association's Senior Events Manager, Amanda Gonser, about upcoming changes to DrupalCon events.
Categories: Drupal CMS

Drupal Europe, Not DrupalCon Europe

Thu, 09/06/2018 - 16:00
Mike and Matt are joined by Joe Shindelar from Drupalize.Me and Baddý Breidert one of the organizers of Drupal Europe, a huge conference that's being billed as "A family reunion for the Drupal community." Drupal Europe is put on by a huge group of community volunteers in collaboration with the German Drupal Association.
Categories: Drupal CMS

Behind the Screens with Matthew Saunders

Mon, 09/03/2018 - 00:00
Matthew Saunders, the Engineering Lead for various programs at Pfizer, talks about managing a distributed team of developers across the globe, his work with the Colorado Drupal Community, and theater!
Categories: Drupal CMS

Behind the Screens with Preston So

Mon, 08/27/2018 - 00:00
Acquia's Director of Research and Innovation, Preston So, dishes about delivering keynote presentations on diversity and inclusion, the state of decoupled Drupal, and the Travel Channels newest star.
Categories: Drupal CMS

Early Rendering: A Lesson in Debugging Drupal 8

Wed, 08/22/2018 - 17:55

I came across the following error the other day on a client's Drupal 8 website:

LogicException: The controller result claims to be providing relevant cache metadata, but leaked metadata was detected. Please ensure you are not rendering content too early.

Leaked? That sounded bad. Rendering content too early? I didn't know what that meant, but it also sounded bad. Worst of all, this was causing a PHP fatal error along with a 500 response code. Fortunately, I caught the error during development, so there was time to figure out exactly what was going on. In so doing, I learned some things that can deepen our understanding of Drupal’s cache API.

Down the rabbit hole

I knew that this error was being caused by our code. We were writing a custom RestResource plugin, which is supposed to fetch some data from the entity API and return that data, ready to be serialized and complete with cacheability metadata. This custom RestResource was the only route that would trigger the error, and it only started happening part way through development as the codebase grew complex. It had been working fine, until the error noted above, which I include here in full with a stack trace:

The website encountered an unexpected error. Please try again later. LogicException: The controller result claims to be providing relevant cache metadata, but leaked metadata was detected. Please ensure you are not rendering content too early. Returned object class: Drupal\rest\ResourceResponse. in Drupal\Core\EventSubscriber\EarlyRenderingControllerWrapperSubscriber->wrapControllerExecutionInRenderContext() (line 154 of core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php). Drupal\Core\EventSubscriber\EarlyRenderingControllerWrapperSubscriber->Drupal\Core\EventSubscriber\{closure}() (Line: 135) Symfony\Component\HttpKernel\HttpKernel->handleRaw(Object, 1) (Line: 57) Symfony\Component\HttpKernel\HttpKernel->handle(Object, 1, 1) (Line: 57) Drupal\Core\StackMiddleware\Session->handle(Object, 1, 1) (Line: 47) Drupal\Core\StackMiddleware\KernelPreHandle->handle(Object, 1, 1) (Line: 119) Drupal\cdn\StackMiddleware\DuplicateContentPreventionMiddleware->handle(Object, 1, 1) (Line: 47) Drupal\Core\StackMiddleware\ReverseProxyMiddleware->handle(Object, 1, 1) (Line: 50) Drupal\Core\StackMiddleware\NegotiationMiddleware->handle(Object, 1, 1) (Line: 23) Stack\StackedHttpKernel->handle(Object, 1, 1) (Line: 663) Drupal\Core\DrupalKernel->handle(Object) (Line: 19)

I was confused that our code didn't appear in the stack trace; this is all Drupal core code. We need to go deeper.

As I do when this kind of situation arises, I took to the debugger. I set a breakpoint at the place in core where the exception was being thrown looking for clues. Here were my immediate surroundings:

// ... elseif ($response instanceof AttachmentsInterface || $response instanceof CacheableResponseInterface || $response instanceof CacheableDependencyInterface) { throw new \LogicException(sprintf('The controller result claims to be providing relevant cache metadata, but leaked metadata was detected. Please ensure you are not rendering content too early. Returned object class: %s.', get_class($response))); } // ...

Foreign land. Knowing a smidgen about the Cache API in Drupal 8 and the context of what we were trying to do, I understood that we were ending up here in part because we were returning a response object that has cacheability metadata on it. That is, we were returning a ResourceResponse object that implements CacheableResponseInterface, including the relevant cacheability metadata with it. I could see from Xdebug that the $response variable in the snippet above corresponded to the ResourceResponse object we were returning, and it was packed with our data object and ready to be serialized. 

undefined

So as far as I knew, I was playing nice and adding cacheability metadata like a good Drupal developer should. What gives?

Seeing the forest for the trees

It was at this point I felt myself getting lost in the weeds. I needed to take a step back and reread the error message. When I did, I realized that I didn't understand what “early rendering” was.

I knew it had some connection to caching, so I started by reading through all the Cache API docs on drupal.org. I’ve read these several times in the past, but it’s just one of those topics, at least for me, that requires constant reinforcement. Another relevant doc I found was CachebleResponseInterface. These provided a good background and laid out some terminology for me, but nothing here talks about early rendering. I also reviewed the Render API docs but again, no mention of early rendering, and nothing getting me closer to a resolution.

So then I zoomed back in a little bit, to the parent class of the code which threw the error: \Drupal\Core\EventSubscriber\EarlyRenderingControllerWrapperSubscriber

As is often the case in Drupal 8 core code, there was an excellent and descriptive doc block for the class. I often find this to be key to understanding Drupal 8. Core committers take great care to document the code they write which makes it worth getting comfortable with reading through core and contrib code.

When controllers call drupal_render() (RendererInterface::render()) outside of a render context, we call that "early rendering." Controllers should return only render arrays, but we cannot prevent controllers from doing early rendering. The problem with early rendering is that the bubbleable metadata (cacheability & attachments) are lost.

At last a definition for early rendering! However, our code wasn't (at least directly) inside a controller, it never called drupal_render() that I could tell, and what in the world is a render context?

Nobody to blame

Still, in need of some context for understanding what was going on here, I looked at git blame to find out where the code that was throwing the error about early rendering came from. Ever since I started to do Drupal 8 development, I’ve always found it useful to use a clone of Drupal locally for such occasions. PHPStorm makes using git blame quite easy. In the file you’re interested in—opened in the editor—just right click the line numbers column and click Annotate. Once the annotations display, click the one that corresponds to the line that you’re interested in to see the commit message. 

undefined

Most, if not all, Drupal core commits will have an issue number in the description, in this case, here is what I found:

Issue #2450993 by Wim Leers, Fabianx, Crell, dawehner, effulgentsia: Rendered Cache Metadata created during the main controller request gets lost

Loading up the issue, I’m faced with a wall of text, 159 comments. Although I did eventually wade through it out of morbid curiosity, what I immediately do when faced with a giant closed core issue, is check for a change record. The Drupal 8 dev cycle has been really excellent about documenting changes, and change records have really helped in the transition from earlier Drupal 7 concepts and explaining new concepts in Drupal 8. For any core issue, first, take a look in the right sidebar of the issue for “Change records for this issue”, and follow any that are linked to get a birds-eye view of the change. If you haven’t already, it’s also handy to bookmark the Change records for Drupal core listing as it's a great place to look when you're stuck on something Drupal 8.

undefined

The change record was very helpful, so if you’re interested, I recommend you definitely give it a read. In short, early rendering used to be rampant (in core and contrib), and this was a problem because cacheability metadata was lost. The change introduced a way to wrap all controllers, detect early rendering, catch and merge the cacheability metadata into the controllers' return (usually a render array). That’s all well and good, but wait! You might think, "If it’s handling the cacheabillity metadata from early rendering, why is it still throwing an error!?" Well, going back to the snippet where the exception is thrown from earlier:

// ... elseif ($response instanceof AttachmentsInterface || $response instanceof CacheableResponseInterface || $response instanceof CacheableDependencyInterface) { throw new \LogicException(sprintf('The controller result claims to be providing relevant cache metadata, but leaked metadata was detected. Please ensure you are not rendering content too early. Returned object class: %s.', get_class($response))); } // ...

What this boils down to is if your controller is returning a response object of type, AttachementsInterfaceCacheableResponseInterface, or CacheableDependencyInterface, Drupal does not give you a pass, nor does it handle cacheability metadata from early rendering for you. Drupal takes the position that since you are returning this type of response, you should also be responsible, be aware of and handle early rendering yourself. From the change log:

Since you're returning responses, you want to fully control what is sent, so you should also be a responsible citizen and not do any early rendering. I solemnly swear not to early render

Ok, so no early rendering, got it. But, what if it’s out of our control? In our case, the code we were working in didn't have any direct calls to drupal_render() (RendererInterface::render()). My next tactic was to understand more about what was triggering early rendering. 

To do this, I set a breakpoint in the sole implementation of RendererInterface::render() and then hit the REST endpoint that was triggering the error. Xdebug immediately broke at that line, and inspecting the stack trace, we saw some of our code! Proof that we broke it! Progress. 

undefined

As it turns out, some code in another custom module was being called. This code is meant to wrap entity queries, massaging the return data into something more palpable and concise for the development team that wrote it. Deep in this code, in processing node entities, it was including a call to $node→url(), where $node is a \Drupal\node\Entity\Node object. Turns out, that triggers early rendering. To this, you might ask, "Why would something as innocuous as getting the URL for a node trigger early rendering?" The answer, and I’m only 80% sure after studying this for a while (do correct me if I’m wrong), is that URLs can vary by context based on language or the site URL. They can also have dependencies, such as the language configuration. Finally, URLs can have CSRF tokens embedded in them, which vary by session. All of which is important cacheability metadata that you want to be included in the response. OK, so what’s a responsible Drupal developer to do?

The complete (and verbose) solution, courtesy of ohthehugemanatee (indeed), is to replace your $node→url() call with something like:

// 1. Confusing: the method is called toString, yet passing TRUE for the first param nets you a \Drupal\Core\GeneratedUrl object. $url = $node->toUrl()->toString(TRUE); // 2. The generated URL string, as before. $url_string = $url->getGeneratedUrl(); // Add the $url object as a dependency of whatever you're returning. Maybe a response? $response = new CacheableResponse($url_string, Response::HTTP_OK); $response->addCacheableDependency($url); return $response;

That’s a lot, and it’ll be different depending on what you're doing. It’s broken down into 3 parts. First, you want to call $node->toUrl()->toString(TRUE);. This will essentially tell Drupal to track any cacheability metadata, which is part of generating the URL, and return an object from which you can get that cacheability metadata so you can deal with it. The second part is just getting the actual URL string, $url_string = $url->getGeneratedUrl();, to do with as you please. Finally, you need to account for any encountered cacheability metadata. In the context of a response as above, that means adding the $url object as a cacheable dependency. In the context of a render array, it might mean merging the $url cacheability metadata into the render array. (eg. CacheableMetadata::createFromObject($url)→applyTo($render_array))

Wrap it up

OK so now I understood where the exception was coming from and why. I also understand how I might change the code that is triggering an early rendering. But as I mentioned before, what if you don’t control the code that is triggering an early rendering? Is all hope lost? Not quite. What you can do is wrap the code triggering the early render in a render context. Let’s look at some code:

$context = new RenderContext(); /* @var \Drupal\Core\Cache\CacheableDependencyInterface $result */ $result = \Drupal::service('renderer')->executeInRenderContext($context, function() { // do_things() triggers the code that we don't don't control that in turn triggers early rendering. return do_things(); }); // Handle any bubbled cacheability metadata. if (!$context->isEmpty()) { $bubbleable_metadata = $context->pop(); BubbleableMetadata::createFromObject($result) ->merge($bubbleable_metadata); }

Let’s break this down:

$context = new RenderContext();

Here, I instantiate a new render context. A render context is a stack containing bubbleable rendering metadata. It’s a mechanism for collecting cacheability metadata recursively, aggregating or “bubbling” it all up. By creating and passing it in the next line, the render context is able to capture what would have otherwise been lost cacheability metadata.

/* @var \Drupal\Core\Cache\CacheableDependencyInterface $result */ $result = \Drupal::service('renderer')->executeInRenderContext($context, function() { // do_things() triggers the code that we don't don't control that in turn triggers early rendering. return do_things(); });

Here I run some arbitrary code within the render context I created. The arbitrary code, somewhere along its execution path that we have no control over, triggers early rendering. When that early rendering occurs, since I’m wrapping the code in a render context, the cacheability metadata will bubble up to the render context I setup and allow me to do something with it.

// Handle any bubbled cacheability metadata. if (!$context->isEmpty()) { $bubbleable_metadata = $context->pop(); BubbleableMetadata::createFromObject($result) ->merge($bubbleable_metadata); }

Now I check if the context is non-empty. In other words, did it catch some cacheability metadata from something that did early rendering? If it did, I get the captured cacheability metadata with $context→pop() and merge it with my \Drupal\Core\Cache\CacheableDependencyInterface object which will be returned. BubbleableMetadata is a helper class for dealing with cacheability metadata. This merge part may look different depending on your context, but the idea is to incorporate it into the response somehow. Take a look at the static methods in \Drupal\Core\Render\BubbleableMetadata  and its parent class for\Drupal\Core\Cache\CacheableMetadata some helpers to merge your cacheability metadata.

Really wrapping up

That was a heavy, long, complex debug session. I learned a lot digging into it and I hope you did as well. Let me know in the comments if you’ve ever run into something similar and came to a resolution in a different way. I’d love to continue furthering my understanding.

While it was great to figure this out, I was left wanting a better DX. In particular, improving the fact that Drupal auto-magically handles early rendering in some cases, but not others. There is also the odd workaround to capture cacheability metadata when cacheability metadata when calling $node→url() that could use some work. A quick search on the issue queue told me I wasn’t alone. Hopefully, with time and consideration, this can be made better. Certainly, there are good reasons for the complexity, but it would be great to balance that against the DX to avoid more epic debug sessions.

Acknowledgements
Categories: Drupal CMS

GatsbyJS with Creator Kyle Mathews

Thu, 08/16/2018 - 08:56
Mike and Matt are joined by Lullabot John Hannah to talk with the creator of GatsbyJS
Categories: Drupal CMS