Installation

The first step is to ensure that you already have a working installation of web server (usually Apache), database server (usually MySQL, PostgreSQL, Oracle or SQL Server), and PHP. Ensure that your PHP installation includes the right optional extensions, as documented in Radicore for PHP.

Then and only then will you be able to download and install this software. Here are the steps you should take after obtaining a copy of the RADICORE zip file:

  1. Unzip the file into whatever folder has been designated as [DOCUMENT_ROOT], but remember to retain the directory structure. You should end up with something like this:
    [DOCUMENT_ROOT]
      - radicore
        - audit
        - classroom
        - css
        - default
        - dict
        - images
        - includes
        - logs
        - menu
        - product
        - survey
        - workflow
        - xample
        - xsl
    

    The structure and usage of the directories in described here.

    You may change the name of the parent "radicore" directory if you wish, but do not change any other directory names. You may even move the parent directory to a subdirectory which is below [DOCUMENT_ROOT].

    You may wish to leave the INCLUDES directory where it is, or you may wish to move it to a place which is outside the web root if you are going to deploy this on a publicly-accessible web server. Whatever you decide to do you must amend the "include_path" directive in the HTACCESS.TXT file appropriately (see item 3 below).

  2. The file HTACCESS.TXT contains some Apache directives. This can be renamed to .htaccess in a *nix environment, or for Windows you can insert the following lines into your httpd.conf (Apache configuration) file:
    #AccessFileName .htaccess
    AccessFileName htaccess.txt
    #
    # The following lines prevent .htaccess and .htpasswd 
    # files from being viewed by Web clients. 
    #
    #<Files ~ "^\.ht">
    <Files ~ "^htaccess\.">
        Order allow,deny
        Deny from all
    </Files>
    
    Note that the contents of .htaccess will be ignored by Apache unless the correct AllowOverride option has been set in your HTTPD.CONF file as follows:
    <Directory "F:/Apache2/htdocs">
    #
    # AllowOverride controls what directives may be placed in 
    # .htaccess files.
    # It can be "All", "None", or any combination of the keywords:
    #   Options FileInfo AuthConfig Limit
    #
        AllowOverride All
    #
    # Controls who can get stuff from this server.
    #
        Order allow,deny
        Allow from all
    </Directory>
    
    For Apache version 2.4 the syntax has changed to:
    AccessFileName htaccess.txt
    <Files "htaccess.txt">
        Require all denied
    </Files>
    
    and
    <Directory "F:/Apache2/htdocs">
        AllowOverride All
        Require all granted
    </Directory>
    
  3. The HTACCESS.TXT file contains an "include_path" directive which is used by PHP when searching for files which are specified on an include() or require() statement. This directive must be modified to reflect the physical location of the following directories:
    • radicore/includes (you may move this to a point outside the web root)

    Note that the contents of the include_path string varies between Windows and *nix systems:

    • Windows uses ';' (semi-colon) and '\' (backslash).
    • *nix uses ':' (colon) and '/' (forward slash).

    The include_path is also amended automatically at runtime to point to various subdirectories used by the framework, such as "menu", "audit" and "workflow".

  4. You will need to change permissions so that the following directories have write access:
    • RADICORE - for the errorlog.html file.
    • CLASSES - for all <table>.class.inc and <table>.dict.inc files.
    • ERROR_LOGS - for errorlog.html file.
    • LOGS - for all output from background tasks.
    • SQL - for all <subsystem>.dict_export.sql and <subsystem>.menu_export.sql files.
    • TEXT - for all <subsystem>.menu_export.txt files.
    • XSL - for all <script_id>.xml files.
  5. Using your favourite database administration tool you need to:
    • Create each database/schema manually (menu, dict, audit, workflow, classroom, product, survey, xample).
    • Create the tables in those databases/schemas from the ???-schema.sql scripts.
    • Load the data from the ???-data.sql scripts. Note that there is no data to be pre-loaded into the AUDIT database.

    These scripts exist in the various radicore/???/sql/mysql/ subdirectories.

    1. The 'menu' database can be loaded from file radicore/menu/sql/<db>/menu-data.sql which contains the data for all subsystems (except the prototype applications), or single subsystems can be loaded individually from the <subsystem>.menu_export.sql files which exist in the radicore/<subsystem>/sql/ directories. These files were created using the Menu Subsystem -> Subsystem -> Export function.
    2. User details must be loaded separately from file radicore/menu/sql/<db>/mnu-user.sql. This should be loaded only once, unlike the other *sql files which can be loaded as many times as you like.
    3. The 'dict' database can be loaded from file radicore/dict/sql/<db>/dict-data.sql which contains the data for all databases (except the prototype applications), or single databases can be loaded individually from the <subsystem>.dict_export.sql files which exist in the radicore/<subsystem>/sql/ directories. These files were created using the Dictionary -> Database -> Export function.
    4. The prototype applications which are included in the download (CLASSROOM, PRODUCT, SURVEY and XAMPLE) are contained within files <subsystem>-prototype.zip, and must be unzipped before they can be used. The contents of files <subsystem>/sql/<subsystem>.dict_export.sql and <subsystem>/sql/<subsystem>.menu_export.sql will also need to be loaded into the DICT and MENU databases respectively.

    Note that each <subsystem>-schema.sql script will create tables in a separate database (or 'schema' in PostgreSQL and Oracle) whose name is identified at the start of each script. You MUST select the right database/schema before running these scripts otherwise the software will not be able to access any tables.

    1. Notes for MySQL users:
      • The tables used by each subsystem must be created in separate databases, as shown in the various <subsystem>-schema.sql scripts. It is not possible to create all the tables in a single database. After connecting to the MySQL server the application will use the mysql_select_db() function to identify the current database.
      • MySQL is case-insensitive by default, but some non-Windows operating systems can reverse this behaviour. In order to avoid any potential problems you should therefore ensure that the lower_case_table_names variable is set to 1. Please refer to Identifier Case Sensitivity for details.
      • In order to allow the use of database names with '-' (hyphen) instead of '_' (underscore) you must use the configuration option sql_mode='ANSI_QUOTES' so that database names can be enclosed in double quotes (the SQL standard) as well as backticks (specific to MySQL). Please refer to Selecting SQL Modes for details. If your version of MySQL is before 4.1 then you must go info MySQL Administrator->Startup Variables->Advanced and ensure that Use ANSI SQL is checked ON. If your version of MySQL is 4.1 or later this option will be set programmatically.
      • Although with MySQL it is possible to use a mix of different collations (character encoding) on different columns, this is not a good idea in practice as it requires more complex SQL statements when comparing columns with different collations. It is therefore best to use the same character set for all columns, with UTF-8 being the most flexible.
    2. Notes for PostgreSQL users:
      • Refer to Creating a PostgreSQL Driver to see the differences encountered when using that DBMS.
      • The database name to be used in the 'connect' function is specified in the $PGSQL_dbname variable in the CONFIG.INC file. The suggested database name is 'radicore', but you can change this if you wish.
      • Each MySQL 'database' must be created as a separate PostgreSQL 'schema' within the specified PostgreSQL database. Do NOT create all tables in the PUBLIC schema. After connecting to this database the application uses the
        SET search_path TO "<schema>"
        directive to identify the current schema.
      • All the ???_export.sql scripts were exported from a MySQL database, so will need to be modified before being imported a PostgreSQL database:
        • Replace all 'REPLACE INTO ' with 'INSERT INTO '.
        • Replace all '`' (backticks) with '' (null).
      • In the dict/sql/postgresql/mysqlcompat-vvv directory (where 'vvv' is the version number) is a series of scripts containing collections of functions, aggregates, operators and casts that make PostgreSQL mimic MySQL as closely as possible. Look at the README file for installation instructions.
    3. Notes for Oracle users:
      • Refer to Creating an Oracle Driver to see the differences encountered when using that DBMS.
      • The connection string should be specified in the $dbhost variable in the CONFIG.INC file in the format //host_name/service_name. If you are using a multitentant version which provides a service for a container as well as a pluggable database you should use the pluggable database in order to avoid the error:
        ORA-65096: invalid common user or role name
        when creating users or schemas.
      • Each MySQL 'database' must be created as a separate Oracle 'schema' (user) within the specified Oracle database. After connecting to this database the application uses the
        ALTER SESSION SET CURRENT_SCHEMA = "<schema>"
        directive to identify the current schema.
      • All the ???_export.sql scripts were exported from a MySQL database, so will need to be modified before being imported an Oracle database:
        • Replace all 'REPLACE INTO ' with 'INSERT INTO '.
        • Replace all '`' (backticks) with '' (null).
  6. (moved to 5.A)
  7. (moved to 5.B)
  8. (moved to 5.C)
  9. The contents of the Dictionary and therefore the <tablename>.dict.inc files were created from a MySQL database and consequently use MySQL data types, sizes and value ranges. For example, with the standard SMALLINT (INT2) type the range is -32768 to 32767, but MySQL has an unsigned version where the range is 0 to 65535. Although the application will run on any database using these ranges you may encounter problems should a value passed by the application be rejected by the database, so you may wish to rebuild these files and adjust the ranges with the following steps:
  10. The only file you need to amend should be CONFIG.INC (in the INCLUDES directory) to specify the username and password for your database. You can rename CONFIG.INC.DEFAULT to CONFIG.INC to provide a starting version.

    You will also need to amend the ERROR_LOG_MAILTO constant to identify the email address(es) to which any error logs will be sent.

    If you are using MySQL on a shared server you may need to set $GLOBALS['dbprefix'] to your account name. If your databases do not have a prefix then this should be set to null.

    If you wish to use the HTTPS protocol with a secure server then please read FAQ 58.

    If you wish to access different databases on different servers then please read FAQ 92.

    If you wish to merge all the databases into a single database then please read FAQ 150.

  11. Each subsystem may contain a file called include.subsystem.inc which can be used to make global environmental changes during the processing of scripts within that subsystem. Please refer to FAQ 86 for details.
  12. To run the application please point your browser to http://localhost/radicore/index.html and use one of the 'logon' hyperlinks. When the logon screen appears you can use the following:

    User = MGR
    Pswd = password (case sensitive)
    
    You can then explore every part of the system. This may be a good opportunity to create your own user id and password.

NOTE: this code will work for both PHP 4 and PHP 5, and (if using a MySQL database) automatically detect if you have loaded the old 'mysql' extension or the new and improved 'mysqli' extension.

As well as the RBAC system, the Menu system, the Audit Logging system, Workflow system, Data Dictionary, Internationalisation facilities and the code for the Transaction Patterns, this software package also includes a few prototype applications.

The DEFAULT directory contains the directory structure which is used by the Build Directory function, and sample scripts which are used by the Generate PHP scripts function.

By default all XSL transformations are performed by the server, but if you have a web browser that supports XSLT then you can switch to client-side XSL transformations by adding "csxslt=on" to the URL. This will stay on until is is turned off with "csxslt=off".

Enjoy!