Added markdown how to use samples

Author: Basic Primitives

samples/AddingNewItemsToChartAtRuntime.md

@@ -0,0 +1,37 @@
+# Adding new items to chart at runtime
+
+Chart is designed to update only visual elements effected by the scope of changed API options. For example on screen annotations are being rendered on top of everything, so when we make changes to on-screen annotations definitions there is no need to redraw all chart elements. The same applies to other visual elements, chart compares current copy of definitions to the new one on API and in case of any changes it triggers rendering cycle for effected scope of visual elements.
+
+Chart does not track individual items, if we make changes in one of the items then the whole collection of items is considered to be changed, so control will layout again all items in diagram. So adding or removing individual item to items collection, does not improve rendering performance. In order to find changes in items collection widget scans all items on every refresh cycle. The chart was designed to be used in modern UI frameworks like AngularJS, so end user may change all API properties on every update, the control will check for changed properties only and make visual updates in the scope of changed properties. The point of this statement is that if we assign new items array to items property, but we make no changes to actual items, chart will not perform any layout calculations and rendering. So usage of collection bindings in Modern UI frameworks is absolutely fine.
+
+Please, pay attention that chart does not update its visual representation on every property change and it does not make any guesses about required changes. Chart provides "update" method triggering reevaluation of API properties and rendering cycle. This "update" method is supposed to be explicitly called when all properties are set on chart's API. That means that opposite is true and it is possible to set individual chart properties one by one via sequential API calls. All these changes to API properties will not trigger any layout changes or rendering till method "update" is called.
+
+The "update" method supports optional parameter which let you choose how you want to redraw your diagram.
+
+## JavaScript
+```Javascript
+control.update(primitives.orgdiagram.UpdateMode.Recreate);
+```
+Recreate - is full content reset and redraw. It is equivalent to complete chart removal and recreation. This is the most expensive update. Use it when you want to be sure that everything ware recreated from scratch.
+
+```Javascript
+control.update(primitives.orgdiagram.UpdateMode.Refresh);
+```
+
+This is above mentioned fast redraw mode, it reuses existing DOM elements in order to speed up update time and it makes visual changes only in scope of changed API properties.
+
+```Javascript
+control.update(primitives.orgdiagram.UpdateMode.PositonHighlight);
+```
+It ignores any API changes except current highlight item position, it just positions highlight item, no layout recalculation or items rendering performed.
+
+## jQuery
+```Javascript
+jQuery("#basicdiagram").orgDiagram("update", primitives.orgdiagram.UpdateMode.Recreate); /* Recreate */
+jQuery("#placeholder").orgDiagram("update", primitives.orgdiagram.UpdateMode.Refresh); /* Refresh */
+jQuery("#placeholder").orgDiagram("update", primitives.orgdiagram.UpdateMode.PositonHighlight); /* Highlight placement */
+```
+The following example demonstrates adding new items to organizational chart at run time, or in other words this sample does not recreate control every time we make changes to its items collection. It uses fast refresh mode to update its layout. This example adds "delete" and "add" buttons and implements onButtonClick event handler for adding and removing items. For more complex implementation of chart editing functionality see chart editor demo.
+
+[JavaScript](javascript.controls/CaseAddingNewItemsToChartAtRuntime.html)
+[JQuery](jquery.widgets/CaseAddingNewItemsToChartAtRuntime.html)

samples/AdviserAndAssistantItemTypes.md

@@ -0,0 +1,33 @@
+# Custom Placement of Children
+## Adviser & Assistant Item Types
+
+Organizational Chart items are defined in form of regular tree, so every item may have only one parent in hierarchy. This is conceptually easy to understand for end user who edits organizational chart and software devloper to maintain required structures in database and in application.
+
+In the reality pure hierarchical relations are rare, so organizational chart provides means to represent none hierarchical realations in form of item types and on-screen annotations.
+
+Chart supports following itemType's:
+
+* Regular,
+* Adviser,
+* Assistant,
+* SubAdviser,
+* SubAssistant,
+* GeneralPartner,
+* LimitedPartner
+* AdviserPartner.
+
+All of them affect child placement relative to its parent in hierarchy. The following example demonstrates  Adviser and Assistant types. Adviser item placed at the same level as its parent and connected to it horizontally. Assistant item is placed at level between parent and its regular children and horizontally connected to connection line between parent and its children as well.
+
+Use `ItemConfig.adviserPlacementType` option to place adviser or assistant on the left or right side of hierarchy;
+
+[JavaScript](javascript.controls/CaseAdviserAndAssistantItemTypes.html)
+[JQuery](jquery.widgets/CaseAdviserAndAssistantItemTypes.html)
+
+## Sub Adviser & Sub Assistant item types
+
+Sub Adviser & Sub Assistant item types are variations of regular Adviser & Assistant types. The only difference is they are shift down one level relative to their parents, so they are connected by their top side to the hierarchy.
+
+Use `ItemConfig.adviserPlacementType` option to place them on the left or right side of parent's hierarchy as well.
+
+[JavaScript](javascript.controls/CaseSubAdviserAndSubAssistantItemTypes.html)
+[JQuery](jquery.widgets/CaseSubAdviserAndSubAssistantItemTypes.html)

samples/AngularJSFirstOrganizationalChartDirective.md

@@ -0,0 +1,10 @@
+# AngularJS Organizational Chart directive example
+This example demonstrates how Organizational Chart Control can be wrapped into AngularJS directive. It demonstrates implementation of the following features:
+
+* Destroy - AngularJS directoive has to destroy control otherwise its event handlers would stay bound to placeholder DOM element.
+* Update Mode - in order to render control faster, directive should reuse existing control and use appropriate update method for changing cursor, highlight or full widget contents refresh.
+* Events looping - directive watches for scope properties and updates widget, so we have to avoid infinite update loops when we apply changes from control back to its scope object.
+* ItemTemplate - directive uses AngularJS templates and it shares items scopes between application and control.
+* Buttons - by default, control uses regular HTML buttons, in case of AngularJS we have to customize item and cursor templates to use AngularJS buttons.
+
+[AngularJS](angularjs.directives/CaseAngularJSFirstOrganizationalChartDirective.html)

samples/Buttons.md

@@ -0,0 +1,8 @@
+# Buttons panel
+
+Organizational chart provides simple API to create custom user buttons. They are defined in primitives.orgdiagram.Config.buttons collection, of type primitives.orgdiagram.ButtonConfig. The option primitives.orgdiagram.Config.hasButtons allows to make buttons visible only for current cursor item or for all normal items in diagram. The same option primitives.orgdiagram.ItemConfig.hasButtons in item controls buttons visibility for individual items.
+
+Buttons can be customized per item template. See Item template example in this section.
+
+[JavaScript](javascript.controls/CaseButtonsPanel.html)
+[JQuery](jquery.widgets/CaseButtonsPanel.html)

samples/ChildrenLayout.md

@@ -0,0 +1,9 @@
+# Children Layout
+Children Placement Layout can be defined individually per item or globally for all chart items. Following chart and item config properties are used to define layout of children:
+
+* childrenPlacementType - this property is available for chart and for individual items, it defines shape of children with enumeration `primitives.common.ChildrenPlacementType` it provides following options Vertical, Horizontal & Matrix
+* leavesPlacementType - this option is available only at global chart level and it is used to control children layout having no sub children, so it is only for children of the last level in hierarchy.
+* maximumColumnsInMatrix - by default children in matrix are shaped into square, in order to form them into rectangular shape you have to limit maximum number of columns in matrix, so rectangular shape would grow vertically.
+
+[JavaScript](javascript.controls/CaseChildrenPlacementType.html)
+[JQuery](jquery.widgets/CaseChildrenPlacementType.html)

samples/ConnectorAnnotation.md

@@ -0,0 +1,6 @@
+# Connector Annotations
+
+Connector annotation is on screen direct connection line between two nodes of diagram. It supports simple conflict resolution, if multiple connections defined between the same pair of nodes, control offsets them and draws them in parallel. The following sample demonstrates connection annotation drawn in offbeat style, this way connection annotation should not overlap diagrams base connection lines:
+
+[JavaScript](javascript.controls/CaseConnectorAnnotation.html)
+[JQuery](jquery.widgets/CaseConnectorAnnotation.html)

samples/CursorTemplate.md

@@ -0,0 +1,31 @@
+# Cursor template controls
+The general idea about cursor template is to provide convenient API to place context control panel as close to the cursor node as possible. The conventional approach is to place control panel on the side of the diagram and change its content as user selects new cursor item, this approach takes a cut of screen space out of the diagram layout. The similar approach is to draw context menu panel on top of the diagram on the side of the selected node, but this will obstruct view of other diagram nodes. The compromise design is to expand space around cursor node and place context controls into that space, so cursor template provides padding option to preserve that required space around cursor node.
+
+User controls in cursor item template plays a role of in-layout annotation, non-blocking neighboring items in chart. In case when every normal item is supposed to have UI controls then item template should be customized instead. Use z-index style attribute to layer controls properly.
+
+Every time we change cursor node control recalculates layout, so this slows down rendering of large diagram. Our design view on this problem is to limit number of simultaneously shown nodes in diagram. Control provides default mechanism to reduce nodes into dots, but general approach is to replace groups of diagram nodes with single node and expand them as user moves cursor close to them. This kind of design approach is implemented in Dynamic Data Loading demo.
+
+The following example demonstrates how to create Bootstrap vertical buttons group in cursor template:
+
+1. Don't use buttons collection option of organizational chart you have create them yourself in cursor or item template.
+2. Create cursor template and add bootstrap buttons group to it. http://twitter.github.com/bootstrap/
+3. Create event handler for onMouseClick event.
+
+[JavaScript](bootstrap.styles/CaseCursorTemplateAndTwitterBootstrap.html)
+
+## Custom cursor template border
+This example demonstrates how to create custom cursor border color and tag element.
+
+Control defines templates in object of type: `primitives.orgdiagram.TemplateConfig`, this object provides options to customize separately item contents, item cursor & item highlight using following options: itemTemplate, highlightTemplate, cursorTemplate. If option is not defined chart uses default template and render for it. Every template object is referenced by its name option, it should be unique string value. Use templateName option of ItemConfig to change template name for individual item. In order to make some template object default for all items in your chart you have to set its name to defaultTemplateName options of chart config.  So again every template objects provides separate HTML fragments and renders to customize item contents, highlight and cursor.
+
+The following example demonstrates how to create custom cursor template:
+
+[JavaScript](javascript.controls/CaseCursorTemplate.html)
+[JQuery](jquery.widgets/CaseCursorTemplate.html)
+
+## Cursor template having item specific context buttons
+
+This example demonstrates how to create item specific context buttons using cursor template. Ideally we have to create individual template for every item type and render buttons depending on template name, for simplicity we added an extra property called buttonsType to every item and use it to render different sets of buttons in cursor. This case is really rare and means that display collection of buttons depends on large set of items options.
+
+[JavaScript](javascript.controls/CaseButtonsInCursorTemplate.html)
+[JQuery](jquery.widgets/CaseButtonsInCursorTemplate.html)

samples/CustomLayoutWithInvisibleItems.md

@@ -0,0 +1,16 @@
+# Custom layout with Invisible items
+Chart navigation is defined by parent-children relations between items. When we select cursor item, all its children and parents displayed in full size, so user can continue navigation further down or up in hierarchy. When child or parent are invisible we display children of child or parents of parent in full size as well. This feature combined with custom item types and children layouts provides great flexibility for children layout.
+
+Following example demonstrates how to use invisible items to display multiple groups of children attached to one parent item. It has two rows of assistants and two levels of children. In order to implement this layout we create two invisible items of regular item type and make them invisible with setting option isVisible to false. Children of invisible items logically belong to their parent in our case it is root item of organizational chart, so when cursor is set to root item all items in chart become selected and displayed in full size, so user may navigate to any of them directly.
+
+See custom item types, children layout and inactive items samples as well. 
+
+[JavaScript](javascript.controls/CaseCustomLayoutWithInvisibleItems.html)
+[JQuery](jquery.widgets/CaseCustomLayoutWithInvisibleItems.html)
+
+## Skipped Levels
+
+Invisible items can be used to skip levels in organizational chart. This is actually workaround, invisible items occupy space, so they can be used to shift children items down one level relative to their parents. See primitives.orgdiagram.ItemConfig.isVisible option.
+
+[JavaScript](javascript.controls/CaseSkippedLevels.html)
+[JQuery](jquery.widgets/CaseSkippedLevels.html)

samples/DiagramSizing.md

@@ -0,0 +1,31 @@
+# Diagram Sizing
+## Responsive Design
+Like any other Data Visualization component it combines scalable and non-scalable graphics elements. For example we would like to show 10'000 labels but it is just physically impossible to fit them, because their total square size is multiple times bigger than available screen space. At the same time we cannot scale all of them down to points, since they become simply unreadable. Try to disable "fit to page" for large hierarchy demo, the resulting diagram is going to be so big that its visualization makes no sense, this rendering mode is useful only for PDF generation for reporting purposes only. If we speak about BI applications designed for data analysis then we need to show nodes only in the scope of current user focus of interest, so diagramming applications should be dynamic and adopt to user data and requirements. Another argument in favour of diagramming applications having auto layout is the fact that in large organizations where we have over 500 people the rate of changes is so high that any organizational structure becomes obsolete as soon as we make its hard copy. So we use various strategies to show as mush data as possible to the user within available screen space, so control needs to be notified about its placeholder size changes in order to trigger rendering cycle. 
+
+## Chart sizing is applications responsibility
+We don't try to refresh control ourselves for the following reasons: 
+
+* Chart does not add any event listeners outside of placeholder. There is no cross browser possibility to notify widget on `<div>` size change. The only workaround is to handle window resize event, but it creates unavoidable conflicts with host application. 
+* Chart does not update itself without explicit call of "update" method or end user mouse or keyboard action.
+
+## Pixel alignment
+When we draw SVG and Canvas lines it is important to have them pixel aligned otherwise they become blurred, so when we call "update" method control aligns placeholder position within pixel range via adding additional margins to left and top sides of the div, so that way pixel rounded lines matches physical pixels of monitor, so they look sharp and clean. 
+
+In the following example we show how to listen to window size change event and use Timer to throttle it so our application stays responsive.
+
+[JavaScript](javascript.controls/CasePageSizeDiagram.html)
+[JQuery](jquery.widgets/CasePageSizeDiagramWithoutUILayoutWidget.html)
+
+## Auto Size Diagram in Article
+
+In order to place diagram inside page article and make it auto expand to accommodate all nodes of diagram use AutoSize option of pageFitMode in Config class. Widget in this mode will auto size its placeholder div element to show all nodes of diagram. 
+
+Use following options to constrain widget auto size:
+
+* autoSizeMinimum - it limits minimal size of diagram, so if it is empty then you are going to see empty area of this size.
+* autoSizeMaximum - does not allow to grow widget beyond this size. Set maximum size to some value if you need to avoid humongous diagram on your page.
+
+for example in order to set widget minimal size: autoSizeMinimum = new primitives.common.Size(800, 600);
+
+[JavaScript](javascript.controls/CaseAutoSize.html)
+[JQuery](jquery.widgets/CaseAutoSize.html)

samples/FamilyChartItemsOrdering.md

@@ -0,0 +1,20 @@
+# Family Items Ordering
+Family Diagram supports multiple parents and children per node, so there is no deterministic way to define groups of items and their order in group, so Family diagram provides non-determenistic API to order items. That means if items expected to be in one layout group then user can use following properties to guide layout engine about user preferred relative order of items:
+
+1. `relativeItem` - item position and placement type defined relative to this property referenced item
+2. `placementType` - item placement on the left or right side of relative item. Property has following values:
+    * `primitives.common.AdviserPlacementType.Left`
+    * `primitives.common.AdviserPlacementType.Right`
+3. `position` - if several items reference the same `relativeItem` and placement then this `position` property defines order of them.
+
+If item has no relative item defined then layout engine will try to find optimal placement for it based on its relations.
+
+Please, pay attention that loops in references are completely ignored, so don't create mutual references between items.
+
+Family Items Ordering Sample
+
+[JavaScript](javascript.controls/CaseFamilyChartItemsOrdering.html)
+
+## Multiple Families Ordering Sample
+
+[JavaScript](javascript.controls/CaseMultipleFamiliesOrdering.html)