Methods

There are a number of methods that can be used on the ShopifyApp object:

ShopifyApp.init(config)

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:

Key Type Description
apiKey String ff9b1d04414785029e066f8fd0465d00 or similar. The API key provided to you for your application in the Shopify Partners area.
shopOrigin String The origin of the Shopify shop. This will come out of the session values returned from the Shopify API and should be set dynamically for each different merchant/shop. It'll be something like "https://example.myshopify.com" and should always include the protocol.
forceRedirect Boolean Defaults to true. Can be used to disable redirection into the admin for debugging or testing purposes.
debug boolean Defaults to false. Will activate some console.log logging output.
ShopifyApp.init({
  apiKey: "ff9b1d04414785029e066f8fd0465d00",
  shopOrigin: "https://example.myshopify.com",
  debug: false,
  forceRedirect: true
});

ShopifyApp.ready(fn)

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.

ShopifyApp.ready(function(){
  alert("Ready");
});

ShopifyApp.pushState(path)

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

ShopifyApp.flashNotice(message)

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

ShopifyApp.flashNotice("Unicorn was created successfully.");

ShopifyApp.flashError(message)

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

ShopifyApp.flashError("Unicorn could not be created.");

ShopifyApp.redirect(path)

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.

ShopifyApp.redirect("/orders");

ShopifyApp.Bar.initialize(config)

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 spinner will never stop spinning.

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

Key Type Description
buttons Object An object describing the buttons displayed in the top bar. The object contains two keys, primary and secondary, and each of those keys contain an array of button objects. Primary buttons default to blue, and have a maximum of one button. Secondary buttons have a maximum of four buttons.
title String The title string displayed in the header behind the application's name.
icon String A URL to an image file used as the icon in the top bar. If omitted, a default app icon will be used.
pagination Object An object configuring and toggling the pagination arrow button group.
breadcrumb Object A button object configuring and toggling the breadcrumb in the top bar.

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:

Key Type Description
callback Function When the button is clicked, this function will be executed in the app.
href String The URL to be opened in the app.
loading Boolean A boolean value stating if the loading spinner should activate when this button is pressed. This defaults to `true`.
ShopifyApp.Bar.initialize({
  buttons: {
    primary: {
      label: "Save",
      message: 'bar_save'
    },
    secondary: [
      { label: "Help", callback: function(){ alert('help'); } },
      { label: "More",
        type: "dropdown",
        links: [
                 { label: "Update", href: "/update", target: "app" },
                 { label: "Delete", callback: function(){ alert("destroy") } }
               ]
      },
      { label: "Preview", href: "http://my-app.com/preview_url", target: "new" }
    ],
  },
  title: 'Page Title',
  icon: 'https://example.com/path/to/icon.png',
  pagination: {
    next: {
      href: "/posts?page=2"
    },
    previous: {
      callback: function(){ alert('no previous pages') },
      loading: false
    }
  },
  breadcrumb: {
    label: "Subsection",
    href: "/subsection",
    target: 'app',
    loading: false
  }
});

ShopifyApp.Bar.loadingOff()

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

ShopifyApp.Bar.loadingOn()

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

ShopifyApp.Bar.setTitle(title)

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

ShopifyApp.Bar.setIcon(icon)

Manually set the icon of the top bar from a URL. See ShopifyApp.Bar.initialize().

ShopifyApp.Bar.setPagination(config)

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

ShopifyApp.Bar.setBreadcrumb(config)

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().

ShopifyApp.Modal.open(init, fn)

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, 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.

To learn how to communicate from the modal iframe to the app iframe, read Modal & App Communication.

Key Type Description
src String The URL to be opened in the iframe.
title String The title of the modal.
width String Defaults to small. This allows you to set a predetermined width for the modal. The acceptable values are:
large - 980px wide
fullwidth - Fills the width of the screen.
height Integer This determines the height of the modal in pixels 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. This can also be set from within the modal using the ShopifyApp.Modal.setHeight() method.
buttons Object An object describing the buttons displayed at the bottom of the modal. The object contains three keys, primary, secondary, and tertiary. Each of those keys contain an array of button objects. Primary buttons default to blue, are floated right, and have a maximum of one button. Secondary buttons are floated right and have a maximum of two buttons. Tertiary buttons are floated left and have a maximum of two buttons.
callback Function When the modal is closed, this function will be executed in the app. Params are (result, data).
ShopifyApp.Modal.open({
  src: 'https://example.com/app/path',
  title: 'A new modal',
  width: 'small',
  height: 300,
  buttons: {
    primary: { label: "OK" },
    secondary: [
      { label: "Cancel", callback: function (label) { ShopifyApp.Modal.close(); } }
    ]
  }
}, function(result, data){
  alert("result: " + result + "   data: " + data);
});

ShopifyApp.Modal.alert(options, fn)

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.

ShopifyApp.Modal.alert("An alert message", function(result){
  alert("The modal was closed.");
});

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.

ShopifyApp.Modal.alert({
  title: "Warning!",
  message: "An alert message",
  okButton: "I understand"
}, function(result){
  alert("The modal was closed.");
});

ShopifyApp.Modal.confirm(options, fn)

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.

ShopifyApp.Modal.confirm("Are you sure you want to?", function(result){
  if(result){
    alert("yeah they're sure");
  }
  else{
    alert("no, lets not");
  }
});

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.

ShopifyApp.Modal.confirm({
  title: "Delete your account?",
  message: "Do you want to delete your account? This can't be undone.",
  okButton: "Yes, delete my account",
  cancelButton: "No, keep my account",
  style: "danger"
}, function(result){
  alert("The modal was closed.");
});

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

ShopifyApp.Modal.input(options, fn)

Opens a Javascript style input() dialog 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 and the contents of the input box passed in.

ShopifyApp.Modal.input("Please enter some data.", function(result, data){
  if(result){
    alert("entered" + data);
  }
  else{
    alert("cancelled");
  }
});

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

ShopifyApp.Modal.close(result, data)

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.

ShopifyApp.Modal.close(true, 'some data');

ShopifyApp.Modal.setHeight(height)

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.

ShopifyApp.Modal.setHeight(320);

ShopifyApp.User.current

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.

Key Description
accountAccess Can have 3 possible values: Account owner, Full access or Limited access. It will depend on the account access level of the current logged-in user.

Here is an example:

ShopifyApp.ready(function(){
  alert(ShopifyApp.User.current.accountAccess);
});

Button objects

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 an callback function that is called on click. Alternately 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:

Key Type Description
label String The text displayed in the button.
message String The value of the post message that Shopify will send down to the application that can then be listened for. Attributes such as callback and href create these messages manually and do not require this to be set.
callback Function When the button is clicked, this function will be executed in the app. Params are (message, data).
href String The URL to be opened. It should be absolute for app links or external links. For links within Shopify it should be of the format /orders/123. The specific location where this link will be opened depends on the target attribute.
target String The location where the value of the href will be opened. Default is app. The acceptable values are:

new - Open a new window/tab.

parent - Replace the current frame/window.

shopify - A redirect to within the Shopify admin. A relative path without the admin prefix, like /products.

app - Redirects the app's iframe to this URL. Essentially clicking a regular navigation link in the app.
loading Boolean A boolean value stating if the loading spinner should activate when this button is pressed. Shopify attempts to make a rational guess as to if this should be true or false depending on the action (ie: target: 'new' defaults to false, but target: 'app' defaults to true). It is always safe and prudent to override this value to be exactly what you require for your specific application.
style String Optional color styling for the button. It will always be a sane default, but can accept danger and disabled. If this is not set, primary buttons appear blue and secondary and tertiary buttons are white.
type String Sets the button to become a dropdown button. Should be used alongside the links attribute. Current accepted value is dropdown. Only valid for secondary top bar buttons.
links Array A list of buttons. Accepts the same attributes as a regular button, like label, target and callback. Only valid for secondary top bar buttons.