Pentaho CDE Atol CD Plugins official release

Change-Id: If0e04a4106aba980a23c20397a82e340aaf75b5b

README.md

@@ -1,17 +1,19 @@
-Pentaho CDE Atol CD plugins
+Pentaho CDE Atol CD Plugins
 ================================
 
 This project provides you CDE components developed by [Atol Conseils et Développements (Atol CD)](http://www.atolcd.com), including **SVG Component**.
 
-[Pentaho CDE Atol CD plugins Home page](https://github.com/atolcd/pentaho-cde-atolcd-plugins/)
+Works with Pentaho 6.0 and above.
+
+[Pentaho CDE Atol CD Plugins home page](https://github.com/atolcd/pentaho-cde-atolcd-plugins/)
 
 Installation instructions
 ---------------------
 1. **Install the Pentaho plug-in atolcd:** start Pentaho BI Server and open it in a browser; search for the plug-in atolcd in Pentaho Marketplace and install its latest version; clear browser’s cache and restart Pentaho server.
-2. **Include Atolcd input types:** reopen Pentaho User Console in browser; open the installation page of atolcd plug-in (menu Tools > Atolcd); click on the button “Include ATOL CD input types”; clear browser’s cache and restart Pentaho server.
+2. **Include Atol CD input types:** reopen Pentaho in browser; open the installation page of atolcd plug-in (menu Tools > Atol CD Plugins); click on the button “Click here to finish plugin installation”; clear browser’s cache and restart Pentaho server.
 3. **Installation complete**.
 
-To get more information about this plugin, see our [documentation](https://github.com/atolcd/pentaho-cde-atolcd-plugins/blob/master/).
+To get more information about this plugin, please refer to our [documentation](https://github.com/atolcd/pentaho-cde-atolcd-plugins/blob/master/docs/SVG%20Component/README.adoc).
 
 
 Contributing

build.properties

@@ -1,14 +1,14 @@
 # Stage: TRUNK | STABLE | BETA | other branch
 project.stage=SPARKL
 project.stage.name=Sparkl
-project.version=
+project.version=1.0
 project.revision=${project.stage}-${project.version}
 # Version: a numeric value or SNAPSHOT. SNAPSHOT is replaced by DSTAMP
 package.url=not defined
 ivy.artifact.id=atolcd
-ivy.artifact.group=
-impl.title=
-project.description=
+ivy.artifact.group=Atol CD
+impl.title=Provides components for Community Dashboard Editor.
+project.description=Provides components for Community Dashboard Editor.
 testsrc.dir=test
 dependency.bi-platform.revision=TRUNK-SNAPSHOT
 #Properties for Pentaho 5.0

cpk.xml

@@ -22,7 +22,13 @@
     </elementTypes> 
     <info>
         <CPK_version>5</CPK_version>
-        <name>Atolcd</name>
+        <description>Provides components for Community Dashboard Editor.</description>
+        <name>Atol CD Plugins</name>
+        <author_email>[email protected]</author_email>
+        <author_name>Atol CD</author_name>
+        <company_name>Atol CD</company_name>
+        <company_url>www.atolcd.com</company_url>
         <creation_date>2017-07-26</creation_date>
+        <version>1.0</version>
     </info>
 </cpk> 

docs/SVG Component/Introduction to SVG Component.adoc

@@ -0,0 +1,57 @@
+= Introduction to SVG Component
+
+ifdef::env-github,env-browser[:outfilesuffix: .adoc]
+
+:sectnums:
+
+<<README{outfilesuffix}#,Back to main index>>
+
+'''
+
+*SVG Component* was one of the first CDE components created by *Atol CD*. Its main purpose is to provide an easy way to include *SVG (Scalable Vector Graphics) image* to CDE dashboards and to apply dynamic information on it in order to create easily memorable visual graphics. It was first developed to create interactive geographical maps, but now it can be used for all types of graphics (metro map, hemicycle group division, etc.), as long as they are SVG images.
+
+== Former solution
+
+Prior to the creation of SVG Component, there was a rather complex way to generate components with similar behaviors to the currently existing SVG Component. We would have to paste the raw XML content of an SVG file into an *Html element* in CDE Layout Panel, then create a *Query Component* to load data from data sources, make use of its *postFetch* function and write some custom JavaScript code modifying the SVG content whenever this component is updated.
+
+This work takes normally a whopping 5 hours for an experienced developer, yet it is not generic nor reusable. A major inconvenience of this method consists in the absence of the *Parameter* property, thus developers would have to write custom JavaScript code inside components’ lifecycle functions or as a resource in Layout Panel, so that other components could listen to changes coming from this component. Another inconvenience is that each graphic’s legend and the colorization would have to be written manually, while this process could very well be automatized with a generic code.
+
+While this solution remains flexible and highly customizable, it should be replaced by a more general solution to enhance work performance, hence the development of *SVG Component*.
+
+== SVG standard
+
+We decided to create a specific CDE component for SVG contents, as the *SVG standard* provides numerous advantages for our cartographic dashboards:
+
+* [*] Free, open, standardized, human and machine readable format for vector graphics.
+* [*] Easy to create using *Inkscape* or any text editor.
+* [*] Supported by all major web browsers.
+* [*] Shapes are well preserved while scaling vector images.
+* [*] Interactive and animated behaviors are defined and can be manipulated.
+
+== Cartographic knowledge
+
+Considering that the SVG Component is intended for interactive maps and graphics, using this component involves possessing some fundamental cartographic knowledge.
+
+The SVG Component is very useful and fitting when it comes to *thematic and chorematic / schematic maps*. These maps usually involve territories, distribution, division, phenomena. This component will help pointing out similarities and differences between entities of a map or graphic, thus make it easier to understand and memorize those characteristics. Since SVG graphics will be colorized, their main entities usually are areal objects.
+
+In graphics generated by SVG Component, some conventional features of a map (scale, directions, etc.) will not be included, since they are already predefined, also they do not help completing the goals of this component. Therefore, users should only focus on determining perception and representation rules permitting the best and easiest understanding of their graphics.
+
+{empty} +
+
+The main elements of a graphic generated by SVG Component are:
+
+* *Title:* informs the focused theme(s) and information of the graphic.
+* *Graphic:* contains various data visually represented by the *colorization* and the *tooltip*.
+* *Legend:* explains the colors used on the graphic.
+
+{empty} +
+
+In general, these 3 elements will be displayed vertically in the exact same order as above, for it is the natural order of almost all maps and graphics.
+
+A visual graphic usually includes its information sources, but SVG Component will not handle this element, either because it can be hard-coded along with SVG content, or it can be easily included in dashboards near the SVG graphic, using a Text Component for example.
+
+Values represented by the colorization of the graphic might be *numeric* (quantitative) or *nominal* (qualitative). They might be raw data directly extracted from data sources, or data processed using a certain statistical method, such as K-means, quantiles, standard deviation, etc.
+
+*Data analysis* can be separated into 2 types: *formula-based calculation* and *statistical analysis*. The former should be done beforehand, directly inside the related query for example, for each data record; while the latter will be done later, when data arrive and form a series, on which statistical methods can be applied and data will be classified into legend groups.
+
+SVG Component incorporates several extra features, which will be described in a <<Original%20features{outfilesuffix}#,dedicated section>>.

docs/SVG Component/Original features.adoc

@@ -0,0 +1,23 @@
+= SVG Component - Original features
+
+ifdef::env-github,env-browser[:outfilesuffix: .adoc]
+
+<<README{outfilesuffix}#,Back to main index>>
+
+'''
+
+Benefiting from the specified standard properties, SVG Component already possesses fundamental features of a CDE component, such as the lifecycle functions, the “*Parameters*” and “*Listeners*” properties, and especially the “*Parameter*” property. So, by developing a new component, we have already easily solved one of the problems residing inside the former solution.
+
+Moreover, with the “*Datasource*” property, you can fetch data related to the entities on the SVG image from a datasource, then display them in the tooltip and / or transmit them to other components by clicking on the entities. The component datasource is not mandatory. If it is not specified, SVG Component can be considered as a select component, where clicking on an entity on the SVG image means making a selection.
+
+. <<features/The%20two%20entry%20modes%20for%20SVG%20content{outfilesuffix}#,The two entry modes for SVG content>>
+. <<features/Ratio%20control{outfilesuffix}#,Ratio control>>
+. <<features/SVG%20graphic%20title{outfilesuffix}#,SVG graphic title>>
+. <<features/Input%20interface%20for%20the%20legend{outfilesuffix}#,Input interface for the legend>>
+. <<features/Colorization%20of%20entities%20on%20the%20SVG%20image{outfilesuffix}#,Colorization of entities on the SVG image>>
+. <<features/Colorization%20filtering{outfilesuffix}#,Colorization filtering>>
+. <<features/Tooltip{outfilesuffix}#,Tooltip>>
+. <<features/Click%20and%20interactions%20with%20other%20components{outfilesuffix}#,Click and interactions with other components>>
+. <<features/The%20dynamic%20selectors{outfilesuffix}#,The dynamic selectors>>
+. <<features/Zoom{outfilesuffix}#,Zoom>>
+. <<features/The%20export%20button%20function{outfilesuffix}#,The export button / function>>

docs/SVG Component/README.adoc

@@ -0,0 +1,13 @@
+= SVG Component Documentation
+
+ifdef::env-github,env-browser[:outfilesuffix: .adoc]
+:imagesdir: ./images
+
+image::atolcdLogo.png[Atol CD logo]
+image::depPopulation.png[SVG Component main image]
+
+* <<Introduction%20to%20SVG%20Component{outfilesuffix}#,Introduction to SVG Component>>
+* <<SVG%20Component%20installation{outfilesuffix}#,SVG Component installation>>
+* <<Standard%20properties{outfilesuffix}#,Standard properties>>
+* <<Signature%20properties{outfilesuffix}#,Signature properties>>
+* <<Original%20features{outfilesuffix}#,Original features>>

docs/SVG Component/SVG Component installation.adoc

@@ -0,0 +1,70 @@
+= SVG Component installation
+
+ifdef::env-github,env-browser[:outfilesuffix: .adoc]
+
+ifdef::env-github[]
+:note-caption: :information_source:
+:tip-caption: :bulb:
+:important-caption: :heavy_exclamation_mark:
+:warning-caption: :warning:
+endif::[]
+
+:sectnums:
+
+<<README{outfilesuffix}#,Back to main index>>
+
+'''
+
+== Prerequisites
+
+Below are the prerequisites for SVG Component:
+
+* An operational *Pentaho BI Platform* (preferably version *6.0* or higher).
+* *CTools (CDA, CDF, CDE)* and *Pentaho Marketplace* already installed. These Pentaho plug-ins are installed by default in Pentaho 6.0 and above.
+
+== Plug-in content
+
+SVG Component is included inside the Pentaho plug-in *atolcd*, and contains:
+
+* *“component.xml”*: the XML metadata file describing the structure of the editor HTML page to be built by Pentaho server and to be rendered by browsers for this specific component.
+* *“SVGComponent.js”* and *“SVG.js”*: the JavaScript files defining all behaviors of the component and how it will be rendered in CDE dashboards.
+* *“SVGComponent.css”*: the CSS file containing specific CSS classes for this component.
+* The *4 JavaScript libraries* that it depends on, including “geostats.min.js”, “simple-statistics.min.js”, “svg-pan-zoom.min.js” and “saveSvgAsPng.js”.
+
+== Installation instructions
+
+SVG Component is a *CDE component* and a plug-in conceived for *CDE*, whereas CDE itself is a plug-in of *Pentaho BI Platform*. In order to install SVG Component on CDE and Pentaho, you should complete the following steps:
+
+. *Install the Pentaho plug-in atolcd:* start Pentaho BI Server and open it in a browser; search for the plug-in *atolcd* in Pentaho Marketplace and install its latest version; clear browser’s cache and restart Pentaho server.
+. *Include Atol CD input types:* reopen Pentaho in browser; open the installation page of *atolcd* plug-in (menu *Tools > Atol CD Plugins*); click on the button “*Click here to finish plugin installation*”; clear browser’s cache and restart Pentaho server.
+. *Installation complete*.
+
+{empty} +
+
+Above is the standard installation process for Pentaho 6.0 and above, and RequireJS dashboards.
+
+IMPORTANT: Atol CD input types inclusion is compulsory, otherwise you will not be able to input information into the 3 properties “*SVG file*”, “*Legend*” and “*indicatorMapping*”. Input types are JavaScript objects defining the way data are input into properties. Each property is associated with exactly one input type, but each input type can be associated with many properties. The association between properties and input types is described in “*component.xml*”.
+
+IMPORTANT: Browser’s cache clearing and Pentaho server restart are also compulsory. The restart will allow Pentaho server to identify the new plug-in *atolcd* and to render the new *SVG Component*. Major browsers often store JS and CSS files in their cache so that data can be served faster in the future. Therefore, cache clearing will force browsers to update CDE interface with the new SVG Component. These two actions will also help updating an old version of SVG Component.
+
+NOTE: We have tested this installation process on *Pentaho 5.x*. You will need to install the specific and corresponding version of SVG Component for Pentaho 5.x, containing some minor changes compared to its standard version. Also, you cannot properly open the installation page of atolcd plug-in (incompatibilities with old versions of Pentaho). Thus, you have to manually include Atol CD input types, by opening the file */pentaho-solutions/system/pentaho-cdf-dd/editor.includes.properties* and add the path to the JS file containing these input types: “*../atolcd/js/cdf-dd-components-atolcd.js,*” at the end of the line “*scripts=[...]*”.
+
+{empty} +
+
+For *legacy / non RequireJS dashboards*, in order to use the export feature, you will need to proceed as follows:
+
+. In the Layout Panel, add a new JS resource as a code snippet with the following code:
+
+ define = undefined;
+
+. In the same panel, add a new JS resource as an external file, and choose the JS library “*saveSvgAsPng.js*” in your file system. You can select the version of this library on which SVG Component depends (*1.1.0*), or your own copy of this library downloaded beforehand from the Internet. Note that this library must be placed below the above code snippet.
+
+{empty} +
+
+There is another way to deploy SVG Component without installing the plug-in *atolcd*:
+
+. Go to the *https://github.com/atolcd/pentaho-cde-atolcd-plugins[GitHub page]* of the plug-in *atolcd* and download its latest version (as a compressed file).
+. Extract the downloaded file, then compress the folder */atolcd/resources/components/SVG* as a ZIP file.
+. Start Pentaho server, upload the ZIP file to the folder *Public/cde/components* in Pentaho repository (if you cannot find it, menu *View > Show Hidden Files*).
+. Copy the file *cdf-dd-components-atolcd.js* to */pentaho-cdf-dd/js*, manually change the file *editor.includes.properties* as above (now with “*js/cdf-dd-components-atolcd.js,*”).
+. Clear browser’s cache, restart Pentaho server.