Methods

Should be called immediately after the script file has loaded, as early as possible on the page (not in a jQuery.ready() or something). It will initialize data values, add postMessage listeners, check that the app is embedded in an iframe, and setup our initializers.

The config hash can contain the following keys:

Works similarly to jQuery's ready() function. It can be called many times on a page, it accepts functions, and when the Admin and the app are loaded it will call the functions in order.

Used to rewrite the current URL. This is called automatically and probably doesn't need to be explicitly called at all.

Displays a message in the Shopify admin chrome styled as a notice. Use only for successful or neutral messages.

Displays a message in the Shopify admin chrome styled as an error. Use only for errors or failures.

Dispatches away from the app to a remote URL. The path must be an absolute URL prefixed with http or https.

Dispatches away from the app and into another section in the Shopify admin. The path should be prefixed with a slash, but should not include the /admin part. Example: /customers/120999015 or /settings/domains.

Accepts an object that defines how the top bar and buttons will look and behave. This should almost always be called in the ready() method. Default behavior if initialize is never called will result in some pretty safe defaults, except that the loading bar will never disappear.

The config object has a number of keys, all optional.

The configuration for pagination is a simplified version of button objects. When the pagination: key contains anything that is not falsy, the buttons will appear but will be inactive. The pagination: key expects an object containing two objects as previous: and next:, each describing a button. The button definition objects look like this:

Stops the loading bar. Should probably be called on every page in ShopifyApp.ready().

Restarts the loading bar. It is a best practice to call it when moving between pages or firing off AJAX requests.

Manually set the title string in the top bar. See ShopifyApp.Bar.initialize().

Manually set the pagination arrows, or pass undefined to remove them entirely. See ShopifyApp.Bar.initialize().

Manually set the breadcrumb in the top bar for an extra level of navigation. Pass a button object, or pass undefined to remove it entirely. See ShopifyApp.Bar.initialize(). Can be applied only if a title has been set with ShopifyApp.Bar.setTitle().

Opens a modal dialog in the Shopify admin that in turn loads an iframe inside of it with the passed in URL. It accepts a src attribute to be loaded (which must have the same origin as the rest of your app), a title for the top of the bar, and a configuration of primary and secondary buttons identical to Bar.initialize(). It also accepts a callback function that is called when the modal is closed.

Opens a JavaScript style alert() in the admin. When the modal is closed the optional callback is called and a modal close message is sent.

The options parameter can be a message to be displayed in the alert window, or it can be an object containing a message, a title for the modal, and a button label.

Opens a JavaScript style confirm() in the admin. When the modal is closed the optional callback is called and a modal close message is sent. The callback has the status of the closure passed in.

The options parameter can be a message to be displayed in the confirm window, or it can be an object containing a message, a title for the modal, and labels for the 'OK' and 'Cancel' buttons.

All modal dialogs can also accept a style: 'danger' attribute which will change the primary button from blue to red, useful for delete confirmations.

Closes the currently open modal window and manually sets the result and data payload. Result expects a true or false and data can contain the message payload, or nothing.

Sets the height of the currently open modal window up to a maximum height of 700px and a minimum of 100px. The height is applied to the body (excluding the header and footer) of the rendered modal.

Returns an object representing the current user logged in to the admin. It is available anytime after the Shopify.ready call. Currently it only returns the accountAccess of the user.

Here is an example:

Opens a modal dialog containing a list of the products or collections available in the store, with a search field for filtering results. The modal can be used for selecting one or more products/collections, using the resource picker's options.

The callback passed into the resource picker is invoked when the dialog is closed or a button is pressed. The callback is passed a success flag (boolean) which will be true if products are selected. The second parameter is a data object (JSON) which contains the selected products (if any) and any errors that may have surfaced.

The collection picker has the same interface as the product picker.

Button objects are used to define buttons on the top bar and in modal windows. A button object has a required label field for the button text. It has optional fields for message which is the postMessage the admin will send when the button is clicked. It also accepts a callback function that is called on click. Alternatively it accepts a href attribute which will make the button open the provided link in a new window. The use case for the link is something like "Open preview in a new window".

Buttons can be defined as follows: