Documentation

Web Programming

Using The Data Dictionary

Your Andromeda Web programming will really begin to take off once you begin using the data dictionary. All Andromeda applications begin with a very thorough and powerful data dictionary. This dictionary is not just for the database, it is also good for generating HTML.

When we are defining a database for an application, we edit a plaintext file in YAML format. This format would be of little use while coding PHP, so Andromeda packages it up into associative arrays that you can load and use in your PHP code.

<?php
class x6example extends androX6 {
    function x6main() {
        # Andromeda contains a built-in table called
        # 'configfw'.  We can load the data dictionary
        # for this table with this command:
        $dd = ddTable('configfw');
        
        # Now lets dump the array out.
        echo "
";
        hprint_r($dd);
        echo "
";
    }
}
?>

When you need to know about a table, you call the ddTable({tablename}) function, and it returns an associative array that completely describes the table, including all columns, primary keys, and many other features.

Repeated calls to ddTable() for the same table are harmless, except for the negligible performance penalty that is required for Andromeda to reload the dictionary.

Simple Dictionary Uses

This example shows how to load the dictionary and then run out a list of the columns in the table.

<?php
class x6example extends androX6 {
    function x6main() {
        # Another built-in table is the 'groups' table,
        # which describes the application group definitions.
        $dd = ddTable('groups');
        
        # For the HTML we will now loop through the
        # "flat" array of the dictionary, which holds 
        # the column definitions.
        $top = html('div');
        
        # Make the Title from the table description
        $top->h('h1','All about '.$dd['description']);
        
        # Now the loop
        $ul = $top->h('ul');
        foreach($dd['flat'] as $colname=>$colinfo) {
            $ul->h('li',"$colname: {$colinfo['description']}");
        }
        
        $top->render();
    }
}
?>

Basic Table Properties

Using the data dictionary, you can find out the following facts about a table:

• description: Standard description of table
• singular: the singular form of the description. If no value is provided in the dd.yaml file, the Andromeda looks for an 's' at the end of the description and removes it. Usually you assign this value when that does not work, so if you have a table named "STORIES", you would want to specify "STORY" in the data dictionary.
• module: The module the table is in.
• nomenu: If "Y", this table does not usually appear on the menu
• viewname: If there is no row or column level security on the table, this will be the table name. If there is row or column level security, this will hold the view name that the currently logged in user must go through instead.
• permrow: Will be "Y" if there is row-level security on this table. permcol: Will be "Y" if there is column-level security on this table.
• pks: A comma-separated list of the primary key columns of the table, in the order they were defined.

Table Projections

There are three more bits of information you can get about a table. You can find out about the table's parents, children, and projections.

The array $dd['projections'] is an associative array. The index key names the projection, and the values are comma-separated lists of columns in each projection. Every table has these projections:

• _primary_key: The list of primary key columns, holds the same values as $dd['pks'].
• _uisearch: The list of columns for which uisearch is set to "Y".
• _uino: Columns the user should not see. These include some Andromeda-created columns and any columns that have uino equal to "Y" in the dd.yaml file.

Parent And Child Tables

The data dictionary for a table has two more arrays, named $dd['fk_children'] and $dd['fk_parents']. Each of these is an associative array where the key is the name of the parent/child table and the value is another associative array. The nested array contains all of the basic properties of the parent/child table listed in the above section such as description, singular, pks, etc. The array also has these additional entries:

• cols_chd: Comma-separated list of columns in the child table that make up the foreign key.
• cols_par: Comma-separated list of columns in the parent table that make up the primary key.
• cols_both: Comma-separated list of column pairs that match the parent to child table. The pairs themselves are colon-separated, and always list the child table column first followed by the parent table column.

Basic Column Properties

Column properties are stored in $dd['flat'], where each entry's key names the column and each entry's value is a child array of column properties. The properties of a column are listed below. For more information on these properties, please refer to documentation on the Data Dictionary.

• table_id
• column_id
• type_id char
• colprec
• colscale
• description
• descshort
• tooltip
• primary_key
• range_from
• range_to
• pk_change
• suffix
• prefix
• automation_id
• auto_formula
• sqloffset
• sqllimit
• value_min
• value_max
• uirows
• uicols
• uisearch
• ins
• uiro
• uino
• dispsize (calculated display size)

Modifying The Dictionary At Run Time

Sometimes you may want to make small changes to the data dictionary, such as setting a column's description, but you do not want to run a build. You can create a function that will modify the data dictionary after it is loaded and before it is given to the original requesting program.

<?php
# This is file application/applib.php

function ddtable_groups(&$dd) {
    # for some reason we want to pretend this
    # column does not exist
    unset($dd['flat']['group_id']);
}

function ddtable_orders(&$dd) {
    $dd['singular'] = "Order";
}
?>