Note
For the versions earlier than 4.x.x (including on-premises ones), please follow this instruction.
In this article I will show how to conditionally format Org Chart boxes and search results according to field values from data source, for example User profiles or SharePoint list. SharePoint Org Chart 1.7.1 and higher allows to add dynamics to boxes using JavaScript. Usually, we need to highlight boxes according to some quite simple rule but sometimes we need to implement more difficult logic. In this article, I will show how to simply highlight boxes with specific color as well as show more complex case with displaying awards and search result highlighting. As a result, I want to change background of boxes and search results according to field values from a data source and add gold, silver, or bronze medals to the boxes of the best employees.
I divided this article into three main steps:
On the first step, I will show how to implement color codding for Org Chart. If you don’t need any additional functionality, you can read the first step only. If you need to implement more complex case and modify boxes dynamically, for example add images to boxes, please read the second and the third steps.
This is how the org chart will look after all customizations:
I assume that you’ve already added the web part to your page and configured it with default settings.
I want to change background of boxes according to a custom field from the data source.
In my case it is Awards
field that has following possible values:
Gold medal
Silver medal
Bronze medal
I want to set light goldenrod background for boxes where Awards
field has the value Gold medal
, to set lavender background for boxes with the Silver medal
field value, and to set maize background for boxes with the Bronze medal
field value.
First of all, I added Awards
field to my data source.
I used a SharePoint list as a data source, but you can use User profiles as well.
If you don’t know how to add new field to your data source, read official Microsoft documentation:
Then, I configured the web part using the configuration wizard. On the Design step, I chose a Modern one because it fits most for the modern SharePoint UI.
After that, I switched to the Custom code (JavaScript) step.
As you can see on the picture above, there is ready to use JavaScript handler with three functions that allow to subscribe for box, tooltip, or search result rendering event. In this article I used only box and search result rendering events to highlight boxes and search results with color. You can find description of JavaScript framework in the documentation.
It is possible to use such code to highlight boxes with Gold medal
field values:
//Subscribe for the box rendering event
api.onBoxRendered((box, itemData) => {
//If the employee has a gold award, color the card
if (itemData.Awards == "Gold medal") {
var $card = $(box.elem).find(".poch-group-item__card");
$card.css({
"background-color": "#ffec8b"
});
}
});
As you can see from the script above I used the onBoxRendered
method to subscribe for event.
The method receives box
and itemData
parameters.
I used Awards
property of the itemData
parameter to check if the current employee has the award.
The itemData
parameter contains all field values from the data source mentioned in the configuration wizard.
Then I applied CSS style to the elem
property of the box using a jQuery css
function.
The box
parameter represents object of current box and the elem
property stores a DOM element of the box.
That is all required to modify color of the box according to the property of employee:
To highlight boxes with other field values you can use the same logic and add the if
condition for each of them.
Such approach also works for search results and tooltips.
So, if you need to add simple CSS styles you can do it right in the JavaScript, but to keep code readable I would recommend to move CSS outside from JavaScript code.
That is why I created CSS class for the box. You can see the CSS style for the gold medal box below:
/*Set a background color for the box with the gold medal*/
.gold-box {
background-color: #ffec8b !important;
}
To apply CSS style I switched to General settings and copied style to Custom CSS property. Then switched back to JavaScript and changed it to following:
//Subscribe for the box rendering event
api.onBoxRendered((box, itemData) => {
//If the employee has a gold award, add a class
if (itemData.Awards == "Gold medal") {
var $card = $(box.elem).find(".poch-group-item__card");
$card.addClass("gold-box");
}
});
As you see, I just added a CSS class to the elem
instead of setting CSS styles manually.
On this step, I showed the part of the script for my case only. I don’t want to overload it with code. You can find complete script and CSS styles on the last step in the article.
On this step, I will show how to use JavaScript to modify Org Chart boxes dynamically. I will add image of award into the box. To keep explanation clear I will not use script from the previous step here, but you can find combined script on the next step.
You can see the JavaScript code I used below:
//Subscribe for the box rendering event
api.onBoxRendered((box, itemData) => {
//If the employee has a gold award, add a div element
if (itemData.Awards == "Gold medal") {
var $card = $(box.elem).find(".poch-group-item__card");
var medalSpan = $("<div class='medal gold-medal'></div>");
$card.append(medalSpan);
}
});
The code above checks if the current item has a Gold medal
and adds a div
element into the box.
I used a getInnerContent
function of the box parameter to get jQuery object for the inner content of the current box.
Then, I added the medal
and gold-medal` CSS classes to the block.
The ``medal
class is used to configure position and size for all medals and the gold-medal
one – to set a background image for the specific award.
You can see CSS style below:
/*Set position for all medals*/
.medal {
position: absolute;
width: 32px;
height: 32px;
top: 60px;
left: 0px;
background-position: center;
background-size: contain;
background-repeat: no-repeat;
}
/*Set image URL for the gold medal*/
.gold-medal {
background-image: url(../SiteAssets/OrgChart/gold-medal32x32.png);
}
Note
I uploaded images for medals to an OrgChart folder of a SiteAssets document library, but you can use any other location. Do not forget to update the path to the image in the CSS style according to your location.
It is enough to add the medal to an Org Chart box:
On this step, I showed how to add HTML elements to boxes dynamically. In my case, it was an image of the gold medal. I showed the part of script and CSS styles for the gold medal only, but you can find complete script on the next step.
Add new Awards
field to your data source, SharePoint list or User profiles.
If you don’t know how to do it, read official documentation from Microsoft:
Open the configuration wizard. On the Design step, choose a Modern skin.
Copy the CSS style below and paste it on the Custom code (CSS) step of the wizard:
/*Set position for all medals*/
.medal {
position: absolute;
width: 32px;
height: 32px;
top: 60px;
left: 0px;
background-position: center;
background-size: contain;
background-repeat: no-repeat;
}
/*Set image URL for a gold medal*/
.gold-medal {
background-image: url(../SiteAssets/OrgChart/gold-medal32x32.png);
}
/*Set image URL for a silver medal*/
.silver-medal {
background-image: url(../SiteAssets/OrgChart/silver-medal32x32.png);
}
/*Set image URL for a bronze medal*/
.bronze-medal {
background-image: url(../SiteAssets/OrgChart/bronze-medal32x32.png);
}
/*set background color for box with the gold medal*/
.gold-box, .gold-search-result {
background-color: #ffec8b !important;
}
/*set background color for box with the silver medal*/
.silver-box, .silver-search-result{
background-color: #e6e6fa !important;
}
/*Set background color for box with the bronze medal*/
.bronze-box, .bronze-search-result{
background-color: #edd19c !important;
}
Then, copy the JavaScript code below and paste it on the Custom code (JavaScript) step:
//Subscribe for the box rendering event
api.onBoxRendered((box, itemData) => {
//If the employee has a gold award, add a div element
if (itemData.Awards == "Gold medal") {
var $card = $(box.elem).find(".poch-group-item__card");
var medalSpan = $("<div class='medal gold-medal'></div>");
$card.append(medalSpan);
$card.addClass("gold-box");
}
//If the employee has a silver award, add a div element
if (itemData.Awards == "Silver medal") {
var $card = $(box.elem).find(".poch-group-item__card");
var medalSpan = $("<div class='medal silver-medal'></div>");
$card.append(medalSpan);
$card.addClass("silver-box");
}
//If the employee has a bronze award, add a div element
if (itemData.Awards == "Bronze medal") {
var $card = $(box.elem).find(".poch-group-item__card");
var medalSpan = $("<div class='medal bronze-medal'></div>");
$card.append(medalSpan);
$card.addClass("bronze-box");
}
});
//Subscribe for the search result rendering event
api.onSearchResultRendered((searchResult, itemData) => {
//Add a class to the search result of the employee with the gold medal
if(itemData.Awards == "Gold medal"){
$(searchResult.elem).addClass("gold-search-result");
}
//Add a class to the search result of the employee with the silver medal
if(itemData.Awards == "Silver medal"){
$(searchResult.elem).addClass("silver-search-result");
}
//Add a class to the search result of the employee with the bronze medal
if(itemData.Awards == "Bronze medal"){
$(searchResult.elem).addClass("bronze-search-result");
}
});
Finish the configuration wizard and you will see the org chart with conditional formatting and awards:
In this article, I showed how to add conditional formatting to SharePoint Org Chart. Now you know how to change the background of boxes according to field values from the data source in six lines of code. The same logic is applicable to tooltips and search results. If you need to implement more complex scenario, you can add HTML elements to the boxes dynamically using the jQuery framework.
I hope this will help you to build clear and useful organization structure.