[BlueOnyx:02133] Re: moidying sausalito ui

[Michael Stauber]

Hi Scott,

> I looked at that before and found it to be a bit over whelming.
>
> I was looking for more of a howto or beginners guide type of thing.

Yeah, the docs that Cobalt released back then were one of a kind. Over the 
years I found them more confusing and in some parts also deliberately 
misleading than helpful. They lack the hands on examples, too, and dive into 
areas that often weren't the least bit of interest to developers.

All the Cobalt docs that I could grab from various sources over the years are 
here at the URL below. But I didn't particularly hunt for them. So I may be 
missing a few.

http://data.smd.net/cobalt.docs/

If you just want to add a menu entry somewhere that shows a custom page in the 
GUI, then all you need are two things:

1.) The actual PHP page. If you don't need to use any GUI functions and just 
want to show some text and a clickable URL, then this could even be a simple 
HTML page.

2.) A menu XML file of a format similar to this:

---------------------------------------------
<item
    id="my_custom_menu_entry"
    label="My Menu"
    description="Description shown on mouse over of the menu label."
    url="/base/mydirectory/my_custom_page.php">
    <parent id="base_sysmanage" order="999">
        <access require="serverConfig"/>
    </parent>
</item>
---------------------------------------------

That XML file adds a menu entry to the vertical menu on the lefthand side of 
the GUI in "Server Management". 

Where it adds under is defined through <parent id>, which our example has set 
to "base_sysmanage". 

order="999" simply means it will show up as one of the last entries, even 
below "Active Monitor".

Some other key / value pairs and what they do:

id: Unique identifier of you menu entry. Different menu entries must have 
different IDs.

label: Text of the menu entry. We're not using the multi-language capability 
of the GUI here, so the text will show in the language that you type it in. 
Explaining how the different language stuff works would go to far for 
starters.

description: Text that's shown in the bottom frame if someone does a mouse 
over on your menu entry.

url: The URL of the link target when you click on your link - relative to the 
base path /usr/sausalito/ui/web

So the page you link to (in this example) must reside under  
/usr/sausalito/ui/web/base/mydirectory/my_custom_page.php

parent_id: Covered above. The next "higher up" menu entry that your own menu 
entry is attached to as a child.

access require: Defines who gets to see the menu entry. In this example 
"serverConfig" means: Only GUI users with the capability "serverConfig" can 
see the menu entry. This would mean only admin users can see it.

If ony site admins should see the menu entry, then set change it to:

<access require="siteAdmin"/>

If everyone should be able to see it, then simply remove the "access require" 
line altogether.

That covers the menu part so far. I could go further into how to create a 
Sausalito conforming GUI page that shows some text and a button, but that 
would be a bit too much for now I guess.

-- 
With best regards

Michael Stauber