Skip to content

Commit 934fdef

Browse files
travis-ehtravis-eh
committed
faasasss
1 parent d65a68e commit 934fdef

File tree

4 files changed

+463
-0
lines changed

4 files changed

+463
-0
lines changed

‎src/embedded/Alert/README.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: Alert
3+
tags:
4+
- embedded
5+
- alert
6+
- confirm
7+
- pop up
8+
- overlays
9+
- disruptive
10+
- disruptor
11+
category: Embedded
12+
hidePlayground: true
13+
---
14+
15+
# Alert
16+
Alerts present a modal dialog in the interface that can be useful to provide confirmation for a merchant action (particularly when the action is potentially dangerous), or to simply provide important information that the merchant needs to see.
17+
18+
This component only works within embedded apps. Read the [Embedded App SDK (EASDK) getting started guide](https://github.com/Shopify/polaris/blob/master/documentation/Embedded%20apps.md) for more details on how to use the EASDK with Polaris.
19+
20+
---
21+
22+
## Properties
23+
24+
| Prop | Type | Description |
25+
| ---- | ---- | ----------- |
26+
| open* | boolean | Whether the alert is open |
27+
| children* | string | The content to display inside the alert |
28+
| title | string | The alert title |
29+
| destructive | string | For confirming a destructive or dangerous action |
30+
| confirmContent* | string | The content of the confirmation button |
31+
| cancelContent | string | The content of the cancel button |
32+
| onConfirm* | function() | Callback when the confirmation button is clicked |
33+
| onCancel | function() | Callback when the cancel button is clicked |
34+
35+
---
36+
37+
## Examples
38+
39+
### Basic alert
40+
41+
Use when you don't provide `onCancel` and `cancelContent` and the merchant must click on the confirmation button to proceed.
42+
43+
```jsx
44+
<Alert
45+
title="Accept terms and conditions"
46+
open={this.state.open}
47+
confirmContent="I accept"
48+
onConfirm={() => this.setState({open: false, confirmed: true})}
49+
>
50+
You must accept the terms and conditions before proceeding.
51+
</Alert>
52+
```
53+
54+
### Destructive warning
55+
56+
Use passing `destructive` to make it clear to the merchant that the action is potentially dangerous. Only use this option when the merchant is about to perform an action that they can’t undo.
57+
58+
```jsx
59+
<Alert
60+
title="Unsaved changes"
61+
open={this.state.open}
62+
confirmContent="Discard changes"
63+
onConfirm={() => this.setState({open: false, confirmed: true})}
64+
cancelContent="Continue editing"
65+
onCancel={() => this.setState({open: false, confirmed: false})}
66+
>
67+
Leaving will cause the changes to your product to be lost.
68+
</Alert>
69+
```

‎src/embedded/App/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: Embedded app
3+
tags:
4+
- embedded
5+
- app
6+
category: Embedded
7+
hidePlayground: true
8+
---
9+
10+
# Embedded app
11+
Embedded app is a wrapper for your entire application which provides access to the Shopify admin using the [Embedded App SDK (EASDK)](https://help.shopify.com/api/sdks/shopify-apps/embedded-app-sdk/getting-started). The props passed to this component initialize your connection to the Shopify admin. Once connected, components in your application can send and receive messages using the EASDK.
12+
13+
This component only works within embedded apps. Read the [EASDK getting started guide](https://github.com/Shopify/polaris/blob/master/documentation/Embedded%20apps.md) for more details on how to use the EASDK with Polaris.
14+
15+
---
16+
17+
## Properties
18+
19+
| Prop | Type | Description |
20+
| ---- | ---- | ----------- |
21+
| apiKey | string | The API key for your application from the Partner dashboard |
22+
| shopOrigin | string | The current shop’s origin, provided in the session from the Shopify API |
23+
| forceRedirect | boolean | Forces a redirect to the relative admin path when not rendered in an iframe |
24+
| debug | boolean | Prints logs of each message passed through the EASDK |
25+
26+
---
27+
28+
## Examples
29+
30+
### Initializing
31+
32+
You must store your API key and the `shopOrigin` provided by the Shopify API somewhere on the page so you can use them to initialize your application.
33+
34+
```jsx
35+
// We are accessing the apiKey and shopOrigin
36+
// from content in script tags.
37+
const shopOrigin = document.querySelector('#ShopOrigin').textContent;
38+
const apiKey = document.querySelector('#APIKey').textContent;
39+
40+
ReactDOM.render(
41+
<EmbeddedApp
42+
shopOrigin={shopOrigin}
43+
apiKey={apiKey}
44+
>
45+
<ResourcePicker
46+
open
47+
products
48+
onSelection={(resources) => console.log('Selected resources ', resources)}
49+
/>
50+
</EmbeddedApp>
51+
)
52+
```

‎src/embedded/Modal/README.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
name: Modal
3+
tags:
4+
- embedded
5+
- pop up
6+
- overlays
7+
- disruptive
8+
- disruptor
9+
- multiple sections
10+
- custom width
11+
- custom height
12+
category: Embedded
13+
hidePlayground: true
14+
---
15+
16+
# Modal
17+
Modals are overlays that prevent merchants from interacting with the rest of the application until a specific action is taken. They can be disruptive because they require merchants to take an action before they can continue interacting with the rest of Shopify. It should be used thoughtfully and sparingly.
18+
19+
**Problem:**
20+
21+
Merchants need a way to focus on certain tasks that can’t be left half-finished.
22+
23+
**Solution:**
24+
25+
Modals require merchants to take an action before they can continue working in other parts of Shopify. It helps them maintain focus or stay in the workflow because the changes can’t be automatically saved.
26+
27+
This component only works within embedded apps. Read the [Embedded App SDK (EASDK) getting started guide](https://github.com/Shopify/polaris/blob/master/documentation/Embedded%20apps.md) for more details on how to use the EASDK with Polaris.
28+
29+
> **Not what you’re looking for?**
30+
>* To present large amounts of additional information or actions that don’t require confirmation, [use the collapsible component](/components/collapsible) to expand content in place within the page.
31+
>* To present a small amount of content or a menu of actions in a non-blocking overlay, [use the popover component](/components/popover).
32+
>* To communicate a change or condition that needs the merchant’s attention within the context of a page, [use the banner component](/components/banner).
33+
>* To present confirmation that an action was successful, [use the flash message component](/components/flash message).
34+
35+
---
36+
37+
## Best practices
38+
39+
Modals should:
40+
41+
- Be used for in-context tasks that require an explicit action to be taken
42+
- Be used for focused, specific tasks that can’t be left half-completed
43+
- Include no more than a single primary call to action
44+
- Not be used as a way to present additional sections of content without actions because they can disrupt a merchant’s workflow
45+
- Not be used for complicated flows that require a merchant to take multiple paths or complete more than one primary task
46+
47+
---
48+
49+
## Content guidelines
50+
51+
### Title
52+
53+
Titles should be:
54+
55+
- Informative and descriptive
56+
- They should label the type of content grouped in the modal
57+
- Concise and scannable:
58+
- Use simple, clear language that can be read at a glance
59+
- Keep headings to single sentence and avoid using punctuation such as periods, commas, or semicolons
60+
- Avoid articles (the, a, an) in [microcopy headings](/content/grammar-and-mechanics#headings-and-subheadings) to keep content short and actionable
61+
- Written in sentence case (first word capitalized, the rest is lowercase)
62+
63+
<!-- usagelist -->
64+
#### Do
65+
Edit email address
66+
67+
#### Don't
68+
Edit the email address for this order
69+
<!-- end -->
70+
71+
### Body content
72+
73+
Body content should be:
74+
75+
- Actionable: start sentences with imperative verbs when telling a merchant what actions are available to them (especially something new). Don't use permissive language like "you can".
76+
77+
<!-- usagelist -->
78+
#### Do
79+
Notification emails will be sent to this address.
80+
81+
#### Don't
82+
You can edit the email address where emails will be sent.
83+
<!-- end -->
84+
85+
- Structured for merchant success: always put the most critical information first.
86+
- Clear: use the verb “need” to help merchants understand when they’re required to do something.
87+
88+
<!-- usagelist -->
89+
#### Do
90+
To buy a shipping label, you need to enter the total weight of your shipment, including packaging.
91+
92+
#### Don't
93+
To buy a shipping label, you must enter the total weight of your shipment, including packaging.
94+
<!-- end -->
95+
96+
### Primary and secondary actions
97+
98+
Actions should be:
99+
100+
- Clear and predictable: merchants should be able to anticipate what will happen when they click a button. Never deceive a merchant by mislabeling an action.
101+
102+
<!-- usagelist -->
103+
#### Do
104+
- Create order
105+
- Buy shipping label
106+
107+
#### Don't
108+
- New order
109+
- Buy
110+
<!-- end -->
111+
112+
- Action-led: actions should always lead with a strong verb that encourages action. To provide enough context to merchants use the {verb}+{noun} format on actions except in the case of common actions like Save, Close, Cancel, or OK.
113+
114+
<!-- usagelist -->
115+
#### Do
116+
- Activate Apple Pay
117+
- View shipping settings
118+
119+
#### Don't
120+
- Try Apple Pay
121+
- View your settings
122+
<!-- end -->
123+
124+
- Scannable: avoid unnecessary words and articles such as the, an, or a.
125+
126+
<!-- usagelist -->
127+
#### Do
128+
Add menu item
129+
130+
#### Don't
131+
Add a menu item
132+
<!-- end -->
133+
134+
---
135+
136+
## Properties
137+
138+
| Prop | Type | Description |
139+
| ---- | ---- | ----------- |
140+
| open* | boolean | Whether the modal is open or not |
141+
| src* | string | The URL that will be loaded as the content of the modal |
142+
| title | string | Modal title, in large type |
143+
| width | enum['large', 'fullwidth'] | Controls the width of the modal |
144+
| height | number | The height of the modal (in pixels) |
145+
| primaryAction | Action | Primary action |
146+
| secondaryActions | Action[] | Collection of secondary actions |
147+
| onClose* | function() | Callback when the modal is closed |
148+
149+
---
150+
151+
## Examples
152+
153+
### Embedded modal
154+
155+
```jsx
156+
<Modal
157+
src="https://my-app.com/update-information"
158+
open={this.state.open}
159+
title="Edit account information"
160+
primaryAction={{
161+
content: 'Update account',
162+
onAction: () => this.setState({open: false}),
163+
}}
164+
secondaryActions={[{
165+
content: 'Change account',
166+
onAction: () => this.setState({open: false}),
167+
}]}
168+
onClose={() => this.setState({open: false})}
169+
/>
170+
)
171+
```

0 commit comments

Comments
 (0)