Adding GraphQL Queries and Fragments to a Custom Handlebars Component

GraphQL is the primary way for you to retrieve the community data to use for your Handlebars component.

If you want to use GraphQL, we highly recommend you check out Learn GraphQL documentation on the GraphQL site.

You can either manually add a styling or use a GraphQL mutation to upload GraphQL queries and fragment files.

For GraphQL queries and fragment files, the query file names should end in .query.graphql format and fragment file names should end in .fragment.graphql format respectively.

An import line can be used to import fragment files into a Query file. If you want to import a component-specific fragment, perform the following:

#import "UserView.fragment.graphql"

If you are importing a common fragment (one that can be used by more than one component), use this import (prefixed with components/).

#import "components/UserView.fragment.graphql"

When the query is run, GraphQL will display an error regarding unused fragments if all of the fragments contained in the imported fragment file are not used in the query file that imported them.

Uploading a GraphQL file for a component via GraphQL

To upload GraphQL query files, you can use two GraphQL mutations:

• Uploading a common fragment or query file that any component can use.
• Uploading a fragment or query file that will only be used by one component.

Uploading a common GraphQL file

To upload a common GraphQL file, you must call the saveCommonGraphQLQueryAssetFromUpload mutation. This mutation should be made as a multipart/form-data request with a file.

Here is an example cURL script that uploads a GraphQL fragment (.fragment.graphql) file.

curl --location 'http://doug-schroeder.mac.qa.lithium.com:8080/lithosphere/api/2.1/graphql' \
--header 'Authorization: Bearer exampleVMkBztKC7dqy40hFQQF66hV+pGotPHG8U=;' \
--header 'Content-Type: multipart/form-data' \
--form 'operations="{ \"query\": \"mutation($assetId: String!, $assetPart: Upload!) { saveCommonGraphQLQueryAssetFromUpload(assetId:$assetId   assetPart: $assetPart){result {name directoryName subDirectoryName feature size lastModified revision mimeType url } errors {...on Error { message fields }}}}\", \"variables\": { \"assetId\": \"UserView.fragment.graphql\", \"assetPart\": null} }"' \
--form 'map="{\"file\":[\"variables.assetPart\"]}"' \
--form 'file=@"UserView.fragment.graphql"'

You can upload a .fragment.graphql or .query.graphql file from the preceding example, and it will be available for use in any component's handlebar template.

Uploading a GraphQL file for a specific component

You should use the saveComponentGraphQLQueryAssetFromUpload mutation to upload a component-specific GraphQL file. This mutation should also be sent as a multipart/form-data request accompanied by a file.

Here is an example curl script that uploads a GraphQL Query (.query.graphql) file.

curl --location 'http://community.mine.com/t5/s/api/2.1/graphql' \
--header 'Authorization: Bearer exampleSVMkBztKC7dqy40hFQQF66hV+pGotPHG8U=;' \
--header 'Content-Type: multipart/form-data' \
--form 'operations="{ \"query\": \"mutation($templateId: String!, $assetId: String!, $assetPart: Upload!) { saveComponentGraphQLQueryAssetFromUpload(templateId:$templateId assetId:$assetId   assetPart: $assetPart){result {name directoryName subDirectoryName feature size lastModified revision mimeType url } errors {...on Error { message fields }}}}\", \"variables\": {\"templateId\": \"TopKudoers\", \"assetId\": \"Users\", \"assetPart\": null} }"' \
--form 'map="{\"file\":[\"variables.assetPart\"]}"' \
--form 'file=@"Users.query.graphql"'

You can upload a .fragment.graphql or .query.graphql file this way, and it will be accessible exclusively to the component for which it was uploaded.

Adding a GraphQL file for a component manually

There are two types of file you need to manually add to the Git repository to add the GraphQL queries for the components to use:

• A query file that concludes with a file extension .query.graphql
• A fragment file that concludes with a file extension .fragment.graphql

There are two places where you can place a query or fragment file depending on whether you only want to utilize it for a specific component or for more than one component:

• If you want to use a query or fragment for a specific component, you would place the query or fragment to a queries directory under the component directory. For our example component, it would be placed in the components/TopKudoers/queries directory.
• If you want to utilize a query or fragment that any component can use, you would place it to the components/queries directory.

Adding a common GraphQL file

All query and fragment files that will be used in multiple components should be placed in the components/queries directory. If it's a query file, the file name should end with .query.graphql, and if it's a fragment file, it should end with .fragment.graphql.

For our example, we will add a fragment file that we can re-use in other components, named UserView.fragment.graphql.

fragment UserView on User {
  id
  uid
  login
  registrationData {
    status
  }
  avatar {
    url
  }
  messagesCount
  solutionsCount
  kudosGivenCount
  kudosReceivedCount
}

Adding a component-specific GraphQL file

All component-specific GraphQL query or fragment files should be placed in the queries directory, which is located in the same directory as the handlebar (.hbs) template file, which is located in the components directory and is named after the component template's ID.

If it's a query file, the file name should end with .query.graphql, and if it's a fragment file, it should end with .fragment.graphql.

If the ID of your component is TopKudoers, then the handlebars markup is placed in the /components/TopKudoers/TopKudoers.hbs and your component GraphQL files would be placed in the /components/TopKudoers/queries directory.

For our example component, we add a component-specific query named TopKudoers.fragment.graphql that imports the common UserView.fragment.graphql query.

#import "components/UserView.fragment.graphql"
 
query TopKudoers {
  users(
    sorts: {
      kudosReceivedCount: { direction: DESC, order: 2 }
      messagesCount: { direction: DESC, order: 3 }
    }
    first: 5
  ) {
    edges {
      node {
        ...UserView
      }
    }
  }
}