JavaScript framework

You can use JavaScript framework to bring dynamics to SharePoint Org Chart. You can subscribe for rendering events, modify boxes, tooltips, search results according to their context. To add custom JavaScript to Org Chart use the configuration wizard. Read Advanced Web Part configuration for more information.

You can use all power of  jQuery to customize Org Chart. Just type ‘$’ in the code editor to access it.

Code editor in the configuration wizard looks like this:

 

Renderer object

Core object for Org Chart is “renderer”. The object provides set of methods which allow you to manage Org Chart and subscribe for Org Chart events.

Methods

Name Description
zoom(value)

Sets scale for entire Org Chart.

value – numeric value, for example 0.5.

The example below shows how to set 50% scale for Org Chart:

renderer.zoom(0.5)
drillDown(itemId, completed)

Drills down Org Chart to specified box.

  • itemId – id of item in a data source. For example it is an account name for user profiles or it can be a list item ID for SharePoint list. Mapping for ID field can be configured on the first step of the configuration wizard for SharePoint list data source.
  • completed – callback function which is executed after drill down.

The example below shows hot to drill down to box of employee with ID equals 3.

renderer.drillDown("3", function(){
  console.log("Drill down executed.");
});
fixConnectionLines()

Sometime if you add content to Org Chart boxes dynamically by JavaScript, connection lines can appear not in correct place. You can use this method to adjust connection lines to newly added content.

The example below shows how to use this method:

renderer.fixConnectionLines();
initTooltips(boxJQueryElement, itemData)

Initializes tooltips for specified box. If you have custom rendering logic you can use this method to initialize tooltip links. This method finds all ‘a’ tags with ‘detailsTooltipLink’ class and initializes tooltips for them.

  • boxJQueryElement – jQuery element for box where tooltips have to be initialized.
  • itemData – the object with properties from ф data source. You can receive it from rendering events. Please find description below at the beginning of ‘Events’ section.

Example:

renderer.initTooltips();
expandNodeLevels(numberOfLevels, completed)

Expands specified number of levels of Org Chart. 

  • numberOfLevels – number of levels to expand
  • completed – callback function which is executed when all levels are expanded.

You can use it together with ‘showLoadingPanel’ and ‘hideLoadingPanel’ functions. Show loading panel before calling this method and hide it inside completed callback.

Example:

renderer.expandNodeLevels(3, function(){
  console.log("Nodes are expanded");
});
prerenderAction(completed)

You can use this method to preform some actions before Org Chart rendering. For example if you need to load some data or some scripts you can hold Org Chart loading and continue it once everything is ready.

Be careful with this method because if you don’t call “completed” function, Org Chart is never rendered. We recommend you to wrap your code with “try – catch – finally” to guarantee that “completed” function is called.

Example:

renderer.prerenderAction = function(completed){
  try {
    //Do some initialization staff }
catch(err) {
    //handle errors
finally {
    //Org chart will not start rendering //until you call 'completed' function completed(); } }
showLoadingPanel()

It shows loading screen for the Org Chart web part.

Example:

renderer.showLoadingPanel();
hideLoadingPanel()

It hides loading screen for the Org Chart web part.

Example:

renderer.hideLoadingPanel();
enableDisableFullScreen()

It toggles full screen mode for the Org Chart web part.

In the example below I check if there is the URL parameter “IsFullScreen” and show Org Chart enable full scheen if it is there.

var isFullScreen = GetUrlKeyValue("IsFullScreen");

if(isFullScreen === "true"){
 renderer.enableDisableFullScreen();
}
dataProvider.getBoxGroupItemDataById(id, completed, error)

Get org chart data item by id (usually account name or list id). 

Example: 

renderer.dataProvider.getBoxGroupItemDataById("3", function(dataItem){
  console.log(dataItem)
});
dataProvider.clearCache()

Clears client side cache for current browser.

Example:

renderer.dataProvider.clearCache();
scrollToBox(id)

Scroll org chart to item by id (usually account name or list id). 

Example: 

renderer.scrollToBox("domain\\username");

Properties

Name Description
config

Stores all configuration settings for Org Chart. You can read it and modify before Org Chart is rendered. Thus, you can change configuration based on your logic dynamically.

Just use renderer.config outside of any events right in the code editor.

Some useful properties from the configuration which you can override:

nodesSortFieldName – name of field which is used for sorting. For User profiles it is “PreferredName” by default.

renderer.config.idFieldMapping.nodesSortOrder = "PreferredName";

nodesSortOrder – it is “ASC” by default, but you can specify “DESC” for descending sorting. Example:

renderer.config.idFieldMapping.nodesSortOrder = "DESC";

searchResultMaxCnt – max number of items is search results. It is 10 by default.

renderer.config.idFieldMapping.searchResultMaxCnt = 15;

idFieldMapping – stores information about field where box id is stored. For example you can extract internal field name like this:

renderer.config.idFieldMapping.InternalFieldName;

parentIdFieldMapping – stores information about field where box parent id is stored. For example you can extract internal field name like this:

renderer.config.parentIdFieldMapping.InternalFieldName;

ListDataSourceSettings – stores information about list data source. For example you can extract list id like this:

renderer.config.ListDataSourceSettings.ListId;

itemsPerNodeLimit – limit for items per one node for compact layout.

renderer.config.itemsPerNodeLimit = 100;

clientSideCachingLifeDays – life time in days for client side cache. Example:

renderer.config.clientSideCachingLifeDays = 0.5;

renderInitialNode – you can disable rendering of initial node if you want to drill down to some other node on web part load. By default it is set to true. It helps to reduce time of initial loading.
Example:

renderer.config.renderInitialNode = false;

 

Other properties can be defined in user interface of the configuration wizard, but you can override them also if required.

Events

Most rendering events receive ‘itemData’ object as input parameter. The object represents the business object from the data source. It is a set of fields with values. Each field has the same name as internal name of the field in the data source.

The object has structure like this:

{
  FieldInternalName1: "FieldValue1",
  FieldInternalName2: "FieldValue2",
  ...
  FieldInternalNameN: "FieldValueN",
}

List of events

Name Description
onBoxRendered(handler)

Adds handler on box rendered event. The handler has three input parameters:

  • event – the object of event.
  • box – the object of rendered box. You can change this box, for example change background.
  • itemData – the business object from the data source. See description at the beginning of ‘Events’ section.

The ‘box’ object has following properties:

  • $elem – The property stores jQuery object of the box element. You can use all methods available in jQuery to customize the box, for example css method.
  • elem – The DOM element of the box.
  • $elemContainer – The property stores jQuery object of the box container element. You can use this object to set width and height of the box.
  • elemContainer – The DOM element of the box container.

The ‘box’ object also provides “getInnerContent” function. It gets jQuery object for the inner content of current box.

Example:

//Changes background of boxes for all employees
//from marketing department
renderer.onBoxRendered(function(event, box, itemData){
  if(itemData["Department"].contains('Marketing')){
    box.$elem.css({
      'background-color': 'red',
      'border-color': 'red'
    });
  }
});

Note: In this example ‘Department’ is an internal name of the field, you can get value from the business object using such syntax:

itemData.Department

But if the internal name of your field contains ‘‘ like ‘SPSResponsibility’ you need to use different syntax:

itemData["SPS-Responsibility"]

The ‘‘ symbol is forbidden in JavaScript, that is why you need to get value of the field using string key.

onTooltipRendered(handler)

Adds handler on tooltip rendered event. The handler has three input parameters:

  • event – the object of event.
  • tooltip – the object of rendered details tooltip. You can change this tooltip, for example change background.
  • itemData – the business object from the data source. See description at the beginning of ‘Events’ section.

The ‘tooltip’ object has following properties:

  • $elem – The property stores jQuery object of the details tooltip element. You can use all methods available in jQuery to customize the tooltip, for example css method.
  • elem – The DOM element of the details tooltip.

Example:

//Changes background for all tooltips of employees
//from marketing department
renderer.onTooltipRendered(function(event, tooltip, itemData){
  if(itemData["Department"]contains('Marketing')){
    tooltip.$elem.css({ 'background-color': 'red' });
  }
});
onSearchResultRendered(handler)

Adds handler on quick search result rendered event. The handler has three input parameters:

  • event – the object of event.
  • searchResult – the object of rendered search result. You can change this search result, for example change background.
  • itemData – the business object from the data source. See description at the beginning of ‘Events’ section.

The ‘searchResult’ object has following properties:

  • $elem – The property stores jQuery object of the quick search result. You can use all methods available in jQuery to customize the search result, for example css method.
  • elem – The DOM element of the search result.

Example:

//Changes background for search results of employees
//from marketing department
renderer.onSearchResultRendered(
  function(event, searchResult, itemData){
    if(itemData["Department"].contains('Marketing')){
      searchResult.$elem.css({ 'background-color': 'red' });
    }
  }
);
onInitialLoadingFinished(handler)

Adds handler on org chart initial loading finished event. It is triggered when org chart is loaded for the first time.

Example: 

renderer.onInitialLoadingFinished(
  function(){
    console.log('Initial loading is finished');
  }
);
onLoadingStarted(handler)

Adds handler on org chart loading started event. It is triggered when progress indicator is showed.

Example: 

renderer.onLoadingStarted(
  function(){
    console.log('Loading is started');
  }
);
 onLoadingFinished(handler)

Adds handler on org chart loading finished event. It is triggered when progress indicator is hidden.

Example: 

renderer.onLoadingFinished(
  function(){
    console.log('Loading is finished');
  }
);