Getting started with admin blocks
This guide is the second part in a three-part tutorial series on how to build a feature using admin action and block extensions. Before starting this guide, you'll need to build or copy the admin action extension from the first guide in the series.
What you'll learn
Anchor link to section titled "What you'll learn"In this tutorial, you'll learn how to do the following tasks:
Create an admin block extension that displays on resource or index pages in the Shopify admin
Fetch information to populate the extensions's initial state
Connect the extension to the admin's contextual save bar when gathering input, to make editing pages seamless
Launch admin action extensions from your admin block extension
Run the extension locally and test it on a development store
Requirements
Anchor link to section titled "Requirements"You've created a Partner account and a development store.
Your app is using Shopify CLI 3.48 or higher.
You've completed or copied the code from the first guide in this tutorial series, which teaches you how to create an admin action.
Step 1: Create a new extension
Anchor link to section titled "Step 1: Create a new extension"To create your admin block extension, you can use Shopify CLI to generate a starter extension.
Navigate to your app directory:
Run one of the following commands to create a new admin block extension:
The command creates a new extension template in your app's `extensions` directory with the following structure:
Step 2: Write the extension's UX and display initial data
Anchor link to section titled "Step 2: Write the extension's UX and display initial data"Complete the following steps to write the extension's UX and display initial data:
Review the configuration
Anchor link to section titled "Review the configuration"The extensions .toml file stores the extension's static configuration. To have the issue tracker display on product detail pages, set the target to admin.product-details.block.render. For a full list of targets and the locations where they display in the Shopify admin, refer to the admin extension configuration reference.
To update the display name when users select the block from menus, in locale files edit the corresponding name value.
Create the UI and populate it with data
Anchor link to section titled "Create the UI and populate it with data"You can use admin UI extension components to build the admin block. For a list of all the available components and their props, refer to the admin UI extension component reference.
You can view the source of your extension in the src/BlockExtension.jsx file. This file defines a functional React component that's exported to run at the extension's target. You can create the extension's body by importing and using components from the @shopify/ui-extensions-react/admin package.
To begin writing the block, you'll intitially need to populate the block with the existing issue data. To achieve this, you'll use direct API to query the metafield. You'll use the metafield data to populate a paginated list in the block. Paginating the issues prevents the block from becoming too tall and difficult for users to interact with.
When you create the block extension, you'll use the i18n API to translate strings so that your app is more accessible to a wider audience. This API gives you access to the strings stored in the locale files, and automatically chooses the correct string for the current user's locale.
Add the following code, that demonstrates this, to your block.
Step 3: Create backend data and integrate with the page's contextual save bar
Anchor link to section titled "Step 3: Create backend data and integrate with the page's contextual save bar"Next, you'll create a Status dropdown and a Delete button that enables users to either mark issues as completed or remove them entirely. When you create the Status dropdown, you'll integrate it with the page's contextual save bar. This enables users to save changes to your block using the same controls that they would use to save changes to other fields in the Shopify admin.
To add these features, modify your block to match the following code:
Step 4: Add a button to open your action extension form
Anchor link to section titled "Step 4: Add a button to open your action extension form"Finally, you'll add a button that lets users create new issues directly from the block extension so that they don't have to navigate to More actions at the top of the page. This button launches the same action extension that you've already written, so you don't have to duplicate your code. Do this by using the navigate API to navigate to extension:{extension-handle}. The extension handle is defined in your extensions shopify.extension.toml file. In the third part of this tutorial series, you'll learn how to pass data along with this navigation to enable editing.
To add the button, modify your code to match the following example:
Step 5: Test the extension
Anchor link to section titled "Step 5: Test the extension"After you've built the extension, test it with the following steps:
Navigate to your app directory:
To build and preview your app, either start or restart your server with the following command:
Press
pto open the developer console.In the developer console page, click on the preview link for the issue tracker block extension.
The product details page opens. If you don't have a product in your store, then you need to create one.
To find your block, scroll to the bottom of the page. It should display the issues that you've created so far.
When you change the status of an issue, the contextual save bar should display. The change is saved when you click the Save button.
- Complete this tutorial series by learning how to connect action and block extensions to enable issue editing.
- Learn about the surfaces in the Shopify admin where you can create admin extensions.
- Learn about the full set of available components for writing admin UI extensions.