SharePoint のプロバイダー ホスト型アドインを使用して UX コントロールを作成するCreate UX controls by using SharePoint provider-hosted add-ins

ホスト Web の UX コントロールと同様に機能および動作する、SharePoint プロバイダー ホスト型アドインの UX コントロールを作成します。Create UX controls in SharePoint provider-hosted add-ins that work and behave like UX controls on the host web.

この記事では、プロバイダー ホスト型アドインで UX コントロールを実装する方法を示す 3 つのサンプルについて説明します。The article describes three samples that show you how to implement UX controls in your provider-hosted add-in:

  • Core.PeoplePicker– ユーザー選択コントロールを追加する方法を示します。Core.PeoplePicker - Shows you how to add a people picker control.

  • Core.TaxonomyMenu– ローカライズ可能な分類メニュー コントロールを実装する方法を示します。Core.TaxonomyMenu - Shows you how to implement a localizable taxonomy menu control.

  • Core.TaxonomyPicker– 分類選択コントロールを実装する方法を示します。Core.TaxonomyPicker - Shows you how to implement a taxonomy picker control.

これらのサンプルでは、JavaScript および JSOM を使用して SharePoint と情報をやり取りし、クロス ドメイン ライブラリ を使用してアドインからホスト サイト ドメインへの関数呼び出しを処理します。These samples use JavaScript and the JSOM to communicate with SharePoint and use the cross-domain library to handle function calls from the add-in to the host site domain.

注意

この記事で提供されるコードは、明示または黙示のいかなる種類の保証なしに現状のまま提供されるものであり、特定目的への適合性、商品性、権利侵害の不存在についての暗黙的な保証は一切ありません。The code in this article is provided as-is, without warranty of any kind, either express or implied, including any implied warranties of fitness for a particular purpose, merchantability, or non-infringement.

ユーザー選択コントロールPeople picker control

Core.PeoplePicker サンプルには、プロバイダー ホスト型アドインにユーザー選択コントロールを実装する方法が示されています。ユーザーが名前をテキスト入力ボックスに入力し始めると、コントロールは一致する可能性のある名前をユーザー プロファイル ストアで検索し、それらを UI に表示します。アドインは、構成と拡張が可能なユーザー選択コントロールを表示します。これはリモート ホストで実行され、ホスト サイトのユーザー プロファイル ストアでクエリを実行して、ユーザー入力と照合します。The Core.PeoplePicker sample shows you how to implement a people picker control in a provider-hosted add-in. When the user starts typing a name into the text input box, the control searches the user profile store for potential matches, and displays them in the UI. The add-in displays a configurable and extensible people picker control that runs on a remote host and queries the user profile store on the host site to match user inputs.

ユーザー選択コントロールPeople picker control

ユーザー選択コントロール

注意

サンプルの Visual Studio ソリューションには、アドインの展開時に確実にアドイン Web を作成するための、"Dummy" というモジュールが含まれています。The Visual Studio 2013 solution for the sample contains a module named "Dummy" to ensure that when the add-in is deployed, it creates an add-in web. クロス ドメイン呼び出しには、アドイン Web が必要です。An add-in web is required for cross-domain calls.

Core.PeoplePickerWeb プロジェクトの Scripts フォルダーには、app.js ファイルと peoplepickercontrol.js ファイルが含まれています (追加の言語サポート用のユーザー選択リソース ファイルと共に)。The Scripts folder of the Core.PeoplePickerWeb project contains app.js and peoplepickercontrol.js files (along with people picker resource files for additional language support). App.js ファイルは、ドメイン間ライブラリを使用してクライアント コンテキストをフェッチし、Default.aspx ファイル内の HTML をユーザー選択コントロールにフックします。The app.js file fetches client context by using the cross-domain library and hooks the HTML in the Default.aspx file into the people picker control. Default.aspx ファイルには、テキスト ボックスとユーザー検索機能の両方を実装する <div> タグが含まれています。The Default.aspx file contains the <div> tags that implement both the text box and the people search capability.

<div id="divAdministrators" class="cam-peoplepicker-userlookup ms-fullWidth">
  <span id="spanAdministrators"></span>
<asp:TextBox ID="inputAdministrators" runat="server" CssClass="cam-peoplepicker-edit" Width="70"></asp:TextBox>
</div>
<div id="divAdministratorsSearch" class="cam-peoplepicker-usersearch ms-emphasisBorder"></div>
<asp:HiddenField ID="hdnAdministrators" runat="server" />


app.js ファイルは、ユーザー選択コントロールを作成して構成します。The app.js file then creates and configures a people picker control.

//Make a people picker control.
//1. context = SharePoint Client Context object
//2. $('#spanAdministrators') = SPAN that will 'host' the people picker control
//3. $('#inputAdministrators') = INPUT that will be used to capture user input
//4. $('#divAdministratorsSearch') = DIV that will show the 'drop-down' of the picker
//5. $('#hdnAdministrators') = INPUT hidden control that will host resolved users
peoplePicker = new CAMControl.PeoplePicker(context, $('#spanAdministrators'), $('#inputAdministrators'), $('#divAdministratorsSearch'), $('#hdnAdministrators'));
// required to pass the variable name here!
peoplePicker.InstanceName = "peoplePicker";
// Hook up everything.
peoplePicker.Initialize();


ユーザー選択コントロールは JSOM ライブラリ内の ClientPeoplePickerWebServiceInterface オブジェクトに問い合わせて、入力された文字列と一致する名前のユーザーの検索を開始します。The people picker control queries the ClientPeoplePickerWebServiceInterface object in the JSOM library to initiate searches for users whose names match the character strings entered.

if (searchText.length >= parent.GetMinimalCharactersBeforeSearching()) {
                            resultDisplay = 'Searching...';
                            if (typeof resultsSearching != 'undefined') {
                                resultDisplay = resultsSearching;
                            }

                  var searchbusy = parent.Format('<div class=\'ms-emphasisBorder\' style=\'width: 400px; padding: 4px; border-left: none; border-bottom: none; border-right: none; cursor: default;\'>{0}</div>', resultDisplay);
                            parent.PeoplePickerDisplay.html(searchbusy);
                            // Display the suggestion box.
                            parent.ShowSelectionBox();

                   var query = new SP.UI.ApplicationPages.ClientPeoplePickerQueryParameters();
                            query.set_allowMultipleEntities(false);
                            query.set_maximumEntitySuggestions(2000);
                            query.set_principalType(parent.GetPrincipalType());
                            query.set_principalSource(15);
                            query.set_queryString(searchText);
                            var searchResult = SP.UI.ApplicationPages.ClientPeoplePickerWebServiceInterface.clientPeoplePickerSearchUser(parent.SharePointContext, query);

                  // Update the global queryID variable so that you can correlate incoming delegate calls.
                            parent._queryID = parent._queryID + 1;
                            var queryIDToPass = parent._queryID;
                            parent._lastQueryID = queryIDToPass;

                  // Make the SharePoint request.
                            parent.SharePointContext.executeQueryAsync(Function.createDelegate(this, function () { parent.QuerySuccess(queryIDToPass, searchResult); }),
                                                Function.createDelegate(this, function () { parent.QueryFailure(queryIDToPass); }));

分類メニュー コントロールTaxonomy menu control

Core.TaxonomyMenu サンプルには、用語ストアからデータを読み込むローカライズ可能な分類メニュー コントロールをプロバイダー ホスト型アドインに実装する方法が示されています。また、アドインは メニューに読み込む必要な用語ストアの言語、グループ、セット、および用語をセットアップし、表示言語を設定するユーザーの言語の優先順位を確認します。The Core.TaxonomyMenu sample shows you how to implement a localizable taxonomy menu control that is populated from the term store in a provider-hosted add-in. The add-in also sets up the required term store languages, groups, sets, and terms for populating the menu, and checks the user's language preference to set the display language.

アドインは、用語ストアをセットアップし、用語をその用語ストアに読み込む TaxonomyHelper クラス (CSOM) を実装します。その後で、ナビゲーション リンクを表示する JavaScript ファイルをサイトのルート フォルダーにアップロードします。The add-in implements a TaxonomyHelper class (CSOM) that sets up the term store and populates it with terms. It then uploads into the site's root folder a JavaScript file that displays the navigational links.

アドインは用語ストアをホスト ストアにセットアップします。また、CSOM オブジェクトとメソッドを使用して、用語のグループおよびセットを作成し、4 つの用語を用語セットに読み込みます。The add-in sets up the term store on the host site. It uses CSOM objects and methods to create a term group and set, and then populates the term set with four terms.

用語ストアのセットアップ画面Term store setup screen

用語ストアのセットアップ画面

[用語ストアのセットアップ] ボタンを選択すると、アドインは以下を実行します。When you choose the Setup term store button, the add-in:

  • 用語ストアで必要な言語 (英語、ドイツ語、フランス語、およびスウェーデン語) が有効になっていることを確認します。Makes sure that the required languages (English, German, French, and Swedish) are enabled in the term store.
  • 用語グループと用語セットを作成し、4 つの新しい用語を用語セットに読み込みます。Creates a term group and term set and populates the term set with four new terms.

TaxonomyHelper クラスの次のコードは、必要な言語が有効であることを確認し、有効でない場合はそれらを有効にします。The following code in the TaxonomyHelper class verifies that the required languages are enabled, and if they're not, it enables them.

var languages = new int[] { 1031, 1033, 1036, 1053 };
            Array.ForEach(languages, l => { 
                if (!termStore.Languages.Contains(l)) 
                    termStore.AddLanguage(l); 
            });

            termStore.CommitAll();
            clientContext.ExecuteQuery();

// Create the term group.
termGroup = termStore.CreateGroup("Taxonomy Navigation", groupId);
                clientContext.Load(termGroup);
                clientContext.ExecuteQuery();


最後に、同じ TaxonomyHelper クラスの次のコードは、ドイツ語、フランス語、およびスウェーデン語のラベルと一緒に新しい用語をそれぞれ作成します。また、用語ストア管理ツールの Simple Link or Header プロパティと同等の _Sys_Nav_SimpleLinkUrl プロパティの値を設定します。この場合、各用語の URL は元のルート サイトをポイントします。Finally, the following code in the same TaxonomyHelper class creates each new term, along with labels for the German, French, and Swedish languages. It also sets a value for the _Sys_Nav_SimpleLinkUrl property, which is equivalent to the Simple Link or Header property in the Term Store Management Tool. In this case, the URL for each term points back to the root site.

var term = termSet.CreateTerm(termName, 1033, Guid.NewGuid());
term.CreateLabel(termNameGerman, 1031, false);
term.CreateLabel(termNameFrench, 1036, false);
term.CreateLabel(termNameSwedish, 1053, false);
term.SetLocalCustomProperty("_Sys_Nav_SimpleLinkUrl", clientContext.Web.ServerRelativeUrl);


次に、アドインはホスト サイトのルート フォルダーに topnav.js ファイルを挿入します。このファイルには、この用語セットからのリンクをホスト サイトのホーム ページのナビゲーションに挿入する JavaScript が含まれています。アドイン UI は、アドインが JavaScript ファイルをアップロードした後に、ナビゲーション リンクがホスト サイトに表示される方法も示します。Next, the add-in inserts the topnav.js file into the root folder of the host site. This file contains the JavaScript that inserts the links from this term set into the navigation of the host site's home page. The add-in UI also shows you how the navigational links will appear on the host site after the add-in uploads the JavaScript file.

topnav.js ファイルの次のコードでは、JSOM を使用してユーザーの優先言語が確認されます。The following code in the topnav.js file uses JSOM to check for the user's preferred language.

var targetUser = "i:0#.f|membership|" + _spPageContextInfo.userLoginName;
        context = new SP.ClientContext.get_current();
var peopleManager = new SP.UserProfiles.PeopleManager(context);
var userProperty = peopleManager.getUserProfilePropertyFor(targetUser, "SPS-MUILanguages");


次いでアドインは、ユーザーの優先言語が有効な言語のいずれかと一致するかどうかを判別します。一致するものが検出されると、次のコードによって、ユーザーの優先言語の用語および関連付けられているラベルが取得されます。The add-in then determines whether the user's language preference matches one of the enabled languages. If it finds a match, the following code gets the terms and the associated labels for the user's preferred language.

while (termEnumerator.moveNext()) {
    var currentTerm = termEnumerator.get_current();
    var label = currentTerm.getDefaultLabel(lcid);

    termItems.push(currentTerm);
    termLabels.push(label);
    context.load(currentTerm);


最後に、topnav.js ファイルの次のコードは、用語を含むリンクをホスト サイトの最上位のナビゲーション要素に挿入します。Finally, the following code in the topnav.js file inserts links that contain the terms into the top navigational element of the host site.

html += "<ul style='margin-top: 0px; margin-bottom: 0px;'>"
        for (var i in termItems) {
            var term = termItems[i];
            var termLabel = termLabels[i];
            var linkName = termLabel.get_value() != 0 ? termLabel.get_value() : term.get_name();
            var linkUrl = term.get_localCustomProperties()['_Sys_Nav_SimpleLinkUrl'];

            html += "<li style='display: inline;list-style-type: none; padding-right: 20px;'><a href='" + linkUrl + "'>" + linkName + "</a></li>";
        }
        html += "</ul>";

        $('#DeltaTopNavigation').html(html);
        SP.UI.Notify.removeNotification(nid);

分類選択コントロールTaxonomy picker control

Core.TaxonomyPicker サンプルは、プロバイダー ホスト型アドインに分類選択コントロールを実装する方法を示します。ユーザーがテキスト入力ボックスに用語を入力し始めると、コントロールは用語ストアで一致する可能性のあるものを検索し、入力ボックスの下のリストに表示します。The Core.TaxonomyPicker sample shows you how to implement a taxonomy picker control in a provider-hosted add-in. When the user starts typing a term into the text input box, the control searches the term store for potential matches and displays them in a list under the input box.

アドインは JSOM 分類ピッカーの要件に準拠する HTML ページを作成し、コントロールを追加して構成します。また、JSOM ライブラリを使用して、ホスト サイトの用語ストアでクエリを実行します。分類ピッカーは SharePoint Managed Metadata Service と通信します。この通信では、閉じられた用語セットを読み込み、オープンな用語セットに書き込めるように、分類アクセス許可の範囲で書き込みアクセス許可が必要になります。AppManifest.xml ファイルで適切な範囲の書き込みアクセス許可が設定されていることを確認します。The add-in creates an HTML page that conforms to the JSOM taxonomy picker requirements, and then adds and configures the control. It uses the JSOM library to query the host site's term store. The taxonomy picker communicates with the SharePoint Managed Metadata Service, which requires write permission at the taxonomy permission scope so that it can read from closed term sets and write to open term sets. Make sure that the AppManifest.xml file has set the write permission at the appropriate scope.

Core.TaxonomyPicker プロジェクトの Scripts フォルダーには、app.js ファイルと taxonomypickercontrol.js ファイルがあります (追加の言語サポート用の分類ピッカー リソース ファイルもあります)。app.js ファイルは、クロス ドメイン ライブラリを使用してクライアント コンテキストをフェッチし、Default.aspx ファイルの HTML を分類選択コントロールにフックします。Default.aspx ファイルには、テキスト ボックスと分類選択機能の両方を実装する非表示フィールドが含まれます。これはまた、箇条書きのリストも追加して、用語ストアから返される候補を表示します。The Scripts folder of the Core.TaxonomyPicker project contains app.js and taxonomypickercontrol.js files (along with a taxonomy picker resource file for additional language support). The app.js file fetches client context by using the cross-domain library and hooks the HTML in the Default.aspx file into the taxonomy picker control. The Default.aspx file contains the hidden field that implements both the text box and the taxonomy picker capability. It also adds a bulleted list to display suggestions returned from the term store.

<div style="left: 50%; width: 600px; margin-left: -300px; position: absolute;">
            <table>
                <tr>
                    <td class="ms-formlabel" valign="top"><h3 class="ms-standardheader">Keywords Termset:</h3></td>
                    <td class="ms-formbody" valign="top">
                        <div class="ms-core-form-line" style="margin-bottom: 0px;">
                            <asp:HiddenField runat="server" id="taxPickerKeywords" />
                        </div>
                    </td>
                </tr>
            </table>

            <asp:Button runat="server" OnClick="SubmitButton_Click" Text="Submit" />

            <asp:BulletedList runat="server" ID="SelectedValues" DataTextField="Label" />
</div>


app.js ファイルは、分類選択コントロールを作成して構成します。The app.js file then creates and configures a taxonomy picker control.

// Load scripts for calling taxonomy APIs.
                    $.getScript(layoutsRoot + 'init.js',
                        function () {
                            $.getScript(layoutsRoot + 'sp.taxonomy.js',
                                function () {
                                    // Bind the taxonomy picker to the default keywords term set.
                                    $('#taxPickerKeywords').taxpicker({ isMulti: true, allowFillIn: true, useKeywords: true }, context);
                                });
                        });


分類選択コントロールは次のコードを使用して、JSOM の TaxonomySession インスタンスを開き、用語ストアからすべての用語を読み込みます。The taxonomy picker control uses the following code to open a TaxonomySession instance in the JSOM to load all the terms from the term store.

// Get the taxonomy session by using CSOM.
            var taxSession = SP.Taxonomy.TaxonomySession.getTaxonomySession(spContext);
            //Use the default term store...this could be extended here to support additional term stores.
            var termStore = taxSession.getDefaultSiteCollectionTermStore();

            // Get the term set based on the properties of the term set.
            if (this.Id != null)
                this.RawTermSet = termStore.getTermSet(this.Id); // Get term set by ID.
            else if (this.UseHashtags)
                this.RawTermSet = termStore.get_hashTagsTermSet(); // Get the hashtags term set.
            else if (this.UseKeywords)
                this.RawTermSet = termStore.get_keywordsTermSet(); // Get the keywords term set.

            // Get all terms for the term set and organize them in the async callback.
            this.RawTerms = this.RawTermSet.getAllTerms();
            spContext.load(this.RawTermSet);
            spContext.load(this.RawTerms);
            spContext.executeQueryAsync(Function.createDelegate(this, this.termsLoadedSuccess), Function.createDelegate(this, this.termsLoadedFailed));

分類選択コントロールは読み込んだ用語から一致する可能性のあるものを検索し、必要に応じて、新しい用語を用語ストアに追加します。The taxonomy picker control then looks for potential matches from the loaded terms, and adds new terms to the term store as needed.

関連項目See also