Basic Primitives

Basic Primitives is a 100% JavaScript component library for building general purpose diagrams without manual nodes layout.

  • Increase font size
  • Default font size
  • Decrease font size

First organizational chart

Basic Primitives diagramming component library implemented in JavaScript without dependencies on 3d party libraries and frameworks. It renders diagrams in browsers optionally using SVG, Canvas and HTML templates. By default it provides very basic node template which you can see in the following example. It serves only one purpose to make first time user experience as simple as possible, software engineer is supposed to provide nodes having basically only id, name and parent id defined, so it is enough to render first diagram.

Basic Primitives controls use existing HTML elements as placeholders on the web page to draw diagrams. The only HTML element which can serve as a placeholder is div. When you resize placeholder chart will not update its content automatically, it will not shrink or expand in size, in order to have the chart adopt to the new placeholder size you have to explicitly call "update" method on its API. In order to create or update diagram you have to pass configuration object or set individual options on its API and then call "update" method to apply changes. The configuration object consists of options and collections of various objects like items, annotations, etc., the API objects are referenced by unique ids. For convenience, all configuration objects are based on their own JavaScript prototype, so you can instantiate them and browse their default properties. Since we are in JavaScript world, all configuration objects can be defined in form of regular JSON objects as well.

JavaScript

The following is the minimal set of files needed to use Basic Primitives components in application.

<link href="/primitives.latest.css" media="screen" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="/primitives.min.js"></script>

The controls are state-full that means they keep internal state of the diagrams in order to minimize updates of visuals and avoid unnecessarily layout calculations. Library has two methods to construct instances of controls: use primitives.orgdiagram.Control for Organizational Diagrams and primitives.famdiagram.Control for Family Diagrams creation. The following code snippet creates organization chart inside empty div having "basicdiagram" id:

var control = primitives.orgdiagram.Control(document.getElementById("basicdiagram"), {/* regular JSON object or instance of primitives.orgdiagram.Config class*/});

Please, keep reference to returned control instance, you need it to update controls options:

control.setOptions({"items", [
	new primitives.orgdiagram.ItemConfig({
		id: 0,
		parent: null,
		title: "Scott Aasrud",
		description: "VP, Public Sector",
		image: "../images/photos/a.png"
	}),
	new primitives.orgdiagram.ItemConfig({
		id: 1,
		parent: 0,
		title: "Ted Lucas",
		description: "VP, Human Resources",
		image: "../images/photos/b.png"
	}),
	new primitives.orgdiagram.ItemConfig({
		id: 2,
		parent: 0,
		title: "Fritz Stuger",
		description: "Business Solutions, US",
		image: "../images/photos/c.png"
	})
]
});

or for individual option

control.setOption("cursorItem", 0);

every time we make changes to control API we need to call explicitly "update" method. This is needed in order to avoid expensive layout updates on every property change.

control.update(primitives.orgdiagram.UpdateMode.Refresh);

Control is interactive component by design, so it needs to add event listeners to placeholder DIV element to handle mouse and keyboard events. So it should be properly destroyed in order to remove event listeners:

control.destroy();

jQuery

Historically Basic Primitives provides jQuery UI Widgets wrapping core controls, so you will find a lot of jQuery UI examples around our site. In order to use Basic Primitives jQuery UI widgets in your web application include following references for jQuery, jQuery UI and Basic Primitives libraries:

<link rel="stylesheet" href="/jquery-ui.min.css" />
<script type="text/javascript" src="/jquery-3.3.1.min.js"></script>
<script type="text/javascript" src="/jquery-ui.min.js"></script>

<script  type="text/javascript" src="/primitives.min.js"></script>
<link href="/primitives.latest.css" media="screen" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="/primitives.jquery.min.js"></script>

Basic Primitives jQuery UI widgets are added as methods on jQuery object, so for example in order to create a new organization chart inside empty div having "basicdiagram" id, we have to call following jQuery method:

jQuery("#basicdiagram").orgDiagram({/* here is we define items & configuration options for our chart*/});

In order to get configuration object of existing widget call its method with argument "option"

var config = jQuery("#basicdiagarm").orgDiagram("option")

or for individual option

var items = jQuery("#basicdiagarm").orgDiagram("option", "items")

See following article for Widget Factory reference, it explains how to use jQuery UI widgets API: https://api.jqueryui.com/jquery.widget/

When we create a new jQuery UI widget instance, jQuery stores it to the internal hash collection and adds its hash key to HTML element as data attribute. So when we call a widget method on the same HTML element second time we actually pass new configuration object to the existing instance. When we delete the HTML element containing widget's visuals inside, jQuery UI will also remove associated widget instance from hash and all nested widgets if such exist in the removed HTML fragment.

So in order to be sure that widget's instance is destroyed and avoid unexpected memory leaks you have to remove HTML elements only with jQuery remove method.

jQuery("#basicdiagram").remove();

Be aware that for obvious logical reasons jQuery("#basicdiagram").empty() method cleans up contents without actual widget removal, so its state becomes invalid after that and its instance stays in memory, since jQuery hash of widgets keeps reference on it.

Following example demonstrates creation of simple org chart having one root item and couple of children.

In order to define the same chart as JSON object, replace it with the following code snippet:

jQuery("#basicdiagram").orgDiagram({
  items: [
	{ id: 0, parent: null, title: "Scott Aasrud", description: "VP, Public Sector", image: "demo/images/photos/a.png" },
	{ id: 1, parent: 0, title: "Ted Lucas", description: "VP, Human Resources", image: "demo/images/photos/b.png" },
	{ id: 2, parent: 0, title: "Joao Stuger", description: "Business Solutions, US", image: "demo/images/photos/c.png"}
  ],
  cursorItem: 0,
  hasSelectorCheckbox: primitives.common.Enabled.True
});

  

 

Comments 

 
#192 Administrator 2018-10-01 17:07
Quoting J Beh:
Hello,

All of your examples show the use of jQuery 1.9.1. I've been able to successfully utilize to jQuery 2.2.4 before your library no longer works properly. Due to the fact that the anything less than jQuery 3 is considered a moderate security risk, are there any plans to offer support for jQuery 3+ ?

The dependency on jQuery and jQuery UI is not required anymore. Download latest demo samples for pure JavaScript demos and samples. Use jQuery for your convenience, jQuery UI let your widget exists without keeping reference to the instance of the control. jQuery UI keeps internal hash of all widgets created in the DOM so that way it destroys them when placeholder DIV is eliminated.
Quote
 
 
#191 Administrator 2018-09-05 07:21
Quoting Dario de Judicibus:
Do you have any example how to create a very simple template with just a box, a title and a description?

Yes, see Item Template samples down the list.
Quote
 
 
#190 Administrator 2018-09-05 07:19
Quoting Aisza:
Hi,
Is it possible to hide the connection line from the hidden root element?
Im using the partner format for the org chart, and I wanted to hide the root level so I set it to isVisible false, but there's a weird line between this 2 partners on the display.

What you see is bug, in order to avoid it you don't need to use invisible root node, you just have to use first partner as root node.
Quote
 
 
#189 Dario de Judicibus 2018-09-02 05:37
Do you have any example how to create a very simple template with just a box, a title and a description?
Quote
 
 
#188 Administrator 2018-08-12 03:07
Quoting J Beh:
Hello,

All of your examples show the use of jQuery 1.9.1. I've been able to successfully utilize to jQuery 2.2.4 before your library no longer works properly. Due to the fact that the anything less than jQuery 3 is considered a moderate security risk, are there any plans to offer support for jQuery 3+ ?

The library works fine in jQuery 3.3.1, the demo itself failed due to bug in jQuery Layout library used in demos. The orgDiagram and famDiagram widgets use very limited set of functions from jQuery. In general widgets rely on jQuery UI mechanism for instantiation and garbage collection of widgets in memory, plus they support nesting of other jQuery UI widgets in items as well.
Quote
 
 
#187 Administrator 2018-07-03 07:50
Quoting Hector Piza:
Hello,

We have been using BasicPrimitives for a while, just have a simple question.
Is it possible to remove any Item that is not somehow connected to the Root Item (or the first item in the json)?

Thanks!


Yes, of course it is possible. The problem here is that you are pushing our product scope from data visualization to general graphs data analytics tool and decisions which are absolutely acceptable for purposes of DV could be non optimal for graphs analytics. Look at Microsoft Cosmos Graph DB in Azure.

We have internal API structure called primitives.common.graph see Unit Tests. It supports disconnected nodes, you can populate this structure and traverse through its connected nodes starting with node you need.
Quote
 
 
#186 Hector Piza 2018-07-02 17:03
Hello,

We have been using BasicPrimitives for a while, just have a simple question.
Is it possible to remove any Item that is not somehow connected to the Root Item (or the first item in the json)?

Thanks!
Quote
 
 
#185 Administrator 2018-05-03 08:32
Quoting Sathya:
Do you have support for the org chart in Angular5
Is there a way to use these JQuery UI objects with typescript templates?

Angular lives well with jQuery. Basic Primitives uses it only to warp control into jQuery UI widget spec, so it has almost no code dependency on it. The TypeScript is designed to be converted into javascript so it can be easily mixed together with javascript and jQuery. We don't convert project to type script because the JavaScript spec itself is evolving fast.
Quote
 
 
#184 Sathya 2018-05-03 02:30
Do you have support for the org chart in Angular5
Is there a way to use these JQuery UI objects with typescript templates?
Quote
 
 
#183 Administrator 2018-03-06 21:42
Quoting Udayakumar:
How to basic primitives used in React-native? Please let me know as soon as possible.

React Native support requires implementation of rendering methods for iOS and Android.
Quote
 
 
#182 Udayakumar 2018-03-06 06:43
How to basic primitives used in React-native? Please let me know as soon as possible.
Quote
 
 
#181 Jaydip 2018-01-03 01:09
i want to all nodes open without click

In Family tree if more tree than it not open nodes we have to click on it but defaul all nodes open without click event
Quote
 
 
#180 Administrator 2017-11-28 08:44
Quoting Lucas Nalli:
Hi,
When I click on a node the first time it a popup to the url that I've setup, but if i click a second time it doesn't work.
I'm using

options.onCursorChanged = function (e, data) {

to open the popup, i suppose i must use another event

See onMouseClick event. It passes regular mouse click event and adds additional diagram context related arguments.
Quote
 
 
#179 Lucas Nalli 2017-11-28 05:45
Hi,
When I click on a node the first time it a popup to the url that I've setup, but if i click a second time it doesn't work.
I'm using

options.onCursorChanged = function (e, data) {

to open the popup, i suppose i must use another event
Quote
 
 
#178 Administrator 2017-09-26 06:47
Quoting Soundrya:
Is it poosible to use relative url of the image for embedding it in the pdf

See the following page http://pdfkit.org/docs/images.html
Adding images to PDFKit documents is an easy task. Just pass an image path, buffer, or data uri with base64 encoded data to the image method along with some optional arguments. PDFKit supports the JPEG and PNG formats. If an X and Y position are not provided, the image is rendered at the current point in the text flow (below the last line of text). Otherwise, it is positioned absolutely at the specified point.
Quote
 

Add comment