Skip to content

Commit 2ef2eae

Browse files
jansenbejansenbe
committed
2 parents ef9ca65 + 8b33753 commit 2ef2eae

File tree

4 files changed

+318
-1
lines changed

4 files changed

+318
-1
lines changed

‎docs/apis/alm-api-for-spfx-add-ins.md

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Application Lifecycle Management (ALM) APIs
2+
3+
ALM APIs are providing simple APIs to manage deployment of your SharePoint Framework solutions and add-ins cross your tenant. ALM APIs support following capabilities.
4+
5+
- Add SharePoint Framework solution or SharePoint add-in to tenant app catalog
6+
- Enable SharePoint Framework solution or SharePoint add-in to be available for installation in tenant app catalog
7+
- Disable SharePoint Framework solution or SharePoint add-in not to be available for installation in tenant app catalog
8+
- Install SharePoint Framework solution or SharePoint add-in from tenant app catalog to a site
9+
- Upgrade SharePoint Framework solution or SharePoint add-in to a site, which has a newer version available in the tenant app catalog
10+
- Uninstall SharePoint Framework solution or SharePoint add-in from the site
11+
12+
ALM APIs can be used to perform exactly the same operations which are available from UI perspective. When these APIs are used, all typical actions will be performed. Here are some of the characteristics for ALM APIs.
13+
14+
- Install and UnInstall events are being fired for provider hosted add-ins when corresponding operations are occurred
15+
- ALM APIs supports app-only based operations
16+
17+
ALM APIs are natively provided using REST APIs, but there is also additional CSOM extensions and PowerShell commandlets available through SharePoint Patterns and Practices
18+
19+
## REST API
20+
21+
### Add solution package to tenant app catalog
22+
23+
Adding solution to the tenant app catalog. This API is designed to be executed in the context of the tenant app catalog site.
24+
25+
```
26+
/_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Add(overwrite=true, url='test.txt')";
27+
method: POST
28+
binaryStringRequestBody: true
29+
body: 'byte array of the file'
30+
```
31+
32+
### Deploy solution package in tenant app catalog
33+
34+
Enable solution to be available to install to specific sites. This API is designed to be executed in the context of the tenant app catalog site.
35+
36+
```
37+
/_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Deploy";
38+
```
39+
40+
> [!NOTE]
41+
> This operation is required to be completed after add, before you can install packages to specific sites.
42+
43+
### Retract solution package in the tenant app catalog
44+
45+
Retract solution to be available from the sites. This API is designed to be executed in the context of the tenant app catalog site.
46+
47+
```
48+
/_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Retract";
49+
```
50+
51+
> [!NOTE]
52+
> If you run this operation after you have already installed solutions to site, they will stop working since solution is disabled from the tenant level.
53+
54+
### Remove solution package from tenant app catalog
55+
56+
Remove the solution package from the tenant app catalog. This API is designed to be executed in the context of the tenant app catalog site.
57+
58+
```
59+
/_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Remove";
60+
```
61+
62+
> [!NOTE]
63+
> Solution will be also automatically retracted, if that operation has not performed before Remove operation.
64+
65+
### List available packages from tenant app catalog
66+
67+
REST API for getting list of available SharePoint Framework solutions or add-ins in tenant app catalog.
68+
69+
```
70+
url: /_api/web/tenantappcatalog/AvailableApps
71+
method: GET
72+
```
73+
74+
### Details on individual solution package from tenant app catalog
75+
76+
REST API for getting details on individual SharePoint Framework solution or add-in available in the tenant app catalog.
77+
78+
```
79+
url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')
80+
method: GET
81+
```
82+
83+
### Install solution package from tenant app catalog to SharePoint site
84+
85+
Install a solution package with specific identifier from tenant app catalog to the site based on URL context. This REST call can be executed in the context of the site where the install operation should happen.
86+
87+
```
88+
url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Install";
89+
method: POST
90+
```
91+
92+
### Upgrade solution package in SharePoint site
93+
94+
Upgrade a solution package from the site to a newer version available in the tenant app catalog. This REST call can be executed in the context of the site where the upgrade operation should happen.
95+
96+
```
97+
url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Upgrade";
98+
method: POST
99+
```
100+
101+
### Uninstall solution package from SharePoint site
102+
103+
Uninstall a solution package from the site. This REST call can be executed in the context of the site where the uninstall operation should happen.
104+
105+
```
106+
url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Upgrade";
107+
method: POST
108+
```
109+
> [!NOTE]
110+
> When you use the REST API to uninstall solution package from the site, it is not relocated to the recycle bin.
111+
112+
113+
## SharePoint PnP PowerShell cmdlets to programmatically add and deploy SharePoint Apps
114+
115+
Using [PnP PowerShell](https://msdn.microsoft.com/en-us/pnp_powershell/pnp-powershell-overview) you can automate the deployment, publishing, installing, upgrading and retracting your apps. Checkout below chapter to learn more about this cmdlets.
116+
117+
### Adding and publishing your app to the app catalog
118+
Adding your app (.sppkg file, .app file) to the tenant app catalog is a per-requisite to later on make your app available for use in your SharePoint sites. Doing so can be done using below simple cmdlet:
119+
120+
```PowerShell
121+
Add-PnPApp -Path ./myapp.sppkg"
122+
```
123+
124+
Once added you'll need to continue with publishing your app, effectively making the app available to be used by the users of your tenant. Below PnP PowerShell cmdlets shows how this can be done:
125+
126+
```PowerShell
127+
Publish-PnPApp -Identity <app id> -SkipFeatureDeployment
128+
```
129+
130+
131+
> [!NOTE]
132+
> Use the SkipFeatureDeployment flag to allow an app that was developed for tenant wide deployment to be actually available as a tenant wide deployed app.
133+
134+
135+
136+
### Removing the app from the app catalog
137+
Obviously you might also want to remove an earlier added app and that can be done using the following cmdlet:
138+
139+
```PowerShell
140+
Remove-PnPApp -Identity <app id>
141+
```
142+
143+
144+
### Using apps on your site
145+
Once the app was added to the app catalog and published you can continue with installing the app to your site.
146+
147+
```PowerShell
148+
Install-PnPApp -Identity <app id>
149+
```
150+
151+
152+
An added app also needs be upgraded:
153+
154+
```PowerShell
155+
Update-PnPApp -Identity <app id>
156+
```
157+
158+
159+
And you off course also uninstall the app again from your site:
160+
161+
```PowerShell
162+
Uninstall-PnPApp -Identity <app id>
163+
```
164+
165+
166+
> [!NOTE]
167+
> When you uninstall an app from your site the app is completely deleted, so it will not end up in the site's recycle bin.
168+
169+
170+
171+
### Knowing which apps are there for you to use
172+
Getting a list of apps that can be added to the site is possible using:
173+
174+
```PowerShell
175+
Get-PnPAvailableApp
176+
```

‎docs/apis/communication-site-creation-rest.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This topic assumes that you are already familiar with the topics Get to know the
99
The following REST commands are available for creating a modern SharePoint Communication site.
1010

1111
- **Create** - Create a new SharePoint Communication site
12-
- **Status** - Get the status of a SharePoint Communication site
12+
- **Status** - Get the status of a SharePoint Communication site
1313

1414
The URL for communication site REST commands is based on `_api/sitepages/communicationsite`. For example, these are the endpoints for the commands listed above:
1515

‎docs/design/accessibility.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: Accessibility in SharePoint web part design
3+
ms.date: 9/25/2017
4+
---
5+
6+
<!--Based on how rough this content is in it's current state, i'm going to pull it from this initial release so we can edit and better prepare. -->
7+
8+
9+
10+
11+
# Accessibility in SharePoint web part design
12+
13+
Developing an equal experience that meets all users' unique visual, hearing, dexterity, cognitive, and speech needs is an important component of SharePoint web part design. Accessible design applies not only to people with disabilities, but also to potential situational impairments. Accessible design is good design.
14+
15+
## Accessibility guidelines
16+
17+
<!-- Make sure that this is an external resource that folks can access. Original link was to a OneNote file. -->
18+
All Microsoft products must meet the requirements listed in the [Microsoft Accessibility Standards](https://microsoft.sharepoint.com/teams/msenable/Pages/MASDetails.aspx
19+
"Link to Microsoft Accesssibility Standards").
20+
21+
<!-- Fabric components are not designed to be accessible already? And, shouldn't components that aren't based on Fabric also be accessible? -->
22+
23+
If you're building a dialog box, file picker, or any other [Office UI Fabric](https://dev.office.com/fabric#/components) component, follow the guidance in this article to ensure that your content is accessible.
24+
25+
<!-- Not sure why we have that link? It currently goes to the OneNote file. Where is the Common UI Controls content? Is that related to accessibility? -->
26+
27+
[Common UI Controls](https://microsoft.sharepoint.com/teams/STS/_layouts/OneNote.aspx?id=%2Fteams%2FSTS%2FShared%20Documents%2FSP%20Accessibility%2FAccessibility%20Guidance&wd=target%28Accessibility%20101.one%7C0005C142-938C-4411-B543-B9F4199E19B3%2FEverything%20you%20need%20to%20know%20about%20Accessibility%7CE099AFE3-8804-4E1F-BA50-99493AB8A3D0%2F%29 "Link to Common UI Controls")
28+
29+
## Accessibility testing
30+
31+
<!-- FYI, I added links. Can we assume that our target audience uses the Edge browser? -->
32+
33+
Test your web part first with [Narrator](https://support.microsoft.com/en-us/help/22798/windows-10-narrator-get-started) and Microsoft Edge, and then verify the accessibility experience with [JAWS](http://www.freedomscientific.com/Products/Blindness/JAWS).
34+
35+
Narrator and Microsoft Edge are standards compliant. When you test with that combination, you are more likely to find issues, and you can validate that your site meets accessibility standards.
36+
37+
JAWS is the market leader in screen readers. JAWS includes features that can improve the accessibility of some websites that aren't as accessible in other screen readers. Therefore testing in JAWS might not ensure that your site meets all accessibility requirements.
38+
 
39+
You might also want to test for whatever combination of browser and screen reader has the greatest market share for your website.
40+
41+
<!-- Delete? This doesn't seem like text that should be in externally published docs?
42+
When suppliers test with JAWS, we ask them to repro identified bugs with Narrator and Edge. In the case a bug does not repro with Narrator/Edge it is sent to Mary Smith who works with VFO for a Jaws specific fix.
43+
-->
44+
45+
## Keyboard navigation
46+
47+
<!-- Is this section telling people how to navigate via a keyboard, or how to design to optimize for keyboard navigation? If the former, . -->
48+
49+
For some users, navigating a site via keyboard is more accessible. Power users also often rely on keyboard navigation. Use keyboard shortcuts such as tabs to go controls on the page, and use arrow keys to navigate inside controls.
50+
51+
### Navigation between controls
52+
53+
Each control is a tab stop. Within a control, the following rules apply:
54+
55+
- In general, the first tab stop is the top left area of the control. The last tab stop is the bottom right control.
56+
- For modal surfaces, the last tab stop should be the commit actions.
57+
- For lists, the first tab stop should be the first item in the list, the next should be the commands, and then the navigation, settings, and so on.
58+
59+
<!-- We should make sure the content in the accessibility topic is accessibible. ;) Please describe the information that the image conveys; something like this (also consider making the image an actual screen shot, that might be more clear):
60+
61+
In the following image:
62+
The first tab is the list item.
63+
The second tab is the command.
64+
The third tab is the navigation.
65+
-->
66+
![Image that shows the tab stops on a SharePoint page](https://i.imgur.com/Vn3VosN.png)
67+
68+
### Navigation within a control
69+
70+
You can use arrow keys to move to items in a control, such as choices in a menu, commands in a command bar, or items in a list.
71+
72+
<!-- This image is not very clear. Do you need to have the "blank" list box on the left? -->
73+
74+
![Using arrow keys to navigate within a control](https://i.imgur.com/vF0Nk73.png)
75+
76+
### Selecting the current item
77+
78+
Use the space bar to select or deselect the item currently in focus in a control.
79+
80+
![Using the space bar to select an item in a list](https://i.imgur.com/j3fBKPl.png)
81+
82+
### Run a control
83+
84+
Press **Enter** or the return key to run a control.
85+
86+
![Press enter to run a control](https://i.imgur.com/s0nMPdT.png)
87+
88+
### Leave a control
89+
90+
Press **Escape** to exit a control and return to the container.
91+
92+
![Pressing Escape to leave a control and return to the container](https://i.imgur.com/uD99zIX.png)
93+
94+
### Go to the first or last item
95+
96+
Press **Home** or **End** to go directly to the first or last item in a list, menu, and so on.
97+
98+
![Pressing Home or End to go to the first or last item in a list](https://i.imgur.com/gGKsh74.png)
99+
100+
101+
## Screen reader navigation
102+
103+
Users who have vision impairments rely on screen readers to navigate the site UI.
104+
105+
<!-- Narrator isn't a third-party product. This image needs more text/explanation; please also clarify the alt text. Is this section important, or can it be removed, given the previous mention of testing with Narrator and JAWS? Again, the intent/target audience for this information isn't clear - is it for the user, or the designer? Can you explain why this information is important from the designer's POV? -->
106+
107+
![Screen reader navigation of a SharePoint page](https://i.imgur.com/ar23o3X.png)
108+
109+
## Alt text and transcripts
110+
111+
Use alt text to provide descriptions of images that can be consumed by screen readers. This is useful for vision-impaired users who cannot consume information visually. Make sure that your alt text is descriptive, keeping in mind that some readers are relying on a screen reader to access the information conveyed in the image.
112+
113+
Don't rely only on color to convey meaning; rely on both color and shape.
114+
115+
To be fully compliant with accessibility standards, include alt text and a complete transcript of audio and video content on your site.
116+
117+
## Minimum readable contrast
118+
119+
A minimum level of contrast is essential to help users with vision impairments consume the content on the page. It is also important to aid readability in low light and glare situations.
120+
121+
<!-- Convert this image into a table, for accessibility. ;) -->
122+
123+
![Neutral, Theme, and Alert colors for minimum readable contrast](https://i.imgur.com/L7pSF1w.png)
124+
125+
126+
## High contrast
127+
128+
Use high contrast colors as a guide for color choices for components and states on the web. Windows computers only have the ability to detect whether a PC is running high contrast, or high contrast white. For this reason, use the default high contrast black setting for any high contrast, non-white theme.
129+
130+
<!-- In the left part of the image, I think the title should be "High Contrast Black". -->
131+
132+
![High contrast black and high contrast white settings](https://i.imgur.com/qvTFzd4.png)
133+
134+
135+
136+
137+

‎docs/toc.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,8 @@
193193
href: design/themes-colors.md
194194
- name: Placeholders and fallbacks
195195
href: design/placeholders-and-fallbacks.md
196+
- name: Accessibility
197+
href: design/accessibility.md
196198
- name: Showcase web part
197199
href: design/showcase-web-part.md
198200
- name: Design considerations
@@ -246,6 +248,8 @@
246248
items:
247249
- name: Create Communication Sites
248250
href: apis/communication-site-creation-rest.md
251+
- name: Application Lifecycle Management (ALM) APIs
252+
href: apis/alm-api-for-spfx-add-ins.md
249253
- name: REST
250254
items:
251255
- name: SharePoint REST service

0 commit comments

Comments
 (0)