Build an extension​

A Checkout UI Customizer is an extension that allows you to customize and enhance the checkout process for online stores. Merchants can integrate the extension at specific extension points on the checkout page to add features such as product recommendations or promotions, potentially increasing sales.

This article guides you through creating, publishing, and adding a Checkout UI Customizer to an online store.

Prerequisites​

Before you begin, ensure that you meet the following requirements:

• You have created a SHOPLINE public app, and the app has passed the review process and is now available on the SHOPLINE App Store.
• You have installed the SHOPLINE CLI.

Extension commands​

The following table outlines the commands necessary for creating a Checkout UI Customizer. You can also use the sl help extension command to review the full list of available commands.

Extension development​

Step 1: Log in to the store​

1. Run the following command in your terminal. Replace example.myshopline.com with your actual store domain name. You will be automatically redirected to your SHOPLINE Admin.

sl login --store={example.myshopline.com}

2. Follow the prompts in the browser to complete the login process.

Step 2: Create an extension​

1. Run the following command in your terminal. You can use --name to specify the extension name.

sl extension create --name={name}

2. Select the extension type Checkout UI Customizer according to the prompts in the terminal.
3. Select the partner organization.
4. Select the app that you would like to register the extension with.
5. Wait for the dependencies to be installed. After installation, you can begin developing the extension.

Step 3: Connect the extension (optional)​

If you already have an extension and you want to use it for the current project, connect it by following these steps:

1. Run the command sl extension connect in your terminal.
2. Select the partner organization.
3. Select the extension you want to connect to.

Step 4: Develop the extension​

Directory structure​

The extension directory structure mainly includes three parts:

• locales: multilingual content
• src: extension source code
• shopline.ui.extension.toml: configuration file

+-- locales
|   +-- en.default.json
|   +-- fr.json
+-- src
|   +-- index.tsx
+-- shopline.ui.customizer.toml

locales​

Store multilingual content in the locales/{iso_code}.json files. The default language file is en.default.json. Language content should be formatted in key-value pairs as shown in the following example.

{
  "welcome": "Welcome to the {{extensionPoint}} extension!"
}

Configure locales for your extension when you need to support content in multiple languages.

For example, the file path for German is locales/de.json. The configuration for the file is as follows.

{
  "welcome": "Willkommen bei der {{extensionPoint}} Erweiterung!"
}

shopline.ui.extension.toml​

This configuration file contains the basic information of the extension, including the extension name, supported extension points, and extension capabilities. For more information about how to configure the file, refer to Configuration file.

src​

Develop the extension using the extension APIs and UI components.

The following example shows how to use the i18n multilingual capability to render text in a Banner component.

render('Checkout::Dynamic::Render', (props) => {
  const { i18n, extension } = props;
  const { extensionPoint } = extension;
  return <Banner title={i18n.translate('welcome', { extensionPoint })} />;
});

Step 5: Preview the extension​

1. After you complete developing the extension, run the following command under the extension directory to preview your work.

sl extension serve

2. Click the last URL output in the terminal to preview the extension.

Step 6: Release the extension​

1. Push the extension using the following command. The SHOPLINE CLI will compile your extension code and push the compiled results.

sl extension push

2. After the extension is pushed successfully, follow the prompt to click the URL to publish the extension in the SHOPLINE Admin.

3. In the SHOPLINE Admin, create an extension version first. Then click Publish under Operation to release the new extension version.

Extension activation​

Step 1: Install the extension app​

1. Go to the SHOPLINE Admin.
2. Find and click the Apps module in the left menu.
3. Go to the App Store by clicking Go to App Store in the top right corner.
4. Find the extension app and install it.

Step 2: Add the extension to the checkout editor​

1. Go to Settings.
2. Find and click Checkout Settings.
3. Click Customize checkout under Theme configuration.
4. In the dropdown menu at the top, select a specific checkout page where you want to add the app extension.
5. Go to the Checkout App module as shown in the following figure and click Add an app.
6. Select and click the target app that you want to add to the checkout page.

Step 3: Test the extension in the store​

1. After successfully adding the app to the checkout page, you will find the Checkout UI Customizer in the checkout editor. Drag the extension to adjust its position to test if it applies as expected.
2. Once you confirm the extension's position, click Save.
3. Click View online store to check if the extension aligns with your expectations.

Extension example​

The following code and image examples shows how to customize an image display component.

Code example​

interface ItemProps {
  image: string;
  name: string;
  price: string;
}
interface GridBoxProps {
  title: string;
  children: any;
}
function BasicItem({ image, name, price }: ItemProps) {
  return (
    <Grid rows={'auto'} blockAlignment="start" columns={['auto', 'fill', 'auto']} spacing="base">
      <ItemThumbnail size="small" src={image}></ItemThumbnail>
      <BlockStack spacing="tight">
        <Text emphasis={"bold"}>{name}</Text>
        <Text emphasis={"bold"}>{price}</Text>
      </BlockStack>
      <View>
        <Button size="small">Add</Button>
      </View>
    </Grid>
  );
}
function GridBox({title, children}: GridBoxProps) {
  return <>
    <Grid rows={[20, 'auto']} columns={'fill'} spacing="base" padding={['none', 'none', 'base', 'none']}>
      <View>
        <Text size="large">{title}: </Text>
      </View>
      <GridItem>
        <Grid
          border="base"
          rows={['auto', 'auto', 'auto']}
          spacing="base"
          padding="base"
          cornerRadius="base"
        >
          <View>
            <Text emphasis="bold" size="medium">
              Best Sellers
            </Text>
          </View>
          {children}
        </Grid>
      </GridItem>
    </Grid>
  </>
}
// Customized implementation of product display
function AddToCartDemo() {
  const productList = [
    {
      image:
        'https://img-va.myshopline.com/image/store/1610440173818/01c5f3bf41533f63207f67ce922c3134865e9bfd.png?w=1056&h=1056',
      name: 'Scarlet Dream Duo - Black',
      price: '$500.00',
    },
    {
      image:
        'https://img-va.myshopline.com/image/store/1610440173818/5d55aa39c28c87881aece99f75d820b1b2db476b.png?w=1056&h=1056',
      name: 'Scarlet Dream Duo - Black',
      price: '$500.00',
    },
  ];
  return (
    <>
      <GridBox title="Basic">
        {productList.map((item, index) => {
            return (
              <BasicItem key={index} image={item.image} name={item.name} price={item.price} />
            );
          })}
      </GridBox>
    </>
  );
}
// Render the corresponding extension point
render("Checkout::Dynamic::Render", (props) => {
  return <AddToCartDemo/>
});

UI effect example​