HelloWorld - part 3 RBO fields

From EPESI framework documentation
Jump to: navigation, search

In the previous tutorial I showed how to use RBO in your module. There are many types of fields you can use in RBO recordsets. You decide which types of fields you will have in Recordset.php in fields() function. Here is a list of all available RBO field types.

text

Holds a string value. HTML entities are escaped. The length of the field must be defined.

$text = new RBO_Field_Text('<field_name>');
$text->set_length(24)->set_required()->set_visible();

Because of fluent interface you can customize the field in one line. You can set the length of the text using the set_length(value) method where value is the length of the text. In order for the field to be visible you must always activate set_visible(). If you want the field to be required you can do so by setting it to set_required(). Now the field will notify if someone was to save the record with this field empty and will have to fill it before saving.

i.e.

$text = new RBO_Field_Text('Text');
$text->set_length(24)->set_required()->set_visible();

Fields text.png

long text

Holds note (long string value). HTML entities are escaped. It has support for the bbcode feature. Due to the fact that attachments are added to nearly all RecordSets - we limit the length of that field to 400 characters (not counting bbcodes tags).

$long_text = new RBO_Field_LongText('<field_name>');
$long_text->set_visible();


i.e.

$longtext = new RBO_Field_LongText('Longtext');
$longtext->set_visible();


Fields longtext.png

integer

Holds integer value.

$int = new RBO_Field_Integer('<field_name>');
$int->set_visible();

i.e.

$integer = new RBO_Field_Integer('Integer');
$integer->set_visible();

Fields integer2.png

autonumber

Creates a primary key for every new record.

$ID = new RBO_Field_Autonumber('<field_name>');
$ID->set_visible();

i.e.

$ID = new RBO_Field_Autonumber('helloworldID');
//$ID->set_visible();;

The id is an autonumber so it does not need to be visible therefor do not use the set_visible method. Comment it.

Fields autonumber.png

WARNING: Do not set the field name to ID.

float

Holds float value.

$float = new RBO_Field_Float('<field_name>');
$float->set_visible();

i.e.

$float = new RBO_Field_Float('float');
$float->set_visible();

Fields float2.png

checkbox

Holds bool value. Return true for checked fields and (empty string - it's used by every type for empty value) for unchecked.

$CB = new RBO_Field_Checkbox('<field_name>');
$CB->set_visible();

i.e.

$CB = new RBO_Field_Checkbox('CB');
$CB->set_visible();

Fields checkbox.png

calculated

Calculated field doesn't hold any value by default. This field is designed to bring some information (it's read-only) to the user. For this reason display_callback is required property. If needed, data type can be selected via param property - this value is then usually modified in processing callback.

$Calc = new RBO_Field_Calculated('<field_name>');
$Calc->set_visible();

i.e.

$Calc = new RBO_Field_Calculated('Calc');
//$Calc->set_visible();

In order for this field to output some calculations you must use the __display_magic_callback function. So let's say that your calculated field is called 'calc' and you wan't to check if someone checked cb and if so you wan't to return the sum of the integer fields value and 20. This is how the function should look like

 public function display_calc($record){
        $a = 0;

        if($record['cb'] == true){
            $a = $record['integer']+20;
        }

        return $a;
 }

As you can see the syntax is display_ as the prefeix followed by the php field name. After you save the record the fields will display the result, so if you type 5 into the integer field the output would be 25.

Fields calculated.png

date

Simple date field with a button that brings pop-up calendar.

$Date = new RBO_Field_Date('<field_name>');
$Date->set_visible();

i.e.

$date = new RBO_Field_Date('Date');
$date->set_visible();

Fields date.png

timestamp

Simple date and time field with a button that brings pop-up calendar. Time is selected using HTML select elements. The timezone conversion is done automatically for both display and update.

$Timestamp = new RBO_Field_Timestamp('<field_name>');
$Timestamp->set_visible();

i.e.

$timestamp = new RBO_Field_Timestamp('timestamp');
$timestamp->set_visible();

Fields timestamp.png

currency

Field that holds value and currency. Currency is selected using HTML select elements. Data format is float_value__currency_id. See Utils_CurrencyField module for more details.

$Currency = new RBO_Field_Currency('<field_name>');
$Currency->set_visible();

i.e.

$currency = new RBO_Field_Currency('Currency');
$currency->set_visible();

Fields currency.png

select

Holds key to selected value. This type is designed to link to other RecordSets and records ids are always used as keys. <Recordset> is essential here.

$Select = new RBO_Field_Select('<field_name>','<Recordset>');
$Select->set_visible();

i.e

$Select = new RBO_Field_Select('Select');
$Select->from('contact')->fields('last_name')->set_visible();

Fields select.png

multiselect

Holds keys to selected values. This type is designed to link to other RecordSets and also CommonData data sets. <Recordset> is essential here. This is the only field that returns and accepts value as an array, rather than single value

$MultiSelect = new RBO_Field_MultiSelect('<field_name>');
$MultiSelect->from('<Recordset>')->fields('<field1>','<field2>')->set_visible();

i.e.

$MultiSelect = new RBO_Field_MultiSelect('MultiSelect');
$MultiSelect->from('contact')->fields('last_name')->set_visible();

Fields multiselect.png

commondata

Holds key to the selected value. This type is designed to link to other RecordSets and records ids are always used as keys. Param is essential here. This type supports ChainedSelect functionality.

$CommonData = new RBO_Field_CommonData('<field_name>','<CommonDataSource>');
$CommonData->set_required();

Replace CommonDataSource with a CommonData array, or create one in your modules install php file.

Utils_CommonDataCommon::new_array('<Array_name>',array('<value1>','<value2>'));

Add as many values as needed.

i.e

$CommonData = new RBO_Field_CommonData('Countr.','Countries');
$CommonData->set_required();

More on commondata here.

Fields commondata.png

page_split

It's a delimiter that splits different tabs of data. Each page split adds new tab with fields under that page split displayed in this tab.

$PageSplit = new RBO_Field_PageSplit('<tab_name>');
$PageSplit->set_visible();

i.e.

$PageSplit = new RBO_Field_PageSplit('PageSplit');
$PageSplit->set_visible();

Fields pagesplit.png

It is best practice to return all the fields in an array. The whole file should now look like this.

<?php

defined("_VALID_ACCESS") || die('Direct access forbidden');

class Custom_HelloWorld_Recordset extends RBO_Recordset {

    function table_name() {

        return 'HelloWorld';

    }

    function fields() {
        $fields = array();

        $ID = new RBO_Field_Autonumber('helloworldID');
        $ID->set_visible();
        $fields[] = $ID;

        $text = new RBO_Field_Text('Text');
        $text->set_length(24)->set_required()->set_visible();
        $fields[] = $text;

        $longtext = new RBO_Field_LongText('Longtext');
        $longtext->set_visible();
        $fields[] = $longtext;

        $integer = new RBO_Field_Integer('Integer');
        $integer->set_visible();
        $fields[] = $integer;

        $currency = new RBO_Field_Currency('Currency');
        $currency->set_visible();
        $fields[] = $currency;

        $PageSplit = new RBO_Field_PageSplit('PageSplit');
        $PageSplit->set_visible();
        $fields[] = $PageSplit;

        $CB = new RBO_Field_Checkbox('CB');
        $CB->set_visible();
        $fields[] = $CB;

        $Select = new RBO_Field_Select('Select');
        $Select->from('contact')->fields('last_name')->set_visible();
        $fields[] = $Select;

        $Calc = new RBO_Field_Calculated('Calc');
        $Calc->set_visible();
        $fields[] = $Calc;


        $MultiSelect = new RBO_Field_MultiSelect('MultiSelect');
        $MultiSelect->from('contact')->fields('last_name')->set_visible();
        $fields[] = $MultiSelect;

        $float = new RBO_Field_Float('float');
        $float->set_visible();
        $fields[] = $float;

        $date = new RBO_Field_Date('Date');
        $date->set_visible();
        $fields[] = $date;

        $CommonData = new RBO_Field_CommonData('Countr.','Countries');
        $CommonData->set_required();
        $fields[] = $CommonData;

        $timestamp = new RBO_Field_Timestamp('timestamp');
        $timestamp->set_visible();
        $fields[] = $timestamp;

        return $fields;


    }
    public function display_calc($record){
         $a = 0;

        if($record['cb'] == true){
            $a = $record['integer']+20;
        }

        return $a;

    }



}
?>

The final result is a form that looks like this:

All fields.png

In the next tutorial you will learn how to set default values for your fields.


Download: Get full tutorial here


NEXT >