The Vortex is configured using a couple of XML configuration files as follows:
The Database Instances also keep a couple of configuration files:
The specifics of the diffent files follow.
The main Vortex configuration file is located in the Vortex framework under /config/xml/config.vortex.xml. This file contains general information about the Vortex Framework and information about where to find the Database Instances to use. This file is an XML version 1.0 file using encoding ISO-8859-1. The root element is called vortex. Examples follow the element descriptions.
Tagname | Attribute | Description |
---|---|---|
locale | file | |
details | file | What does this do? |
database | Each database tag specifies information about a database instance. | |
available | A list of hostnames that this database will be visible for. Separated by ; [Optional] | |
default | One host that this CBI will be default for. When surfing to this host no database choise will be available, this DBI will be loaded. [Optional] | |
id | The ID of the database instance. This value is used when referring to the database from Command Line and direct links. | |
path | Relative path of the root of the database instance. Knowing this the system knows where to find the DBI Config. | |
user | Information regarding users in the framework. | |
user.password | Information regarding the password. | |
user.password.lifetime | What does this do? | |
user.password.lockfailures | How many attempts the user has before the account is locked. | |
user.password.expirewarning | What does this do? | |
user.loggedinfor | How many minutes until automatic logout. | |
user.admin | Settings for the admin user created by default for new Database Instances. | |
iduser | ID of the admin user. | |
username | Default admin username. | |
password | Default admin password. | |
user.ad | Settings for AD connection | |
server | IP to AD server authenticating the users | |
enabled | True or false, wether to allow AD authentication |
<?xml version="1.0" encoding="ISO-8859-1"?> <vortex> <locale file="swedish" /> <details file="config.details.xml" /> <database id="myTest" path="../TestDBI/" default="mytesturl.mytestdomain.com" /> <database id="myTest2" path="../TestDBI2" available="mytesturl2.mytestdomain.com;127.0.0.1" /> <user> <password> <lifetime>0</lifetime> <lockfailures>5</lockfailures> <expirewarning>10</expirewarning> </password> <loggedinfor>10</loggedinfor> <admin iduser="1" username="vortexadmin" password="vortexpassword" /> <ad server="server_ip" enabled="true/false" /> </user> </vortex>
The Vortex can use several different database engines. To ensure this no SQL syntax is hard coded into the vortex. All SQL commands are stored in SQL configuration files. Translating these files for use with a new database engine requires good knowledge of the database engine and of the Vortex SQL Configuration syntax.
These files reside in /config/xml/sql.[Database Engine name].xml. To see which tags should be translated, use one of the currently working configurations. Currently the following Database Engines are supported:
The SQL Configuration files are XML 1.0 files with UTF-8 encoding. The root element is called sql and the structure below must be strictly followed in all new SQL Configuration files. The syntax is as follows:
<command_name [noescape="[true/false]"]>[SQL COMMAND]</command_name>
The noescape attribute executes the SQL command without using the internal SQL escaping. All parameters that are sent to the SQL command must be escaped before passed. The SQL commands can be built using printf syntax substituting variables with either %d or %s:
SELECT * FROM myTable WHERE id=%d OR name='%s'
These type of SQL Commands are referenced in the code with the same type of syntax:
$res = Vortex::$dbh->query( "sql.mycommand", $id, $name );
Another option, which is preferred, is the Vortex syntax for variable substitution:
SELECT * FROM myTable WHERE id=%[id]% OR name='%[name]%'
These type of SQL Commands are referenced in the code with the following syntax:
$attribs = array( "id"=>$id, "name"=>$name ); $res = Vortex::$dbh->query( "sql.mycommand", $attribs );
One thing that makes this the preferred method is that it simplifies keeping track of passed parameters, and allows the SQL Command to re-use variables only passed once.
The configuration of the DataBase Instance is done in the file /config/config.xml in the DBI directory. In this file the configuration of the database connectivity, DBI description, loggers, menu and webservices is done.
The root element of the config file is the <config> element.
The database connectivity is configured within the database element. This element contains the following attributes, and no child elements.
Attribute | Description |
---|---|
id | The ID of the database, used when referencing the database in webservices and direct calls |
database | The name of the database to connect to |
username | The username to use when authenticating the database connection |
password | The password to use when authenticating the database connection |
server | The name of the server hosting the database |
type | Type of database, currently only mysql is supported |
The DBI description is configured within the description element, which has the following attributes and no child elements.
Attribute | Description |
---|---|
title | Title of the DBI, shown in the title bar of the browser |
icon | The icon shown in the database selection |
icon2 | The icon shown in the database selection when the mouse is over the icon |
css | Which CSS to load |
menuhead | The title in top of the menu |
By adding a defaultuser element to the configuration default values can be set for every attribute for a new user. Default groups can also be specified, and theese default values will be set for a new user where no overriding value is specified.
... <defaultuser> <valid_from_time>{date}</valid_from_time> <valid_to_time>{date.Y+1}</valid_to_time> <group>UsersGroup</group> <group>MyGroup</group> </defaultuser> ...
Attribute values are parsed as VxStrings and groups are identified by supplying the UUID for the chosen group. All the fields in the database can be given a default value using this configuration element, even your own custom fields.
The configuration of the loggers is done within the loggers element. This element has one attribute, logpath containing the relative path within the DBI directory where the logfiles are kept. Make sure the user running the webserver has full permissions on the files in this directory. The bind and logger elements are subelements to the loggers element.
The configuration of the loggers is done in two steps. First the actual loggers are defined, within logger elements.
Attribute | Description |
---|---|
name | Name of the logger, used when binding the logger |
file | Name of the logfile |
level | Loglevel, valid values are LEVEL_ALL, LEVEL_FINE, LEVEL_NORMAL, LEVEL_COARSE, LEVEL_NONE |
format | Names the formatter to use. Default value is StdFormatter. This formatter needs to be implemented in the vortex /classes/logger path |
keepfiles | How many files to keep when cycling |
sizelimit | The logfile is cycled when exceeding this sizelimit |
The configured loggers are then bound to PHP classes using bind elements.
Attribute | Description |
---|---|
class | Name of the class to bind |
logger | Name of the logger to bind |
If the class attribute is set to all, all classes that has no specifically bound logger will be logged using the given logger. Likewise, the class ERROR will be used as an errorlog where all caught Exceptions and handled errors are logged to.
The menu shown on the left of the screen in the Vortex can be customized. If no menu configuration is given, all Tables are shown in the menu as a straight list of items. Using the menu configuration, the menu can be configured as a tree structure containing only the wanted Tables. Permissions can be set only allowing a subset of users to see certain submenus or Tables, and Scripts can be added to the menu.
The base element of the menu configuration is the menu element. This element has no attributes and contains the rest of the menu elements.
The menu configuration currently consists of the menuitem, table, spacer and script elements.
The menuitem describes a sub menu structure. The menuitem can contain other menuitem(s), table(s), spacer(s) and/or script(s).
<menuitem name="My SubMenu" default="open"> <table name="myTable" /> </menuitem>
Attribute | Description |
---|---|
name | The name of the submenu, shown in the menu |
default | open/closed , the default state of the sub menu |
requiredgroup | If given, contains a comma separated list of groups to see this menuitem |
icon | Path to an icon to show for the menuitem |
The table element describes a reference to a Table to be shown in the menu.
Attribute | Description |
---|---|
name | The name of the Table to show |
id | The ID of the table to show, either name or ID is required, not both |
requiredgroup | If given, contains a comma separated list of groups to see this table |
icon | Path to an icon to show for this table |
type | For import/export functionallity. |
descriptive | For import/export functionallity. |
The spacer shows an empty row in the menu, for layout purposes only. It has no attributes or sub elements.
Describes a script to run and to show the output for. Scripts are defined in the /script folder in the DBI directory.
Attribute | Description |
---|---|
name | Name to show in the menu |
class | Class containing the method to run |
method | Name of the method to run |
param_[x] | Where x = 1,2,3,4,… Parameters to pass to the method. All numbers must be given in sequence. |
requiregroup | If given, contains a comma separated list of groups to see this script |
icon | Icon to show for this script |
In order to let the current user edit details regarding his/her own profile the My Profile script can be added to the menu.
<script name="My Profile" class="User" method="myProfile" requiregroup="users" param_1="password" />
This calls the myProfile() method of the User class which lets the current user edit details of their profile. The param_1 parameter contains a comma separated list of the names of the fields in the user profile that the user is able to edit. Related fields can be added here by giving their full name, ie relation.fieldname. If a fieldname is prefixed with an asterix * the field will be shown as read-only for the user.
Configuration of default ShowList properties is done with the showlist element in the config file. Currently this element only supports one child element displayrows which controls how many rows will be shown .
<showlist> <displayrows>100</displayrows> </showlist>
See Webservices
In order to use SQL queries from the Searchbox and in filters those queries need to be predefined on the server. This is done by placing XML-formatted .sql files in the /sql path under the DBI. The syntax of the .sql files is described in the section above.
To include custom sql files in a DBI add the sql element to the config.xml file:
... <sql> <file filename="my_custom_sql.sql" nodename="custom" /> <file filename="my_other.sql" nodename="other" /> </sql> ...
Theese queries can be addressed from the Vortex like:
$res = Vortex::$dbh->query( "sql.custom.mysqltagname" ); $res2 = Vortex::$dbh->query( "sql.other.mysqltagname" );
where mysqltagname is the full name of the sql query in the .sql file. The type of the database is added before the extension in the file so the files that will be opened in the example above for a DBI using a mysql type database will be
my_custom_sql.mysql.sql my_other.mysql.sql
See The User Manual
All CSS-files and icons can be overridden by making local copies in the DBI. Files that are put under the local/ path in the DBI will be accessable through the vortex using the URL syntax
http://vortex/?vortex_callertype=getlocal&vortex_localfilename=[filename]
where filename is the full path under the public/ folder for the file to be fetched.
By copying the files from the Vortex css/ path into the DBI public/css/ path you can make DBI-local changes to the CSS files. By having icon files in the DBI path public/gfx/icons/ with the same names as the icons in the Vortex gfx/icons/ path, the local DBI icons will be used instead.