Advanced Web Part configuration

How to run configuration wizard

Note: You can run the configuration wizard any number of times. It will not force reconfiguration, all data will be stored, just go through the wizard and correct any settings you need.

If Web Part is not configured yet you need to start the configuration as it is described in the quick web part configuration guide.

If you need to change settings of an already configured Web Part, to open the configuration wizard you need to perform following actions:

In version for SharePoint On-Premises you need to click on the icon on the top right corner of the Web Part:

ConfigLink

Data source configuration

This is the first step of the wizard.

You can choose between two data sources:

  1. SharePoint list
  2. User profiles

If you choose ‘User profiles’ as a data source, no additional configuration of data source is needed, just go through the wizard until the end. To understand how Org Chart communicates with User profiles service, read blog article.

If you choose ‘SharePoint list’ as a data source, it will be configured to create a new list with demo data by default. You only need to fill ‘List name’.

CreateNewList

If you want to use an existing SharePoint list, you can choose it from combo box. Then you will have to specify mapping for list fields required for building correct hierarchy. The interface for mapping looks like this.

ConfiguredListFiedsMapping

Mapping defines the connection between Organization Chart field and List field. Data from the corresponding list field will be used by the Organization Chart, for example you can specify mapping between ‘Item ID’ and list item ID.

‘Item ID’, ‘Item parent ID’ and ‘Display text’ mappings are required, you can leave other mappings empty. Once you configured it, you can go through the wizard and click the finish button.

‘Item ID’ and ‘Item parent ID’ are used to build hierarchy. ‘Display text’ is used as display text for entities in the org chart. For example you will see ‘Display text’ in the breadcrumb.

Description of mappings
NameDescription
Item IDThis is unique ID of an entity in the Org Chart. It can be list item ID, user login or any other unique identifier of the person.
Item parent IDThis is unique ID of a parent entity. For example it could be ID of manager or login of manager. We need it to build a well-structured tree.
Display textDisplay text is displayed in the breadcrumbs of the Org Chart.
Assistant ID

This mapping defines where information about assistant is stored for current item. This is optional mapping.

Note: You need to enable assistants on “General settings” step of the configuration wizard.

Dotted parent ID

This is unique ID of dotted parent (dotted manager). For example it could be ID of manager or login of manager. Type of this field should be the same as type of “Item parent ID”.

Note: You need to enable dotted managers on “General settings” step of the configuration wizard.

 

Filtration

This is the second step of the wizard.

RootDetection

Root ID

By default you can specify the ID of the root item. The hierarchy will be build from the item with this ID.

You can leave root ID empty. In this case the following logic will be used:

  • If User profiles were chosen as a data source, root person will be located based on current user relations. The current person will be found, then the Org Chart will traverse up by manager relation until a person without a manager is found. The person without manager will be displayed as a root person.
  • If SharePoint list were chosen as a data source, the first item found without parent item will be taken as a root of hierarchy.

Org Chart filtration

You can include or exclude items from the Org Chart using the filtration rule. For example this rule will only include employees from the Marketing department:

function(itemData){
 
  //You can get field values like this: itemData["Department"]
  return itemData["Department"] == "Marketing";

}

You can find complete description of filtration syntax in the separate article.

Note: Filtration syntax described above is actual for Org Chart 2.0 and later. If you have previous version you can find description of filtration syntax here:

General settings

This is the third step of the configuration wizard. You can use it to:

  • Choose layout. It is “Top to bottom” by default, but you can choose “Left to right”
  • Choose predefined skin;
  • Set number of visible levels;
  • Enable\disable zoom;
  • Enable\disable box collapsing;
  • Enable\disable compact layout;
  • Enable\disable displaying assistants;
  • Enable\disable displaying dotted subordinates – read Dotted managers for more information
  • Enable\disable displaying vacancies –  read Vacancies section below for more information
  • Vacancies list URL – read Vacancies section below for more information

VisualOptions

To change the skin of the Organization Chart choose it from combo box. There are two skins adopted for mobile devices BlackMetroTouch and MetroTouch, they have large expand buttons to simplify touch navigation, all skins support dragging of the visible area with touch.

List of available skins:

  • Black
  • BlackMetroTouch
  • Forest
  • Glow
  • Hay
  • Metro
  • MetroTouch
  • Office2007
  • Office2010Black
  • Office2010Blue
  • Windows7
  • Office2010Silver
  • Outlook
  • Silk
  • Simple
  • Sitefinity
  • Sunset
  • Vista
  • Web20
  • WebBlue

 

You can use mouse wheel to zoom in and zoom out in the Org Chart web part. To disable/enable this functionality use ‘Enable zoom’ checkbook.

Compact layout is enabled by default, but you can disable it by unchecking ‘Compact layout’ check box.

You can also control a number of levels visible by default. Use input ‘Number of visible tree levels’ to change it. You may expand all hierarchy tree by default, just set a value large enough in the input, for example 1000.

Note: this can affect performance of Org Chart on large structures.

Vacancies

Currently, vacancies are not supported in SharePoint 2010 version.

Note: If vacancies don’t appear in your web part try to clear cache.

Vacancies are stored in a separate SharePoint list. A list will be created automatically at specified ‘Vacancies list URL’. Once you enabled vacancies ‘Manage vacancies’ menu item will appear:

ManageVacanciesMenu

This menu item redirects user to vacancies list. To create new vacancies, create new list item and specify ‘Manager’. It can be account name for ‘User Profiles’ data source and list item ID for ‘SharePoint list’ data source:

CreateVacancy 

Dotted managers

Currently dotted managers are not supported in SharePoint 2010 version.

If you use ‘User profiles’ as a data source, org chart uses “Dotted-line Manager”  user profile property to get information about dotted-line manager.

Note: If dotted reports don’t apper in your web part try to clear cache.

Office 365 version configuration

If you use Org Chart for Office 365, then you need to add search managed property for “Dotted-line Manager” of a user profile. It is required to allow Org Chart to find dotted-line subordinates. Follow the guide below to add it. Org Chart will not display dotted-line subordinates unless you added managed property. 
How to add new search managed property for “Dotted-Line Manager” in Office 365

SharePoint Online search refreshes search cache periodically. As result you can see delays between update of dotted manager in user profile and visualization in the org chart. You need to wait some time for search crawling (search cache refresh).

SharePoint 2013 version configuration

If you use Org Chart for SharePoint 2013 and synchronize Active Directory with SharePoint profiles, you may need to configure mapping between “Dotted-line Manager” profile property and AD attribute. Read how to map user profile properties.

SharePoint 2013 Org Chart caches dotted-line managers to improve performance. So, your modifications may not appear in org chart instantly.  You can clear cache using menu at the top corner of the web part or perform IIS reset.

 

Box template

You can customize the template of the box inside the Org Chart web part. There are two options:

  1. To use visual editor (Design mode)
  2. To use HTML editor (HTML mode)
Design mode

In the visual editor you need to specify photo URL field. This property defines the field which will be used to get photo URLs for boxes. These photos will be displayed in the left side of the boxes. You can leave this property empty if you don’t have photos.

Under photo URL field property you can see area with list of fields. You can choose field from the combo box and click ‘Add field’ button. Added field will be included in the box template.

Once you added a new field you can drag it up and down to change order of fields in the box. See the picture below:

Each field has ‘Display as’ property. You can use it to change behavior of the field. There are four display types:

  • Tooltip link – if you apply this type to the field, it will be displayed as a link. This link will show the details tooltip for the current box on click.
  • Text – if you apply this type to the field, it will be displayed as a plain text.
  • E-mail – if you apply this type to the field, it will be displayed as a ‘mailto’ link.
  • Link – if you apply this type to the field it will be displayed as a link.

Once you choose the ‘Link’ as a display type you can see the tooltip. This tooltip allows to choose other field, which will be used as a URL for the link. You also can specify the URL manually:

Once you click to the ‘HTML mode’ button, all modifications from visual editor will be converted to HTML template.

Note: If you switch to HTML mode and finish the wizard you will not be able to go back to visual editor without resetting template to default.

 

HTML mode

Once you switched to HTML mode you see HTML template editor. To get more information about the HTML templating syntax read HTML templating syntax description.

 

Tooltip template

This step allows to specify the template for the details tooltip. This tooltip appears when you click on the link inside specific box.

The logic for this step is the same as for the the box template step.

 

Search result template

This step allows to specify template for single result of quick search. You can see the search box in the left top corner of the web part.

The logic for this step is the same as for the box template step.

 

Custom JavaScript

This step allows to specify custom JavaScript code. You can use functions from JavaScript framework to subscribe for box, tooltip, search results rendering events. Each event receives rendered element and object with field values from the data source. The object contains all fields specified in the templates of box, tooltip and search result.

You can use jQuery to customize rendered element. Read description of JavaScript framework for more information.

On the picture below you can see example of JavaScript which changes the background of boxes to red for all employees with award ‘Employee of the month’ .

 

Custom CSS

The Org Chart allows to specify custom CSS styles. If you are familiar with CSS, you can adjust visualization of company structure to your brand book.

For example you can change the background of the person’s box to black using such CSS:

.poch-web-part .pl-item .pl-item-template{ 
  background-color: black;
  border-color: black;
}

And this is another example which resizes Org Chart boxes to smaller size. Thus, more boxes can be displayed in the single screen.

/*Width of the box*/
.poch-web-part .poch-control .pl-item {
  width: 170px;
}

/*Font size for the fields in the box*/
.pl-item-card .field-container {
 font-size: 12px;
}

/*Font size for the header field in the box (the first in the box)*/
.pl-item-card .field-container.header-field {
 font-size: 12px;
}

/*Width of the photo in the box*/
.pl-item-photo img {
  max-width: 42px;
}

On the picture below you can see example of CSS style which changes the background of boxes to red:

CustomCssWizardStep

 

Printing custom CSS

With Org Chart you can also create custom CSS styles that will be applied to the chart only when you print it. That way, you can apply custom styles that will help reading the chart after printing it, but without affecting the chart on your SharePoint site.

You can change font-size for printing purposes only:
01-font-size

Similarly, you can also change background color of boxes:
02-bg-color

Org Chart will add the class “print-mode” (on Office 365) or the class “pl-print-mode” (on SharePoint 2010/2013/2016) to elements before printing out the chart. This way, you can handle styles in the “Custom CSS” tab that will be applied only when printing the chart.

To enlarge font-size for printing, the code used was:

.print-mode .pl-item-card .field-container {
   font-size: 16px;
}

And to modify the background color of boxes the following code was added:

.print-mode .pl-item .pl-item-template {
   background-color: green;
}

 

Resetting configuration

You can reset the configuration to initial state. All changes will be erased and the initial settings will be restored. Then you will have to run the configuration wizard from scratch.

To reset the configuration use the button in the bottom left corner of the wizard.

ResetConfiguration