-- PedroRio - 30 Jan 2011

boConfig - XEO Application Configuration

The boConfig.xml file (located at the root of every XEO Application) is the basic configuration file in a XEO Application.

The boConfig.xml file has a root element boConfig and then several child elements, each of them responsible for the configuration of different parts of the XEO Application.

Definition Directory

Path to the directory where the XEO Packages (containing the XEO Models) are located (by default "bodef")

Example:

<definitiondir>.\bodef\</definitiondir>

Profiles Definition Directory

Path to the directory where workplaces and profile definition files are located (by default "uidef\default")

Example:

<uidefinitiondir>.\uidef\default</uidefinitiondir>

Web Context Root

The web context root of the application (it must also be configured in your Application Server as well, this value does not deploy the application in that address) - by default "/xeo".

Example:

<webcontextroot>/xeo</webcontextroot>

Encoding

The encoding of the application - default is "UTF-8"

Example:

<encoding>UTF-8</encoding>

Deployment - Configurations of the XEO Builder

The deployment section configures the XEO Builder, it has several subconfigurations:

• Class Directory - Where to put the compiled generated classes by the Builder
• Source Directory - Where to put the source code for the generated classes by the builder
• Object Model Directory - Where to put the XEO Models so that they are acessible by the application
• Java Compiler - Path to the Java compiler (JDK 1.6)
• Model Templates - TODO
• JSP Deploy Directory - Where to put the JSP's generated from viewer definition inside Object Models
• Web Modules Directory - Where to find the web applications from the XEO Core and Modules
• Library Directory - Where to find Java Libraries required by the project
• Tablespace - The database tablespace (Oracle), in MySQL, use the database name

Example of a configuration:

<deployment>
        <class_dir>.\.build\classes\</class_dir>
        <src_dir>.\.build\src\</src_dir>
        <obj_dir>.\.build\bodef-deployment</obj_dir>
        <obj_compiler>C:/jdk1.6.0_14/bin/javac.exe</obj_compiler>
        <obj_templates>.\.templates</obj_templates>
        <obj_deployjspdir>.\.build\webresources\default\</obj_deployjspdir>
        <obj_moduleswebdir>.\base_lib\modules_web\</obj_moduleswebdir>
        <lib_dir>.\lib\</lib_dir>
        <tablespace>USERS</tablespace>
    </deployment>

_

Threads - Background work configurations

This section allows to define the background workers (threads) available in the XEO Application (by default, only the FullText Indexer (Ebo_TextIndex) is active)

To know more about Background work, check the Threads and Schedules section.

Notes:

JBoss = type='ejbTimers'

OC4J = type='userThreads'

Example:

<threads type="userThreads">
        <thread interval="15000" ejb-name="ejb/boTextIndexAgent" name="boTextIndex Agent"/>
</threads>

_

DataSources - Configurations about the datasources used

The datasources section, defines the implementation classes that are used in order to access the relational database.

Example (for Oracle connection):

<DataSources>
        <DataSource boql="true" name="DATA">
            <Driver>netgest.bo.data.oracle.OracleDriver</Driver>
            <DML>jdbc/xeo</DML>
            <DDL>jdbc/xeo_nojta</DDL>
        </DataSource>
        <DataSource boql="true" name="SYS">
            <Driver>netgest.bo.data.oracle.OracleDriver</Driver>
            <DML>jdbc/xeo_nojta</DML>
            <DDL>jdbc/xeo_nojta</DDL>
        </DataSource>
    </DataSources>

At the moment there are three driver implementations (MySQL, Oracle and SQL Server). XEO Studio will generate the approriate boConfig when you configure the database connection but the three driver implementations are as follows:

• netgest.bo.data.mysql.MysqlDriver (MySQL)
• netgest.bo.data.oracle.OracleDriver (Oracle)
• netgest.bo.data.sqlserver.SqlServerDriver (MS SQL Server)

_

Log Configuration

Configures the Logger for the XEO Application ( read more)

Mail Configuration

Configures the mail server to allow the XEO application to send mails. The mail configuration can include any number of properties (which you can access using XEO's API). The basic configuration is the following (the smpthost property is required to exists, although the values does not need to have a valid smtp server)

<mail>
       <smtphost>smtp.host.domain</smtphost>
</mail>

If you have your own mail sending mechanism you can also use boConfig just to keep your configuration values. The boConfig.xml file is read and made available by a wrapper class (netgest.bo.system.boApplicationConfig) which can be accessed through class boApplication. The boApplicationConfig class has a method getMailConfig which returns a Properties instance. By default the only property will be "smtphost" but if you in the boconfig file you include additional elements, those elements will be transformed to properties, as follows:

<mail>
        <smtphost>smtp.host.domain</smtphost>
        <defaultuser>SUPERUSER</defaultuser>
        <serverPort>338</serverPort>
         <myVeryCustomConfiguration></myVeryCustomConfiguration>
</mail>

If you used this configuration, when retrieving the Properties from the getMailConfig method you would have four properties (smtphost, defaultuser, serverPort and myVeryCustomConfiguration).

Skins / Themes (optional)

You can include several CSS files to customize the theme of your XEO Application. There are several themes included with XEO, namely blue, gray, slate, green, olive, pink, purple. The default boConfig.xml file includes the following:

<themes>  
        <theme name='blue' description='Default Blue Theme' default='true'>  
        </theme>  
        <theme name='gray' description='Gray Theme'>  
            <files>  
                <file path='extjs/resources/css/xtheme-gray.css' description='Gray Theme' id='css_gray'></file>  
            </files>  
        </theme>  
        <theme name='slate' description='Slate Theme' >  
            <files>  
                <file path='extjs/resources/css/xtheme-slate.css' description='Slate Theme' id='css_slate'></file>  
            </files>  
        </theme>  
        <theme name='green' description='Green Theme'>  
            <files>  
                <file path='themes/css/xtheme-green.css' description='Green Theme' id='css_green'></file>  
            </files>  
        </theme>  
        <theme name='olive' description='Olive Theme'>  
            <files>  
                <file path='themes/css/xtheme-olive.css' description='Olive Theme' id='css_olive'></file>  
            </files>  
        </theme>  
        <theme name='pink' description='Pink Theme'>  
            <files>  
                <file path='themes/css/xtheme-pink.css' description='Pink Theme' id='css_pink'></file>  
            </files>  
        </theme>  
        <theme name='purple' description='Purple Theme'>  
            <files>  
                <file path='themes/css/xtheme-purple.css' description='Purple Theme' id='css_purple'></file>  
            </files>  
        </theme>  
    </themes>  

To add a new theme to the Application you can use the Administration Interface to create a new Theme, or add a new theme in the boconfig.xml file and issue a build command to let the builder create the new theme. Each theme is identified by a name and a description and a set of files. Each file must have a unique identifier, if you need three files included for a given theme, do the following:

<theme name='multiple' description='Theme'>  
            <files>  
                <file path='themes/css/file1.css' description='File1' id='css_1'></file>  


                <file path='themes/css/file2.css' description='File2' id='css_2'></file>  

            </files>  
        </theme>  

Note: Changing a configuration for a Theme after it's been created by the builder will have no effect. If you want to change the Theme settings you'll have to use the Administration Interface. Main_admin.xvw -> Administration -> Themes. Open the default theme, uncheck the "default" field, save and open the theme you want check the "default" field and save.

Also, it's possible for each user to select its own theme (independently of the application theme). It's done either by editing the user or by changing the user properties (accessible from the Tree Menu)

ECM Repositories (optional)

Not yet available in XEO

Enterprise Content Management (ECM) Repositories allow you to store documents, which can be used whithin a XEO Application (just like regular files). XEO supports Repositories which are compatible with the JCR 1.0 specification. You can configure several JCR repositories to be available in a XEO Application; to configure a single repository you use the following properties:

Repository Properties

Property Name	Type	Description	XML declaration	Notes
name	String	The repository identifier	name='JackRabbitXEO'
default	boolean	Whether this is the default repository or not	default = 'true'	If a repository is not specified when saving/reading, etc... the default repository is used
classConnection	String	The fully qualified name of a class that implemets the netgest.io.jcr.ECMRepositoryConnection interface which is responsible for creating a JCR Session with the repository	classConnection='netgest.io.jcr.JackRabbitXEO'
showAllProperties	boolean	Whether the visual layer should try to display all properties of files/folders or only the ones declared in the File/Folder/Metadata nodes (see bellow)	showAllProperties='false'
repositoryConnection	XML element	Parameters to be passed to the connection class (see classConnection property) this is done automatically when instatianting the class.	<repositoryConnection> <parameters> <parameter name='foo' value='bar'> <parameter name='bar' value='foo'> </parameters> </repositoryConnection>

System Properties

The system properties configuration allows you to declare which (if any) properties in JCR nodes are system specific and you don't to display them when using the visual components. You declare the system properties as follows (the example includes a real configuration for the JackRabbit repository):

<system>
       <!-- System Properties that we don't want to display in forms and etc.. -->
       <properties>
           <property name='jcr:createdBy'></property>
           <property name='jcr:uuid'></property>
           <property name='jcr:primaryType'></property>
       </properties>
</system>

_

File Node Configuration

The file node configuration allows you to specify the nodes that will represent files (for the XEO Application) in the repository. You can specify:

• Type of node
• The node property which represents the binary data
• The node property which represents the creation date
• The node property which represents the update
• The node property which represents the mimetype

Properties

You should configure the properties you want to have (or the ones the existing nodes already have) so that the implementation can correctly read/update the properties. The properties can be spread in the main node or child nodes.

Child Nodes

A File Node can have child nodes and have its properties stored in those file nodes (depending on the reposito

A sample XML configuration for the File Node when trying to use a default JackRabbit instalation

<fileNode
   type="nt:file" 
   binaryProperty="jcr:data"
   createDate="jcr:created"
   updateDate='jcr:lastModified'
   mimeType="jcr:mimeType">
   <properties>
      <property label='Create Date' name="jcr:created" type='attributeDate' mainNode='true'/>
      <property label='File' name='jcr:data' type='binary'></property>
      <property label='Encoding' name="jcr:encoding" type='attributeText' />
      <property label='MimeType' name='jcr:mimeType' type='attributeText'></property>
      <property label='Date Update' name='jcr:lastModified' type='attributeDate'></property>
   </properties>
   <childNodes>
     <childNode name="jcr:content" type="nt:resource">
          <properties>
               <property label='MimeType' name="jcr:mimeType" type="string"></property>
               <property label='Encoding' name="jcr:encoding" type="string"></property>
               <property label='File' name="jcr:data" type="binary"></property>
               <property label='Date Update' name="jcr:lastModified" type="date"></property>
          </properties>
      <childNode />
    </childNodes>
</fileNode>

And another when using a repository that has the nodes declared by default by the XEO framework

<fileNode
    type="xeo:file" 
    binaryProperty="xeo:data"
    createDate=""
    updateDate=""
    mimeType="">
                 
    <properties>
       <property label='File' name='xeo:data' type='binary' mainNode='true'></property>
    </properties>
                 
    <childNodes>
    </childNodes> 
</fileNode>

_

Folder Node Configuration

The file node configuration allows you to specify the nodes that will represent folders (for the XEO Application) in the repository. You can specify:

• Type of node
• The node property which represents the creation date
• The node property which represents the update date
• The type of child nodes

Like with FileNodes you should also declare the properties and the child nodes of a folder node. A sample XML configuration to use a default JackRabbit folder node in a XEO Application:

<folderNode type="nt:folder"  
     createDate="jcr:created" 
     updateDate=""
     childFilesType='nt:hierarchyNode'>
  <properties>
     <property label='Create Date' name="jcr:created" type='date' mainNode='true'/>
  </properties>
  <childNodes />
</folderNode>

And a configuration to XEO default folder nodes:

<folderNode type="xeo:folder"  
   createDate="" 
   updateDate=""
   childFilesType='xeo:hierarchyNode'>
                
   <properties />
   <childNodes />
</folderNode>

Metadata Node Properties

You can also declare several different types of metadata nodes which can be associated to File and Folder Nodes. When declaring a metadata node you can define the following:

• Type of the node
• The name of the metadata node
• If nodes of this type can be created
• If this type is the default node
• Query to reach metadata nodes (if metadata nodes are within some path, this tells the implementation where to find and save metadata nodes (other than the root of course)
• List of properties of the metadata node
• Child nodes that the metadata node can have

A sample XML configuration bellow (for XEO's default metadata nodes, JackRabbit by default does not provide such a node type):

<metadataNodes>
     <metadataNode type="xeo:metadata" name="metadata" canCreate="true" default="true">
        <queryToReach>metadata/categories</queryToReach>
        <parent></parent>
        <properties />
        <children />
    </metadataNode>
</metadataNodes>

_

Sample XML (for a complete configuration of one repository):

<?xml version="1.0" encoding="UTF-8"?>
<ecmRepositories>
    <ecmRepository name='JackRabbitXEO' default='true' fileConnector='netgest.io.jcr.FileConnector'
        classConnection='netgest.io.jcr.JackRabbitXEOConnection' showAllProperties='false'>
        <repositoryConnection>
            <parameters>
                <parameter name='exampleParameter' value='bar'></parameter>
            </parameters>
        </repositoryConnection>
        <system>
            <!-- System Properties that we don't want to display in forms and etc.. -->
            <properties>
                <property name='jcr:createdBy'></property>
                <property name='jcr:uuid'></property>
                <property name='jcr:primaryType'></property>
            </properties>
        </system>
        <fileNode
            type="xeo:file" 
            binaryProperty="xeo:data"
            createDate=""
            updateDate=""
            mimeType="">
            <properties>
                <property label='File' name='xeo:data' type='binary' mainNode='true'></property>
            </properties>
            <childNodes>
            </childNodes> 
        </fileNode>
        <folderNode type="xeo:folder"  
            createDate="" 
            updateDate=""
            childFilesType='xeo:hierarchyNode'>
            <properties>
            </properties>
            <childNodes />
        </folderNode>
        <metadataNodes>
            <metadataNode type="xeo:metadata" name="metadata" canCreate="true" default="true">
                <queryToReach>metadata/categories</queryToReach>
                <parent></parent>
                <properties>
                </properties>
                <children></children>
            </metadataNode>
        </metadataNodes>
    </ecmRepository>
</ecmRepositories>

_

Repositories

Repositories are used to represent data sources for the XEO application and are configured as following:

<Repositories>
        <Repository>
            <Name>default</Name>
            <UserName></UserName>
            <Password></Password>
            <DataSource>DATA</DataSource>
            <DataSourceDef>DATA</DataSourceDef>
            <Schema>_DATABASE_NAME_OR_SCHEMA</Schema>
            <Parent></Parent>
        </Repository>
    </Repositories>

The DATABASE_NAME_OR_SCHEMA value should be replaced with the name of the database (MySQL, SQLServer) used by the application, or the schema name (Oracle). Also, it's the only value you need to change.

Languages (@deprecated, see Localization)

The languages allows you to define the default language for the XEO Application and set the available languages for the application.

<languages>  
 <ApplicationLanguage>PT</ApplicationLanguage>
    <availableLanguages>
       <language>
         <code>EN</code>
         <description>English</description>
       </language> 
      <language>
         <code>PT</code>
         <description>Português</description>
      </language>
    </availableLanguages>
</languages>

RenderKits

Starting with version 3.2 there's a new concept, which is called the renderKit. Whenever a request is made to the application, that request is rendered in a particular renderKit. Components have a registered renderer in a given renderKit and so, according to the renderKit the renderer will be chosen accordingly. There are two main renderKits in XEO: the XEOHTML and XEOJQUERY renderKits. Not all components have renderers in both renderKits and not everything works the same in both renderKits, remember this.

The default renderKit in a XEO Application is the XEOHTML renderer.

The important setting here is that with each renderKit comes associated a class. An Implementation of the XUITheme interface, which has the following methods:

/**
     * The base url for resources
     * 
     * @return
     */
    public String getResourceBaseUri();
    /**
     * Add CSS resources to the page
     * 
     * @param styleContext
     */
    public void addStyle( XUIStyleContext styleContext );
    /**
     * Add Javascript resources to the page
     * 
     * @param scriptContext
     */
    public void addScripts( XUIScriptContext scriptContext );
    /**
     * 
     * Html style to apply to the <code>body</code> tag
     * 
     * @return
     */
    public String getBodyStyle();
    /**
     * 
     * Html style to apply to the <code>html</code> tag
     * 
     * @return
     */
    public String getHtmlStyle();
    /**
     * 
     * The page DOCTYPE (full string including the DOCTYPE)
     * 
     * @return The string with the DOCTYPE 
     */
    public String getDocType();
    
    /**
     * 
     * Allows to write to the header of the page (metatags, etc...)
     * 
     * @param writer
     * @throws IOException
     */
    public void writeHeader(XUIResponseWriter writer) throws IOException;
    /**
     * 
     * Write content right after opening the body tag
     * 
     * @param context
     * @param writer
     * @param viewRoot
     * @throws IOException
     */
    public void writePostBodyContent(XUIRequestContext context, XUIResponseWriter writer,
          XUIViewRoot viewRoot) throws IOException ;
    
    /**
     * 
     * Write content right before closing the body tag
     * 
     * @param context
     * @param writer
     * @param viewRoot
     * @throws IOException
     */
    public void writePreFooterContent(XUIRequestContext context, XUIResponseWriter writer,
          XUIViewRoot viewRoot) throws IOExcepti
on ;

You have two default implementations (one for the XEOHTML renderkit and another for the XEOJQUERY renderKit, which you can (and should) extend as a base for your implementations, because they include some of the required scripts and CSS files)

• netgest.bo.xwc.components.classic.theme.ExtJSTheme
• netgest.bo.xwc.components.classic.theme.JQueryTheme
  

How do I configure a renderKit?

 <renderKits default='XEOHTML'>
       <renderKit id='XEOJQUERY' themeClass='netgest.bo.xwc.components.classic.theme.JQueryTheme'></renderKit>
  </renderKits
>

The default property tells the application which renderKit is the default for every request (unless overriden in the XWC Servlet). Each <renderKit> element has an ID attribute and a themeClass attribute. The ID must be one of XEOHTML or XEOJQUERY but the theme class can be your own implementation of XUITheme as stated earlier.

Localization

Beginning with version 3.2.014, XEO now fully supports users in differente Locales. Meaning that each user can have its own definitions of things like the currency symbol, the date format, etc... The Application can also configure a system-wide default in the boconfig.xml file. For each user to define their own settings they must go to a Main viewer to the "User Properties" option on the TreePanel toolbar.

How do I configure?

<localization>

<decimalSeparator>,</decimalSeparator>

<groupSeparator>.</groupSeparator>

<currencySymbol>€</currencySymbol>

<currencyPosition>right</currencyPosition>

<dateFormat>dd/MM/yyyy</dateFormat>

<timeFormat>HH:mm</timeFormat>

<locale>pt_PT</locale>

<timezone>Europe/Lisbon</timezone>

<dateTimeSeparator> </dateTimeSeparator>

<availableLocales>

<locale>pt_PT</locale>

<locale>en_US</locale>

<locale>es_ES</locale>

</availableLocales>

</localization>

Attribute	Default Value	Notes
decimalSeparator	,	A single character for the decimal separator
groupSeparator	.	A single character for the group separator
currencySymbol	€	The currency symbol
currencyPosition	right	The position of the currency symbol (left/right)
dateFormat	dd/MM/yyyy	A valid java.text.SimpleDateFormat with day, month and year
timeFormat	HH:mm	A valid java.text.SimpleDateFormat with hour and minute (no seconds)
locale	pt_PT	A valid java.util.Locale pattern (pt, pt_PT)
availableLocales	pt_PT, en_US, es_ES	The list of available Localizations (XEO has three defaults Portugues, English and Spanish)
timezone	TimeZone.getDefault()	A valid java.util.Timezone ID
dateTimeSeparator	space	One character (space, dot, etc...)

browser

@Deprecated

Word Templates

@Deprecated

Win 32 Client

@Deprecated

Modules

When some modules are installed in a XEO Application, additional properties can be configured in boConfig: namely:

Content Manager

In order to configure the Content Management you'll need to define the XEO Models that used as Content and the XEO Models that are used as Images, like the following:

<Content_Manager>
        <Contents_Type>XEOCM_Contents;XEOAG_Contents;XEOCM_Noticias;XEOCM_Contents_Link;XEOCM_Document;XEOCM_Map</Contents_Type>
        <Images_Type>XEOCM_Image</Images_Type>
</Content_Manager>

_