Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+====== Configuration of the Vortex ======
+The Vortex is configured using a couple of XML configuration files as follows:
+  * [[#main_vortex_config|/config/xml/config.vortex.xml]]
+  * [[#vortex_sql_config|/config/xml/sql.DBType.xml]]
+  * [[#vortex_language_config|/lang/Language.xml]]
+The Database Instances also keep a couple of configuration files:
+  * [[#dbi_config|/config/config.xml]]
+  * [[#dbi_import_scripts|/config/import/]]
+  * [[#dbi_webservice_config|/webservices/Webservice/config.xml]]
+The specifics of the diffent files follow.
+==== Main Vortex Config ====
+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.
+=== Element descriptions ===
+^Tagname^Attribute^Description^
+|locale|file|Sets the default language to load for this Vortex. See [[#vortex_language_config|Language config]] for more information about language files.
+|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|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|
+=== Sample config file ===
+<code xml>
+<?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>
+</code>
+==== Vortex SQL Config ====
+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:
+  * MySQL
+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:
+<code xml>
+<command_name [noescape="[true/false]"]>[SQL COMMAND]</command_name>
+</code>
+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//:
+<code>
+SELECT * FROM myTable WHERE id=%d OR name='%s'
+</code>
+These type of SQL Commands are referenced in the code with the same type of syntax:
+<code php>
+$res = Vortex::$dbh->query( "sql.mycommand", $id, $name );
+</code>
+Another option, which is preferred, is the //Vortex syntax// for variable substitution:
+<code>
+SELECT * FROM myTable WHERE id=%[id]% OR name='%[name]%'
+</code>
+These type of SQL Commands are referenced in the code with the following syntax:
+<code php>
+$attribs = array( "id"=>$id, "name"=>$name );
+$res = Vortex::$dbh->query( "sql.mycommand", $attribs );
+</code>
+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.
+==== Vortex Language Config ====
+==== DBI Config ====
+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.
+=== Database connectivity configuration ===
+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|
+=== DBI Description configuration ===
+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|
+=== Default user configuration ===
+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.
+<code xml>
+   ...
+   <defaultuser>
+      <valid_from_time>{date}</valid_from_time>
+      <valid_to_time>{date.Y+1}</valid_to_time>
+      <group>UsersGroup</group>
+      <group>MyGroup</group>
+   </defaultuser>
+   ...
+</code>
+Attribute values are parsed as [[vortex:scripting:vxstring|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.
+=== Logger configuration ===
+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.
+=== Menu configuration ===
+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.
+== menuitem ==
+The //menuitem// describes a sub menu structure. The //menuitem// can contain other menuitem(s), table(s), spacer(s) and/or script(s).
+<code xml>
+  <menuitem name="My SubMenu" default="open">
+    <table name="myTable" />
+  </menuitem>
+</code>
+^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|
+== table ==
+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.|
+== spacer ==
+The //spacer// shows an empty row in the menu, for layout purposes only. It has no attributes or sub elements.
+== script ==
+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|
+== Enabling the user to edit My Profile ==
+In order to let the current user edit details regarding his/her own profile the //My Profile// script can be added to the menu.
+<code xml>
+  <script name="My Profile" class="User" method="myProfile" requiregroup="users" param_1="password" />
+</code>
+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.
+=== Showlist configuration ===
+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 .
+<code xml>
+    <showlist>
+        <displayrows>100</displayrows>
+    </showlist>
+</code>
+=== Webservices configuration ===
+See [[vortex:scripting:webservices|Webservices]]
+=== Custom SQL Scripts ===
+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:
+<code xml>
+...
+<sql>
+    <file filename="my_custom_sql.sql" nodename="custom" />
+    <file filename="my_other.sql" nodename="other" />
+</sql>
+...
+</code>
+Theese queries can be addressed from the Vortex like:
+<code php>
+  $res = Vortex::$dbh->query( "sql.custom.mysqltagname" );
+  $res2 = Vortex::$dbh->query( "sql.other.mysqltagname" );
+</code>
+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
+<code>
+my_custom_sql.mysql.sql
+my_other.mysql.sql
+</code>
+==== DBI Import Scripts ====
+See [[vortex:usermanual#Import_data|The User Manual]]
+==== DBI Webservice Config ====
+==== Customizing the looks of the Vortex ====
+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
+<code>
+http://vortex/?vortex_callertype=getlocal&vortex_localfilename=[filename]
+</code>
+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.

Stilit Wiki

User Tools

Site Tools

Differences

Page Tools