Fork me on GitHub

Summary

Introduction

A small introduction of the framework

This framework is built and updated by microapps based on the layout of Shopify merchant admin, as well as its embedded applications, in order to help the developers to easily and quickly write the application's frontend so that it has the same look and feel as Shopify merchant admin.

The documentation follows the framework interface and it is divided by sections, which are organized in rows and cells. In which section it is possible to see the elements that are being described by the framework as well as the code used to generate such elements.

For the most complex structures, a brief explanation will be given along with the sample and the snippet, while for the simple elements, they along with the snippet are self explanatory

The legacy apps, nowadays the most common among all apps available for installation for Shopify stores, are apps that, when accessed through the merchant's store admin, open in a new window or tab, as total "independent" (considering the user experience) application, even though it is obviously tightly related to Shopify in terms of funcionality and use of information.

Because of this, in order to improve the user experience, Shopify has given the application developers the possibility to develop embedded applications or, in other words, Shopify now allows developers to embed their applications directly inside Shopify admin as well as access and customize many native GUI features.

Check the following list of apps available for installation, in order to take a look at a real embedded app using SEAFF:

If your Shopify app uses SEAFF and you want it to be listed here, just fork the project, add your app and do a PR against master.

To build an embedded app using SEAFF, there are 3 main files involved in the job

  • SEAFF (Shopify Embedded App Frontend Framework) css file - has all the elements needed to build a good looking embedded application
  • EASDK (Embedded App SDK) js file - has all the elements needed to build a good looking embedded application
  • Your project HTML files - has to follow the structures defined and explained in this document in order to be well rendered into a very good-looking embedded application.

This is essentialy a CSS framework, so in order to use it, all you have to do is to add seaff.css to your application page(s), as shows the following snippet:

You can notice by taking a look at the code snippet of each interface element that the styles are applied by putting specific classes to it.

This documentation provides snippets for default usage of the classes but, for some elements, different tags can be rendered by using the same class.

It is also important to notice that some elements have already all the styles applied to them without using any classes and that for some elements besides the main class there is also a modifier class, that should change that element styles a little. Therefore, the structure of the tags can be generically described, ignoring the attributes and considering "[...]" as optional blocks, using an example of a opening tag, as:

This framework is meant for anyone who wants to have a very good-looking application, following all the patterns stabilished by Shopify merchant admin, and its development is also opened to everyone interested on offering help, which is very appreciated.

In order to contribute, just fork the repository Shopify-Embedded-App-Frontend-Framework and do as many pull requests as you wish.

We thank you in advance!

Embedded App SDK

This section gives an overview about the SDK, used to embed the application into Shopify environment, to add buttons to the header, build modals and show messages to the user.

Check SDK docs

As said before, Embedded Apps are those that are accessed inside of the Shopify Merchant Admin, what makes the experience of using an application much better, since the merchant feels inside the environment, as if your application were part of Shopify functionalities.

The Embedded App SDK (EASDK) is an API that provides:

  • Custom modal windows
  • Dialogs:
    • Alert
    • Confirm
    • Input
  • Top bar with icon elements:
    • Icon
    • Breadcrumbs
    • Buttons
    • Pagination
    • Dropdown menus
  • Flash messages

The SDK can be added to your application by including the following snippet

<script src="https://cdn.shopify.com/s/assets/external/app.js"></script>

To learn more and check the full documentation of EASDK, please check this link.

You can also check all the elements explained in this section by using this sample application, provided by Shopify team.

The top bar is where most of the elements mentioned in overview are placed.

Although the elements of the top bar have the same layout as SEAFF elements, all these elements are inserted by calling methods of Shopify Embedded App SDK and their layout is not influenced by any of SEAFF styles, since they are placed in your application's "parent environment".

To have the complete information about what can be placed in top bar, check the Embedded App SDK documentation.

The Embedded App SDK also has modals and flash messages for several purposes. Despite the content of modals that use iframe, the layout of the modals is out of your application's control and therefore it is not influenced by SEAFF CSS styles.

Since it is not possible to simulate the modal windows using the SDK in this page, below are placed some images that show what kind of messages can be displayed to the merchant as well as how they look like

This message is shown at the bottom of the page. A very common use of it is to give the merchant a feedback when an action was successfully done.

This message, like the flash messages, is shown at the bottom of the page to represent errors generated by some action done by the merchant.

Sections

The sections are the main organizational unit of the framework

"Introduction", "Sections", "General Inputs", among others, are examples of sections. The sections are used to organize the blocks of information all over the applications (and also all over this document) and they fill the full available width provided by Shopify merchant admin.

Below some little facts about the sections that are important to be taken into account when organizing the interface:

  • The sections are divided into two main blocks, the summary and the content.
  • The content is divided into rows (as many as you want).
  • The rows are divided into cells (as many as you want).

"Sections" is a good example of a section with multiple rows and cells. The snippet below shows the general structure of a section:

Section title

Section explanation

...
...
...
...
...
...
...
...
...
...
...
...
...
...
...

"Links", among other sections along this document, is a good example of this kind of section. The following snippet shows how to create this kind of section.

Section title

Section explanation

Information related to the section

The sample snippet below is used to generate a row with 3 cells. Notice that this snippet reffers only to the row and the cells and doesn't take the other parts of the section structure. To build a whole section with 3 sections, replace all the rows in this snippet for the row below.

The following snippet reffers to the row just below it.

This is a cell.
This is a cell.
This is a cell.
This is a cell.
This is a cell.
This is a cell.

The sample snippet below is used to generate a row with 1 cell divided into columns ("Column 1" and "Column 2"), the second one subdivided in 2 columns ("Column 2A" and "Column 2B")

It is possible to add as many "cell-column" divs as you want and it is also possible to add "cell-container" div inside any "cell-column", to subdvide it in more columns.

This is the first column

This is the second column. Below you there is another "cell-container" div divided in 2 other columns

This is the first column inside the "Column 2"

This is the second column inside the "Column 2"

This is the first column

This is the second column. Below you there is another "cell-container" div divided in 2 other columns

This is the first column inside the "Column 2"

This is the second column inside the "Column 2"

Inputs

In this section, the general inputs are documented (text input, text areas, dropdowns, etc)




Links

In this section you can find all the links provided by this framework

Default Link

This is the default link. No class should be specified

The tooltip modifier is used to add to a tag the ability to show a tooltip.

Hover Over Me This order has a high risk of fraud


Buttons & Links as buttons

In this section you can find all the buttons provided by this framework

Primary Button




Default Button





Destroy Button




Disabled Button




This is a modifier to reduce the size of primary, default or any button you need.

Slim Primary Button




Segmented Buttons

This section exaplains how to use segmented buttons, a modifier that provides the style to concatenate some buttons

  • Button one
  • Button two
  • Button three


  • Button one
  • Button two
  • Button three
  • Button one
  • Button two
  • Button three


  • Button one
  • Button two
  • Button three
  • Button primary
  • Button default
  • Button disabled


  • Button primary
  • Button default
  • Button disabled

Tags

A tag can be generated by applying a main class and optionally one or more modifier classes. To generate a tag, you should apply the main class "tag", one of the 4 modifier classes named as colors and optionally the modifier class "inactive". The general structure is as follows:

Tag 1

The following samples are ilustrating the use of the modifiers. Notice that one of them has two modifiers, one that applies the color and other to apply a level of transparency.

Approved

Approved
Unfulfilled

Unfulfilled
Spam

Spam
Light gray tag

Light gray tag
Gray tag

Gray tag
Blue tag

Blue tag
Orange tag

Orange tag

This sample tag is used to show how to apply the "inactive" effect and it has three classes, the main class "tag", the modifier color class "blue" and the modifier class "inactive".

As you can see, the "inactive" class should be used along with "tag" and one of the available modifier color classes.

Inactive tag

Inactive tag

This element has its own color and effects so it doesn't need any modifier color class. As you can see in the code below, it is necessary to include the element that shows the closable button inside the tag.

Closable tag

Closable tag

Tables

This section describes the tables used by the framework. The tables that use the whole available width are described right after.

Column 1 Column 2 Column 3 Column 4
Link Tag Regular text Button
Link Tag Regular text Button
Link Tag Regular text Button

Column 1 Column 2 Column 3 Column 4
Link Tag Regular text Button
Link Tag Regular text Button
Link Tag Regular text Button

This table fills the whole available width. If used in place of "section", it will fill the whole iframe width, or else, it will fill the available width inside the tag where it is inserted.

In the example below, it is inserted inside a "section-row", in a "section" with "section-summary", so it doesn't fit the whole width. For an example where it fits the full width, check the Full Width Table. Notice in this case that the absence of the "section-summary" div is enough to make it fill the full width of the page.

Column 1 Column 2 Column 3 Column 4
Link Tag Regular text Button
Link Tag Regular text Button
Link Tag Regular text Button
Column 1 Column 2 Column 3 Column 4
Link Tag Regular text Button
Link Tag Regular text Button
Link Tag Regular text Button

Message boxes

List of available message boxes. They should be placed right below the body tag.

Message
<body>
Message
...
Message
<body>
Message
...

Icons

This section lists the available icons in the Shopify admin and describes how to use them.

You can put the icon you need inside any element, like buttons, anchors, etc. Also you can use the class "icon" to view them like simple icons.