Calling Trackunit GraphQL API
Beta
This is a beta version and subject to change without notice. Pricing, terms, conditions and availability may change in the final version.
Trackunit exposes a GraphQL API to create your query and we also expose an NX executor to make it easy to query our GraphQL API inside your Iris App extension.
In this example, we will use a Query for asset information.
1. Open a Terminal or Command Window and enter:
npm install @trackunit/react-graphql-tools
2. Add "graphql-hooks" to targets
Assuming you have already created an extension - go to the root of that project (like libs/[feature-name]/[name-of-your-extension]/ ) otherwise follow this guide and open the project.json
and add to the targets node:
"graphql-hooks": {
"executor": "@trackunit/react-graphql-tools:createHooks"
},
3. Add "codegen.ts" to lib
Now go to the root of that project (like libs/[feature-name]/[name-of-your-extension]/ ) and create a file called 'codegen.ts' and add this code to it:
import { type CodegenConfig } from "@graphql-codegen/cli";
import { getGraphqlCodegenConfig } from "@trackunit/iris-app-build-utilities";
const config: CodegenConfig = {
...getGraphqlCodegenConfig(__dirname),
};
export default config;
4. Create Graphql Query
Now you are ready to create React hooks from your GraphQL queries, just copy your query or the below query to your src folder in the libs/[feature-name]/[name-of-your-extension]/src and name it demo.graphql
query GetAssetsByProductionYear($first: Int, $productionYears: [String!]) {
assets(first: $first, filters: {productionYears: $productionYears}) {
payload {
productionYear
model
brand
}
}
}
5. Generate React Hooks
Call this command:
nx run [feature-name]-[name-of-your-extension]:graphql-hooks
6. Use it in your React code
Now that it has generated a folder with generated files in your src folder you can use it in your React code. The syntax takes the form <YOUR_QUERY>Document.
In the above example GetAssetsByProductionYear
will translate into GetAssetsByProductionYearDocument
import { useQuery } from "@apollo/client";
import { GetAssetsByProductionYearDocument } from './generated/graphql-api/graphql';
const { data, loading, error } = useQuery(GetAssetsByProductionYearDocument, {
variables: {
// Any variables your query requires
},
});
7. You are now ready to call GraphQL using hooks
For more advanced info on the executor you can read up on how to generate code from GraphQL codegen cli
Example: Full React Component (App.tsx)
import { useQuery } from "@apollo/client";
import {
Card,
Text,
Spinner,
Heading,
} from '@trackunit/react-components';
import { GetAssetsByProductionYearDocument } from './generated/graphql-api/graphql';
export const App = () => {
const { data, loading, error } = useQuery(GetAssetsByProductionYearDocument, {
variables: {
first: 5, // Take first 5 results
productionYears: ["2017", "2023"] // Filter by these production years
},
// skip: <some_assetId>,
context: {
headers: { // Your http-headers here
//"TU-PREVIEW": "TIME-EXCAVATORS,JUNGLE-DIGGER", // enables speicifc properties that are in preview only
},
},
});
return (
<div className="w-full h-full grid place-content-center">
<Card className="w-full">
{loading && <Spinner centering="centered" />}
{error && <div>CRASHED: {error.message}</div>}
{data &&
<div>
<Heading variant="primary">We can now use useGetAssetsByProductionYearQuery</Heading>
{data?.assets?.payload?.map((asset, index) => (
<Card key={index}>
<Text>Brand: {asset.brand}</Text>
<Text>Model: {asset.model}</Text>
<Text>Year: {asset.productionYear}</Text>
</Card>
))}
</div>
}
</Card>
</div>
);
};
Nice to know
The generated
graphql-hooks
employ the Apollo library to interact with the GraphqlAPI. In addition to the options demonstrated in the above example, such asvariables
,skip
, andcontext
, there exist various other options. You can find a comprehensive list of these options in the Apollo Docs.
Nice to know 2!
In the complete example mentioned above, we have commented out the HTTP header
TU-PREVIEW:<codeword(s)>
.
Certain GraphQL objects are currently in a preview state and may undergo changes without prior notice.
To indicate your acceptance of these terms, include the HTTP headerTU-PREVIEW:<codeword(s)>
in your query requests.
The specific codeword varies for each preview object and can be found by referring to the GraphQL Explorer.
You can include one or more comma-separated codewords.
Updated 12 days ago