|
1 | 1 | # Embedded apps |
2 | 2 |
|
3 | | -In addition to the [visual components](https://polaris.shopify.com/components/get-started) provided as part of Polaris, we provide React wrappers around Shopify’s [Embedded App SDK (EASDK)](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods). When using Polaris, you don’t need to go through the initialization of the EASDK as described [in the docs](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/initialization). Instead, configure the connection to the Admin through the `AppProvider` component: |
| 3 | +In addition to the [visual components](https://polaris.shopify.com/components/get-started) provided as part of Polaris, we provide React wrappers around the [Shopify App Bridge](https://github.com/Shopify/app-bridge) (formerly known as the EASDK). |
4 | 4 |
|
5 | | -```js |
6 | | -import React from 'react'; |
7 | | -import {render} from 'react-dom'; |
8 | | -import {AppProvider, Page, Card} from '@shopify/polaris'; |
| 5 | +When using Polaris, you don’t need to go through the initialization of the Shopify App Bridge as described [in the docs](https://github.com/Shopify/app-bridge/blob/master/packages/app-bridge/README.md). Instead, configure the connection to the Shopify admin through the [app provider component](https://polaris.shopify.com/components/structure/app-provider#initializing-the-shopify-app-bridge), which must wrap all components in an embedded app. This component initializes the Shopify App Bridge using the `apiKey` you provide. **The `apiKey` attribute is required** and can be found in the [Shopify Partner Dashboard](https://partners.shopify.com). |
9 | 6 |
|
10 | | -class MyApp extends React.Component { |
11 | | - render() { |
12 | | - return ( |
13 | | - <Page title="Example application"> |
14 | | - <Card sectioned> |
15 | | - Insert the rest of your app here, including those components detailed |
16 | | - below, which can now communicate with the Embedded App SDK. |
17 | | - </Card> |
18 | | - </Page> |
19 | | - ); |
20 | | - } |
21 | | -} |
| 7 | +## Components which wrap Shopify App Bridge |
22 | 8 |
|
23 | | -render( |
24 | | - <AppProvider |
25 | | - apiKey="YOUR_APP_API_KEY" |
26 | | - shopOrigin="https://CURRENT_LOGGED_IN_SHOP.myshopify.com" |
27 | | - > |
28 | | - <MyApp /> |
29 | | - </AppProvider>, |
30 | | - document.querySelector('#app'), // or another DOM element you want to mount the app in |
31 | | -); |
32 | | -``` |
33 | | - |
34 | | -Your apiKey and shopOrigin attributes are required. The [EASDK init section](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-init-config) describes the details of these attributes and where to find them. |
35 | | - |
36 | | -## Components |
37 | | - |
38 | | -To access the EASDK components you need to add them to you project: |
39 | | -`import * as Embedded from '@shopify/polaris/embedded';` or `import {Alert, ResourcePicker} from '@shopify/polaris/embedded';` if you want to import a subset of the components. |
40 | | - |
41 | | -All components must be wrapped by the `<AppProvider />` component. This component initializes the EASDK using the apiKey and shopOrigin you provide. |
42 | | - |
43 | | -- [`<AppProvider />`](https://polaris.shopify.com/components/structure/app-provider): The root component that manages the communication with the Shopify admin. |
44 | | -- [`<Page />`](https://polaris.shopify.com/components/structure/page): An outer wrapper of the embedded app content used to control page title and associated page actions. This replaces the [`ShopifyApp.Bar.initialize`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-bar-initialize-config), [`ShopifyApp.Bar.setTitle`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-bar-settitle-title), [`ShopifyApp.Bar.setIcon`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-bar-seticon-icon), [`ShopifyApp.Bar.setPagination`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-bar-setpagination-config) and [`ShopifyApp.Bar.setBreadcrumb`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-bar-setbreadcrumb-config) |
45 | | -- [`<Alert />`](https://polaris.shopify.com/components/embedded/embedded-alert): A modal alert presented to the user with a configurable option to cancel or confirm. This replaces the [`ShopifyApp.Modal.alert`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-modal-alert-options-fn) and [`ShopifyApp.Modal.confirm`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-modal-confirm-options-fn) EASDK methods. |
46 | | -- [`<Modal />`](https://polaris.shopify.com/components/embedded/embedded-modal): A modal dialog presented over top of your application. This dialog will present another page of your choice from your application. This replaces the [`ShopifyApp.Modal.open`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-modal-open-init-fn) EASDK method. |
47 | | -- [`<ResourcePicker />`](https://polaris.shopify.com/components/embedded/embedded-resource-picker): A modal dialog that allows the user to select one or more of their products or collections, and provides you with details on the selected resources. This replaces the [`ShopifyApp.Modal.productPicker`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-modal-productpicker-options-fn) and [`ShopifyApp.Modal.collectionPicker`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-modal-collectionpicker-options-fn) EASDK methods. |
48 | | - |
49 | | -## Access to further EASDK APIs |
50 | | - |
51 | | -We’ve provided access to some functionality of the underlying EASDK API. This enables performing actions like redirects or displaying a flash message from within your embedded app. |
52 | | - |
53 | | -In order to call these methods, you must get the `easdk` object that we add to [React’s `context`](https://facebook.github.io/react/docs/context.html). The example below demonstrates how to access the `easdk` object from React’s `context`: |
54 | | - |
55 | | -```js |
56 | | -import React from 'react'; |
57 | | -import {render} from 'react-dom'; |
58 | | -import * as PropTypes from 'prop-types'; |
59 | | -import {AppProvider, Page, Card, Button} from '@shopify/polaris'; |
60 | | - |
61 | | -class MyApp extends React.Component { |
62 | | - // This line is very important! It tells React to attach the `easdk` |
63 | | - // object to `this.context` within your component. |
64 | | - static contextTypes = { |
65 | | - easdk: PropTypes.object, |
66 | | - }; |
67 | | - |
68 | | - render() { |
69 | | - return ( |
70 | | - <Page title="Example application"> |
71 | | - <Card sectioned> |
72 | | - <Button onClick={() => this.context.easdk.startLoading()}> |
73 | | - Start loading |
74 | | - </Button> |
75 | | - <Button onClick={() => this.context.easdk.stopLoading()}> |
76 | | - Stop loading |
77 | | - </Button> |
78 | | - </Card> |
79 | | - </Page> |
80 | | - ); |
81 | | - } |
82 | | -} |
83 | | - |
84 | | -render( |
85 | | - <AppProvider |
86 | | - apiKey="YOUR_APP_API_KEY" |
87 | | - shopOrigin="https://CURRENT_LOGGED_IN_SHOP.myshopify.com" |
88 | | - > |
89 | | - <MyApp /> |
90 | | - </AppProvider>, |
91 | | - document.querySelector('#app'), |
92 | | -); |
93 | | -``` |
94 | | - |
95 | | -### Methods provided: |
96 | | - |
97 | | -We provide the following methods, (annotated with the types of their parameters and return values): |
98 | | - |
99 | | -#### `easdk.showFlashNotice()` |
100 | | - |
101 | | -```ts |
102 | | -showFlashNotice(message: string): void; |
103 | | -``` |
104 | | - |
105 | | -Presents a flash message in the Shopify admin and replaces the [`ShopifyApp.flashNotice`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-flashnotice-message) and [`ShopifyApp.flashError`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-flasherror-message) methods in the EASDK. |
106 | | - |
107 | | -By default, this method call will present an informational message. In order to present an error message, pass `{error: true}` as the second parameter to this method. |
108 | | - |
109 | | -##### Best practices |
110 | | - |
111 | | -Use flash messages sparingly and only for very quick, tactical feedback on an action. Remember that flash messages disappear after 3 seconds so they can be hard to read for anyone with low literacy, limited vision, or anyone who doesn’t speak English as their first language. |
112 | | - |
113 | | -Make flash messages very short and scannable. |
114 | | - |
115 | | -##### Content guidelines |
116 | | - |
117 | | -Flash messages should: |
118 | | - |
119 | | -- Follow a {noun} + {verb} pattern (e.g. Settings saved, Buy Button removed, Discount deleted) |
120 | | -- Confirm a previous call to action performed by the merchant (e.g. if the merchant selects a button that says “Add channel”, the flash message that follows should say “Channel added”) |
121 | | -- Be short and specific (2 or 3 words) |
122 | | - |
123 | | -###### Do |
124 | | - |
125 | | -Changes saved |
126 | | - |
127 | | -###### Don’t |
128 | | - |
129 | | -Successfully saved changes |
130 | | - |
131 | | -#### `easdk.pushState()` |
132 | | - |
133 | | -```ts |
134 | | -pushState(location: string): void; |
135 | | -``` |
136 | | - |
137 | | -Rewrites the URL to the passed location. Note that this is called automatically by other methods, so it is rarely needed directly. Replaces the [`ShopifyApp.pushState`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-pushstate-path) method in the EASDK. |
138 | | - |
139 | | -#### `easdk.redirect()` |
140 | | - |
141 | | -```ts |
142 | | -redirect(location: string): void; |
143 | | -``` |
144 | | - |
145 | | -Navigates away from your app and to another section of the Shopify admin. The path should be prefixed with a slash, but should not include the `/admin` part. Example: `/customers/120999015` or `/settings/domains`. Replaces the [`ShopifyApp.redirect`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-redirect-path) method in the EASDK. |
146 | | - |
147 | | -#### `easdk.startLoading()` |
148 | | - |
149 | | -```ts |
150 | | -startLoading(): void; |
151 | | -``` |
152 | | - |
153 | | -Starts a loading indicator in the Shopify admin. It is a best practice to trigger this when you start any long-running asynchronous operation, such as an AJAX request. Replaces the [`ShopifyApp.Bar.loadingOn`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-bar-loadingon) method in the EASDK. |
154 | | - |
155 | | -#### `easdk.stopLoading()` |
156 | | - |
157 | | -```ts |
158 | | -stopLoading(): void; |
159 | | -``` |
160 | | - |
161 | | -Stops the loading indicator in the Shopify admin. Make sure to match this to any calls to `startLoading` once the asynchronous task is complete. Replaces the [`ShopifyApp.Bar.loadingOff`](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/methods#shopifyapp-bar-loadingoff) method in the EASDK. |
| 9 | +- [`<Toast />`](https://polaris.shopify.com/components/feedback-indicators/toast) |
| 10 | +- [`<Loading />`](https://polaris.shopify.com/components/feedback-indicators/loading) |
| 11 | +- [`<Page />`](https://polaris.shopify.com/components/structure/page) |
| 12 | +- [`<Modal />`](https://polaris.shopify.com/components/overlays/modal) |
| 13 | +- [`<ResourcePicker />`](https://polaris.shopify.com/components/overlays/resource-picker) |
0 commit comments