How to add and read SharePoint Hosted custom App Part properties

This post was most recently updated on July 31st, 2024

Hello everyone, in this post we will discuss about custom Add-in Part properties with how to add and read custom Add-in Part properties.

If you are reading this post first, I would recommend to read SharePoint Hosted Add-ins as an App-Part first, that mentions what is an app part and how to create and show add-in as app part.

The ClientWebPart Element.xml contains the core definition (properties) for a Client Web Part.

Element.xml file have three elements which are <ClientWebPart> parent and <Content> ,<Properties> have child.

<ClientWebPart> : Use for configuring a client web part properties like Name, Title, Description, Width and Height.

<Content> : Content element identifies the location of the page inside that will render inside an client web part. Also we passed query string using pattern propertyName=_propertyName_.

Src="~appWebUrl/Pages/AccordionAppPartPage.aspx?{StandardTokens}&amp;BooleanProperty=_BooleanProperty_&amp;EnumProperty=_EnumProperty_&amp;StringProperty=_StringProperty_&amp;IntProperty=_IntProperty_"

1	Src="~appWebUrl/Pages/AccordionAppPartPage.aspx?{StandardTokens}&BooleanProperty=_BooleanProperty_&EnumProperty=_EnumProperty_&StringProperty=_StringProperty_&IntProperty=_IntProperty_"

<Properties> : In Properties element we define custom properties.

Client Web Part support only four custom properties. You define the custom properties in the Elements.xml file. There are four types of custom properties:

string – create simple string type text-box
int – create simple integer type text-box
boolean – create simple checkbox
enum – create simple selection list

The following example shows an Elements.xml file that declares a custom properties of Add-In part.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
 <ClientWebPart Name="AccordionAppPart" Title="Simple Accordion" Description="Create simple Accordion based on Accordion List" DefaultWidth="500" DefaultHeight="500">
 <!-- Content element identifies the location of the page that will render inside the client web part
 Properties are referenced on the query string using the pattern _propertyName_
 Example: Src="~appWebUrl/Pages/ClientWebPart1.aspx?Property1=_property1_" -->
 <Content Type="html" Src="~appWebUrl/Pages/AccordionAppPartPage.aspx?{StandardTokens}&BooleanProperty=_BooleanProperty_&EnumProperty=_EnumProperty_&StringProperty=_StringProperty_&IntProperty=_IntProperty_" />
 <!-- Define properties in the Properties element.
 Remember to put Property Name on the Src attribute of the Content element above. -->
 <Properties>
 <Property Name="StringProperty" Type="string" WebBrowsable="true" WebDisplayName="Web Part Title" WebDescription="Web Part Title shown on top of Web Part" WebCategory="Acccordion Properties" DefaultValue="Basic Accordion" RequiresDesignerPermission="true" />
 <Property Name="IntProperty" Type="int" WebBrowsable="true" WebDisplayName="Number of items to Display" WebDescription="Number of items to Display" WebCategory="Acccordion Properties" DefaultValue="3" RequiresDesignerPermission="true" />
 <Property Name="BooleanProperty" Type="boolean" WebBrowsable="true" WebDisplayName="Display Order default Ascending" WebDescription="Display list of data either a ascending or descending" WebCategory="Acccordion Properties" DefaultValue="true" RequiresDesignerPermission="true"/>
 <Property Name="EnumProperty" Type="enum" WebBrowsable="true" WebDisplayName="Header Color" WebDescription="Header Color" WebCategory="Accordion Header Properties" DefaultValue="Blue" RequiresDesignerPermission="true">
 <EnumItems>
 <EnumItem Value="Green" WebDisplayName="Green"/>
 <EnumItem Value="Blue" WebDisplayName="Blue"/>
 <EnumItem Value="Purple" WebDisplayName="Purple"/>
 </EnumItems>
 </Property>
 </Properties>
 </ClientWebPart>
</Elements>

<!-- Content element identifies the location of the page that will render inside the client web part

Properties are referenced on the query string using the pattern _propertyName_

Example: Src="~appWebUrl/Pages/ClientWebPart1.aspx?Property1=_property1_" -->

<!-- Define properties in the Properties element.

Remember to put Property Name on the Src attribute of the Content element above. -->

</EnumItems>

</Property>

</Properties>

</ClientWebPart>

</Elements>

As you see above code you notice each property has six attribute are they

Name: The Name attribute is simply the name of the property to be used to get property value.
WebBrowsable: The WebBrowsable attribute tells SharePoint whether or not the custom property should be rendered in the Edit Web Part’s Tool Part.
WebDisplayName: The WebDisplayName attribute is simply the friendly name of the property to be used in the UI.
WebDescription: The WebDescription is the text to be displayed in the ToolTip of the web part.
WebCategory: The WebCategory attribute is the expandable section that the property will be defined under in the Edit Web Part’s Tool Part.
DefaultValue: The DefaultValue attribute is the set default value of property.
RequiresDesignerPermission: Gets a flag that indicates whether a property in a Web Part requires the user to have design permissions to modify it.

Now at the end we get those property value in jQuery file.

// Function to retrieve a query string value.
function getQueryStringParameter(paramToRetrieve) {
 var params =
 document.URL.split("?")[1].split("&");
 var strParams = "";
 for (var i = 0; i < params.length; i = i + 1) {
 var singleParam = params[i].split("=");
 if (singleParam[0] == paramToRetrieve)
 return decodeURIComponent(singleParam[1]);
 }
}
$(document).ready(function () {
 /*Get Acccordion Properties */
 var webpartTitle = getQueryStringParameter("StringProperty"); //Get Web part title
 var noOfItemsDisplay = getQueryStringParameter("IntProperty"); //Get No of list item shown to display
 var displayOrder = getQueryStringParameter("BooleanProperty"); //Display list of data either a ascending or descending on load true==ascending
 /*Get Accordion Header Properties */
 var headerColor = getQueryStringParameter("EnumProperty"); //Get header color
});

// Function to retrieve a query string value.

function getQueryStringParameter(paramToRetrieve) {

var params =

document.URL.split("?")[1].split("&");

var strParams = "";

for (var i = 0; i < params.length; i = i + 1) {

var singleParam = params[i].split("=");

if (singleParam[0] == paramToRetrieve)

return decodeURIComponent(singleParam[1]);

}

$(document).ready(function () {

/*Get Acccordion Properties */

var webpartTitle = getQueryStringParameter("StringProperty"); //Get Web part title

var noOfItemsDisplay = getQueryStringParameter("IntProperty"); //Get No of list item shown to display

var displayOrder = getQueryStringParameter("BooleanProperty"); //Display list of data either a ascending or descending on load true==ascending

/*Get Accordion Header Properties */

var headerColor = getQueryStringParameter("EnumProperty"); //Get header color

});

Steps to add and read custom add-in properties on accordion

Create an add-in, name Accordion in Microsoft Visual Studio 2013. For more info to create accordion read post How to Create a Basic Accordion SharePoint Hosted Add-in
So we assume that you have setup Basic Accordion add-in. Now we setup Add-In as an App Part for this read my article SharePoint Hosted Add-In as an App Part

Here we add custom property to Accordion.

Edit Elements.xml file and add following xml code.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
 <ClientWebPart Name="AccordionAppPart" Title="Simple Accordion" Description="Create simple Accordion based on Accordion List" DefaultWidth="500" DefaultHeight="500">
 <!-- Content element identifies the location of the page that will render inside the client web part
 Properties are referenced on the query string using the pattern _propertyName_
 Example: Src="~appWebUrl/Pages/ClientWebPart1.aspx?Property1=_property1_" -->
 <Content Type="html" Src="~appWebUrl/Pages/AccordionAppPartPage.aspx?{StandardTokens}&BooleanProperty=_BooleanProperty_&EnumProperty=_EnumProperty_&StringProperty=_StringProperty_&IntProperty=_IntProperty_" />
 <!-- Define properties in the Properties element.
 Remember to put Property Name on the Src attribute of the Content element above. -->
 <Properties>
 <Property Name="StringProperty" Type="string" WebBrowsable="true" WebDisplayName="Web Part Title" WebDescription="Web Part Title shown on top of Web Part" WebCategory="Acccordion Properties" DefaultValue="Basic Accordion" RequiresDesignerPermission="true" />
 <Property Name="IntProperty" Type="int" WebBrowsable="true" WebDisplayName="Number of items to Display" WebDescription="Number of items to Display" WebCategory="Acccordion Properties" DefaultValue="3" RequiresDesignerPermission="true" />
 <Property Name="BooleanProperty" Type="boolean" WebBrowsable="true" WebDisplayName="Display Order default Ascending" WebDescription="Display list of data either a ascending or descending" WebCategory="Acccordion Properties" DefaultValue="true" RequiresDesignerPermission="true"/>
 <Property Name="EnumProperty" Type="enum" WebBrowsable="true" WebDisplayName="Header Color" WebDescription="Header Color" WebCategory="Accordion Header Properties" DefaultValue="Blue" RequiresDesignerPermission="true">
 <EnumItems>
 <EnumItem Value="Green" WebDisplayName="Green"/>
 <EnumItem Value="Blue" WebDisplayName="Blue"/>
 <EnumItem Value="Purple" WebDisplayName="Purple"/>
 </EnumItems>
 </Property>
 </Properties>
 </ClientWebPart>
</Elements>

<!-- Content element identifies the location of the page that will render inside the client web part

Properties are referenced on the query string using the pattern _propertyName_

Example: Src="~appWebUrl/Pages/ClientWebPart1.aspx?Property1=_property1_" -->

<!-- Define properties in the Properties element.

Remember to put Property Name on the Src attribute of the Content element above. -->

</EnumItems>

</Property>

</Properties>

</ClientWebPart>

</Elements>

In Elements.xml file we add property under two category Accordion Properties and Accordion Header Properties, for separate section in edit web part. Also we change query sting according to property name.

Read custom property value. Edit Accordion.js file and add following code

// Function to retrieve a query string value.
function getQueryStringParameter(paramToRetrieve) {
 var params =
 document.URL.split("?")[1].split("&");
 var strParams = "";
 for (var i = 0; i < params.length; i = i + 1) {
 var singleParam = params[i].split("=");
 if (singleParam[0] == paramToRetrieve)
 return decodeURIComponent(singleParam[1]);
 }
}
var hostweburl; //Getting host web url
var appweburl; //Getting App web url itself only
$(document).ready(function () {
 //Get the URI decoded URLs.
 hostweburl = getQueryStringParameter("SPHostUrl");
 appweburl = getQueryStringParameter("SPAppWebUrl");
 /*Get Acccordion Properties */
 var webpartTitle = getQueryStringParameter("StringProperty"); //Get Web part title
 var noOfItemsDisplay = getQueryStringParameter("IntProperty"); //Get No of list item shown to display
 var displayOrder = getQueryStringParameter("BooleanProperty"); //Display list of data either a ascending or descending on load true==ascending
 /*Get Accordion Header Properties */
 var headerColor = getQueryStringParameter("EnumProperty"); //Get header color
 //Call AccordionListData function
 getAccordionListData(noOfItemsDisplay, displayOrder, headerColor);
 //Accordion Exapnd/Collapse on Header Click
 $('.accordion-Items .accordion-Header').on('click', function (e) {
 e.preventDefault();
 if ($(this).hasClass('Expand')) {
 //Slide Up Next accordion content
 $(this).next().slideUp();
 $(this).removeClass('Expand').addClass('Collapse');
 } else {
 //Slide Up Header Who have Expand Class
 $('.Expand').removeClass('Expand').addClass('Collapse').next().slideUp();
 //Slide Up Next accordion content
 $(this).next().slideDown();
 $(this).addClass('Expand').removeClass('Collapse');
 }
 });
 $(".accordion-Items").before(document.createTextNode(webpartTitle));
});
function getAccordionListData(noOfItemsDisplay, displayOrder, headerColor) {
 if (displayOrder == "true") {
 displayOrder = "asc";
 }
 else {
 displayOrder = "desc";
 }
 //Make A Rest API Call to fetch data from created custom sharepoint add-in list
 $.ajax({
 url: appweburl + "/_api/web/lists/GetByTitle('Accordion List')/items?$select=ID,Title,KpiDescription&$top=" + noOfItemsDisplay + "&$orderby=Id " + displayOrder + "",
 method: "GET",
 async: false,
 headers: { "Accept": "application/json; odata=verbose" },
 success: function (data) {
 //SUCCESS
 if (data.d.results.length > 0) { //Check list if have any Data
 var accordionHeader = '', accordionContent = '', accordionHTML = ''; //Declare Variables
 $.each(data.d.results, function (index, obj) {
 accordionHeader = obj.Title; if (accordionHeader == undefined) { accordionHeader = "NA"; } //Get value of Accordion List Title
 accordionContent = obj.KpiDescription; if (accordionContent == undefined) { accordionContent = "NA"; } //Get value of Accordion List Content
 //Push html tag into accordionHTML
 accordionHTML += '<div class="accordion-ItemWrap">';
 accordionHTML += '<h3 class="accordion-Header ' + headerColor + '">' + accordionHeader + '</h3>';
 accordionHTML += '<div class="accordion-Content">';
 accordionHTML += '<p>'+ accordionContent +'</p>';
 accordionHTML += '</div>';
 accordionHTML += '</div>';
 });
 $('.accordion-Wrapper .accordion-Items').html(accordionHTML); //Push whole accordionHTML string in accordion-Items
 }
 },
 error: function (data) {
 //ERROR
 console.log(data);
 }
 });
}

// Function to retrieve a query string value.

function getQueryStringParameter(paramToRetrieve) {

var params =

document.URL.split("?")[1].split("&");

var strParams = "";

for (var i = 0; i < params.length; i = i + 1) {

var singleParam = params[i].split("=");

if (singleParam[0] == paramToRetrieve)

return decodeURIComponent(singleParam[1]);

}

var hostweburl; //Getting host web url

var appweburl; //Getting App web url itself only

$(document).ready(function () {

//Get the URI decoded URLs.

hostweburl = getQueryStringParameter("SPHostUrl");

appweburl = getQueryStringParameter("SPAppWebUrl");

/*Get Acccordion Properties */

var webpartTitle = getQueryStringParameter("StringProperty"); //Get Web part title

var noOfItemsDisplay = getQueryStringParameter("IntProperty"); //Get No of list item shown to display

var displayOrder = getQueryStringParameter("BooleanProperty"); //Display list of data either a ascending or descending on load true==ascending

/*Get Accordion Header Properties */

var headerColor = getQueryStringParameter("EnumProperty"); //Get header color

//Call AccordionListData function

getAccordionListData(noOfItemsDisplay, displayOrder, headerColor);

//Accordion Exapnd/Collapse on Header Click

$('.accordion-Items .accordion-Header').on('click', function (e) {

e.preventDefault();

if ($(this).hasClass('Expand')) {

//Slide Up Next accordion content

$(this).next().slideUp();

$(this).removeClass('Expand').addClass('Collapse');

} else {

//Slide Up Header Who have Expand Class

$('.Expand').removeClass('Expand').addClass('Collapse').next().slideUp();

//Slide Up Next accordion content

$(this).next().slideDown();

$(this).addClass('Expand').removeClass('Collapse');

}

});

$(".accordion-Items").before(document.createTextNode(webpartTitle));

});

function getAccordionListData(noOfItemsDisplay, displayOrder, headerColor) {

if (displayOrder == "true") {

displayOrder = "asc";

}

else {

displayOrder = "desc";

}

//Make A Rest API Call to fetch data from created custom sharepoint add-in list

$.ajax({

url: appweburl + "/_api/web/lists/GetByTitle('Accordion List')/items?$select=ID,Title,KpiDescription&$top=" + noOfItemsDisplay + "&$orderby=Id " + displayOrder + "",

method: "GET",

async: false,

headers: { "Accept": "application/json; odata=verbose" },

success: function (data) {

//SUCCESS

if (data.d.results.length > 0) { //Check list if have any Data

var accordionHeader = '', accordionContent = '', accordionHTML = ''; //Declare Variables

$.each(data.d.results, function (index, obj) {

accordionHeader = obj.Title; if (accordionHeader == undefined) { accordionHeader = "NA"; } //Get value of Accordion List Title

accordionContent = obj.KpiDescription; if (accordionContent == undefined) { accordionContent = "NA"; } //Get value of Accordion List Content

//Push html tag into accordionHTML

accordionHTML += '<div class="accordion-ItemWrap">';

accordionHTML += '<h3 class="accordion-Header ' + headerColor + '">' + accordionHeader + '</h3>';

accordionHTML += '<div class="accordion-Content">';

accordionHTML += '<p>'+ accordionContent +'</p>';

accordionHTML += '</div>';

});

$('.accordion-Wrapper .accordion-Items').html(accordionHTML); //Push whole accordionHTML string in accordion-Items

}

error: function (data) {

//ERROR

console.log(data);

}

});

}

Edit accordion.css file to add css class for accordion header code

/*REST Style START*/
html, body, div, h3 {
 margin: 0;
 padding: 0;
 border: 0;
 vertical-align: baseline;
 font-size: 100%;
}
body {
 line-height: 1;
 background-color: #fff;
 color: #000;
}
/*REST Style END*/
/*Accordion Wrapper Style*/
.accordion-Wrapper {
 font-family: "Segoe UI Light","Segoe UI","Segoe",Tahoma,Helvetica,Arial,sans-serif;
 font-size: 16px;
 margin: 14px 15px 0;
 font-weight: normal;
}
/*Accordion Items Style*/
.accordion-Wrapper .accordion-Items {
 margin: 50px 0 15px;
}
/*Accordion Headers Style*/
.accordion-Wrapper .accordion-Header {
 cursor:pointer;
 line-height: 1.3;
 color: #fff;
 font-size: 18px;
 font-weight: 400;
 padding: 12px 10px;
 margin-bottom: 10px;
}
.accordion-Wrapper .accordion-Header:hover {
 color: #000!important;
 background-color: #f1f1f1;
}
.accordion-Wrapper .accordion-Header .Expand {
 color: #000;
 background-color: #f1f1f1;
}
/*Accordion Contents Style*/
.accordion-Wrapper .accordion-Content {
 padding: 0px 12px;
 display:none;
 font-size: 16px;
border: 1px solid #ccc;
 line-height: 1.5;
 margin-bottom: 10px;
}
/*ClearFix Style*/
.clearFix {
 clear: both;
}
.Green
 {
 background:rgb(35, 135, 75) ;
}
.Blue
 {
 background:rgb(2, 115, 235) ;
}
.Purple
 {
 background:rgb(129, 81, 253) ;
}

/*REST Style START*/

html, body, div, h3 {

margin: 0;

padding: 0;

border: 0;

vertical-align: baseline;

font-size: 100%;

}

body {

line-height: 1;

background-color: #fff;

color: #000;

}

/*REST Style END*/

/*Accordion Wrapper Style*/

.accordion-Wrapper {

font-family: "Segoe UI Light","Segoe UI","Segoe",Tahoma,Helvetica,Arial,sans-serif;

font-size: 16px;

margin: 14px 15px 0;

font-weight: normal;

}

/*Accordion Items Style*/

.accordion-Wrapper .accordion-Items {

margin: 50px 0 15px;

}

/*Accordion Headers Style*/

.accordion-Wrapper .accordion-Header {

cursor:pointer;

line-height: 1.3;

color: #fff;

font-size: 18px;

font-weight: 400;

padding: 12px 10px;

margin-bottom: 10px;

}

.accordion-Wrapper .accordion-Header:hover {

color: #000!important;

background-color: #f1f1f1;

}

.accordion-Wrapper .accordion-Header .Expand {

color: #000;

background-color: #f1f1f1;

}

/*Accordion Contents Style*/

.accordion-Wrapper .accordion-Content {

padding: 0px 12px;

display:none;

font-size: 16px;

border: 1px solid #ccc;

line-height: 1.5;

margin-bottom: 10px;

}

/*ClearFix Style*/

.clearFix {

clear: both;

}

.Green

{

background:rgb(35, 135, 75) ;

}

.Blue

{

background:rgb(2, 115, 235) ;

}

.Purple

{

background:rgb(129, 81, 253) ;

}

Run and Deploy the Add-In solution, Now go to the developer site and add the App Part in Web Part page, here you notice that our app part name and description will change.

As you see in below screen shot our Accordion will created by default property value.
Now we change custom property on Edit Web Part where Header Color to Green and Web Part Title to Accordion only.

Read my further article on SharePoint Hosted App Parts

Resize Add-In Parts dynamically in SharePoint Add-Ins

4 thoughts on “How to add and read SharePoint Hosted custom App Part properties”

Yesubabu says:

July 19, 2018 at 8:50 pm

Hi,
I got it thank you.

Yesubabu says:

July 19, 2018 at 3:35 pm

Yes.I got it thank you.

Yesubabu says:

July 18, 2018 at 11:39 pm

Hi,
I am not able to get property value().Please help me.

var webpartTitle = getQueryStringParameter(“StringProperty”);

In my scenario i am passing the List Name.So i am trying to catch the list name value:

var webpartTitle = getQueryStringParameter(“ListName”);
getQueryStringParameter() this function did not getting the text box value.

1. TechBytes Admin says:
  
  July 19, 2018 at 12:22 pm
  
  Hello Yesubabu,
  
  Please check the Content-type url and Property name both are should be same [ Src=”~appWebUrl…. ], after that console the getQueryStringParameter(); function. You can also test with any other custom properties like int or enum and check they are returning any value?. if this not helps provide Elements.xml.
  
  Thank You for the comment.

How to add and read SharePoint Hosted custom App Part properties

Get in Touch

4 thoughts on “How to add and read SharePoint Hosted custom App Part properties”

Leave a Reply Cancel reply

About Us

Get in Touch

Related articles

Using CAML query show SharePoint list items for the previous and next week

How to create List using List Template?

How to write Complex CAML Query with Nested AND Conditions

4 thoughts on “How to add and read SharePoint Hosted custom App Part properties”

Leave a Reply Cancel reply