Orchard Core CMS GraphQL using GraphiQL

Orchard Core Developer

GraphQL was recently added to Orchard Core CMS and I have been eager to try it out. Turns out the development team made this really easy to try by including GraphiQL in the Orchard Core Administrator Dashboard. GraphiQL is a graphical interactive in-browser GraphQL IDE that allows developers to easily create and experiment with various queries without having to use the API. In this tutorial I will discuss GraphQL and GraphiQL in Orchard Core CMS. In later tutorials, I will explore more advanced queries and the GraphQL APIs.

The Agency Theme

I will be using The Agency Theme with GraphiQL and GraphQL in Orchard Core CMS, because The Agency Theme has a rich homepage of type Landing Page that gets created during setup. The Landing Page Content Type has several named BagParts that include various other Content Types that we can explore to our heart's content. Below is a partial screenshot of the Landing Page Content Type Definition in The Agency Theme. Services, Portfolio, About, Team, and Clients are all named BagParts that serve as a collection of other content items, and it's the richness of these types, parts and fields that make it a good candidate for practicing GraphQL and GraphiQL.

LandingPage Content Type in The Agency Theme in Orchard Core CMS

When creating and editing the homepage you will see the BagPart collections and their content items. Below is a partial screenshot of two of the BagParts, Portfolio and About from the homepage. Portfolio is a collection of Project Content Items and About is a collection of Milestone Content Items. I'll be focusing on the Portfolio in this Orchard Core CMS tutorial.

BagPart ContentParts for the LandingPage Content Type in The Agency Theme in Orchard Core CMS

When I expand a Project Content Item in the Portfolio BagPart, I can see a treasure trove of parts and fields that make up the Content Item. There is Title Part, an HtmlBodyPart, a Text Field, and a Media Field that we can query using GraphQL and GraphiQL.

Project Content Item in The Agency Theme in Orchard Core CMS

GraphQL and GraphiQL in Orchard Core CMS

Now that we have a good grasp of the Landing Page Content Type in The Agency Theme, it's time to enable GraphQL from the Admin Dashboard in Orchard Core. Choose Configuration -> Modules and enable the GraphQL feature.

GraphQL Feature in Orchard Core CMS

Enabling GraphQL adds an additional menu item in the Admin Dashboard under Configuration, called GraphiQL. Selecting GraphiQL displays GraphiQL in the browser. If you don't have any past saved queries in the GraphiQL history, it will display a welcome message with a few tips and tricks. If you have used GraphiQL in the past, it will display the last query.

GraphiQL in Orchard Core CMS

Using GraphQL in Orchard Core CMS

Let's jump right into our first GraphQL Query in Orchard Core. I want to query all the Landing Page Content Items and display their titles (displayText). According to The Agency Theme Setup Recipe, I should have 1 Landing Page Content Item and it should be titled the same as my website, which I called Test.

First GraphQL Query in Orchard Core

When I run the query it indeed shows 1 Landing Page with a title of "Test." Let's drill deeper into the homepage. We know it has several BagParts that serve as a collection for other content items. Let's query the Portfolio BagPart, which is a collection of Project Content Items. Let's get the titles of those projects as well as some of their metadata, like ContentItemId, ContentType, etc.

This may seem like a lot to type and remember, but GraphiQL will assist you in constructing the queries, which makes this a breeze. A BagPart was named Portfolio and as you begin typing in GraphiQL it will display portfolio as an option.

GraphQL Intellisense in Orchard Core

As I begin to type displayText GraphiQL will assist me in finding it as well as other options.

GraphiQL Intellisense in Orchard Core CMS

In a matter of seconds we have our GraphQL Query displaying a list of projects in the portfolio with the information of our choice.

{
  landingPage {
    portfolio {
      items {
        contentItemId
        contentType
        displayText
        published
      }
    }
  }
}
{
  "data": {
    "landingPage": [
      {
        "portfolio": {
          "items": [
            {
              "contentItemId": "4k40qjds6wzf1zyverpk0yrhmg",
              "contentType": "Project",
              "displayText": "Threads",
              "published": false
            },
            {
              "contentItemId": "4gsfqv9renjdzvt6f0nf3gqvc7",
              "contentType": "Project",
              "displayText": "Explore",
              "published": false
            },
            {
              "contentItemId": "47ddfjjn4ankfwmq3jp0rxk5dy",
              "contentType": "Project",
              "displayText": "Finish",
              "published": false
            },
            {
              "contentItemId": "4ffz6hgz3d4fxr606a855b9cmz",
              "contentType": "Project",
              "displayText": "Lines",
              "published": false
            },
            {
              "contentItemId": "4etpm8swc1t1e2p0hzcw1exgm7",
              "contentType": "Project",
              "displayText": "Southwest",
              "published": false
            },
            {
              "contentItemId": "48a15fbfpp3jk57trc43dn7qmr",
              "contentType": "Project",
              "displayText": "Window",
              "published": false
            }
          ]
        }
      }
    ]
  }
}

We can dive even deeper into those projects that make up the portfolio. Let's display the HTMLBody, Category, and Image path/url of each project. We have to provide GraphQL a little hint that the content items in the portfolio are Project Content Types to access their specific properties by adding ... on Project to the query.

{
  landingPage {
    portfolio {
      items {
        title: displayText
        ... on Project {
          content: htmlBodyPart {
            html
          }
          category
          image {
            paths(first: 1)
            urls(first: 1)
          }
        }
      }
    }
  }
}

Here are the results of the query (showing only 1 project for brevity).

{
  "data": {
    "landingPage": [
      {
        "portfolio": {
          "items": [
            {
              "title": "Threads",
              "content": {
                "html": "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Est blanditiis dolorem culpa incidunt minus dignissimos deserunt repellat aperiam quasi sunt officia expedita beatae cupiditate, maiores repudiandae, nostrum, reiciendis facere nemo!"
              },
              "category": "Illustrations",
              "image": {
                "paths": [
                  "/portfolio/01-full.jpg"
                ],
                "urls": [
                  "/media/portfolio/01-full.jpg"
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

If you haven't already, I recommend you create a new Orchard Core CMS website using The Agency Theme and try these GraphQL queries for yourself. In addition to querying the Portfolio BagPart, try querying the other BagParts using the same techniques as described in this tutorial.

In subsequent tutorials, I will discuss queries more in detail and explore the Orchard Core GraphQL APIs.