Author

May 14 2018
May 14

In this series we take a closer look at progressive decoupling in Drupal 8. We go through the project setup, check the tools and libraries and discuss potential applications. The first post of the series showed some new features that made it into JavaScript in the last few years. This time let’s see how to use it in a project.

JavaScript transpilation has been added to Drupal core in 8.4.0. The Core JS contribution workflow has been described in the change record Drupal core now using ES6 for JavaScript development. Unfortunately, the scripts mentioned there cannot be used to transpile contrib code yet. There’s an ongoing discussion about that in Use ES6 for contrib and custom JavaScript development. So we need to wait for that to be solved, right?

Not really. It turns out that it is enough to place the package.json file from core/ two levels up in the directory tree (in case of a composer project) and adjust paths to scripts to enjoy modern JS in contrib and custom code. With this file in the repository root we can run

to install dependencies, and we’re good to go with ES6.

will start the watcher, which monitors all .es6.js files and transpiles them to their .js counterparts whenever a change is detected.

The scripts can be invoked in one of 4 ways

To commit or not to commit?

Is it fine to commit the output (.js) files? That depends on the nature of the code. If it’s a contrib module / theme it’s best to do so. Target users shouldn’t be forced to transpile themselves and the build process of Drupal modules is not adjustable at the time off writing this post.

Source maps

Contrib modules would most likely provide just the optimized code (without source maps). The committed source .es6.js files can be used to overwrite the output files with dev features enabled for individual environments if needed.

Custom code

The choice here depends on the hosting platform. If it supports adjusting the build process based on the environment, then the .js files don’t have to be committed at all. The source files are enough and the compilation can be done before each deployment. Source maps can be used for dev and prod should get the optimized build. This is how it looks like in an .amazee.io.yml file for instance:

As with every artifact, ruling out the compiled versions of js files from the repository makes the development process smoother, mainly by reducing conflicts. On the other hand, it doesn’t have to be a big problem if the team is small enough.

Example

Here’s a recipe for adding an example ES6 library to a theme.

  1. Add this package.json file the root of your project
  2. Install dependencies
  3. Start the file watcher
  4. Add a library definition to package_name.libraries.yml in your module or theme.
  5. Create the index file (js/mylib/index.es6.js)
  6. Save the file and check the terminal window with the file watcher, js/mylib/index.es6.js should be mentioned there and the compiled version - index.js - should be created next to the source file. The library is now ready to be used in a module or theme.

That’s it for setting up ES6 in a project. In the next post we’ll take a look at polyfills, talk about the fetch API and a see how to use async functions - the undeniable game changer from ES8.

If you want to learn more about Drupal libraries check these out

May 08 2018
May 08

In this series we’ll take a closer look at progressive decoupling in Drupal 8. We’ll go through the project setup, check the tools and libraries and discuss potential applications. Let’s start with the definition.

Progressive decoupling

Decoupled Drupal is a thing for quite a while now. There seem to be two ways of doing it. We either let the Javascript take control and use Drupal only as a data store (fully decoupled) or let Drupal do the heavy lifting and use the front end frameworks to render discrete parts of the site (progressive decoupling). The first option seems to be much more popular now, even despite the fact that it’s expensive and forces us to re-implement a lot of things that Drupal does well. Why is that?

I think there are two main reasons. Firstly, and this is a huge pain point, there is no out-of-the-box way to use modern Javascript in Drupal contrib and custom code. Whoever wrote a line of ES6 never wants to go back to the stone-age JS that is understood by IE. Luckily, this is something we can fix and, in this and the next posts, we’ll see how to do that.

Another question, which arises quickly after solving the problem above, is how to import packages from npm. JavaScript projects usually have a package.json file containing all the dependencies and importing them in the code is as easy as calling the require function. We don’t have such a central place to declare JS dependencies in Drupal projects. In the later posts, we’ll see how this can be worked around right now and, hopefully, try to define the shape of the ideal solution for the future. But now let’s get back to the language.

Modern JavaScript

Regardless of which front-end framework we choose, we’re going to need the ability to write our code in modern JavaScript. It’s been a while since ES6 (or ES2015) was released. There was ES7 (2016) and ES8 (2017), each adding new features. These new functions decrease the WTF/h rate when developing and, arguably, can even make the language likeable, which was rather unimaginable a decade ago. Let’s go through some of the most interesting ones.

Deconstructing assignment

Reduces the redundancy when getting values from arrays and objects.

Property shorthand

Reduces redundancy when composing objects out of variables.

Spread syntax

Makes it possible to compose objects out of other objects.

Arrow functions

Make function definitions more compact.

It’s especially useful for higher order functions. A click handler, for instance, can be created like this.

Default parameter values

Classes

Object Oriented Programming is much more intuitive now.

Example from http://es6-features.org

Template literals

These friendly creatures make it possible to insert variables into strings.

We’ve defined what we mean by decoupling Drupal and have shown some of the cool new features available in EcmaScript 6 and above (for a comprehensive comparison see http://es6-features.org/). All these functions have something in common, namely none of them are supported by our beloved IE. In the next post we’ll see how to overcome that and use modern JavaScript in our modules and themes.

Jan 29 2018
Jan 29

GraphQL is becoming more and more popular every day. Now that we have a beta release of the GraphQL module (mainly sponsored and developed by Amazee Labs) it's easy to turn Drupal into a first-class GraphQL server. In this series, we'll try to provide an overview of its features and see how they translate to Drupal.

In the last post we talked about the basic building blocks of every GraphQL query - the fields. We've discussed their types and traits as well as described the rules according to which Drupal fields turn into GraphQL fields. This week we were going to expand the topic further and cover field creation, but Daniel Noyola asked an interesting question in the comment below one of the recent articles:

How can I filter the results in a nodeQuery? Like I would in a normal View or with the "where" clause in a SQL Statement. I noticed that it receives a NodeQueryFilterInput but I don't see how to use it.

Fetching entities based on a filter or a set of filters is a common use case, so let's focus on that first.

TL;DR

There are two ways to query the entity repository. First one would be through the entityQuery fields which are shipped with the core module but are limited in functionality. They only allow us to filter by base fields and there's no way to use an operator other than equals to. The other approach is much more powerful, as it's based on Views. It requires an additional module - graphql_views - to be installed though. Let's start with the built-in way.

The nodeQuery

Each entity type in the system gets its own query field. Let's see in the explorer how it looks like for nodes:

The nodeQuery signature

So it's a field (blue) with 3 arguments: offset, limit and filter (purple) which returns a value of type EntityQueryResult (all types are in yellow).

The first two arguments, offset and limit, are for paging and they work the same way as in SQL. Both are integers and both have default values of 0 and 10 respectively (green). Arguments that have default values can be omitted. We'll use this feature in a while.

The last argument - filter - is of a complex type NodeQueryFilterInput. Let's click it:

NodeQueryFilterInput fields

So it comprises all the base fields of the entity type that is being queried. It's not enough to issue arbitrary queries but it will suffice for a simple use case. This is how we could fetch a list of articles created by a given user:

We haven't specified the offset nor the limit, so they'll get their default values. It means that the output will contain at most 10 results, starting from the result number 0.

That's cool, but what if we wanted to order the articles by node id (nid) to only show the latest articles? Or filter by tags? Or fetch the title text of an image that is attached to a media entity that is connected with the first event that starts after the article's release date?

Use The Views

The answer is: we can do it like we'd normally do it in Drupal - with a view. Views integration has been moved to a separate project, so it has to be downloaded with composer (composer require drupal/graphql_views), from drupal.org or from github.

With graphql_views enabled we can add a GraphQL display to any view in the system.

Adding GraphQL display to a view

Now we can sort the results, filter based on content fields and add relationships. We also have the option to return either the full entities, just a selection of fields, or even search results taken straight from a search server.

Row type options for userArticles view

Contextual filters set in the view will automatically turn into the arguments of the GraphQL field. Let's see an example:

userArticles field signature

This field represents a simple view showing nodes. It has one contextual filter - Content: Authored by - so the corresponding input type consists of just one field:

contextualFilter type

and its row type is set to Entity (as pictured on the screenshot above), so the result will be of type NodeArticle:

userArticles result type

We can use the filed like this:

Views integration is a pretty broad topic, so in the next post we might try to cover it in more detail. There are quite a few more interesting aspects like sorting, exposed filters, and attaching views to entities, so we'll focus on that in an attempt to fully answer Daniel's question. For those interested in the back-end side of things I'd recommend the great Extending GraphQL series by Philipp Melab. The first post that explains how to create fields is here: Extending GraphQL: Part 1 - Fields.

P.S. GraphQL Views is not stable yet. In fact, two issues were spotted and fixed in the process of writing this article. If you spot a bug please report it on github  or let us know in the #graphql channel at Drupal slack.

Other posts in the series

Dec 04 2017
Dec 04

GraphQL is becoming more and more popular every day. Now that we have a beta release of the GraphQL module (mainly sponsored and developed by Amazee Labs) it's easy to turn Drupal into a first-class GraphQL server. In this series, we'll try to provide an overview of its features and see how they translate to Drupal.

In the last post we covered the basic building blocks of GraphQL queries. We started with the naming conventions, then we took a look at how and when to use fragments. Finally, we moved on to aliases, which can be used to change names of the fields as well as to use the same field more than once in the same block. This week we'll delve into the ambiguous concept of Fields.

What exactly are GraphQL fields?

Fields are the most important of any GraphQL query. In the following query nodeById, title, entityOwner, and name are all fields.

Types

Each GraphQL field needs to have a type that is stored in the schema. This means that it has to be known up front and cannot be dynamic. At the highest level, there are two types of values a field can return: a scalar and an object.

Scalars

Scalar fields are leafs of any GraphQL query. They have no subfields and they return a concrete value, title and name in the above query are scalars. There are a few core scalar types in GraphQL, e.g.:

  • ​String: A UTF‐8 character sequence.
  • Int: A signed 32‐bit integer.
  • Float: A signed double-precision floating-point value.
  • Boolean: true or false.

If you're interested in how Drupal typed data is mapped to GraphQL scalars check out the the graphql_core.type_map service parameter and graphql_core.type_mapper service.

Complex types

Objects, like nodeById and entityOwner in the query above, are collections of fields. Each field that is not a scalar has to have at least one sub-field specified. The list of available sub-fields is defined by the object's type. If we paste the query above into graphiQL (/graphql/explorer), we'll see that the entityOwner field is of type User and name is one of User's subfields (of type String).

Arguments

Fields can also have arguments. Each argument has a name and a type. In the example above nodeById field takes two arguments: id (String) and langcode. The same field can be requested more than once with a different set of arguments by using aliases, as we've seen in the last post.

How do Drupal fields become GraphQL fields?

One of the great new traits of Drupal 8 core is the typed data system. In fact, this is the feature that makes it possible for GraphQL to expose Drupal structures in a generic way. For the sake of improving the developer experience, especially the experience of the developers of decoupled frontends, Drupal fields have been divided into two groups.

Multi-property fields

The first group comprises all the field types that have more than one property. These fields are objects with all their properties as sub-fields.

This is how we'd retrieve values of a formatted text field (body) and a link field. Date fields and entity references also fall into this category. The latter have some unique features so let's check them out.

Entity reference fields

This type of field has 2 properties: the scalar target_id and the computed entity. This special property inherits its type from the entity that the field is pointing to. Actually, we've already seen that in the named fragments example in the last post, where fieldTags and fieldCategory were both term reference fields. Let's bring a simplified example.

Since fieldCategory links to terms, its entity property is of type TaxonomyTerm. We can go further.

The entityOwner property is of type User, so we get their email. Apparently, we can go as deep as the entity graph is. The following query is perfectly valid too.

It retrieves the title of an article that is related to the article that is related to the article with node id one and this is where GraphQL really shines. The query is relatively simple to read, it returns a simple-to-parse response and does it all in one request. Isn't it just beautiful? :)

Single-property fields

The second group comprises all the field types that have exactly one property (usually called value), like core plain text fields, email, phone, booleans and numbers. There's been a discussion about whether such fields should be rolled up to scalars or remain single-property objects. The former option won and in 3.x members of this group have no sub-fields.

That's it for the fields. Next week we're going to talk about... fields again :) but this time we'll see how to create one.

Nov 23 2017
Nov 23

GraphQL is becoming more popular every day. Now that we have a beta release of the GraphQL module (mainly sponsored and developed by Amazee Labs) it's easy to turn Drupal into a first-class GraphQL server. In this second post of the series, we'll describe they way Drupal fields are represented in GraphQL and look at a few examples.

Last week we talked about the new structure of the GraphQL package. We have also looked at the tools bundled with the module - the explorer and the voyager - and we've explored how to fetch a username. Now let's use GraphiQL to assemble queries that are a bit more complex.

The Naming

GraphQL naming conventions are slightly different than Drupal's.

  • Fields and properties are in camelCase. This means that field_image in Drupal becomes fieldImage in GraphQL and the revision_log property becomes revisionLog.
  • Entity types and bundles use camelCase with the first letter capitalized so taxonomy_term becomes TaxonomyTerm and the tags vocabulary becomes TaxonomyTermTags. As we can see bundles are prefixed with the entity type name.

The structures

While fields and properties both translate to the same GraphQL structure called Field, entity types and bundles, despite sharing the naming convention, don't. The former is implemented as GraphQL Interfaces and the latter are GraphQL Types (implementing these Interfaces). As an example: 

This query contains fields from 3 different GraphQL structures that build upon one another.

  • entityId and entityCreated come from the Entity Interface. These fields are available for all entity objects. nodeById query returns a Node Interface which extends Entity Interface.
  • title and status are defined in the Node Interface and are available for all nodes, regardless of their content type.
  • fieldSubtitle is a field (field_subtitle in Drupal) that has been added to the Article content type. It's not a part of neither Node nor Entity Interfaces, it is only available in the NodeArticle Type. nodebyId can return any node, not just Article, so we need to wrap the fieldSubtitle in a GraphQL Fragment.

If we paste the query into GraphiQL (/graphql/explorer) we'll get a result similar to this one:

The Fragments

GraphQL Fragments, as the name implies, are just pieces of a query. They mostly serve two purposes:

  1. Executing part of a query conditionally - only when the result is of a specified type. In the example above fieldSubtitle will be evaluated only when the node with id 1 is an Article. If it turns out to be a Basic Page, the fragment will be omitted and the response will just be one field shorter without raising any exceptions.
  2. Reusability. A fragment can be given a name and be used more than once.

There are two fragments in this query. The first one starting on line 3 is an inline fragment. We need it because fieldCategory and fieldTags are only attached to Articles and nodeById can return any node.

The other one, defined on line 18, is a named fragment thanks to which we don't need to repeat the sub-queries for fieldCategory and fieldTags.

This is how the result could look like. Node 1 is an Article, it has 2 tags in one category term.

The Aliases

There might be situations when we want to use the same field more than once in a single query, to fetch node 1 and 2 simultaneously for instance. We can do that thanks to GraphQL Aliases

Here we're calling nodeById twice, each time with different arguments and aliases. The former will appear under nodeOne key in the result and the latter will be available under nodeTwo. We've also transformed the inline fragment holding the article fields into a named fragment and used it in both queries to reduce unnecessary repetition.

That's it for this post. In the next one, we'll see how to retrieve the values of Drupal fields and properties.

Nov 09 2017
Nov 09

GraphQL is becoming more and more popular every day. Now that we have a beta release of the GraphQL module (mainly sponsored and developed by Amazee Labs) it's easy to turn Drupal into a first-class GraphQL server. This is the new GraphQL series in which we'll describe the features that are new in beta and provide a detailed overview of the integration with Drupal's entity and field systems.

This is the new GraphQL series about the new features that are in beta (published 2 weeks ago) and how they are connected with Drupal out of the box

The modules

Let's start with the modules we need. Recently there were quite a few changes in this field. In alpha we had:

  • graphql - The main module laying the foundations for exposing data using Drupal plugins.
  • graphql_core - which exposed Drupal core data - the info about entity types and bundles, but not fields
  • graphql_content - which handled field exposition with the view modes
  • other auxiliary modules (e.g., graphql_boolean graphql_entity_reference) that provided behaviours for specific field types

In beta, the structure has changed. Now the default schema exposes all the Drupal fields and (content) entities in raw form, using the typed data. Thanks to that GraphQL became a zero-configuration plug and play module. We just need to enable graphql and graphql_core (the only two modules that are shipped with the package now) and we're good to go.

NOTE: The other modules are still available in case you need them, they're just not part of the core package anymore. graphql_legacy is where most of the field modules went. Besides that, there are graphql_views  which lets us expose views, the promising graphql_twig that allows using GraphQL queries without a decoupled setup and a few more. All of the modules are listed in the drupal-graphql organization page on GitHub.

The Explorer

After enabling graphql and graphql_core we can go ahead and test it with GraphiQL; an interactive tool that lets you run queries, see results in real time and preview all the available fields along with arguments and return types. It also provides query validation, autocompletes suggestions and keyboard shortcuts. Thus, it's a kind of an IDE. The explorer is connected with the schema. We can find it next to the Default Schema under: Configuration -> Web services -> GraphQL -> Schemas or using the direct path - graphql/explorer.

GraphiQL initial screen.

This is how it looks. On the left, there is a query box with a comment describing the tool and listing the keyboard shortcuts. Results show up in the box on the right. To run the query we can use the «play» button at the top, or the keyboard shortcut (Ctrl-Enter). One more important piece is the < Docs button in the upper right corner. This is where we can see all the available elements. Let's go ahead and click it.

Root query in document explorer

The only thing we can start with is the query field which is of type RootQuery. Clicking on the type shows a list of available sub-fields, including userById, which looks like this:

userById field signature

This field takes two arguments: an id (which is a string) and a language (which can be set to any language enabled on the site) and is of type User. Clicking on the type brings up a list of fields on a user. The name is a string:

Document explorer user name

Strings are scalars (which means they don't have subfields) so we can finish our simple query here. It will look like this:

and (after running it with Ctrl-enter) the response is what we'd expect

The GraphQL explorer (or GraphiQL) gives us the ability to easily write and debug every GraphQL query. That's a feature that's hard to overestimate so getting familiar with it is a good starting point to understanding how GraphQL works in general and how we can get our Drupal data out of it.

The Voyager

Voyager is another schema introspection tool, a visual one this time. It draws a chart of all the types and field in the system and presents it in a nice way. It can be found next to The Explorer under: Configuration -> Web services -> GraphQL -> Schemas or using the direct path - graphql/voyager.

Tags field in GraphQL Voyager

That's it for this post. In the next one, we'll see some examples of retrieving data from Drupal fields.

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