2005-11-08
Jason Schoonover
Initial href print functions were added in 1.0.6

Index file PHP link generator

	1. Explanation
	2. Syntax
	2. Examples

1. Explanation

New to 1.0.6, there is now a way to auto generate all of the links of
the front index.php page.  This makes adding hosts/devices to unnoc much
easier because if you choose to use this method, you no longer have to
worry about adding links as well to the front page, just add it to the
unnoc.conf and you're finished.

There are three functions:

	print_href_type  - will display all of a specified 'type'
	print_href_group - will display all of a specified 'group'
	print_href_host - will display a list of hosts

Each function can be called many times, and can take multiple arguments,
there are also two extra arguments you can specify for each function that 
will adjust the number of columns generated and where the colored dot 
goes.

The purpose of these functions is to print bundles of hosts, bundles of
types, or groups specified per host. 

2. Syntax

The order that the host links will be printed on the page is the order
that they are defined in the unnoc.conf file.

Valid syntax for all of the functions is one string per item, and and an
array for the options.  Like this:

	print_href_type ('aironet', 'airport', array (cols => 2));
	print_href_host ('hostname1', 'hostname2', 'hostthree');
	print_href_group (4, 5, array (cols => 2, status_after => 1));

	print_href_group ('11', array (cols => 1, 'only' => '1-3,5,6'));
	print_href_group ('11', array (cols => 1, 'only' => '4,7-13'));

Valid modifiers for print_href (array ()) are:

	cols n		Print the links in a table of 'n' columns

	status_after	This will print the little red/yellow/green dot
			after the href link, instead of before.  It
			really doesn't look all that good right now, but
			hopefully in the future it will look better.
	
	only		This can be a comma separated list, or a range
			(or a combination of both)

If you specify a description in the config file, then it will use that
description for the link on the front page.  If you specify a
description with $snmp or $hostname, then they will be replaced with the
SNMP description and hostname respectively.

	host {
		hostname = host
		description = Application Database
	}

Will print the title link as "Application Database"

	host {
		hostname = aironet1
		description = Cisco Aironet - $snmp ($hostname)
	}

Will print the title links as "Cisco Aironet - Lobby (aironet-2)"

It will check the database, and lookup the description column for the host,
if it exists then it will replace $snmpname with the description.  It will
also replace $hostname with the hostname.
	
The default is to print the hostname as the link.

NOTE: descriptions are not yet implemented for servers

a. print_href_type()

Valid arguments for print_href_type are: generic, server, netapp,
aironet, airport, em01, apc

There are also two more types you can use, for the wireless association
list:

	all_aironets	This will display a link that will take you to a
			page that will display all of your Cisco
			Aironets, without graphs.  The link description
			will look something like this:

				All Aironet Associations

			And when you click on it, the page will be a
			list of all of your SSID's and all of your Cisco
			Aironets, without graphs.

	all_airports	This will display a link identical to the
			all_aironets page, except it is for Apple
			Airports.  The link description will be:

				All Airport Associations

			And when you click on it, the page will be a
			list of all of your Apple Airports with their
			SSID's, and all of the clients per, without
			graphs.

You can specify columns and status_after as well, in an array.

b. print_href_group()

This function will take all of the hosts that have listed group = n in
the unnoc.conf file, and will print them out in a table.  The syntax for
the unnoc.conf definition is:

	host {
		hostname = host
		community = public
		...
		group = 1
	}
	
	host {
		hostname = server
		community = priv
		...
		group = 1
	
	host {
		hostname = host1, host2, host3, host4
		community = public
		..
		group = 2
	}

When you call the function print_href_group (1,2), it will print host,
server, host1, host2, host3, and host4.

You can also just specify print_href_group (1), which will just print
host, server.

You can specify columns and status_after as well, in an array.

c. print_href_host

This function will just print the hostname listed.

	print_href_host('host1', 'host3', 'host2')

That will print host1, host3, host2 in that order.

You can specify columns and status_after as well, in an array.


3. Examples

For most hosts, the href link it prints out is:

<a class='host' href=$wwwroot/display.php?host=hostname>$display</a>

Where $display is either the description pull from SNMP, the description
as listed in the unnoc.conf, or the hostname of the device.

a.  print_href_type('aironet', 'all_aironets');

	Lets assume that there are 4 aironet definitions, with no
	'description' directive in the unnoc.conf file.

	This example will print an href list of all Cisco Aironets and a
	link at the end for all of your aironets, the output would look
	like:

	aironet1
	aironet2
	aironet3
	aironet4
	All Aironet Associations


b. print_href_host ('host3', 'host2', 'host1', 'host4', 'host5', array (cols => 2));

	This example will print out the hostnames in two columns, like
	this:

	host3	host2
	host1	host4
	host5

c. print_href_group (1, 4 array (cols => 3, status_after => 1));
 
 	This example will print out everything in group 1 and group 4,
	in the columns, and put the colored status dot after each host

	server-1 x	server-2 x	db-1 x
	server-3 x	server-4 x	db-5 x
	server-5 x	netapp-1 x
	netapp-2 x

d. print_href_type ('airport', 'all_airports', array (cols => 3));

	This example will print every aironet that it knows about in 3
	columns, and then at the end it will print a link for 'All
	Aironet Associations'

	Like this:

	aironet-1	aironet-2	aironet-3
	All Aironet Associations


e. print_href_group, using the 'only' clause

	<table>
		<tr>
			<td>
				print_href_group ('11', array (cols => 1, 'only' => '1-3,5,6'));
			</td>
			<td>
				print_href_group ('11', array (cols => 1, 'only' => '4,7-13'));
			</td>
		</tr>
	</table>
 
	This example will print 1 through 3 and 5 and 6 in the first column of a table
	and will print out 4 and 7 through 13. This can be useful, for instance, if you are building your own
	table and are trying to even it out
	
	x server-1	x server-4
	x server-2	x server-7
	x server-3	x server-8
	x server-5	x server-9
	x server-6	x server-10
			x server-11
			x server-12
			x server-13



vim:tw=72:wm=1