Hi Rashid,
> I would like to create a simple form within the UI so that I can then
> execute a backend process. I would like to pass variables to that
> perl script. Can I get some pointers in the right direction?
Check this:
http://data.smd.net/cobalt.docs/slush_barn/
Especially: http://data.smd.net/cobalt.docs/slush_barn/DevGuide.pdf
It's a sample PKG for the Qube3 for learning purposes and also the Sausalito
developer guide.
Another good starting point is the BlueQuartz SVN - in particular one of the
more simplicistic BlueQuartz modules:
http://bluequartz.org/trac/browser/5100R/trunk/ui/base-shell.mod
However, let me add a few things. I am not wishing to discourage you, but
whoever wrote the Sun Cobalt developer guide for the architecture utterly
failed. I don't say that the document is worthless, but it's not really a
hands on guide and it contains too much useless information. The really saucy
parts are either well hidden under piles of garbage information, or absent.
The code tree of a typical BlueQuartz module usually looks like this:
base-shell.mod/
base-shell.mod/glue/
base-shell.mod/glue/handlers/
base-shell.mod/glue/schemas/
base-shell.mod/glue/conf/
base-shell.mod/locale/
base-shell.mod/locale/en/
base-shell.mod/locale/ja/
base-shell.mod/templates/
base-shell.mod/templates/rpmdefs.tmpl
base-shell.mod/ui/
base-shell.mod/ui/menu/
base-shell.mod/ui/web/
base-shell.mod/Makefile
base-shell.mod/packing_list
I start with the more visible parts first:
ui/menu:
=======
Contains XML files with the menu entries that define where pages appear in the
BlueQuartz GUI.
ui/web:
======
Contains the web pages that this module adds to the GUI.
locale:
======
Contains sub folders for each supported language. Each language folder within
holds at least one localization file which maps strings to the full text in
that given language for display in the GUI. The "gettext" RPM is needed
to "translate" this human readable *.PO files into binary *.MO files.
templates:
========
Contains the template of the RPM specfile used to build RPMs out of this
module.
Makefile:
========
The Makefile is used to set the modules name, vendor and version information
and also defines what is built (UI, Locale, Glue, SRPM).
Typically in order to build the module RPM's one needs a build environment.
Which means that the RPMs for gcc, automake, autoconf, patch, rpmbuild,
sausalito-devel, gettext and a few other odds and sods are installed.
Then one just goes into the module directory and runs ...
make clean
make
make rpm
... and it will build the RPMs and will put them into the folder "as_rpms" in
the code directory.
Now on to the less obvious parts and the inner workings of CCE:
===================================================
glue/schemas:
============
Contains one or more XML files. These XML files define Classes and Objects in
Sausalitos CODB database. That's the database in which the GUI stores all its
information.
The almost worthless developer guide has some lengthy paragraphs about this.
Let me try to sum that info up in a more comprehensible form:
A sample schema could look like this:
----------------------------------------------------------------------------
<class name="MyOwnClass" version="1.0">
<property
name="my_own_switch"
type="scalar"
default="0"
writeacl="ruleCapable(adminUser)"
/>
</class>
----------------------------------------------------------------------------
Now what does it do?
It creates a Class called "MyOwnClass" in CODB. This class has one storage
entry with the name "my_own_switch".
Into that storage entry we can write information of the type "scalar", which
literally means: Data of any type.
Available "types" are:
scalar: any data
word: any non-whitespace data
alphanum: any alphanumeric data
alphanum_plus: alphanumeric data plus a "safe" subset of punctuation
boolean: boolean is "0" for FALSE, "1" for TRUE
ipaddr: Valid IP address
For a full list of pre-defined "types"
see /usr/sausalito/schemas/basetypes.schema
When you restart CCEd, all Schema files are parsed and if you add a Schema
file, it will also create the respective Class in CODB. In our case it would
create the class "MyOnwClass", with the storage entry "my_own_switch" in it.
That switch will be set to "0", as we defined that as the default.
The last line in the above example Schema is "writeacl", which defines who can
write data to Objects of this Class or to the data fields within. In our case
only admin users can do that.
The "type" is also more important than it might seem at first glance. Because
if we try to put data into a storage field which doesn't match the "type"
specified for it, then the CODB won't let us. Additionally the GUI will also
show an error message that explains that the entered data doesn't match the
expected format.
So if we set the correct "type" in our Schema files, then we save a lot of
work on cross checking if the input the user submitted matches the expected
format. This is a true time saver when coding.
Interaction between GUI and Shell:
==============================
This is the really juicy part:
glue/conf:
=========
Contains one or more config files. Lets say our config file in there looked
like this:
-------------------------------------------------------------------------------------------------------------------
MyOwnClass.my_own_switch perl:base/my-own-module/myscript.pl EXECUTE
-------------------------------------------------------------------------------------------------------------------
Then it would do the following:
Whenever someone changes the value of "my_own_switch" of any Object of the
Class "MyOwnClass", then the script ...
/usr/sausalito/base/handlers/my-own-module/myscript.pl
... would be executed with root privileges.
"EXECUTE" is only one of a few possible way how one can call a
handler. "VALIDATE", "CONFIGURE" and "CLEANUP" are also possible. But those
do things beyond the scope of a basic documentation.
Security wise this is slick, because in our Schema we already made clear that
only authenticated and verified admin users could write to this Object.
Now what's left for you to do is to create a GUI page, which allows you to
display a checkbox that allows admin users to tick or untick a checkbox. Upon
submit you then parse the returned information and use PHP to set the
switch "my_own_switch" in the existing Object "MyOwnClass".
The config file and the handler will then to the rest.
glue/handlers:
============
That's where your Perl script(s) resides which are called by the config file.
These handlers cannot be executed directly from the command line. If you do,
they will do nothing. They're dependent on being called by CCE as specified
in the conf files of the modules.
constructor:
==========
Optional. These are similar to "handlers". But they're run every time when
CCEd is started or restarted. They're often used to gather system information
(network settings, reading various info from config files, etc.) and then
submit that info into Objects in CODB. Constructors need root privileges to
be run (otherwise they won't do much).
--------
Well, this pretty much covers the raw basics. There are still plenty of more
details. The next obvious question would be:
How do I create a PHP webpage that reads what value is stored in the Object
named "MyOwnClass" in the data field for "my_own_switch" and displays that in
the GUI?
And the next step after that is of course: How do I parse that form data and
write the new info back into CODB?
For that I'd like to point you to the developers guide, or towards a page from
base-shell.mod:
http://bluequartz.org/trac/browser/5100R/trunk/ui/base-shell.mod/ui/web
/usr/sausalito/ui/web/base/shell/shellAccess.php
This should get you started.
--
With best regards,
Michael Stauber