Shopify Embedded App User Interface Options

The Shopify Embedded App SDK provides a way for Shopify apps to be placed seamlessly within the Shopify admin section.

In this post, I’ll walk you through the various Shopify Embedded App user interface options with examples of how they work.

We’ll cover the following topics:

• The main embedded app iframe
• The top bar
• Modal dialogues
• Flash messages
• Shopify admin links

The main embedded app iframe

Embedded Shopify apps are displayed directly within the Shopify Admin via an iframe. In the above example, i’ve added a blue border around the iframe portion of the page. This iframe is able to expand horizontally as much as needed and scroll bars will be shown.

Here is the code used to create the above page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<style>
  #app-wrapper {
    border: 10px solid mediumblue;
    padding: 20px;
  }
</style>

<div id="app-wrapper">
  <h1>Embedded App - Main Section</h1>
  <p>This is being rendered within an IFRAME</p>
</div>

<script src="//cdn.shopify.com/s/assets/external/app.js?2016021109"></script>
<script type="text/javascript">
  ShopifyApp.init({
    apiKey: "...",
    shopOrigin: "..."
  });
  ShopifyApp.ready(function(){
    ShopifyApp.Bar.initialize({});
  });
</script>

This iframe can serve any page for an embedded app directly your application’s servers. This means you can put just about any content within this iframe.

However, pages within an iframe have a few limitations such as not being able to communicate directly with other parts of the containing web page. As we’ll see in the following sections, the Shopify Embedded App SDK provides tools to allow embedded apps to work around some of these limitations.

The top bar

The top bar above the embedded app iframe is made up of several components:

• An icon
• The title
• Breadcrumbs
• Primary and secondary buttons
• Pagination links

The Shopify Embedded App SDK allows each of these to be modified via the provided Javascript library. Here is the code used to build the above top bar:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
ShopifyApp.Bar.initialize({
  title: "A Different Title",
  icon: "chart.png",
  buttons: {
    primary: {
      label: "Save",
      message: 'bar_save'
    },
    secondary: [
      { label: "Help", callback: function(){ alert('help'); } },
      { label: "Menu",
        type: "dropdown",
        links: [
          { label: "Update", href: "/update", target: "app" },
          { label: "Delete", callback: function(){ alert("destroy") } }
        ]
      },
      { label: "Home", href: "/" }
    ],
  },
  pagination: {
    next: {
      href: "/posts?page=2"
    },
    previous: {
      callback: function(){ alert('no previous pages') },
      loading: false
    }
  },
  breadcrumb: {
    label: "Breadcrumb",
    href: "/example",
    target: 'app',
    loading: false
  }
});

For more details on the different top bar options available, check out the Embedded App SDK docs.

Modal dialogues

Shopify embedded apps can also display modal popups like the one shown above to interact with the user. This modal was generated by using the following Javascript from within the embedded iframe:

1
2
3
4
5
6
7
8
ShopifyApp.Modal.confirm({
  title: "Hello",
  message: "Would you like to play a game?",
  okButton: "Yes, let's play",
  cancelButton: "No, the only way to win is to not play",
}, function(result){
  alert("Result: " + result);
});

There is support for 4 different types of modal dialogues:

• ShopifyApp.Modal.open is a general modal window that allows any content to be displayed. Under the covers, this uses an iframe inside of the modal window, similar to the main iframe approach.
• ShopifyApp.Modal.alert displays an alert dialogue to communicate important information to the user.
• ShopifyApp.Modal.confirm displays a confirmation dialogue with two options. This is the modal used in the above example.
• ShopifyApp.Modal.input displays a single input field to capture data from the user.

Flash messages

Shopify provides a way to briefly display (a.k.a - flash) messages to the user. This message will be shown at the bottom of the screen for a few seconds before disappearing. A flash message would typically be used after a user initiated action such as submitting a form.

There are two types of flash messages available:

• ShopifyApp.flashNotice for displaying general information such as a successful form submission.
• ShopifyApp.flashError for displaying error messages, such as an invalid form submission.

Here is the code to generate a flash notice:

1
ShopifyApp.flashNotice("You did great!")

And this how the flash notice is displayed:

Here is the code to generate a flash error:

1
ShopifyApp.flashError("Something bad happened.");

And this is how the flash error is displayed:

Shopify admin links

Shopify apps may also optionally configured to have custom admin links. These admin links will be displayed within a specific section of the Shopify admin, such as on Collection or Product pages.

In the Shopify app settings, there is a section to configure shop admin links as shown here:

In this example, I’ve setup a link to add a new best sellers collection which will be shown from the collection overview section of the Shopify admin like so:

There are many different types of admin links you can create. Here is a listing of the available admin link options:

Summary

Using the Shopify Embedded App SDK provides a nice, seamless experience for users of your app.

Let’s recap what was covered in this post:

• Embedded apps can show any page within an iframe directly within the Shopify admin.
• The app can customize various elements of the top bar above the iframe such as the icon, title, breadcrumbs and buttons.
• Modal dialogues can be used to interact with the user outside of the iframe.
• Flash messages provide a way to communicate feedback to the user based on actions performed.
• Shopify admin links allow an app to add context-sensitive actions within other sections of the Shopify admin UI.