Features

Some features are immediately available through the ShopifyApp object upon app.js file's load:

Form Submission

On any form, you can add the attribute data-shopify-app-submit with the value matching the message value of one of the title bar buttons. When the button is clicked, it will automatically submit that form:

<script type="text/javascript">
  ShopifyApp.ready(function(){
    ShopifyApp.Bar.initialize({
      buttons: {
        primary: {
          label: 'Save',
          message: 'unicorn_form_submit',
          loading: true
        }
      }
    });
  });
</script>
<form data-shopify-app-submit="unicorn_form_submit">
  ...
</form>

Note

This feature calls form.submit() which may not fire callbacks or other events bound with libraries like jQuery. If this is the case, you can always add a custom callback function to the button and handle firing your callbacks and form submissions yourself.

You can access the JavaScript and DOM elements of a modal using:

ShopifyApp.Modal.window()

For example, if you want to call a function called performValidation that exists in the context of the modal, from your application, you can invoke the function as follows:

ShopifyApp.Modal.window().performValidation()

To access the body element:

ShopifyApp.Modal.window().$("body")

If you'd like to access your application's JavaScript or DOM elements from the modal, just use:

ShopifyApp.window()

So if you want to get the body element of your application:

ShopifyApp.window().$("body")

Keep in mind that calling ShopifyApp.window() by itself might print cross-domain errors on the browser console. Always call functions and elements from the ShopifyApp.window() to keep the console clean.

Printing

For applications requiring print support, the ShopifyApp object provides print capturing and redirection over postMessage. This ensures that only the app's iframe will be printed, and not the truncated Shopify admin view.

Configuring a top bar button with the option print: true will send a print message to the application's iframe.

The function ShopifyApp.print defaults to simply calling window.print(). The function can be overridden to execute some custom actions:

<script type="text/javascript">
  ShopifyApp.print = function(){
    changeSomeLayout();
    window.print();
    doSomeOtherAction();
  }

  ShopifyApp.ready(function(){
    ShopifyApp.Bar.initialize({
      buttons: {
        primary: {
          label: 'Print',
          print: true
        }
      }
    });
  });
</script>

Auto-Redirection

The app.js script automatically detects if your embedded application is not nested inside an iframe. If not, it will redirect the page into the Shopify admin.

Error Pages

The Shopify admin listens for some special messages to support 404, 422, and 500 error pages. The following snippet can be copied to the static error pages and does not require any setup or configuration:

<script type="text/javascript">
  window.parent.postMessage('{"message": "Shopify.API.Bar.error.404"}', "*");
</script>
<script type="text/javascript">
  window.parent.postMessage('{"message": "Shopify.API.Bar.error.422"}', "*");
</script>
<script type="text/javascript">
  window.parent.postMessage('{"message": "Shopify.API.Bar.error.500"}', "*");
</script>