/*******************************************************************************

    Author ......... Reinhard Scheck
    Contact ........ gandalf @ cacti forums
    Home Site ...... http://www.cacti.net
    Program ........ Cacti Aggregate Builder
    Version ........ 0.62
    Purpose ........ Build Aggregate Graphs from existing ones

*******************************************************************************/


----[ Purpose

    This plugin aggregates graphs from Graph Management.
    All data you want to see must already be present on any existing graphs.

----[ Features

    1) Aggregates existing Graphs into a single Aggregate Graph, keeping the sequence
       of selected Graphs and of the Graph Items within theses Graphs.
    2) Provides a new Graph Title for the Aggregate.
    3) Prepends all legend items with the hostname the item belongs to.
    4) Provides a checkbox to manually add additional <HR> linebreaks.
       This prevents ugly formatting.
    5) Allows for converting into AREA/STACK or LINE1 graphs
    6) Displays a list of Graph Items (taken from the first Graph selected) to allow 
       for skipping selected graph items
    7) Defines "Color Templates". These define a list of colors, e.g. light red to dark
       red. Allows to associate colored Graph Items to a Color Template. By doing so,
       Graph Items of same data source will no longer show the same color but instead
       will be colorized according to the Color Template

----[ Prerequisites

    Before you install Aggregate, you need to have met the following pre-requisites:

    1) Cacti 0.8.6i or Above.  Versions of Cacti prior to 0.8.6 are not supported.
    2) Cacti Plugin Architecture v1.0 (requires 3 new hooks provided as a patch) OR
       Cacti Plugin Architecture v1.1 (includes the needed hooks)

----[ Installation

    Install is similar to other plugins.
    Realm ID is 72, needed to manage Color Templates. Using Color Templates is
    possible without access to this realm id.
    DO NOT FORGET TO INSTALL THE aggregate.sql

----[ Usage

    This plugin adds a new dropdown action to Graph Management, called
    "Create Aggregate Graphs". To use it, please filter the graphs you want to 
    aggregate and select all of those you want to be aggregated. The topmost
    one serves as a "template" for the basic graph properties.

    If you like to aggregate graphs of different type (e.g. a traffic graph and
    a graph showing the numbers of logged in users), no one will stop you doing so.
    But in case you want to interpret the data, this will be left to you.
    So, better aggregate graphs of same graph template.
    
    Be aware: If the basic graphs include e.g. AREA/STACK graph items, those will
    overlap on the aggregate. Please select the option "Make it an AREA/STACK Graph",
    and the plugin will take care for it.
    Alternatively, by checking "Make it a LINE1 Graph", all AREA/STACKs are converted
    to LINE1.
    If the basic graphs include "Totals", the aggregate will include those as well.
    It may not make that much sense to include several "Totals"; so you may want to
    delete some of them.
    If the basic graph includes "COMMENTS", you may want to delete some of them as well.
    This is supported by checking the "Skip" checkboxes for those Graph Items.

	Graph templates may omit <HR> line breaks for the last graph item. You will want to
	provide those by checking the <HR> checkbox. This may come in useful as well when
	deleting special graph items in the middle of a graph templatre that carry a <HR>.
	If you skip those items, ugly formatting would be the result. To prevent this,
	mark the previous graph item with <HR>

    In general, colors of graph items from different graphs will be equal. You will want
    to change colors to make the aggregate better readable.
    This plugin supports re-colorization by means of "Color Templates". Color Templates
    are a list of different colors. Selecting a Color Template for a colorized Graph
    Item from the dropdown selection list will associate this Graph Item with the color
    defined by the Color Template.

    When aggregating, you will be prompted

    - Title Format:
    Enter a new title for the Template.
    
    - Graph Type:
    Select one of the following
    	Keep Graph Types				- no changes to Graph Item Type
    	Make it an AREA/STACK Graph		- create an AREA/STACK Graph
		Make it a LINE1 Graph			- convert to LINE1
		
	- Graph Template Items
		Select a given Color Template to change the color of a Graph Item
		Select the "<HR>" checkbox to set a linebreak for that graph item
		Select the "Skip" checkbox to suppress this Graph Item for the Aggregate

----[ Additional Help?

    If you need additional help, please goto forums.cacti.net.

----[ Possible Bugs?
   
    If you figure out this problem, let me know!!!

----[ Special Thanks

	The idea to create such a plugin was first mentioned by TheWitness, even if he
	preferred to work on Data Sources instead of Graphs.
	All this would not have been possible without the cacti core development team
	and the work of cigamit, who created the Plugin Architecture for cacti.

----[ Future Changes


----[ Changelog
    --- SVN ---

    --- 0.62 ---
	Bug fix: Initialization issues

    --- 0.61 ---
	Bug fix: Error, when deleting a Color Template
	Tweak:   include statements use $config path variables

    --- 0.6 ---
    Added checkboxes for <HR>. On specific Graph Templates, it will not be possible
    to compute all needed <HR>s. So we prompt you to set them manually.
    bug: LINEx graphs converted to AREA/STACK will now have AREA on the first graph items

    --- 0.5 ---
    Managing of Color Templates
    Referring to Color Templates allows for different colors for same data source

    --- 0.4 ---
    Add skipping of selected Graph Items

    --- 0.3 ---
    Add Graph Type Conversion

    --- 0.2 ---
    First public release, very basic functions

    --- 0.1 ---
    Initial release, first shown at 1.CCC.eu, the 1. European Cacti Community
    Conference.