Development

A Docksal Training -- ON DEMAND!

jflynn — Sat, 19 Dec 2020 00:49:45 +0000

A Docksal Training -- ON DEMAND! jflynn Fri, 12/18/2020 - 18:49

It has been quite a while since I last posted anything, mainly because 2020 has been 2020 and I haven't been in the best mindset for several months. I've had a lot of difficulty focusing on anything, and as a result, I've found my motivation has gone pretty much away.

However, last month I decided that lack of motivation be damned. I spent quite a bit of time converting a training that I had prepped to give at camps and conferences into a YouTube video series. This is a 12 lesson series that takes the viewer from a brief intro to Docker all the way up to building a custom Docksal application that combines 2 servers with a NodeJS backend and a PHP backend to simulate a production decoupled web application setup.

Here is a quick rundown of the videos and what you might expect from each:

Part 1 - Intro and Docker Basics

The first video is a starting point for someone who may or may not have much experience with Docker. I wouldn't recommend learning React without knowing some JavaScript, so I can't recommend using Docksal without having a bit of an understanding of Docker.

Part 2 - The Gush

This second part is basically where I fanboy about Docksal and why I think it's great. If you want to hear me ranting about the benefits of Docksal and everything it brings to the party, this is your clip!

Part 3 - Docksal Stacks

Docksal uses .yml files that define various stacks. Stacks are collections of services that make up an application. If you want to learn more, stop reading and check out the video!

Part 4 - Docksal Services

Remember way back under the last video when I used the word "services"? I remember. This video goes into what services are available to make up the stacks that are preconfigured or that you build on your own.

Part 5 -Getting Started with Docksal

Yeah, I know... 5 videos in is a long time to wait for a "Getting Started" vid, but the wait is worth it. Get your editors ready, roll up your sleeves, and get learning!

Part 6 - Using a Boilerplate

It's not just for warming the kettle anymore! A boilerplate is a ready-to-go application that you just need to start and it works. In part 6 we're going to look at spinning up a project with one of these boilerplates.

Part 7 - Installing a Drupal Site

This is what we've been working up to. This video will show you how to use Docksal to install and run a brand new Drupal site on your local machine. It takes less time than you think!

Part 8 - Doing More with Docksal and Drupal

Let's take it to 11. This tutorial goes over some of the ways we can further customize a local site, going so far as making the local Docksal environment actually mirror our hosting platform!

Parts 9, 10, 11 - Advanced Customization Projects

Each of these gets a little more in-depth with the customizations and they build off the previous for the most part. I had a lot of fun coming up with Project 3. What do you think?

Part 12 - Local Files

Let's call this one a bit of housekeeping. It doesn't matter what you use Docksal for if you end up committing your API keys to a public repo. (Don't do that!) This one goes over how to use local Docksal files to keep your safe, secret info safe and secret.

Conclusion

This is my first attempt at instructional videos, but hopefully not my last. I'll be posting stuff as I can when I have time, but I'd really like to know what you all would like to see me cover. Feel free to comment on one of the videos above, on this post, on Twitter, or wherever else I might see it. Be sure to subscribe to my channel JDDoesDev on YouTube to get notified when I put new stuff up. Until then, you're my favorite person.

Category

Development

Tags

Docksal

Drupal

Drupal Planet

GatsbyJS + Drupal: Create Content Type Landing Pages

jflynn — Sun, 01 Dec 2019 22:30:00 +0000

GatsbyJS + Drupal: Create Content Type Landing Pages jflynn Sun, 12/01/2019 - 16:30

At NEDCamp I had the pleasure of seeing many wonderful people and sessions, but, as you may know, my favorite track at most events is the "Hallway Track". If you're not familiar, the Hallway Track is the time in-between sessions where some real magic happens. You have a chance to talk with some of the most amazing minds in the world about topics you're passionate about. You can share knowledge, bounce ideas, have epiphanies, and realize that your current problems (code-wise) are things that other people have run into. One such conversation happened that inspired me to think outside the box to solve a problem.

In my last post we went over how to create a related content section with references to entities that may have empty fields. Today, we're going to take that one step further and create landing pages for content types.

In Drupal, we would ordinarily build these by attaching a view to a content type based on contextual filters or similar in order to get a collection of all content of that content type. Since we don't have Views in GatsbyJS, we need another solution. There are a couple of options out there, including the recently released JSON:API Cross Bundles module, compliments of Centarro and Matt Glaman. However, at the time of this writing there is an issue with the JSON:API Cross Bundles conflicting with JSON:API Extras. So, if you're relying on JSON:API Extras, you'll need another solution.

The problem:

Out of the box, JSON:API does not create a route to retrieve all nodes with any ease. However, there's no need to fear. This post is here!

Now if you're not using JSON:API Extras, I strongly recommend looking into JSON:API Cross Bundles. It creates a route to all content and will simplify your life. If you are using JSON:API Extras, have I got something for you.

Let's dive in.

Scenario:

You're building a decoupled Drupal site and you want to have a reusable template for landing pages that display all content of a content type. This is easy enough to do in Drupal using Views, but we lose Views when going decoupled so we need another way. How do we accomplish this in a decoupled application using GatsbyJS as the front-end?

Solution:

Strap in folks, this one gets a little bumpy.

Drupal side:

We need to do some work on both sides of the application for this to work. First, we will setup a content type in Drupal to use for our Content Landing Pages. This is kind of a choose your own adventure scenario, but one thing that you absolutely must have is an Entity Reference field that references the Config Entity: Content Type with a cardinality of 1.

Select this field type:

And this is the entity type to reference:

Now that we have our field created, select any content type that will require a content landing page as an available option.

Whatever else you want to put on this page is up to you. Go wild. Want a hero image? Add a hero image. Want a dancing baby gif? That's your choice and I respect it. Once you've finished making the greatest landing page content type ever™ we can move on to the fun part in GatsbyJS.

GatsbyJS side:

JSON:API gives us something that can help us out a bit. It goes by the name allNodeTypeNodeType and it will let us workaround the lack of a base all-content route. If we explore this in GraphiQL we'll see that we can drill down a bit and get exactly what we need.

{
  allNodeTypeNodeType {
    nodes {
      relationships {
        node__article
        node__landing_page
        node__basic_page
      }
    }
  }
}

NOTE: I didn't drill down too far, but all fields are available here.

Let's first create our landing page template in Gatsby.

First, let's just create a simple, empty component for our Landing Page with a basic graphql query.

// src/components/templates/LandingPage/index.js
import React from 'react'
import { graphql } from 'gatsby'

function LandingPage({ data }) {
  return (
    <div>
      
    </div>
  )
}

export default LandingPage

export const query = graphql`
  query($LandingPageID: String!){
    nodeLandingPage(id: { eq: $LandingPageID }) {
      id
      title
    }
  }
`

Nothing too fancy here, right? Just a template that we can use to build our pages out without Gatsby yelling at us on build.

Next, we're going to add this template to gatsby-node.js so that we create our pages dynamically.

// gatsby-node.js

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions

  const LandingPageTemplate = require.resolve(`./src/components/templates/LandingPage/index.js`)

  const LandingPage = await graphql(`{
    allNodeLandingPage {
      nodes {
        id
        path {
          alias
        }
      }
    }
  }
  `)

  LandingPage.data.allNodeLandingPage.nodes.map(node => {
    createPage({
      path: node.path.alias
      component: LandingPageTemplate,
      context: {
        LandingPageID: node.id,
      }
    })
  })
}

This is pretty straightforward so far, right? Let's think about what we're going to need in order for this to work the way we want it to and pull all of a single content type into our landing page.

We're going to need:

The content type we want to build a landing page for.
A query to fetch all content a content type.
The landing page template with logic to display the content type.
Probably some other things, but we'll sort that out along the way. We're in this together, remember?

How are we going to get these things? Let's go down the list.

The content type we want to build a landing page from:

We have this from our Drupal side. Remember, we created the Content Type field on our Landing Page content type? This can be placed in our gatsby-node.js and passed to our query via the context option.

Let's add it in. First we need to update our graphql query to pull it in:

// gatsby-node.js
  const LandingPage = await graphql(`{
    allNodeLandingPage {
      nodes {
        id
        relationships { // <---- add from this line
          field_content_type {
            drupal_internal__type
            name
          }
        } // <---- to this line
      }
    }
  }
  `)

What we're doing here is looking at GraphiQL and exploring our data to see what we have available. If we drill down into allNodeLandingPage.nodes we can see that in relationships we have field_content_type with some useful things. Specifically, our drupal_internal__type and name values. Also, notice that we removed nodes.path.alias from the query.

By adding these to our query we can now pass the info through to our created pages. We're going to do a bit of data manipulation here to create our paths dynamically as well. I follow the convention that a landing page's path should reflect the content type that it's a landing page for. So, if we were making a landing page for "Articles" the path would be path-to-my.site/articles and articles would have that as a base path to path-to-my.site/articles/my-awesome-article. However, you can follow whatever convention you see fit.

To do this, we're going to manipulate the name from the content type into a URL-friendly string by using the JavaScript .replace() function and then pass that to the path option. Since we also want to query for the content type on our landing page, we're going to pass the drupal_internal__type through the context option.

Let's do that:

// gatsby-node.js
  LandingPage.data.allNodeLandingPage.nodes.map(node => {
    const pathName = node.relationships.field_content_type.name.toLowerCase().replace(/ /g, '-') // <---- New line
    createPage({
      path: pathName, // <--- Changed line
      component: LandingPageTemplate,
      context: { 
        LandingPageID: node.id,
        ContentType: node.relationships.field_content_type.drupal_internal__type, // <---- New line
      }
    })
  })

What does the the context option do? It passes data to our component as props. GraphQL already pulls the context data for the queries, which you can see in any query that has a variable for the filter. Usually this is the content ID so that it can build a page for a specific piece of content from Drupal, but we can leverage this to add more variables and more filtering however we see fit.

Our next step is going to be to actually USE this additional info to do something amazing with.

A query to fetch all content a content type:

Let's look back at our src/components/templates/LandingPage/index.js and see what we need to query. We know we want to get all nodes of a certain content type, and we know that we want to reuse this template for any landing pages with content listing. Since we've established that allNodeTypeNodeType gives us access to all content on available to Gatsby, let's query on that.

// src/components/templates/LandingPage/index.js

export const query = graphql`
  query($LandingPageID: String!, $ContentType: String!){
    nodeLandingPage(id: { eq: $LandingPageID }) {
      id
      title
    }
    allNodeTypeNodeType(filter: { drupal_internal__type: { eq: $ContentType }}) { // <---- New section
      nodes {
        relationships {
          node__article {
            id
            title
            path {
              alias
            }
          }
          node__page {
            id
            title
            path {
              alias
            }
          }
        }
      }
    }
  }
`

What we're doing here is using that variable we passed via the context option in gatsby-node.js and filtering to only return the content type we're wanting to see. One 'gotcha' here is that this query will also return the landing page that references the content type. However, if you're not creating a landing page of landing pages then you should be alright.

Since we're only creating landing pages for two content types, this is fine, although we're not getting a lot back. Most projects that I've worked on have had some kind of "teaser" display for these kinds of pages. I'm not going to cover the specifics of creating a teaser template here, but the TL;DR is: start with your full display and take out everything but what you want on the teaser. For this post, we're going to create the list of links using the titles.

Now, if the content types that we're creating landing pages for don't have any content, then you're going to have a bad time. In this case, go back to my previous post about empty entity reference fields and see if you can use that to create some default fields and prevent errors or just create some content of the missing type.

Next, let's flesh out our landing page template a bit.

The landing page template with logic to display the content type:

So far, our template, minus the query, is pretty empty and not doing a lot. Let's add in the title of this landing page.

// src/components/templates/LandingPage/index.js
function LandingPage({ data }) {

  const landingPage = data.nodeLandingPage

  return (
    <div>
      <h1>{landingPage.title}</h1>
      <div className='content-list'></div>
    </div>
  )
}

I like to clean up the variables a bit and rename data.nodeLandingPage to landingPage. It's a bit cleaner to me, but do what you want.

Alright, we have the title of this content, but what about the list of content we want to show on this page? Well, we're going to need to do some logic for that. First off, we need to know which content type we're looking for. Second, we need a way find it. Third, we need to clean this data into something usable. Finally, we need to display it.

We could just display everything returned from our allNodeTypeNodeType query, but there would be a lot of nulls and issues parsing the arrays. Here's an example of what that query returns before we massage the data, using the Drupal internal type article:

{
  "data": {
    "allNodeTypeNodeType": {
      "nodes": [
        {
          "drupal_internal__type": "article",
          "relationships": {
            "node__article": [
              {
                "id": "0e68ac03-8ff2-54c1-9747-3082a565bba6",
                "title": "Article Template",
                "path": {
                  "alias": "/article/article-template"
                }
              }
            ],
            "node__basic_page": null
          }
        }
      ]
    }
  }
}

Now, to get the content this way we could do some complex mapping and sorting and filtering, but I tried that and it wasn't fun. Fortunately, Gatsby is here to rescue us and make life easier. Our context option gets passed into our page component as props. If you're unfamiliar with the concept of Props in React, and therefore Gatsby, props are properties that are passed into components. The line

function LandingPage({ data }) {

could be rewritten as

function LandingPage(props) {
  const data = props.data

but we're using a concept called Destructuring to only pass in the prop that we need. This allows us to create variables from object keys without having to take the extra steps. Our page component props object also contains the key pageContext which is where anything in the context option gets stored to give the page template access to.

Let's bring that in:

// src/components/templates/LandingPage/index.js
function LandingPage({ data, pageContext }) {

  const landingPage = data.nodeLandingPage
  const nodeType = data.allNodeTypeNodeType
  const contentType = 'node__' + pageContext.ContentType

Since we set our ContentType in gatsby-node.js we're able to use that here. Note that we're concatenating the string node__ with our pageContext.ContentType. We're doing this because everything in Gatsby is a node, including content types. This allows us to do the next steps.

Next, we want to clear out all of the non-content type data from the allNodeTypeNodeType query. This is what it looks like if we were to console.log(nodeType.nodes):

Array(1)
  0:
    relationships:
      node__article: Array(1)
        0: {id: "0e68ac03-8ff2-54c1-9747-3082a565bba6", title: "Article Template", path: {…}, …}
        length: 1
        __proto__: Array(0)
      node__page: null

We only want the node__article array, so how do we get that? Well, we need to use .map() and a concept called currying. This is essentially creating a function that allows us to use a variable from outside of the .map() scope inside of the .map() callback. It allows us to break down a function into more functions so that we have more control over it, which is what we need here.

// src/components/templates/LandingPage/index.js
function LandingPage({ data, pageContext }) {

  const landingPage = data.nodeLandingPage
  const nodeType = data.allNodeTypeNodeType
  const contentType = 'node__' + pageContext.ContentType

  const getContentArray = (contentType) => { // <---- Curry function, but not as delicious
    return (node) => (node.relationships[contentType])
  }

  const contentArray = nodeType.nodes.map(getContentArray(contentType))

We created our curry function that takes our contentType as an argument. From within there, it completes the mapping and returns our desired array... almost.

Here's what we get back if we console.log(contentArray):

[Array(1)]
  0: Array(1)
    0: {id: "0e68ac03-8ff2-54c1-9747-3082a565bba6", id: 1, title: "Article Template", …}
    length: 1
    __proto__: Array(0)
  length: 1
  __proto__: Array(0)

We're almost there, but now we have an array of our content within another array. If only there were a function to help us out here...

Just kidding, there is! For this, we're going to use .flat(). The .flat() function flattens out a nested array into a single level. However, there's a gotcha with it, as mentioned in this Stack/Overflow question. We can get around this by using the array-flat-polyfill polyfill.

Add gatsby-plugin-polyfill-io to your project by installing with yarn or npm

npm install array-flat-polyfill
// or
yarn add array-flat-polyfill

and in your component file add the following within

import 'array-flat-polyfill'

So, let's flatten that array!

function LandingPage({ data, pageContext }) {

  const landingPage = data.nodeLandingPage
  const nodeType = data.allNodeTypeNodeType
  const contentType = 'node__' + pageContext.ContentType

  const getContentArray = (contentType) => {
    return (node) => (node.relationships[contentType])
  }

  const contentArray = nodeType.nodes.map(getContentArray(contentType))
  const contentArrayFlat = contentArray.flat()

And the resulting console.log(contentArrayFlat):

0:
  id: "0e68ac03-8ff2-54c1-9747-3082a565bba6"
  path: {alias: "/article/article-template"}
  title: "Article Template"
  length: 1
__proto__: Array(0)

Now we've got exactly what we wanted! The final step is to put this to work. We'll do that by creating a list of titles that link to the content. Your finished component should look like:

// src/components/templates/LandingPage/index.js
import React from 'react'
import { graphql, Link } from 'gatsby' // <--- added 'Link' here to use the link component
import 'array-flat-polyfill'

function LandingPage({ data, pageContext }) {

  const landingPage = data.nodeLandingPage
  const nodeType = data.allNodeTypeNodeType
  const contentType = 'node__' + pageContext.ContentType

  const getContentArray = (contentType) => {
    return (node) => (node.relationships[contentType])
  }

  const contentArray = nodeType.nodes.map(getContentArray(contentType))
  const contentArrayFlat = contentArray.flat()

  return (
    <div>
      <h1>{landingPage.title}</h1>
      <div className='content-list'>
        <ul>
          // One-liner to create the list of items.
          {contentArrayFlat.map((item, i) => <li key={i}><Link to={item.path.alias}>{item.title}</Link></li>)}
        </ul>
      </div>
    </div>
  )
}

export default LandingPage

export const query = graphql`
  query($LandingPageID: String!, $ContentType: String!){
    nodeLandingPage(id: { eq: $LandingPageID }) {
      id
      title
    }
    allNodeTypeNodeType(filter: { drupal_internal__type: { eq: $ContentType }}) {
      nodes {
        relationships {
          node__article {
            id
            title
            path {
              alias
            }
          }
          node__page {
            id
            title
            path {
              alias
            }
          }
        }
      }
    }
  }
`

And that's all there is to it. Hopefully you find this useful and it helps speed up your development with Gatsby a little bit. If I missed anything on here, please don't hesitate to let me know in the comments. Always feel free to reach out to me on Twitter or Slack or any way you want to.

Credit where credit is due: Shane Thomas (AKA @codekarate) and Brian Perry (AKA @bricomedy) helped me work through this issue at NEDCamp.

Patron thanks:

Thank you to my Patreon Supporters

David Needham
Tara King
Lullabot

For helping make this post. If you'd like to help support me on Patreon, check out my page https://www.patreon.com/jddoesthings

Category

Tags

GatsbyJS + Drupal: Create Custom GraphQL Schema for Empty Fields

jflynn — Mon, 18 Nov 2019 20:40:00 +0000

GatsbyJS + Drupal: Create Custom GraphQL Schema for Empty Fields jflynn Mon, 11/18/2019 - 14:40

Stop me if you've heard this one...

A developer is trying to connect Drupal to Gatsby. Drupal says, "I've got a Related Content field that allows SEVEN different entity types to be referenced, but only THREE slots for content. What do you think?"

Developer says, "Sure, no problem, Drupal!"

Gatsby jumps in and says, "You better make sure that all seven of those entity types are in those three slots."

Developer and Drupal look at each other in confusion. Developer says, "Gatsby, that's not GREAT"

** Laughs go here **

What happened?

It turns out the way that Gatsby builds what it calls "nodes" is by querying the data available. This usually works perfectly, but there are occasions where all the data might not be present, so Gatsby doesn't build the nodes, or it builds the nodes, but doesn't create all of the fields. Any optional field can fall into this if there is no content in that field on a Drupal entity, and if you're building templates for your decoupled site, then you might just want some content in that field.

NOTE: A Drupal "node" and a GraphQL "node" are not the same thing. This may take some time to sink in. It definitely did for me! For the remainder of this post I will refer to GraphQL nodes as "nodes" and Drupal nodes as "entities". Everybody got that? Good, moving on.

Because the nodes with your hypothetical content have not yet been created, or the fields on your entity don't have anything in them, Gatsby just passes right over them and acts like they don't even exist.

Commonly, you'll see something like this pop up during gatsby build or gatsby develop:

Generating development JavaScript bundle failed


/var/www/gatsby/src/components/templates/homepage/index.js
  56:9  error  Cannot query field "field_background_media" on type "node__homepageRelationships".

This can be frustrating. And when I say "frustrating" I mean that it's table-flipping, head slamming into desk, begging for help from strangers on the street frustrating. The quick fix for this one is simple: ADD SOMETHING TO THE FIELD. In fact, you don't even have to add it to every instance of that field. You can get away with only putting some dummy content in a single entity and you'll have access to that field in Gatsby.

You could also make it a required field so that there MUST be something in it or else the author can't save. This is valid, but in the event that your project's powers-that-be decide that it should be optional, you may need another alternative. This is where GraphQL schema customization comes in.

GraphQL schema and Gatsby

First, a little primer on GraphQL schema. Outside of Gatsby, a system using GraphQL usually needs to define the schema for GraphQL nodes. Gatsby takes this out of the developer's hands and builds the schema dynamically based on the content available to it from its source, in this case gatsby-source-drupal. However, empty data in the source results in no schema in Gatsby.

Let's look at the fix for the optional image above and why it works:

In gatsby-node.js we build our schema through createPages, createPage, and GraphQL queries. This is also where we're going to place our code to help GraphQL along a little bit. This will live in a function called createSchemaCustomization that we can use to customize our GraphQL schema to prevent empty field errors from ruining our day.

The Gatsby docs outline this in the Schema Customization section, but it didn't really click there for me because the examples are based on sourcing from Markdown as opposed to Drupal or another CMS. Things finally clicked a little when I found this issue on Github that showed how to work around a similar problem when sourcing from WordPress.

Three scenarios and three solutions

Scenario 1: Empty field

This is by far the simplest scenario, but that doesn't make it simple. If you have a basic text field on a Drupal entity that does not yet have any content or at some point may not have any content, you don't want your queries to break your site. You need to tell GraphQL that the field exists and it needs to create the matching schema for it.

Here's how it's done:

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    type node__homepage implements Node {
      field_optional_text: String
  `
  createTypes(typeDefs)
}

Now, to walk through it a bit. We're using createSchemaCustomization here and passing in actions. The actions variable is an object that contains several functions so we destructure it to only use the one we need here: createTypes.

We define our types in a GraphQL query string that we lovingly call typeDefs. The first line of the query tells which type we're going to be modifying, in this case node__homepage, and then what interface we're implementing, in this case Node.

NOTE: If you're looking at GraphiQL to get your field and node names it may be a bit misleading. For example, in GraphiQL and in my other queries node__homepage is called as nodeHomepage. You can find out what the type name is by running a query in GraphiQL that looks like:

query MyQuery {
  nodeHomepage {
    internal {
      type
    }
  }
}

or by exploring your definitions in GraphiQL.

Next, we add the line field_optional_text: String which is where we define our schema. This is telling GraphQL that this field should exist and it should be of the type String. If there are additional fields, Gatsby and GraphQL are smart enough to infer them so you don't have to redefine every other field on your node.

Finally, we pass our customizations into createTypes and restart our development server. No more errors!

Scenario 2: Entity reference field

Suppose we have a field for media that may not always have content. We still want our queries to work in Gatsby, but if there's only one Drupal entity of this content type and it happens to not have an image attached, then our queries are going to break, and so will our hearts. This requires a foreign key relationship because the entity itself is a node to GraphQL.

Here's how it's done:

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    type node__homepage implements Node {
      relationships: node__homepageRelationships
    }
    type node__homepageRelationships {
      field_background_media: media__image @link(from: "field_background_media___NODE")
    }
  `
  createTypes(typeDefs)

Looks a little similar to the previous scenario, but there's a bit more to it. Let's look at the changes.

Instead of defining our custom schema under the type node__homepage implements Node { line, we reference our relationships field which is where all referenced nodes live. In this case, we tell GraphQL that the relationships field is of type node__homepageRelationships. This is another thing you can find using GraphiQL.

The next section further defines our relationships field. We declare that node__homepageRelationships should have the field field_background_media of type media__image, but what's that next part? That's where our foreign key link is happening. Since field_background_image is an entity reference, it becomes a node. This line links the field to the node created from the field. If you don't include the @link(from: "field_background_media___NODE) in your query you'll get a deprecation notice:

warn Deprecation warning - adding inferred resolver for field node__homepageRelationships.field_background_media. 
  In Gatsby v3, only fields with an explicit directive/extension will get a resolver.

Edit: This post was edited to reflect the deprecation notice instead of indicating that @link is optional.

Scenario 3: Related content field with multiple content types

This is the one that had me crying. I mean scream-crying. This is the widowmaker, the noisy killer, the hill to die upon. At least it WAS, but I am triumphant!

Like my horrible joke from the beginning of this post, I have a related content field that is supposed to allow pretty much any content type from Drupal, but only has three slots. I need to have queries available for each content type, but if one doesn't exist on the field, then GraphQL makes a fuss. I can't say for sure, but I've got a feeling that it also subtly insulted my upbringing somewhere behind the scenes.

Now, I'm here to save you some time and potentially broken keyboards and/or monitors.

Here's how it's done:

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    union relatedContentUnion =
      node__article
      | node__basic_page
      | node__blog_post
      | node__cat_food_reviews
      | node__modern_art_showcase
      | node__simpsons_references

    type node__homepage implements Node {
      relationships: node__homepageRelationships
    }
    type node__homepageRelationships {
      field_related_content: [relatedContentUnion] @link(from: "field_related_content___NODE")
    }
  `
  createTypes(typeDefs)
}

The biggest changes here are the union and the brackets around the type. From the GraphQL docs:

Union types are very similar to interfaces, but they don't get to specify any common fields between the types.

This means that any type in the union can be returned and they don't need to have the same fields. Sounds like exactly what we need, right?

So we define our union of our six content types and create the relationship using a foreign key link. We use the node created from our field, field_related_content___NODE as our foreign reference, and we get results. However, the brackets around the union are there, and they must do something. In fact they do. They indicate that what will be returned is an array of content in this union, meaning that there will be multiple values instead of one single value returned.

Summary

This seriously took me much longer than it should have to figure out. Hopefully, you don't suffer my same fate and find this post useful. One thing to note that almost destroyed me is that there are THREE, count them 1, 2, 3, underscores between the field name and NODE in the link. _ _ _ NODE. I only put two when I was fighting this and it cost me more time than I'm willing to admit on a public forum.

Special thanks to Shane Thomas (AKA Codekarate) for helping me sort through this and being able to count to 3 better than me.

Category

Tags

Docksal gets a Training

jflynn — Tue, 12 Nov 2019 23:19:43 +0000

Docksal gets a Training jflynn Tue, 11/12/2019 - 17:19

In July of last year I started a new job as a developer with a new agency. During my first week, in between meetings, HR trainings, and all the other fun things that happen during onboarding, I was introduced to the preferred local development environment that was being used on most of the projects.

It was lightweight, based on Docker, it ran easily, and it was extremely easy to configure. Prior to this, I had bounced around from local setup to local setup. My local dev environment resume included such hits as MAMP, WAMP, Acquia Dev Desktop, Kalabox, VAMPD, DrupalVM, Vagrant, ScotchBox, VirtualBox, native LAMP stacks, and everything in between. All of them had their strengths and weaknesses, but none of them really had that spark that really hooked me.

Enter Docksal.

When I first started using Docksal, I thought it was just like any other setup, and to a point, it is. It creates a reusable environment that can be shared across multiple developers and setup to mimic a hosting provider to a certain point, but the two things that really grabbed me were how easy it was to get started and how fast it was compared to other systems. Docksal has one key, killer feature in my opinionated mind, and that’s the fact that the entire application is written in Bash. The primary binary (which may or may not be the name of my upcoming one-man, off-Broadway, off-any stage show) begins with #! /usr/bin/env bash and runs on any system that has the bash executable, which encompasses Linux (of course), macOS, and now Windows thanks to WSL and the ability to add Ubuntu.

One thing that was missing, though, was a training guide. It has AMAZING documentation, available at https://docs.docksal.io, including a great getting started walkthrough, but for someone just starting out using it who might not have guidance and support from people they work with, it might take a little getting used to.

If you know me, you know that I enjoy talking at conferences. I’ve given over two dozen presentations at several types of events from local meetup groups to national level conferences. If you don’t know me, you just learned something new about me. Since I enjoy talking in front of people so much, the next logical step was to find something I’m familiar with and make a training of it. Turns out, I’m familiar with Docksal.

I submitted my pitch for a training to NEDCamp, the New England Drupal Camp, and they accepted it. Since I now had a reason to write a training, I began writing a training. Initially, I started with a very high-level outline, and eventually built a framework for my training. Thanks to the nature of open source, I was able to use many of the features that https://docs.docksal.io already had in order to make my training seem a little familiar to current users and easily accessible to new users.

The first go at this training will be at NEDCamp 2019 on Friday, November 22nd. This will be the first time a dedicated training spot has been used to train on Docksal, and I'm extremely excited to see how it goes and how to improve. After that training, I will make my handbook available online, eventually to be merged into the Docksal Github repo as part of the documentation. I have had help from numerous people in building this training, especially from the Docksal maintainers, Sean Dietrich, Leonid Makarov, Alexei Chekiulaev; folks who have reviewed what I've written so far, Dwayne McDaniel and Wes Ruvalcaba; and people who have challenged me to learn more about Docksal, whose numbers are too high to list them all.

If you're interested in learning how to use Docksal or what it's all about, consider attending my training at NEDCamp on November 22nd. You can find all the details on the NEDCamp training page, and if you can't make it, be sure to watch for the handbook to be released soon.

Since I'm still working on the finishing touches, why not take the time to let me know what you would like to get out of this type of training or what you wish you would have known when learning how to use Docksal or a similar product in the comments and where you feel extra attention should be placed.

Category

Tags

Using Drupal Blocks in a Decoupled GatsbyJS Application

jflynn — Sun, 03 Nov 2019 18:40:45 +0000

Using Drupal Blocks in a Decoupled GatsbyJS Application jflynn Sun, 11/03/2019 - 12:40

One of the most useful components of Drupal is the Block system. This system allows for pieces of content to be created and reused throughout a site in various regions of the page structure. You can also select which bundles or content types this piece of content should appear on, making it so that a blog post gets a certain Call to Action section while an article gets something similar, but different.

When we use GatsbyJS for a decoupled front-end solution with a Drupal back-end, we lose out on quite a bit, if not everything, that the theme layer of Drupal provides. This means that Drupal regions mean nothing to Gatsby, nor does block placement. In fact, any functionality that would go into a .theme file is no longer available on the Drupal side.

Before I get into the "how" of using Drupal blocks in Gatsby, I want to cover a little bit of the "why".

Why Use Drupal Blocks for Content in a Gatsby Front End?

The main advantage of blocks in Drupal is that the content is created in one place, but can be placed in several spots. I have worked with solutions that use Paragraphs (from the Paragraphs contrib module) for similar functionality, but the problem remains where the content needs to be recreated on every new parent entity. For example, I can create a Call to Action (CTA) Paragraph and place fields that reference them on every content type, but the Paragraphs themselves remain separate. A Paragraph is more like a collection of fields to be filled out than a reusable entity, and that's okay.

In contrast, a Block can be created in one place, usually using the Block UI, and the content of the Block remains the same no matter where it is placed. A CTA block on a blog post will have identical content to the CTA block on an article. This makes content changes extremely fast compared to having to update every article and blog post if the wording or link need to change.

It is entirely possible to create these types of entities in Gatsby by defining a reusable component, however the editing experience doesn't really pan out. It may require a developer to go in and edit a React component, adding a middle-person to the process. Using reusable Drupal blocks can save time and budget when set up appropriately.

How to Use Drupal Blocks for Content in a Gatsby Front End

This section is going to make a few assumptions.

You have a basic understanding of Gatsby and React components.
You understand the Drupal theme layer.
You have a basic understanding of the Drupal block system.
Your decoupled application is already setup and pulling content from Drupal (not necessary, but it helps if you can try it out)
You have the JSON:API module enabled on Drupal
You're sourcing content from Drupal.

If you're having problems with any of these, feel free to reach out to me on Drupal Slack, I go by Dorf there.

Now the "how". We're going to start by creating a Custom Block Type. Let's keep going with the CTA theme and call it "CTA Block". We do this by logging into our site as someone with permissions to access the Block UI and going to admin/structure/block/block-content/types. Once there, select "Add custom block type".

Let's label this CTA Block and begin creation. After we create it, we need to add some fields, so let's add the following fields:

CTA Heading
- A plain text field, max 255 chars
CTA Link
- A Link field using URL and label, internal and external links, Label required.
CTA Content Types
- This is the field that will make all the difference. Create this field as Reference: Other... to begin with.
- Label it CTA Content Type.
- Under "Type of entity to reference" choose "Content type" from the select list, under Configuration.
- Set unlimited cardinality.
- Go through the remaining screens to create this field. Once you're back on the field list, select "Manage form display"
- From here, we're going to change the widget from Autocomplete to Check boxes/radio buttons.
- Save your changes

Now we're going to create a new block using this Custom Block Type. When we create the block under block/add/cta_block the form should look something like this:

Now, add whatever text you want to the fields, but only select a single content type in the CTA Content Type field. Save the block and spin up your Gatsby dev environment. We're going to switch over there for a bit.

Let's fire up our develop environment and take a look at GraphiQL to see what we have going on.

As you can see, we now have access to allBlockContentCtaBlock in GraphiQL, but what are we going to do with it? Well, we are first going to create the CTA Block React component. We'll do that by creating the file src/components/blocks/CtaBlock.js and adding the following:

import React from 'react'
import { graphql } from 'gatsby'

const CtaBlock = ({ data }) => {

  return <div class='ctaBlock'>
    <h3>CTA Heading</h3>
      <p>CTA Text goes here and here and here.</p>
      <a href="http://example.com">Link Text</a>
    </div>
}

export default CtaBlock

This is pretty simple and doesn't include anything having to do with our GraphQL query yet, but we have the structure in place. Now, let's look at the data we can pull from GraphQL. We want to get the heading, body, link, and content type, so our query is going to look something like this:

query MyQuery {
  allBlockContentCtaBlock {
    nodes {
      field_cta_heading
      field_cta_link {
        title
        uri
      }
      body {
        value
      }
      relationships {
        field_cta_content_type {
          name
        }
      }
    }
  }
}

Which will give us back:

{
  "data": {
    "allBlockContentCtaBlock": {
      "nodes": [
        {
          "field_cta_heading": "Heading for the CTA Block",
          "field_cta_link": {
            "title": "Learn more!",
            "uri": "http://google.com"
          },
          "body": {
            "value": "<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Vestibulum facilisis, purus nec pulvinar iaculis, ligula mi congue nunc, vitae euismod ligula urna in dolor. Aenean massa.</p>\r\n\r\n<p>Praesent nec nisl a purus blandit viverra. Nullam nulla eros, ultricies sit amet, nonummy id, imperdiet feugiat, pede. Phasellus dolor.</p>\r\n"
          },
          "relationships": {
            "field_cta_content_type": [
              {
                "name": "Blog Post"
              }
            ]
          }
        }
      ]
    }
  }
}

Perfect! Now I want you to notice a couple of things here. First, we're querying ALL of the CTA blocks here. Second, we're using the content type in the query. Let's get this into our component. Add in the query to our CtaBlock.

import React from 'react'
import { graphql } from 'gatsby'

const CtaBlock = ({ data }) => {

  return <div class='ctaBlock'>
    <h3>CTA Heading</h3>
      <p>CTA Text goes here and here and here.</p>
      <a href="http://example.com">Link Text</a>
    </div>
}

export default CtaBlock

export const CtaBlockQuery = graphql`
  allBlockContentCtaBlock {
    nodes {
      field_cta_heading
      field_cta_link {
        title
        uri
      }
      body {
        value
      }
      relationships {
        field_cta_content_type {
          name
        }
      }
    }
  }`

But wait, this isn't a page template, and it shouldn't be. What's the problem then? We have a query in a non-page template, and that's not good. What we need to do is figure out which of our templates are going to use this block and add it in there. Since we chose to have the block show on the blog post content type, we're going to use the blog post template. This will probably differ for your setup.

Let's open up our page template and take a look:

  import React from 'react'
  import { graphql } from 'gatsby'

  import Layout from '../layouts'

  const BlogPostTemplate = ({ data }) => {

    const blogBody = data.nodeBlogPost.body.value

    return <Layout>
      <h3>{data.nodeBlogPost.title}</h3>
      {data.nodeBlogPost.body.value}
    </Layout>
  }

  export default BlogPostTemplate

  export const query = graphql`
  query($BlogPostID: String!){
  nodeBlogPost(id: { eq: $BlogPostID }) {
    id
    title
    body {
      processed
    }
  }
}
`

Now let's update this to have the block appear.

import React from 'react'
import { graphql } from 'gatsby'

import Layout from '../layouts'
import CtaBlock from '../blocks/CtaBlock'

const BlogPostTemplate = ({ data }) => {

  const blogBody = data.nodeBlogPost.body.value

  return <Layout>
    <h3>{data.nodeBlogPost.title}</h3>
    {data.nodeBlogPost.body.value}
    <CtaBlock />
  </Layout>
}

export default BlogPostTemplate

export const query = graphql`
  query($BlogPostID: String!){
  nodeBlogPost(id: { eq: $BlogPostID }) {
    id
    title
    body {
      processed
    }
  }
}
`

But we still need to include the query for the block itself. To do this, we're going to make a few edits to both of our components. We'll start with the CtaBlock component and convert the query into a fragment that we can reuse in multiple places if need be.

import React from 'react'
import { graphql } from 'gatsby'

const CtaBlock = ({ data }) => {

  return <div class='ctaBlock'>
    <h3>CTA Heading</h3>
      <p>CTA Text goes here and here and here.</p>
      <a href="http://example.com">Link Text</a>
    </div>
}

export default CtaBlock

export const CtaBlockQuery = graphql`
  fragment CtaBlockQuery on block_content__cta_block {
  field_cta_heading
  field_cta_link {
    title
    uri
  }
  body {
    value
  }
  relationships {
    field_cta_content_type {
      name
    }
  }
}`

If you have a keen eye, you'll notice that we've removed the nodes section of the query. This is because we're now going to query for a single block. However, there is some risk to this. In the event that a content creator creates a new CTA block on Drupal for this content type instead of editing the existing one, the old one will remain in place because a single item query will only return a single item.

Now, let's move back over to our page template and use this fragment to query for our block.

import React from 'react'
import { graphql } from 'gatsby'

import Layout from '../layouts'
import CtaBlock from '../blocks/CtaBlock'

const BlogPostTemplate = ({ data }) => {

  const blogBody = data.nodeBlogPost.body.value

  return <Layout>
    <h3>{data.nodeBlogPost.title}</h3>
    {data.nodeBlogPost.body.value}
    <CtaBlock />
  </Layout>
}

export default BlogPostTemplate

export const query = graphql`
  query($BlogPostID: String!){
  nodeBlogPost(id: { eq: $BlogPostID }) {
    id
    title
    body {
      processed
    }
  }
  blockContentCtaBlock (relationships:
    {field_cta_content_types:
      {elemMatch:
        {name:
          {eq: "Blog Post"}
          }
        }
      }
    ){
    ...CtaBlockQuery
  }
}
`

Take a look at what we've done here. We've added in a query for the CtaBlock and we're filtering it by the content type it's attached to. After that, we're pulling in everything from the query on our component. This is exactly what we were wanting to do, but there's another step that we need to take to actually use the data on our component.

If you look at the JSX element for

<CtaBlock />

you'll notice we aren't passing anything to it, so we've got to make sure it has data to work with or we're going to end up rendering nothing. Edit that line to be

<CtaBlock data={data} />

In case you're not familiar, this is a React concept known as passing props, or properties, to a child component. We're passing the data object that was returned from our GraphQL query to the CtaBlock component so that it can use the included data. Since this is just a demo, we're passing the entire thing along, but it's easy enough to only pass the relevant parts of the object.

Now back in our CtaBlock component we can use the data to render out our block's content.

import React from 'react'
import { graphql } from 'gatsby'

const CtaBlock = ({ data }) => {

  return <div class='ctaBlock'>
    <h3>{data.blockContentCtaBlock.field_cta_heading}</h3>
      <p dangerouslySetInnerHtml= {{
        __html: data.blockContentCtaBlock.body.value}} />
      <a href={data.blockContentCtaBlock.field_cta_link.uri}>{data.blockContentCtaBlock.field_cta_link.title}</a>
    </div>
}

export default CtaBlock

export const CtaBlockQuery = graphql`
  fragment CtaBlockQuery on block_content__cta_block {
  field_cta_heading
  field_cta_link {
    title
    uri
  }
  body {
    value
  }
  relationships {
    field_cta_content_type {
      name
    }
  }
}`

Now we have our block based on content type rendering within our content type's Gatsby template. Note that I've left out a few things that should be noted for decoupled sites.

An internal link should us the Gatsby <Link /> component.
Drupal needs some love to pass the correct alias over for an internal link so that it renders correctly.
This is a very basic example. YMMV.

Anyway, I hope that this helps someone out there who ran into the same problems that I did. Please feel free to reach out to me on Twitter @jddoesdev, on Slack where I'm usually Dorf, or just leave a comment here if you have questions, concerns, comments, or just something nice to say.

Also, please feel free to support my efforts in speaking on mental health in tech or creating blog posts and tutorials like these by checking out my gofundme and patreon campaigns in the sidebar.

Thanks for reading!

Category

Tags

Quick Hit: Using Drupal and Symfony Components Without Bootstrapping Drupal

jflynn — Fri, 26 Jul 2019 06:47:48 +0000

Quick Hit: Using Drupal and Symfony Components Without Bootstrapping Drupal jflynn Fri, 07/26/2019 - 01:47

Sometimes we just want to see if a thing works

Recently I ran into a situation while building out the Watson/Silverpop Webform Parser where I just wanted to test and see if a few things worked without having to reload and bootstrap Drupal every time I refreshed a page. I also wanted to utilize some of the classes and methods made available from Symfony and Drupal. Can you feel my dilemma?

Let's be honest, running drush cr and refreshing a page takes time, and I'm an impatient person, so I wanted to see if there was a way to use some of these things without going through the pain of waiting for a Drupal bootstrap. Turns out, the solution wasn't that difficult and it made development on many methods of my module more pleasant than it could have been.

Here's the scenario

I wanted to test a few things that didn't require the database connection. Specifically, Drupal\Core\Serialization\Yaml to parse an array that I was building into YAML. So, what I did was stubbed out what would become my class WatsonFormEntityForm in a file in my docroot that I creatively named test.php. Now I was able to navigate to local.docksal/test.php on my local machine and see things working.

Get to the good stuff, already!

I got to a point in my development where I was able to convert the submitted HTML, in this case from a call to file_get_contents('./test.html'); into an array that I could work with. Xdebug was going great, and so was the module, but I wanted to see if I could convert it into YAML using a native Drupal method. The solution came with one single line of code.

$autoloader = require_once 'autoload.php';

This tells PHP, "Hey, we got a file here that wants to use some of the methods and classes in the Autoloader. Let's go ahead and let it!" This variable doesn't need to be called anywhere in the file. It just needs to exist. Now I was able to update the file with a few friendly use statements from within the Drupal and Symfony ecosystem without having to wait for all the database connections to happen.

The end result was:

<?php

use Drupal\Core\Serialization\Yaml;

$autoloader = require_once 'autoload.php';

// Do all the things here, including:

$yaml = Yaml::encode($array);

var_dump($yaml);

It sped up development, and it made it so I didn't have to wonder if something wasn't working because I forgot to drush cr all the things or if it was just because I made some mistakes.

Gotchas

Be sure that any code you're running doesn't rely on database calls or the container. For instance, if you try to run $nodes = \Drupal::entityTypeManager()->getStorage('node')->loadMultiple(); is going to throw a painful error.

Also, this is mainly for rapid prototyping or proving concepts. I don't recommend writing an entire module in procedural code and then trying to refactor later. Maybe take it one function at a time just to make sure it's doing what you want it to do.

Let me know if this helped you out or if you have better suggestions for rapidly testing some Drupal stuff without having to rely on a full bootstrap. As always, feel free to reach out to me on the Drupal Slack, where I'm always Dorf and always willing to help if I can.

Category

Development

Tags

Drupal

Drupal Planet

An Open Letter to the Drupal Community

jflynn — Tue, 23 Jul 2019 16:00:00 +0000

An Open Letter to the Drupal Community jflynn Tue, 07/23/2019 - 11:00

Let's Start a Conversation

Dear friends,

Over the past few weeks there have been some conversations among many of us regarding the issue credit system and how it could be used to "game the system." This started with a conversation in a Slack team asking if a d.o user was a bot because of the number of issue credits attached to their profile. At the time it was around 550 in the past year. There was assurance from someone who knew this person that the person in question was not a bot, however a cursory look at the issues they had been credited for revealed that the majority of these issues were issues that could be considered Novice level and were very similar to each other.

I didn't think much of it until I pushed a custom module into the contrib space, and within 30-60 minutes I received an email notice from d.o saying an issue had been opened on my module. My brand new, still in alpha, less than an hour old module. I read the issue and two things stuck out:

The name of the person creating the issue.
The verbiage used in this issue.

These stuck out because it was the exact same person who had been brought up in Slack and the words were an exact copypasta of issues I had looked at when trying to figure out how this person had earned so many credits without being a bot. I did a little more looking into it and noticed that the issue description was exactly the same as other issues opened by this person, and so was the comment. I copied the text of the comment and pasted it into Google and found that there were 8 pages of results with this exact same text, almost all of them were opened by this person. This did not help claims of being a definite human not-bot.

What's Wrong With This Picture?

Now why is this an issue, you may be asking. Why do I care and why am I making a fuss about it?

Let me preface this by saying that I don't care about the number of issue credits by my name. My skills (or lack thereof) speak for themselves, as does my reputation. I'm happy in my current position, I have a reasonable grasp on what I do, and even though I don't have a ton of credits next to my name, I consider myself a member of the community and an asset to the Drupal project.

As for making a fuss about it, there are three main reasons that I'm bothered by this situation.

Reason 1.

We've all seen the CMS Learning Curve image, right?

If not, here it is.

This has always been a joke within the community. Drupal has a high barrier to entry from a developer perspective. Drupal 8, even moreso than Drupal 7 which (IIRC) is the version that earned Drupal's place on this infamous image.

Because of this barrier, we've tried to make it possible for new contributors to get comfortable with contributing through issues that are tagged "Novice". These issues are often documentation, coding standards, or basic code fixes that can be handled by someone who may not have as much experience contributing to the project, whether it be the core Drupal project or contributed modules.

These novice issues are important to have. Sure, they may take some of the core maintainers or more advanced developers a few minutes to handle, but if they're not critical then there's no reason to not utilize them to help bring in new talent and give novice contributors a chance to get into the weeds a bit.

Looking through this person's issue credits, every single issue I found has been a novice issue. I did not take the time to look through all 570 credits to verify this, but my sample size was large and based on that sample, I'm willing to wager that the vast majority of these issues would have made for decent entry points for new contributors. With one person collecting all of the proverbial "low-hanging fruit" to pad their profile, this effectively gates new contributors from having the opportunity to help the project and removes upwards of 570 novice issues that would make perfect entry points for novices, not counting issues that have not been credited yet.

Reason 2.

In speaking with some other developers, it's demoralizing. This person was recently mentioned in a tweet as "the most impressive http://Drupal.org profile page I've ever seen". I'm not trying to say that these issues aren't important, and if they improve the project overall, then it's a good thing that they're being handled, but the process and the "reward" system makes it seem like the problems are larger than they really are.

Imagine this scenario, please: Developer A has taken the challenge to move from novice issues to something a little more advanced and spends twenty four working hours debugging an issue in core that is preventing an entity from saving under certain circumstances. They find the problem, discuss it with the core maintainers on Slack, toss ideas back and forth on the issue node, create a patch, create tests, submit the patch, wait for RTBC, and the patch gets committed. The project is made better because Developer A is passionate about Drupal, they spent their free time trying to improve Drupal, and when the patch is committed, they get credit for the issue. This credit is worn as a badge of honor on their profile. They feel pride in what they've done and what they've given back.

Developer A is scrolling through Twitter and sees mention of Developer B as "the most impressive http://Drupal.org profile page I've ever seen" and wants to know what their secret is. Developer A starts looking at the issues, and finds that the "impressive" profile is primarily novice issues that can be handled in a matter of minutes, yet they're the ones marked as "impressive". Developer A feels like their credit is devalued because the only thing seen on the profile is the number, not the number of issues by difficulty or number of lines in a patch, but number of issue credits.

Developer A decides that contributing back isn't worth their time because the only thing that seems to matter is the number of credits. Drupal loses a talented contributor, and the project is poorer for it.

Reason 3.

The Drupal Marketplace page puts weight on the number of contributions over the last 90 days in its ranking system. Outwardly, this would seem to reward companies who invest in improving the Drupal project, and it does. However, it also incentivizes companies who hire new developers who are just thrilled to have a job into positions that exist only for the sake of getting their company to the top of the marketplace. This is unfair to other companies who may not have the budget, but still contribute how they can, and it's unfair to the employee who is stuck searching for module releases, looking for novice issues, and copying and pasting descriptions and comments to get more and more credits.

In a sense, it's gating the employee from being able to move on from this position because even though they have 570+ credits, they've potentially never done anything past that. I'm not claiming that the person who sparked this conversation doesn't have skills, but churning out that many bug reports and quickfix patches doesn't really empower that person to show what they're really capable of. I know if I spent all day doing the same thing over and over, I definitely would not want to even look at a text editor on my free time, let alone feel that it would be worth it to try and expand my skill set.

Possible Solutions

There is no one-size-fits-all solution for this. Hell, there's probably no good solution at all. However, here are some ideas that I would like to throw out there that are just that, ideas. They're not fully fleshed out, and they aren't ultimatums of "Do this or I'm going to walk!" They're potential starting points and hopefully help to spark a larger conversation.

Solution 1: Weighted Credits

Not every credit should be worth the same as others. There could be a number of ways to do this, but in my opinion the easiest way would be to weigh by difficulty of the task. A novice, non-critical issue could be weighted less than an advanced, critical issue.

Pros:

Could incentivize contributors to move up in difficulty of tasks.
Gives contributors who spend a lot of time on difficult issues more credit than contributors who seek out the easiest fixes.
Rewards growth as a developer.

Cons:

Difficult to implement.
Creating a weighting system can be difficult and fairness cannot be guaranteed.
Valuation of an issue is subjective and could be gamed if a module maintainer decides to start tagging every issue as "Critical" or similar.

Solution 2: Mandatory Difficulty Tagging

The word "Difficulty" is difficult here. Some other possibilities would be "severity", "level of effort", "need", or any number of words that could be placed there. The point is that for this solution, I recommend creating a specific taxonomy that relates to difficulty or [insert word here] of the issue. This would be mandatory before marking an issue as fixed by the maintainer, whether it be a contrib module maintainer or a core committer. Then, on a user's profile credits could be divided by rating. For example: User Credited on 50 "Novice" issues, 3 "Intermediate" issues, 15 "Advanced" issues, and 3 "Critical" issues.

Pros:

Makes it easier to discern how much effort is actually being put into contributions.
More transparent for potential employers looking at d.o for references.
Creates a weight system without actually having to weight contributions.

Cons:

Puts the responsibility on module/core maintainers to assign difficulty, which can be very subjective.
Does not prevent a module maintainer from marking their own issue as "Critical" when it could easily be tagged "Novice"
Potentially devalues novice credits and gates new contributors.

Solution 3: Credit limits

I'm of the opinion that if someone has over 100 novice credits, they should probably be at a point where they are either taking on more serious issues and leaving the novice issues as entry points for new contributors. This solution would still require tagging of issues by maintainers, but instead of creating tiers based on difficulty it would limit the number of "novice" issues a contributor would receive credit points for. The number would have to be decided and I don't know if it should be 10 or 100. I'm just spitballing here.

Pros:

Incentivizes contributors to move on from novice issues.
Keeps novice issues for actual novices.
Creates more entry points for new contributors.

Cons:

May deter non-novice contributors from taking on novice issues that need to be done.
Again, module maintainers may tag issues inappropriately to ensure credit.
The term "novice" is very subjective and could easily be debated.

Solution 4: Redistribution of Credits

Sorry, my politics are showing on this one, but I don't mean take credits from the top 1% and give them to the bottom 25%. Instead, give others a chance to take on the tasks and open the gates to new contributors. The issues that are being created, fixed, and credited are issues, but they're mostly novice issues. My Google-fu returned over 20 pages with identical descriptions. I don't know exactly how many because I just stopped clicking "Next Page" when I hit about page 15, but it's safe to say that this person knows how to fix this issue.

Great. Good job. Now give someone else a chance!

If the goal of these issues is truly to move the project forward and not just farm credits like a World of Warcraft sweatshop circa 2008 CE, then let's get some new people contributing. Create the issue, tag it as novice, and let it be. Find an upcoming camp and tag it with that camp so that if there is a space for contribution and/or a beginning contributor workshop, there are plenty of issues to work on to help get the new contributors comfortable with the steps needed for code contribution. If it's critical, go ahead and fix it. If it's non-breaking and a good chance for someone to learn some git-fu, how to branch and create patches, how to comment in the issue queue, how to push up a patch in a comment, and the lifecycle of an issue from creation to RTBC to fixed, then let it be for a bit.

If there's no movement after a few days or after the camp it was tagged for, then go ahead and fix it. Sure, maybe the module maintainer will fix it in the meantime. Maybe it'll get marked as "Closed: Outdated" because it's already been taken care of on a dev branch that just hasn't made it up to d.o yet. Maybe, just maybe, a new contributor in the wild will be searching the issue queue for novice issues to get started and they'll take the reins on the issue and get their first credit. You may not get credit for authoring the issue, but you'll definitely get a warm fuzzy feeling for helping foster a new contributor into the world of Drupal. That's truly what building community is about.

Pros:

Gates are open for new contribution.
Knowledge is shared and the community grows stronger.
You can almost hear the DING when they level up into the world of open source contribution.

Cons:

Won't necessarily get credit for every issue created, but we shouldn't be here just for credits.
Issues may become stale and overlooked.
That's all I can think of...

Closing Thoughts

This post is not meant to attack any person or any company. If anything, I hope that it sparks some conversations and helps make the Drupal project richer and more diverse by helping spread the wealth of entry-level issues and credits to people who may or may not have opportunities otherwise. Since I began writing this post I've tried keeping an eye on things in the issue queues and I found that some people are taking the example from the account that got me thinking about this and running with it. I've even seen some people trying to patch core testing modules with the .info.yml Dependency Namespacing issue. Fortunately these were caught pretty early and core maintainers made it a point to redirect the issue reporter to fixing more than just one file in core in a patch.

The credit system is great and it rewards hard work, but the issue credit system has issues with credits and needs some work as well. I have brought this up to both the CWG and the DA and they're understandably in tough spots. Yes, fixing issues definitely makes the project better regardless of how small the issue is, but there are thousands upon thousands of developers out there just looking for a project to grab onto and start working with. We need to make it as easy as possible for these people to jump in and become part of the Drupal community. I travel for a lot of camps and, unfortunately, for the most part I see a lot of the same faces in the contrib rooms and areas. I would like to see some new people feel welcomed the same way I felt welcomed at my first contribution days when I was able to get my first patch committed to core. Sure, those maintainers could have taken care of the issue and taken credit for themselves, but instead they created the issue and passed it to me, an eager entry-level developer still trying to find my place in this crazy Drupal world.

We shouldn't have to rely on the CWG or DA to police these things. We should be able to police ourselves. We should be able to know if what we're doing is self-serving or if it for the betterment of the Drupal project and the Drupal community. We should be able to feel good about the credits we get and the credits we help others get. We should try our best to be good people and do the right thing whenever we can.

We shouldn't reward companies or individuals who hoard issue credits just to look better on the marketplace or in a wordcloud on a powerpoint. We can do better than that.

If you're a new developer or an aspiring contributor looking for something to do to contribute back to the project, contact me. I'll help you find an issue to work on and run you through the process of patching, commenting, testing, and whatever else it is that you need to succeed. I want to stress that you don't need to know how to code to contribute back to Drupal. Ask me how!

If you're a seasoned developer or contributor, I challenge you to mentor someone who's eager to learn. Give up a credit or two to someone who is looking for that first DING. Take the time and we'll all be better for it.

Sincerely,

JD Flynn, Drupal Developer and Community Member

Category

Tags

Damn you, DEV-MASTER!

jflynn — Mon, 27 May 2019 21:12:51 +0000

Damn you, DEV-MASTER! jflynn Mon, 05/27/2019 - 16:12

Category

Development

Tags

Drupal Planet

Drupal-Check, Site Factory, and Acquia BLT, OH MY!

jflynn — Wed, 08 May 2019 14:02:56 +0000

Drupal-Check, Site Factory, and Acquia BLT, OH MY! jflynn Wed, 05/08/2019 - 09:02

I was fortunate enough to attend DrupalCon Seattle this year, as well as give a presentation on mental health in tech, but one of the key topics of DrupalCon was Drupal 9 readiness. Dries mentioned it several times in the Driesnote and we even had some contribution efforts specific to Drupal 9 readiness at MidCamp 2019.

One thing that stuck out to me as particularly awesome was my friend and fellow MidCamp organizer Matt Glaman's drupal-check tool that will check your modules for deprecated code that is NOT ready for Drupal 9 being mentioned in the Driesnote. Additionally just as awesome was another good friend, Dwayne McDaniel getting a shoutout for going through EVERY. SINGLE. CONTRIB. MODULE. and running this tool against it. That's a lot of modules!

In case you didn't know, the upgrade path from Drupal 8 to Drupal 9 is supposed to be extremely easy. As someone who had to migrate from 7 to 8, this is welcome news. The TL;DR version is: Once there are backwards compatibility breaks, we're at a new version. What does this mean? It means that code that is marked as deprecated in 8 will NOT be in 9 and you can't upgrade from 8 to 9 if you're using this deprecated code. (I'm looking at you array())

The Problem(s)

Drupal Check is AMAZING! That's not a problem. The first problem is making sure that your code is ready to be checked by Drupal Check.

Issue 1 (Acquia Cloud Site Factory/Multisite)

We use Acquia Cloud Site Factory extensively at Genuine. This leads to many multi-site installs. Why is this an issue? Well, it's not unusual to have multiple profiles available on Site Factory. Often times, these profiles will be based off another one, but different in theme, look and feel, or functionality. This means that there is a chance that there will be some duplicated functions in the .theme file. Specifically, helper functions that may not fall into the _THEMENAME_function_name() convention and may be missed when you change everything around.

Fatal error: Cannot redeclare _my_poorly_named_function() (previously declared in /var/www/docroot/profiles/custom/profile_1/themes/profile_1_theme/profile_1_theme.theme:150) in /var/www/docroot/profiles/custom/profile_2/themes/profile_2_theme/profile_2_theme.theme on line 168

It happens. Stop looking at me like that.

Solution 1

Well, this is a pretty easy fix, again compliments of Matt Glaman and Will Long AKA Kerasai. You can either prefix the functions OR use namespaces!

<?php

namespace my_profile_name;

Your .profile files are autoloaded so the namespace will be valid. This prevents the error above.

Issue 2 (Acquia BLT)

This one is a doozy. Acquia BLT or Build and Launch Tool (as of 9.2) has a little command in it that checks for deprecated code, but the dependencies it uses are outdated and cause Drupal Check to fail before it gets anywhere.

blt tests:php:sniff:deprecated

This command depends on the package sensiolabs-de/deprecation-checker which has a dependency on nikic/php-parser:~3.0. Drupal Check requires nikic/php-parser:^4.0 due to the way it's built. Trying to run composer require nikic/php-parser:^4.0 will make composer yell at you. A lot.

Solution 2

This one gets a bit tricky. There are a few things that need to happen here if you're wanting to reap the benefits of Drupal Check, and trust me, you do.

In your base composer.json file there should be a couple of lines that look like this

        "merge-plugin": {
            "require": [
                "blt/composer.required.json"
            ],
            "include": [
                "blt/composer.overrides.json"
            ],

The composer.required.json file is in your blt/ folder and is autogenerated by BLT so it's not safe to change. The workaround for this is to copy the file to composer.required-modified.json and update the line below "require": [ to blt/composer.required-modified.json. The end result should look like this:

"merge-plugin": {
            "require": [
                "blt/composer.required-modified.json"
            ],
            "include": [
                "blt/composer.overrides.json"
            ],

Next, you will need to run the command composer remove sensiolabs-de/deprecation-detector This should remove the old package and update nikic/php-parser but if it doesn't, check in your new composer.required-modified.json file, make sure that Deprecation Detector is gone, and add in "nikic/php-parser": "^4.0" at the end of the "require-dev" section. DON'T FORGET YOUR COMMA!

Now you should be able to run Drupal Check without issues, but there's still one thing we need to take care of before saying we're done. That little BLT command from above blt tests:php:sniff:deprecated. If we try running it without the deprecation-detector package then we're going to have a bad time.

My workaround for this was to create a replacement command for BLT. This is done by using replace command annotation in a custom class. The BLT docs are here but they are lacking and caused me some headaches, so I've got some docs for you right here.

My custom command file lives in blt/src/Hooks/NoDeprecatedCommandHook.php. The name of the file and class needs two things:

It can't be the same as the class you're replacing.
It needs the word Hook at the end.

DeprecatedCommandHook.php will not work. NoDeprecatedCommand.php will not work. MyReplacementCommandHook.php will definitely work, so long as your class shares the same name, but let's stick with my own file here.

<?php

namespace Acquia\Blt\Custom\Hooks;

use Acquia\Blt\Robo\BltTasks;

/**
 * Defines commands in the "tests:php:sniff:deprecated*" namespace.
 */
class NoDeprecatedCommandHook extends BltTasks {

  /**
   * Detects usage of deprecated custom code.
   *
   * @hook replace-command tests:php:sniff:deprecated
   *
   * @aliases tpsd deprecated
   */
  public function detect() {
    $this->say("This command has itself been deprecated. Please use drupal-check for all of your deprecated code needs.");

    return 0;

  }

}

Let's walk through the file a bit

namespace Acquia\Blt\Custom\Hooks;

Without this line, it won't work It needs to be in this namespace or you're going to have a bad time.

use Acquia\Blt\Robo\BltTasks;

This is optional, but I used it to get the say() method available.

class NoDeprecatedCommandHook extends BltTasks {

Our class name. If you're using BltTasks, don't forget to extend it.

  /**
   * Detects usage of deprecated custom code.
   *
   * @hook replace-command tests:php:sniff:deprecated
   *
   * @aliases tpsd deprecated
   */

This is where the magic happens. @hook replace-command tells the system to forget about the original command, this one is driving now.

  public function detect() {
    $this->say("This command has itself been deprecated. Please use drupal-check for all of your deprecated code needs.");

    return 0;

  }

This is our function that does nothing more than tell us to stop using this function. Clever, right?

The end result is a functioning drupal-check and a function that tells its own deprecation.

➜  project git:(master) ✗ blt tests:php:sniff:deprecated
This command has itself been deprecated. Please use drupal-check for all of your deprecated code needs.

Conclusion

This is a pretty specific use case and hopefully Acquia BLT will be pushing out an update in the near future that doesn't require us to have to workaround much longer, but this works for us.

Please test the hell out of your project after making these updates. BLT should really only be used for local dev and deployment artifacts, but it's still worth noting what does and doesn't happen that might bork up your site.

Edit: BLT is going to be getting rid of the DeprecatedCommand function that is replaced in this post in the very near future from 5/8/19. That will help all of you out, but it also means that I spent way too much time typing this thing out. See: https://github.com/acquia/blt/pull/3621

Category

Tags

Connecting React to Drupal in a Progressive Decoupled App

jflynn — Thu, 18 Jan 2018 15:09:06 +0000

Connecting React to Drupal in a Progressive Decoupled App jflynn Thu, 01/18/2018 - 09:09

Keeping up with the times

ReactJS is all the rage these days, and for good reason. It's a great library, it's well known, it's well documented, and it's easy to jump into if you have any JavaScript experience. Between its nice learning curve and the ability to use JSX it makes sense to use it on applications that you want to be fast and scalable.

Headless is all the rage these days in the Drupal community, and for good reason. It gives Drupal the chance to do what it's best at, managing content. Sure, Drupal is great at other stuff, but the first two words of CMS are "Content" and "Management".

When we look back at the release of Drupal 8, we notice that one of the biggest pieces of D8 was a built in REST API with minimal configuration needed. This opened up a world of possibility for developers to merge the speed and scalability of JavaScript with the content management framework strengths of Drupal.

How Decoupled Should You Go

In a recent blog post, Dries goes into the Future of Decoupled Drupal. In it he mentions progressive vs fully decoupled. Personally, with a background specifically in Drupal and PHP and only a side of JavaScript, I prefer the progressively decoupled approach that keeps all the familiar parts of the Drupal ecosystem available, like the theme layer, the admin side, the block rendering engine, etc., but also allows the flexibility to render an app that uses React or Angular or any of the other libraries out there that can consume data from a REST API.

I have more familiarity with theming Drupal than anything, so that makes it less painful to build something with Drupal than it would if I were to try and build a SPA with a completely different front end that still consumes the Drupal data. For this post I'm going to be focusing primarily on a progressively decoupled solution.

My Progressively Decoupled Solution

The project that brought us to this involved a site that revolved around a single search app and we wanted it to be fast and easy to use, but there were other aspects to the site that would benefit from being Drupally. We needed blocks in certain places, a user configurable menu system, login/logout capabilities, and a decent content management side for users to enter content in a friendly way, but we also wanted to have some decoupled/headless elements using the ReactJS library.

For React to work inside Drupal, the React side needed something to hold onto, known as a Mount Node. To the Drupal dev, the term "mount node" can be misleading since nodes have a completely different meaning in the Drupal world, but in the React world, a mount node is a node in the DOM that the JavaScript side can grab onto and take control of. The index.js file contains the code that defines the expected ID of the mount node and it looks a little like this:

ReactDOM.render(<App />, document.getElementById('react-div'));

Where 'react-div' is the ID of the div that React will be mounting to. Essentially, the React app will take that div and inject all of its code inside of there as the parent of the React app's DOM. What does that mean for us in the Drupal world? Basically, we need to have a div somewhere inside a page for or Drupal node for the React app to grab onto.

There are a few different ways that we could handle this.

A custom twig file built specifically for a single use case
Full HTML body field in a Drupal node with a matching ID
A custom content type with a twig file
Probably more, but I don't like lists going longer than they should

For my project, I decided to use the third option: A custom content type with an associated twig file, and I wanted it to be reusable so I made a module for that, React Mount Node, and I contributed that module back to Drupal so that anyone can use it.

Thanks to the magic of Drupal Console I was able to quickly bootstrap everything that I needed for a module including the .module file, the .info.yml file, and a composer.json file in case I wanted to contribute the module back to the community.

After getting the base of the module setup, there were a few other things that needed to happen. Specifically, I needed a content type to be built within the module. Fortunately, there's a pretty simple way to do that outlined in this documentation. We need a config/install/node.type.<content-type>.yml in our module to give us some info about our new content type, and then we need our config to build out a content type. A few ways to do this are by exporting config and cleaning it up a bit by drush or through the UI, or we can use Drupal Console to do it. Either way, we need to make sure that the UUID gets stripped so we don't run into any errors.

Depending on how complex your content type is, you may only need do edit one or two files, maybe more. The important thing is that you look through and delete the UUID line in every relevant .yml file that comes from your new content type.

uuid: be001aff-1508-485c-916b-86062ebdb811 <<< GET RID OF ME
langcode: en
status: true

Drupal Console does this automatically when you export a content type.

The content type created by this module is called React Mount Node because it creates a node that you use to mount a React app. Get it? GET IT???

React Mount Node has three fields: Title, Div ID, and Library. The Title field is just for the title of the node that you're creating. The Div ID is where you set the ID that you're using inside of your React app that you set in index.js. The Library field is where you tell the module what library it should be looking for. We'll get to that in a moment.

If you're building the React side of things in addition to the Drupal side, you may notice that out-of-the-box, React spits code out using the naming convention app-name.hash.min.js. I highly recommend changing that to something a little more friendly. For the setup I use, create-react-app, I can do that inside of the webpack config file at the line in the output object array under filename that should look something like:

  output: {
    // The build folder.
    path: paths.appBuild,
    // Generated JS file names (with nested folders).
    // There will be one main bundle, and one file per asynchronous chunk.
    // We don't currently advertise code splitting but Webpack supports it.
    filename: 'path/to/your/libraries/react-app/react-app.js',
    chunkFilename: 'static/js/[name].[chunkhash:8].chunk.js',

It's my suggestion that you do this so that every time you compile your React app you don't have to change your libraries files. It's a pain. I speak from experience. Trust me.

This will give you a reusable filename to that you can, as the infomercials say, "SET IT AND FORGET IT!"

What this doesn't give you, however, is the actual library. In Drupal 8 we've changed from drupal_add_js() and drupal_add_css() to something a little more elegant. Libraries.

Creating and Connecting Your Library

Libraries are essentially collections of assets. If you look in your theme folder, you'll see a file that ends in .libraries.yml. This is true for every theme, including Bartik and Stark. The themename.libraries.yml file is where the libraries are built, at least those associated with that theme. It's slightly different for libraries defined in modules, but the base concepts remain the same. If you were inclined to place your compiled React app into a module, it would be a very similar procedure.

For our purposes though, we added the React app into the theme folder and defined the library in themename.libraries.yml. It looks like this

react-app:
  js:
    libraries/react-app/react-app.js: {}

This is where the Library field on our React Mount Node content type comes into play. Because we defined the library in our theme, the library name is themename/react-app and that's what we place in the field.

Another beauty of D8 is that we don't have to load every JS file on every page. That library will only be loaded on the node(s) it's attached to. How do we do this? Through the magic of twig. Twig allows us to attach a library on a per-node/page/block/site basis with one simple line of code:

  {{ attach_library(my_lib) }}

That's the line from the twig file that's used to render the React Mount Node content type and it tells Drupal to attach this library to this node that has this ID. The end result is a React app living inside of a Drupal node.

This is really the tip of the iceberg though. With this module and the flexibility of React and a REST API we're able to do a ton of stuff. I highly suggest getting to know the Fetch API that makes getting data a breeze and learning more about how to setup Drupal as a REST endpoint.

I'll be doing posts in reference to the REST API, normalization, and one of my new favorite things -- REST Flagging in the near future. In the meantime, what excites you the most about going decoupled with Drupal?

Category

Tags