In this article, we discuss the limitations in using an app part’s custom properties to store configuration data, and then we recommend an alternative approach by using the SharePoint hidden list.

When developing the Yammer app for SharePoint, we found that using an app part’s custom properties to store configuration data is easy and straightforward. However, we can’t use this method if we don’t know the URLs ahead of time. An alternative solution is to use the SharePoint hidden list built within the app’s hosting page when an app is installed on a SharePoint website. 

The following sections explain the reason that we don’t recommend to use app part’s custom properties to store data and how to use a SharePoint hidden list to store data.

What is an app part?

An app part (AppPart) is an embedded part for a SharePoint website. It is one type of WebPart represented by the ClientWebPart class. With an app part, you can install and show your apps for SharePoint right in a page inside the SharePoint hosting website. Users can add multiple app parts to a single SharePoint hosting website. And sometimes, they want to customize each app part instance’s appearance and behavior. 

An app part is essentially a wrapper for an IFrame that hosts a page within the app’s hosting website. If the page rendered within an app part wants to visit the app part’s properties, it needs the app part’s hosting website’s URL and the hosting page’s URL. With these two URLs, all the web parts on the app part hosting website can be retrieved. And then we can filter them using WebPart ID. Finally, we can store configuration data in the app part. For how to create an app with an app part, and add some properties to it, see How to: Create app parts to install with your app for SharePoint.

How do you store the various configuration data so that the hosting SharePoint website and the app part can interact with each other? In this article, we discuss two approaches, the first approach’s limitations are discussed and then we recommend the second approach.  Using an app part’s custom properties to store configuration data is not recommended

If you already know the app part hosting website’s URL and the hosting page’s URL, you can use the AppPart’s custom properties to store all configuration data. It has two advantages.

1. Data is stored in an AppPart, and data will be deleted once the AppPart is deleted. 
2. The implementation and maintenance is easy.  

However, the AppPart custom properties approach has limitations.

Limitations

Using the AppPart custom properties to store data has its limitations:

1. There isn’t a good way to access the hosting website's URL from the app part page (document.referrer doesn’t always work well). Developers need to know ahead of time the app part’s hosting website’s URL and the hosting page’s URL. 
2. Granting an app the list manage permission inside the hosting SharePoint site is not a good practice because the app might therefore access all app parts from other apps inside that hosting website. This is contrary to the SharePoint apps’ philosophy of being self-contained.
3. Implementation related to API oWebPartDefinition.get_id() only works on WebPart pages. It doesn’t work on Wiki pages. 

Due to these limitations, we don’t recommend you to use app part’s custom properties to store data. In the following subsection, we talk briefly the process of this approach for demo purpose. We don’t recommend this approach therefore we don’t provide the details.

How to use app part’s custom properties to store configuration data?

Because this app is trying to visit the hosting SharePoint website, you need grant the app the list scope manage permission of the hosting SharePoint website page. You do this by updating the manifest file AppManifest.xml.

Assign appropriate list scope permission to the app

Open the file AppManifest.xml in Visual Studio 2012, click the Permissions tab and then add the Manage permission to the list scope.

Figure 1. Assign the list scope manage permission to your app

Define an app part’s custom properties  

In one app part, custom properties can be defined in the app part’s element.xml file. Each property can be given attributes such as name, type, and default value. 

In the following element.xml file, the attribute Src points to the app page to be rendered in an app part. It includes several tokens. Here WpId stands for the WebPart ID of the current app part. And there are two custom properties named strProp and intProp.

<Content Type="html" Src="~appWebUrl/Pages/SampleAppPart.aspx?{StandardTokens}
&strProp=_strProp_&intProp=_intProp_&wpId=_WPID_" /><Properties><PropertyName="strProp"Type="string"RequiresDesignerPermission="true"DefaultValue="String default value"WebCategory="Basic app part category"WebDisplayName="A property of type string.">Property><PropertyName="intProp"Type="int"RequiresDesignerPermission="true"DefaultValue="0"WebCategory="Basic app part category"WebDisplayName="A property of type integer.">Property>Properties>

After these tokens are added, when the SampleAppPart.aspx file loads, the property values can be extracted from the query string using the following JavaScript scripts.  

for (var i = 0; i < params.length; i = i + 1) {var param = params[i].split("=");if (param[0] == "wpId") {
        webpartId = decodeURIComponent(param[1]);
        webpartId = webpartId.replace("g_", "").split("_").join('-');
    } else if (param[0] == "strProp")
        strProp = decodeURIComponent(param[1]);else if (param[0] == "intProp") {
        intProp = decodeURIComponent(param[1]);
    }
}

To get or set custom properties, we need specify the app part’s hosting website’s URL (siteUrl) and the hosting page’s URL (serverRelativeUrl). Otherwise, this implementation does not work.  

var siteUrl = "/sites/test";var serverRelativeUrl = "/sites/test/SitePages/sample.aspx";

We could get all the web parts on this hosting website by limitedWebPartManager.get_webParts(), find the current app part using WebPartId, and get all properties of an app part by get_properties(). And then we update the custom properties by set_item('strProp', 'My String Prop value').

As mentioned above, we don’t  recommend this approach and we recommend the SharePoint hidden list approach mentioned in the following section.

Use SharePoint hidden list to store configuration data

We recommend to use the SharePoint hidden list to store data for each app part instance. The SharePoint hidden list is built within the app’s hosting web when the app is installed on a SharePoint site. 

How to use the SharePoint hidden list to store configuration date?

First you get the current WebPart ID via a way similar to the first approach by adding tokens in the URL, and then you store data related to the current app part to one record of the hidden list when the app part is added. 

1. Create a list within the current project. 
   1. Right click the current project, choose Add > New Item. The Add New Item – Sample windows appears as in Figure 3
      Figure 2. Add a list in your app web
   2. Name the list ConfigList, and click Add. 
   3. Choose the default custom list and click Finish. This list will be created once the app is installed on the SharePoint site, and it will be deleted after the app is uninstalled.
      Figure 3. Create a list
2. Create columns and each column represents one configuration data. 
   1. In the Solution Explorer, double click “ConfigListInstance” under ConfigList.
   2. Edit the columns for this list.
      Here we create two columns of strings named “WebPartId” and “Name” respectively, and a numeric type column named “Id” as shown in Figure 4. And you can customize your configuration columns according to your own specific requirements.
   3. Add the "wpId=_WPID_" to src as a parameter similar to the way we used in the previous section and to parse out the WebPart Id with JavaScript.
   4. Next, we would write code and realize this: once the app part is loaded, we detect whether the current web part has its record in ConfigList by WebPart ID. If not, we will add one; otherwise, we will retrieve all the configuration data and use the data to render pages.
      Figure 4. Customize your list columns

Note that in this approach, when a user removes an app part, no event can be detected within the app’s hosting page. Hence the corresponding record cannot be removed, which could be a risk for scenarios with big configuration data and app part frequent deletion. 

References

• WebPart Class
• ClientWebPart class
• How to: Create app parts to install with your app for SharePoint

Attribution 

This article was written by ecoSystem team SDE Peng Wang and content publisher Tony Liu. Content publisher Ricardo Loo Foronda and program manager Sudheer Maremanda provided valuable feedback.