Skip to content

Commit 2f0671d

Browse files
lemonmadelemonmade
committed
Embedded guide
1 parent c5e174d commit 2f0671d

File tree

1 file changed

+141
-0
lines changed

1 file changed

+141
-0
lines changed

‎documentation/Embeddded app.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Embedded apps
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#shopifyapp-redirect-path). 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 an `EmbeddedApp` component:
4+
5+
```js
6+
import React from 'react';
7+
import {Page, Card} from '@shopify/polaris';
8+
import {EmbeddedApp} from '@shopify/polaris/embedded';
9+
10+
export default class MyApp extends React.Component {
11+
render() {
12+
return (
13+
<EmbeddedApp
14+
apiKey="YOUR_APP_API_KEY"
15+
shopOrigin="https://CURRENT_LOGGED_IN_SHOP.myshopify.com"
16+
>
17+
<Page title="Example application">
18+
<Card sectioned>
19+
Insert the rest of your app here, including those components detailed below, which can now communicate with the Embedded App SDK.
20+
</Card>
21+
</Page>
22+
</EmbeddedApp>
23+
);
24+
}
25+
}
26+
```
27+
28+
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.
29+
30+
## Components
31+
To access the EASDK components you need to add them to you project:
32+
`import * from @shopify/polaris/embedded` or `import {EmbeddedApp, Alert, Modal} from @shopify/polaris/embedded` if you want to import only the components you will use.
33+
34+
All EASDK components must be wrapped by the `<EmbeddedApp />` component. This component initializes the EASDK using the apiKey and shopOrigin you provide.
35+
36+
* [`<EmbeddedApp />`](https://polaris.shopify.com/components/embedded/embedded-app): The root component that manages the communication with the Shopify admin.
37+
* [`<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)
38+
* [`<Alert />`](https://polaris.shopify.com/components/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.
39+
* [`<Modal />`](https://polaris.shopify.com/components/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.
40+
* [`<ResourcePicker />`](https://polaris.shopify.com/components/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.
41+
42+
## Access to further EASDK APIs
43+
44+
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.
45+
46+
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`:
47+
48+
49+
```js
50+
import React from 'react';
51+
import PropTypes from 'prop-types';
52+
import {Page, Card, Button} from '@shopify/polaris';
53+
import {EmbeddedApp} from '@shopify/polaris/embedded';
54+
55+
export default class MyApp extends React.Component {
56+
// This line is very important! It tells React to attach the `easdk`
57+
// object to `this.context` within your component.
58+
static contextTypes = {
59+
easdk: PropTypes.object,
60+
};
61+
62+
render() {
63+
return (
64+
<EmbeddedApp
65+
apiKey="YOUR_APP_API_KEY"
66+
shopOrigin="https://CURRENT_LOGGED_IN_SHOP.myshopify.com"
67+
>
68+
<Page title="Example application">
69+
<Card sectioned>
70+
<Button onClick={this.context.easdk.startLoading()}>Start loading</Button>
71+
<Button onClick={this.context.easdk.stopLoading()}>Stop loading</Button>
72+
</Card>
73+
</Page>
74+
</EmbeddedApp>
75+
);
76+
}
77+
}
78+
```
79+
### Methods provided:
80+
81+
We provide the following methods, (annotated with the types of their parameters and return values):
82+
83+
#### `easdk.showFlashNotice()`
84+
85+
```ts
86+
showFlashNotice(message: string): void;
87+
```
88+
89+
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) method in the EASDK.
90+
91+
##### Best practices
92+
93+
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.
94+
95+
Make flash messages very short and scannable.
96+
97+
##### Content guidelines
98+
99+
Flash messages should:
100+
101+
* Follow a {noun} + {verb} pattern (e.g. Settings saved, Buy Button removed, Discount deleted)
102+
* 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”)
103+
* Be short and specific (2 or 3 words)
104+
105+
###### Do
106+
Changes saved
107+
108+
###### Don't
109+
Successfully saved changes
110+
111+
#### `easdk.pushState()`
112+
113+
```ts
114+
pushState(location: string): void;
115+
```
116+
117+
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.
118+
119+
#### `easdk.redirect()`
120+
121+
```ts
122+
redirect(location: string): void;
123+
```
124+
125+
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.
126+
127+
#### `easdk.startLoading()`
128+
129+
```ts
130+
startLoading(): void;
131+
```
132+
133+
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.
134+
135+
#### `easdk.stopLoading()`
136+
137+
```ts
138+
stopLoading(): void;
139+
```
140+
141+
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.

0 commit comments

Comments
 (0)