From 61fad6b89cf192eb1725d62439820491e511c7f4 Mon Sep 17 00:00:00 2001
From: Matthias Jentsch <matthias.jentsch@netways.de>
Date: Tue, 20 Aug 2013 16:04:13 +0200
Subject: [PATCH] Add documentation for components

Add a documentation about how to create and load documents

refs #4456
---
 doc/components.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 doc/components.md

diff --git a/doc/components.md b/doc/components.md
new file mode 100644
index 000000000..c61ff6695
--- /dev/null
+++ b/doc/components.md
@@ -0,0 +1,130 @@
+# Frontend components
+
+Frontend components are JavaScript modules that can be required directly through the HTML markup of
+your view, to provide additional functionality for the user. Although its best practice to
+make all features available without JavaScript, these components can be used to provide a richer
+and more comfortable user experience in case JavaScript is available.
+
+There is a certain set of frontend components which come directly with the Icinga2-Web core application,
+but it is also possible to define new components directly in Icinga2-Web modules.
+
+
+## How do components work?
+
+Components are defined in JavaScript files that provide a set of functionality that will be added to the
+targeted HTML node. Icinga2-Web uses [RequireJS](http://requirejs.org) to load
+all frontend components, so each frontend component is in fact
+[defined exactly like a RequireJS-Module](http://requirejs.org/docs/api.html#define) .
+
+The important difference to plain RequireJS is, that the loading and execution of these components is
+done automatically through the HTML markup. The attribute *data-icinga-component* in a DIV
+element will indicate that this element is a container for a frontend component and will trigger
+the component loader to create a component instance for this HTML node. The component loader
+keeps track of all available components and makes it possible to retrieve this instance when needed.
+
+
+### Component names
+
+A component name consists of two parts: the namespace and the name of the component itself. The component
+is named exactly like its JavaScript file, while the namespace is the name of the Icinga2-Web module that contains
+the component. Each Icinga2-Web module can contain its own components in the folder *public/js*.
+
+   <module>/<component>
+
+
+NOTE: The namespace used for modules defined in the Icinga2-Web core application is "app". In opposition to
+the modules the core application keeps its modules located in *public/js/icinga/components*
+instead of *public/js*.
+
+
+#### Example Names
+
+
+The full name for the component *modules/monitoring/public/js/someComponent.js* in the module "monitoring" would be:
+
+    "monitoring/someComponent"
+
+
+The full component name for the component *public/js/icinga/components/datetime.js* in the Icinga2-Web
+ core application would:
+
+   "app/datetime"
+
+
+## Creating a component
+
+As described in the chapters above, components are defined exactly like RequireJS modules, but
+with the additional requirement that they must always return a class constructor. The component below will
+search all date pickers, set the time format and create a JavaScript date picker when there is no native one
+available.
+
+    /**
+     * Ensures that our date/time controls will work on every browser (natively or javascript based)
+     */
+    define(['jquery', 'datetimepicker'], function($) {
+        "use strict";
+
+        var DateTimePicker = function(target) {
+            $(target).find('.datetime input')
+                .attr('data-format', 'yyyy-MM-dd hh:mm:ss');
+
+            $(target).find('.datetime')
+                .addClass('input-append')
+                .append('<span class="add-on">' +
+                    '<i data-time-icon="icon-time" data-date-icon="icon-calendar"></i></span>')
+                .datetimepicker();
+        };
+        return DateTimePicker;
+    });
+
+
+## Loading a component
+
+The following code will load the module *datetime*, which will ensure that there is always a datetime-picker
+with right time-format available.
+
+    <div id="date-time-picker" data-icinga-component="app/datetime">
+
+        <div class="datetime">
+            <input data-format="dd/MM/yyyy hh:mm:ss" type="text"/>
+        </div>
+
+    </div>
+
+
+### Component ids
+
+When an ID is assigned to the HTML element, it will be used by the component loader to reference this
+component. Otherwise an ID in the form "icinga-component-<ID>" will be created and the ID attribute in the
+HTML Element will be updated accordingly.
+
+
+### Component "target"
+
+The div-element with the *data-icinga-component* will be used as the "target" for the loaded component,
+which means that the component will perform its actions on this HTML node.
+
+
+
+# Retrieving a component
+
+Sometimes it can be necessary to retrieve the instances of the components itself, for example when they implement
+additional functions that can be called. The component loader is available in the Icinga object and can be used
+to retrieve component instances using their ID or their full component name.
+
+
+## By component id
+
+    var component = Icinga.components.getById("component-id");
+    component.doSomething();
+
+
+## By full component name
+
+    var components = Icinga.components.getByType("app/datetime");
+    // ... do something with every component of the type app/datetime
+
+## All components
+
+    var components = Icinga.components.getComponents();
+    // ... do something with every component