Author

May 06 2019
May 06

Using UI pattern libraries in Storybook allow us to build a collection of front end UI components that can be used to build bigger components, even full web pages. However, frontend/backend integrations can be fraught with difficulties. In this piece, I’ll explain our process to make these challenges easy, even when using GraphQL fragments inside Twig templates.

What Drupal and GraphQL do well

At Amazee Labs, we build decoupled web applications using GraphQL and Drupal. We’ll touch on the reasons that we use this approach in this article, but if you’d like to know more, check out these blogs:

Drupal is known for its complex and unwieldy theming and rendering system. Data to be rendered comes from across the system in the form of templates, overrides, preprocess functions and contributed modules such as Panels and Display Suite. Sometimes trying to track down where data is being generated or altered is like a murder mystery. 

Thankfully, GraphQL Twig simplifies the situation massively. Each template has an associated GraphQL query fragment that requests the necessary data. This “pull” model (as opposed to Drupal’s normal “push” model) means that finding where the data comes from and how it is structured is really easy. We don’t need to worry about preprocessing or alteration of data, and this method lets us keep the concerns separated.

Advantages of UI component libraries

The main advantage of using a UI component library (also known as a pattern library) is that it facilitates the reusability of components. This means that when a component is created it can be used by any developer on the project to build their parts of the front end and in turn can be used to make larger and more complex components.

There are multiple extra advantages to this, the most obvious being the speed of development. Since all components are simply made up of smaller components, building new ones is usually much quicker, since we don’t need to reinvent the wheel.

This also makes maintenance a breeze, since we’re only maintaining one version of any component. If we decide that all buttons on the frontend need to have an icon next to the text, we simply change the button component and this change will apply everywhere that the component is used.

Finally, the reusability of components in a pattern library means that the UI is consistent. Often, web projects face difficulties where there are multiple versions of various components, each with their own implementation. This is especially true of larger projects built by multiple people, or even multiple teams, where no single person knows the entirety of the project’s implementation details. Thanks to the reusability of our components, we only have one implementation per component.

Challenges of using Drupal, GraphQL, and Storybook together

If done poorly, using pattern libraries like Storybook can be difficult and cause problems during the integration phase(s) of development. The main issue is usually that the frontend and backend developers have different approaches and different goals when developing. 

The frontend developer wants to create the best UI they can in the most efficient way possible, using the paradigms and approaches that are standard or preferred. Unfortunately, at times the implementation doesn’t sync well with the data structure that the backend developers receive from Drupal, so the frontend needs to be refactored or the data structure needs to somehow be altered.

How to make it work

I won’t go into detail on our implementation of the Storybook library, but we keep Storybook in the same repo as our Drupal application, outside the root. We then define a base storybook theme and using the Components module (built by my talented colleague John Albin), we define our path to the Storybook Twig templates as a component library in our .info.yml file. This way, the Drupal theme has access to all of our templates.
 

component-libraries:
  storybook:
    paths:
      - ../../../../storybook/twig

We then create our project-specific theme, which extends the base Storybook theme, and start to work on our integration. A generic page.html.twig file might look like this:
 

{#graphql
query {
  ...Header
  ...Footer
}
#}
{% extends '@storybook/page/page.html.twig' %}

{% block header %}
  {% include '@storybook/navigation/header.html.twig' with graphql only %}
{% endblock %}

{% block content %}
  {{ page.content }}
{% endblock %}

{% block footer %}
  {% include '@storybook/footer/footer.html.twig' with graphql only %}
{% endblock %}


So, how does GraphQL tie in here? Well, this is the really clever part. Our developers can create the GraphQL snippets to get the data needed for a specific component, and Storybook allows us to use JavaScript to use this data as mock fixtures. This means that the frontend can be built with realistically structured data, so no refactoring of templates or data alteration on the backend is needed. And since we already have the GraphQL snippet, this automatically works when run in Drupal. 

Conclusion

At Amazee, we use a UI component library because it makes sense to build a maintainable, reusable and consistent set of components for our frontend that also encourages faster development. We also try our best to streamline our integration processes so that all of our developers are more closely aligned and developing solutions that make it easier for their colleagues to use, learn and extend easily. 

Storybook gives us the power to build a component library using mock data that is structured in the exact manner that our GraphQL queries deliver it. This means no refactoring, building both queries and templates only once and an overall smooth integration process. 

Want to know more about using GraphQL and Twig? Check out our webinar
 

May 06 2019
May 06

Using UI pattern libraries in Storybook allow us to build a collection of front end UI components that can be used to build bigger components, even full web pages. However, frontend/backend integrations can be fraught with difficulties. In this piece, I’ll explain our process to make these challenges easy, even when using GraphQL fragments inside Twig templates.

What Drupal and GraphQL do well

At Amazee Labs, we build decoupled web applications using GraphQL and Drupal. We’ll touch on the reasons that we use this approach in this article, but if you’d like to know more, check out these blogs:

Drupal is known for its complex and unwieldy theming and rendering system. Data to be rendered comes from across the system in the form of templates, overrides, preprocess functions and contributed modules such as Panels and Display Suite. Sometimes trying to track down where data is being generated or altered is like a murder mystery. 

Thankfully, GraphQL Twig simplifies the situation massively. Each template has an associated GraphQL query fragment that requests the necessary data. This “pull” model (as opposed to Drupal’s normal “push” model) means that finding where the data comes from and how it is structured is really easy. We don’t need to worry about preprocessing or alteration of data, and this method lets us keep the concerns separated.

Advantages of UI component libraries

The main advantage of using a UI component library (also known as a pattern library) is that it facilitates the reusability of components. This means that when a component is created it can be used by any developer on the project to build their parts of the front end and in turn can be used to make larger and more complex components.

There are multiple extra advantages to this, the most obvious being the speed of development. Since all components are simply made up of smaller components, building new ones is usually much quicker, since we don’t need to reinvent the wheel.

This also makes maintenance a breeze, since we’re only maintaining one version of any component. If we decide that all buttons on the frontend need to have an icon next to the text, we simply change the button component and this change will apply everywhere that the component is used.

Finally, the reusability of components in a pattern library means that the UI is consistent. Often, web projects face difficulties where there are multiple versions of various components, each with their own implementation. This is especially true of larger projects built by multiple people, or even multiple teams, where no single person knows the entirety of the project’s implementation details. Thanks to the reusability of our components, we only have one implementation per component.

Challenges of using Drupal, GraphQL,
and Storybook together

If done poorly, using pattern libraries like Storybook can be difficult and cause problems during the integration phase(s) of development. The main issue is usually that the frontend and backend developers have different approaches and different goals when developing. 

The frontend developer wants to create the best UI they can in the most efficient way possible, using the paradigms and approaches that are standard or preferred. Unfortunately, at times the implementation doesn’t sync well with the data structure that the backend developers receive from Drupal, so the frontend needs to be refactored or the data structure needs to somehow be altered.

How to make it work

I won’t go into detail on our implementation of the Storybook library, but we keep Storybook in the same repo as our Drupal application, outside the root. We then define a base storybook theme and using the Components module (built by my talented colleague John Albin), we define our path to the Storybook Twig templates as a component library in our .info.yml file. This way, the Drupal theme has access to all of our templates.
 

component-libraries:
  storybook:
    paths:
      - ../../../../storybook/twig

We then create our project-specific theme, which extends the base Storybook theme, and start to work on our integration. A generic page.html.twig file might look like this:
 

{#graphql
query {
  ...Header
  ...Footer
}
#}
{% extends '@storybook/page/page.html.twig' %}

{% block header %}
  {% include '@storybook/navigation/header.html.twig' with graphql only %}
{% endblock %}

{% block content %}
  {{ page.content }}
{% endblock %}

{% block footer %}
  {% include '@storybook/footer/footer.html.twig' with graphql only %}
{% endblock %}


So, how does GraphQL tie in here? Well, this is the really clever part. Our developers can create the GraphQL snippets to get the data needed for a specific component, and Storybook allows us to use JavaScript to use this data as mock fixtures. This means that the frontend can be built with realistically structured data, so no refactoring of templates or data alteration on the backend is needed. And since we already have the GraphQL snippet, this automatically works when run in Drupal. 

Conclusion

At Amazee, we use a UI component library because it makes sense to build a maintainable, reusable and consistent set of components for our frontend that also encourages faster development. We also try our best to streamline our integration processes so that all of our developers are more closely aligned and developing solutions that make it easier for their colleagues to use, learn and extend easily. 

Storybook gives us the power to build a component library using mock data that is structured in the exact manner that our GraphQL queries deliver it. This means no refactoring, building both queries and templates only once and an overall smooth integration process. 

Want to know more about using GraphQL and Twig? Check out our webinar

Feb 26 2019
Feb 26

With the announcement of Drupal 9 we want to talk about how this affects our customers, what to expect when new versions come out and to let you know what we do at Amazee Labs to ensure the transition will be painless.

“The big deal about Drupal 9 is … that it should not be a big deal.”

- Dries Buytaert, Drupal Founder
 

Background

The changes to Drupal between versions 7 and 8 were, quite frankly, enormous. Drupal previously had a justified reputation for doing its own thing and ignoring burgeoning standards and practices utilised elsewhere in the PHP community. So, when Drupal 8 was announced, one of the main goals of the release was to get off the Drupal island and start to utilise some of the millions of lines of open source code and documentation available elsewhere.

There were many great sides to this upgrade. The code was being built on a more solid and tested foundation, principally being based on the Symfony framework and leveraging numerous other systems and libraries. This helped Drupal become more enterprise focussed whilst opening the development field to engineers of other systems who were already familiar with the standards and practices now utilised in Drupal.

Unfortunately, the major technical upgrade to Drupal also introduced some headaches. Migrating between Drupal 7 and Drupal 8 can be time consuming and expensive. As a result of this, businesses who undertook such a migration can be forgiven for worrying about Drupal 9 being released just 5 years after Drupal 8. Some clients have expressed concern about using Drupal 8 when another expensive upgrade seems to be just around the corner.

Why Drupal 9 is different

In short, if you keep your Drupal 8 website up-to-date, there will be no major upgrade worries. The core maintainers of Drupal want to make Drupal upgrades easy forever from now on. The Drupal team has a plan to ensure that Drupal 9 will essentially be a minor process. This is possible because Drupal 9 will be built in the same manner as Drupal 8, with the same practices and core libraries. Unlike Drupal 7 to Drupal 8, there will be no major architectural or structural changes to the codebase. 

The main changes, other than bug fixes, improvements and new features will be the upgrades to Drupal’s core libraries. For example, Symfony 3 (the library upon which Drupal is built) comes to its end-of-life in 2021, so it makes sense to have Drupal 9 running on Symfony 4 at that point.

End of support flow chart

How is this easy upgrade achievable? Well, the Drupal team will continue its 6-month release cycle until Drupal 9 is released. In these releases, the code will be deprecated and upgraded to bring it closer to the components and libraries that will be used by Drupal 9, ensuring that when the time does come to upgrade everything will be in place for an easy transition.

Maintenance is key 

Keeping up with new releases and updates ensures that your website stays relevant and secure, and also means that switching from Drupal 8 to 9 will be much more routine. By partnering with us even after your website is created, we can take proactive steps such as making sure there’s no deprecated code in your site before the newest release.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web