| page_type | products | languages | extensions | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
sample |
|
|
|
Localize the add-in web, host web, and remote components of a SharePoint Add-in
SharePoint add-in model is considered as a legacy option for extending SharePoint user interface. Please see SharePoint Framework documentation and the SharePoint Framework samples for the future proven option to extend SharePoint Online. Possible backend services should be using Azure Active Directly based registration and related app models.
Summary
Use resource (resx) files and JavaScript string files to localize custom add-in parts, web parts, popup dialogs, page chrome, lists, and list columns.
Applies to
- SharePoint Online and on-premise SharePoint 2013 and later
Prerequisites
This sample requires the following:
-
A SharePoint 2013 development environment that is configured for add-in isolation and the Spanish (es-ES) and French (fr-FR) language packs. (A SharePoint Online Developer Site is automatically configured for add-in isolation and all language packs. For an on premise development environment, see Set up an on-premises development environment for SharePoint Add-ins and Language packs in SharePoint Server 2013.)
-
The SharePoint Online tenancy (or on-premise SharePoint web application) must have site collections created with the Developer Site template in each of these languages:
- English (en-US)
- Spanish (es-ES)
- French (fr-FR)
To create a Developer Site see Test your localized SharePoint Add-in. For more information about creating a developer site in SharePoint Online, see Create a developer site on an existing Office 365 subscription. For more information about creating one in SharePoint on-premises, see Set up an on-premises development environment for SharePoint Add-ins.
-
Visual Studio and the Office Developer Tools for Visual Studio (March, 2014, version or later) installed on your developer computer
Description of the code
This sample simulates a bookstore by using a SharePoint 2013 document library in which every document is a book. End users can request and buy new books by using the provided custom actions. The components of the add-in are localized for English and Spanish.
Note: The add-in is designed to use the base language of the SharePoint website -- the language that was selected when the website was created -- to determine which language it should use to render the add-in's componenents. It does not use the default language of set in the user's browser, however, some of the techniques in the sample can be used, with some modification when the browser setting is the criterion.
This sample includes a remote web application that has web pages to handle the book request and book buying experiences in a simulated bookstore. (These remote web pages are never opened full screen. Some are surfaced in add-in parts. Some serve only to pass cross-domain JavaScript through an iFrame.
Custom actions provide the link between the document library and the add-in pages. The cross-domain library provides data access from the remote web application to the document library. The chrome control and SharePoint style sheet provide the classes to consistently style the web application pages. A custom list provides storage for the orders placed by the end user. End users can use the provided add-in part to display the orders history.
The sample demonstrates how to localize the following kinds of add-in components:
- Add-in title
- Custom lists
- Custom actions (menu commands)
- Add-in part
- SharePoint pages
- Remote web application pages
- SharePoint Chrome control
Components of the sample
The sample contains the following:
-
SharePoint-Add-in-Localization project, which includes the following components:
- Request a book custom action (menu command)
- But this book custom action (menu command)
- My orders add-in part
- Orders custom list
- Order status custom list
- Add-in start page in the add-in web
- Add-in web resource (resx) files
- Host web resource (resx) files
- JavaScript resource (strings) files
-
SharePoint-Add-in-LocalizationWeb project, which includes the following components:
- BookOrders remote web page and JavaScript file
- BookPurchase remote web page and JavaScript file
- BookRequest remote web page and JavaScript file
- ChromeLoader JavaScript file
- Common JavaScript file
- StyleLoader JavaScript file
- Resource (resx) files
- JavaScript resource (strings) files
To use the sample
-
Open Visual Studio as an administrator.
-
Open the .sln file.
CARRY OUT THE REMAINING STEPS OF THE PROCEDURE THREE TIMES: The first time for your English developer site. Then for the Spanish developer site, and then for the French developer site. Screenshots show what you should see in English and Spanish. For the French developer site, you should see the "invariant language" strings, which are English in this sample. The instructions below use English for the SharePoint and add-in UI elements. You will find the Spanish equivalents in the same relative locations in the UI.
-
In Solution Explorer, highlight the SharePoint add-in project and replace the Site URL property with the URL of your SharePoint developer site.
-
Press F5.
-
After the add-in installs, the consent page opens. Click Trust It.
-
The start page opens and looks similar to the follwoing. (The content is a very brief version of these instructions.)
-
Open the raw HTML view of the page. (In IE, right-click the page and select View Code.)
-
Find the line
<h2 id="instructionsheading">INVARIANT Instructions</h2>. -
Notice that the term "INVARIANT" is part of the heading but it only appears on the rendered version of the page on the French website. On the English and Spanish websites, alternate strings are injected into the page by JavaScript.
-
Close the raw view, and in the browser open another tab and navigate to the host web home page. Then navigate to any document library on the host web, such as Documents.
-
Open the Library tab on the ribbon and click the Request a Book button.
-
On the dialog that opens, enter a book title and press Request book.
-
The new file appears in the library.
-
Open the context menu for the new document and select Buy this book. A book purchase form page opens.
-
Press the Buy book! link, and the fake Latin text of the book appears on the form.
-
Navigate to any other page on the host web, such as its home page.
-
On the ribbon select Page | Edit | Insert.
-
On the Insert ribbon select Add-in part. (On older versions of SharePoint, it may say App part.)
-
Select the Book orders add-in part, and then put the cursor in any Web Part zone on the page and click Add. The add-in part will be added to the page. It may take a full minute for the data to be populated. When it has finished rendering, there is a list of all the books you have ordered.
-
Delete the add-in part from the page. (Removing an add-in, or retracting it in Visual Studio, does not remove add-in parts from pages.)
-
Reopen the tab with the add-in's start page, and use the link to the Orders list in the last line of the instructions to open the Orders list in another tab. Notice that the price in English site is USD, but it is Euros in the Spanish site.
-
Just to the right of the list title is a small "i" in a circle. Click this to see the list description.
-
Reopen the tab with the add-in's start page, and use the link to the Order status list in the last line of the instructions to open the Order status list in another tab. Note again that the description, as well as the title and the status values has been localized.
Troubleshooting
The following table lists common configuration and environment errors that prevent the sample from running or deploying properly, and how to solve them.
|
Problem |
Solution |
|---|---|
|
The add-in part does not display any content. The add-in part displays the following error: Navigation to the webpage was canceled. |
The browser blocked the content page. The solution might be different depending on the browser you are using:
|
|
Error "This content cannot be displayed in a frame." when the user selects a custom menu command. |
See this forum discussion: Error when viewing apps that utilize webparts this content cannot be displayed in a frame. |
Questions and comments
We'd love to get your feedback on this sample. You can send your questions and suggestions to us in the Issues section of this repository.
## Additional resourcesCopyright
Copyright (c) Microsoft. All rights reserved.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.