Manual

SDK

 
<< Approval workflow  Permissions and sections >> 

Tutorials
 

Translation and i18n

Datatypes in Exponential 3

Datatypes are the most useful building blocks in Exponential 3. To create any attribute in any class, you need to choose a suitable datatype to represent your attribute. The concept of Exponential datatypes is not exactly the same as datatypes in common programming languages although Exponential has some basic datatypes such as integer, float and textline which is actually a string type. Datatypes in Exponential are defined as fundamental and common elements which can build complex products on the Internet.

Overview of available datatypes

Exponential 3 comes with the following fundamental datatypes.

  • Text line
  • Integer
  • Float
  • Text field
  • XML Text field
  • User account
  • Image
  • Media
  • Check box
  • Enum
  • Option
  • Email
  • Author
  • Price
  • Date field
  • Time
  • Datetime
  • Object relation
  • ISBN
  • URL
  • BinaryFile

Creating a new datatype

When you are creating or editing a class object, you should decide which datatypes are going to be used by your attributes. Although the datatypes that come with Exponential are powerful enough for creating complex content classes, you might still need to create your own datatypes for specific cases. Creating new datatypes requires having some basic knowledge of how Exponential datatypes work and which classes are necessary to be changed or added. In the following tutorial, how to create a new datatype is shown step by step using the datatype Email as an example. The Email datatype is used to save email address and implements some check rules to verify that input email is of correct format.

Step 1: Build the file structure for your new datatype.

To make the datatype Email, you should first create the folder ezemail under ./kernel/classes/datatypes/, then create the file called ezemailtype.php under the newly created folder. Note that the name of the folder and PHP file is important since it will be used to locate the file. The basic structure is that if you added a datatype x, it should be stored like this: ./kernel/classes/datatypes/ezx/ezxtype.php.

Step 2: Write the datatype file inherited from file ./kernel/classes/ezdatatype.php.

All datatype files should inherit from the file ./kernel/classes/ezdatatype.php and implement some functions which the super class has defined but not implemented. Let's work through the code of ezemailtype.php to see how this class was implemented. 

<?php

// Include the super class file
include_once( "kernel/classes/ezdatatype.php" );

// Include the file which will be used to validate email
include_once( "lib/ezutils/classes/ezmail.php" );

// Define the name of datatype string
define( "EZ_DATATYPESTRING_EMAIL", "ezemail" );

class eZEmailType extends eZDataType
{
    /*!
     Construction of the class, note that the second parameter in eZDataType is the actual name
     showed in the datatype dropdown list.
    */
    function eZEmailType( )
    {
        $this->eZDataType( EZ_DATATYPESTRING_EMAIL, "Email" );
    }

    /*!
     Validates the input and returns true if the input was valid for this datatype. Here you could
     add special rules for validating email.
     Parameters $http holds the class object eZHttpTool which has functions to fetch and check http input.
     Parameters $base holds the base name of http variable, in this case the base name will be 'ContentObjectAttribute'.
     Parameters $contentObjectAttribute holds the attribue object.
    */
    function validateObjectAttributeHTTPInput( &$http, $base, &$contentObjectAttribute )
    {
        if ( $http->hasPostVariable( $base . '_data_text_' . $contentObjectAttribute->attribute( 'id' ) ) )
        {
            $email =& $http->postVariable( $base . '_data_text_' . $contentObjectAttribute->attribute( 'id' ) );
            $classAttribute =& $contentObjectAttribute->contentClassAttribute();
            if( $classAttribute->attribute( "is_required" ) == true )
            {
                if( $email == "" )
                {
                    $contentObjectAttribute->setValidationError( ezi18n( 'content/datatypes',
                                                                         'A valid email account is required.',
                                                                         'eZEmailType' ) );
                    return EZ_INPUT_VALIDATOR_STATE_INVALID;
                }
            }
            if( $email != "" )
            {
                $isValidate =  eZMail::validate( $email );
                if ( ! $isValidate )
                {
                    $contentObjectAttribute->setValidationError( ezi18n( 'content/datatypes',
                                                                         'Email address is not valid.',
                                                                         'eZEmailType' ) );
                    return EZ_INPUT_VALIDATOR_STATE_INVALID;
                }
            }
        }
        return EZ_INPUT_VALIDATOR_STATE_ACCEPTED;
    }

    /*!
     Fetches the http post var string input and stores it in the data instance.
     An email could be easily stored as variable characters, we use data_text filed in database to save it.
     In the template, the textfile name of email input is something like 'ContentObjectAttribute_data_text_idOfTheAttribute',
     therefore we fetch the http variable '$base . "_data_text_" . $contentObjectAttribute->attribute( "id" )'.
     Again, parameters $base holds the base name of http variable and is 'ContentObjectAttribute' in this example.
    */
    function fetchObjectAttributeHTTPInput( &$http, $base, &$contentObjectAttribute )
    {
        if ( $http->hasPostVariable( $base . "_data_text_" . $contentObjectAttribute->attribute( "id" ) ) )
        {
            $data =& $http->postVariable( $base . "_data_text_" . $contentObjectAttribute->attribute( "id" ) );
            $contentObjectAttribute->setAttribute( "data_text", $data );
        }
        return false;
    }

    /*!
     Store the content. Since the content has been stored in function fetchObjectAttributeHTTPInput(),
     this function is with empty code.
    */
    function storeObjectAttribute( &$contentObjectattribute )
    {
    }

    /*!
     Returns the content.
    */
    function &objectAttributeContent;( &$contentObjectAttribute )
    {
        return $contentObjectAttribute->attribute( "data_text" );
    }

    /*!
     Returns the meta data used for storing search indices.
    */
    function metaData( $contentObjectAttribute )
    {
        return $contentObjectAttribute->attribute( "data_text" );
    }

    /*!
     Returns the text.
    */
    function title( &$contentObjectAttribute )
    {
        return  $contentObjectAttribute->attribute( "data_text" );
    }
}
eZDataType::register( EZ_DATATYPESTRING_EMAIL, "ezemailtype" );
?>

As the code illustrates, it must include the PHP file ezdatatype.php and inherit from eZDataType. The class should implement the functions validateObjectAttributeHTTPInput, fixupObjectAttributeHTTPInput, fetchObjectAttributeHTTPInput, and storeObjectAttribute. The function validateObjectAttributeHTTPInput, which validates the datatype input, and the function fetchObjectAttributeHTTPInput, which gets the datatype input and stores it, are the most important functions that need to be rewritten for every new datatype. Other functions may have the same content. At the end of the file, the new datatype should be registered in the system by calling the register method in the class eZDataType.

In this example, the following line 

eZDataType::register( EZ_DATATYPESTRING_EMAIL, "ezemailtype" );
was added.

Step 3: Add associated template files for the content class.

Not every datatype needs to have a template file in class level since most datatypes can use standard UI supplied with Exponential. It is only necessary when the datatype has specific constraints that need to be defined during class editing. Examples are setting a default value for the datatype, adding customer action buttons, etc. If so, the datatype file should implement the functions storeClassAttribute, validateClassAttributeHTTPInput, fixupClassAttributeHTTPInput, and fetchClassAttributeHTTPInput which are defined in the super class ezdatatype.php. These functions deal with how to fetch and validate input and then store it in the database. Note that the template file should be located at ./design/standard/templates/class/datatype/edit/ezx.tpl. The datatype Email does not have a specification in class level and therefore nothing needs to be done in this case.

Step 4: Add associated template files for content object.

For every datatype, two template files must to be added. One template file for content object editing and one for content object viewing. In this example, we add one ezemail.tpl (shown below) under ./design/standard/templates/content/datatype/edit/. This is just a normal text field with corresponding name we defined in eZEmailtype.php. Users will use this text field to edit or input email address. 

<input type="text" size="10" name="ContentObjectAttribute_data_text_{$attribute.id}" value="{$attribute.data_text}" />

The second ezemail.tpl is added under ./design/standard/templates/content/datatype/view/, this template file will show the result of the saved email address. 

{$attribute.data_text}

Step 5: Add the new datatype to the site.ini file.

The last step is to add the newly created datatype to the content.ini file so it will be displayed in the datatype dropdown list. Open the content.ini file under ./settings/ with a text editor and find the line with 

[DataTypeSettings]
# A list of directories to check for datatypes
RepositoryDirectories[]=kernel/classes/datatypes
ExtensionDirectories[]

AvailableDataTypes[]=ezstring
AvailableDataTypes[]=eztext
AvailableDataTypes[]=ezxmltext
AvailableDataTypes[]=ezdate
AvailableDataTypes[]=ezdatetime
AvailableDataTypes[]=eztime
AvailableDataTypes[]=ezboolean
AvailableDataTypes[]=ezinteger
AvailableDataTypes[]=ezfloat
AvailableDataTypes[]=ezenum
AvailableDataTypes[]=ezobjectrelation
AvailableDataTypes[]=ezimage
AvailableDataTypes[]=ezbinaryfile
AvailableDataTypes[]=ezmedia
AvailableDataTypes[]=ezauthor
AvailableDataTypes[]=ezurl
AvailableDataTypes[]=ezemail
AvailableDataTypes[]=ezoption
AvailableDataTypes[]=ezprice
AvailableDataTypes[]=ezuser
AvailableDataTypes[]=ezisbn

Add a new line with the name of the new datatype to somewhere under [DataTypeSettings] . In this example, we should add line "AvailableDataTypes[]=ezemail" under [DataTypeSettings]. You can check the result by refreshing your browser and then go to the class editing page. If everything goes fine, you should find Email on the dropdown list.

Create more complex datatypes

In this tutorial, a simple datatype Email, which uses only one field in the database to store its content, was created. To create more complex datatypes, extra tables may need to be added and extra classes may need to be written. Please refer to the eZEnum type for more detail about how complex datatypes can be created.


Exponential