Field Type is an exciting new addition to Mosets Tree 2.0 as it allows you to extends the existing set of field types to suit various needs. This document is written for developers who wish to develop new field type for Mosets Tree. Field Type is packaged and distributed as an XML file and consist of 3 parts:

• PHP Class based mFieldType parent class
• Metadata
• Attachments

PHP Class

The PHP Class is the main part of a field type. It inherits all methods and properties from mFieldType base class. In its simplest form, a field type will have the following class definition:

class mFieldType_yourFieldType extends mFieldType {    }  

This will give you a basic field type that works exactly like a Text field type.

 

Before going further, let's look at the list of methods available and inherited from mFieldType, in no specific order:

• isCore()
• isRequired()
• inBackEnd()
• hasValue()
• hasInputField()
• hasSearchField()
• hasCaption()
• hasJSValidation()
• parseValue( string value )
• getId()
• getLinkId()
• getFieldType()
• getValue()
• getSize()
• getFieldElements()
• getArrayFieldElements()
• getInputHTML()
• getSearchHTML()
• getJSValidation()
• getName()
• getCaption()
• getFieldTypeAttachmentURL()
• getDataAttachmentURL()
• getModPrefixText()
• getModSuffixText()
• getDisplayPrefixText()
• getDisplaySuffixText()
• getParam()
• getSearchFieldName()
• getInputFieldName()
• getKeepFileName()
• getKeepFileCheckboxHTML()
• getOutput()
• getWhereCondition()

Let's start with the 6 methods, that will be used (and overrided) very often in Field Type's development.

getOutput(int view)

getOutput(int view)

getOutput() is called everytime it displays a custom field's data in summary or details view. This is the method you want to override if you wish to format a custom field's data before sending the output to the user. Data mentioned here is the value that is stored in the database. By default, it returns the value without any formatting.

 

For example, in Weblink's field type, its getOutput function will look like this:

function getOutput(int $view) {  	return  '<a href="' . $this->getValue() . '"&gy;' . $this->getValue() . '</a>';  }  

getOutput() accepts a single parameter called $view which represents one of the two views where this is being called - details view or summary view. The value passed is 1 when called from details view and the value is 2 when called from summary view. This parameter is useful when you need to determine if you want to display expanded or full information in details view or a summarized version of the data in summary view considering the limited amount of space available in summary view.

 

$this-<getValue() as the name implies return the data store for the custom field. This method will be used very often throughout a field type's development.

getInputHTML()

getInputHTML()

getInputHTML() is called to display the HTML codes needed to accept data from users in front and back-end. By default it displays a textbox, ie:

function getInputHTML() {  	return '>input class="inputbox text_area" type="text" name="' . $this->getInputFieldName(1) . '" id="' . $this->getInputFieldName(1) . '" size="' . $this->getSize() . '" value="' . htmlspecialchars($this->getValue()) . '" />';  }  

You can see a method called $this->getInputFieldName(1) is used to get the name for the input field. $this->getSize() as the name implies return the size value as entered during the creation of a custom field.

getSearchHTML()

getSearchHTML()

getSearchHTML() is called in the front and back-end's Advanced Search page. Similar to getInputHTML, getSearchHTML() returns the HTML codes needed to accept search string for a custom field. By default, it return a textbox, ie:

function getSearchHTML() {  	return '<input class="inputbox text_area" type="text" name="' . $this->getName() . '" id="' . $this->getName() . '" size="' . $this->getSize() . '" />';  }  

getWhereCondition()

getWhereCondition()

getWhereCondition() is called when Mosets Tree is performing a simple or advanced search. It returns part of the SQL query required to search against data stored in a custom field. Here's an example:

function getWhereCondition() {  	if( func_num_args() == 0 ) {  		return null;  	} else {  		return '(cfv#.value LIKE \'%' . func_get_arg(0) . '%\')';  	}  }  

null is returned if a search should not proceed for a custom field. In the above example, if there is no search string passed to the method, null is returned. A valid SQL query return value for this method should be in this format:

cfv#.value|cfv#.attachment OPERATOR 'SEARCHSTRING'  

where cfv#.value or cfv#.attachment refers to the column that stores a custom field's data. cfv#.value is is used to search for stored data, while cfv#.attachment is used when searching for the presence of an attachment. cfv#.attachment's possible value is 1 or 0. 1 is returned when there is an attachment for a custom field and 0 is returned when there is none. Attachment names are not searchable.

 

"OPERATOR 'SEARCHSTRING'" refers to a MySQL comparison operator and an operand. You can take a look at all the operands at MySQL's Reference manual on Comparison Functions and Operators.

 

If not overrided, getWhereCondition() returns query that searches a custom field simply by looking for the presence of the supplied search text.

getJSValidation()

Each custom field has an optional javascript validation that make sure a field has been filled up before a user can proceed. getJSValidation() allows you to add additional javascript validation by returning part of a javascript if-else codes. Here's an examplpe of getJSValidation for the E-mail field type which checks for a valid e-mail:

function getJSValidation() {  	global $_MT_LANG;  	$js = '';  	$js .= '} else if (form.' .$this->getName() . '.value != "" && /^[a-zA-Z0-9._-]+@([a-zA-Z0-9.-]+\.)+[a-zA-Z0-9.-]{2,4}$/i.test(form.' .$this->getName() . '.value)==false) {';   	$js .= 'alert("' . $_MT_LANG->PLEASE_ENTER_A_VALID_EMAIL . '");';  	return $js;  }  

By default, it returns null and does not perform additional javascript validation.

parseValue( string|array $value )

parseValue() is called for each field before its data is stored to a database. This method is very useful as it gives you the possibilities to create complex field types since it allows you to manipulate data entered by user before storing it to a database.

 

Most simple field types (ie: Text field type) simply stored whatever that is entered by a user without going through this method. However, field types like Checkbox and Select Multiple uses parseValue to convert multiple selected options in to values that can be stored in a single database column. When saving Checkbox and Select Multiple's data, array is passed as a parameter and converted to strings separated by a pipe character '|'.

 

Another example is Weblink and Number field type. parseValue() is used to run a validation checks to make sure data entered for these field types are in fact a valid URL and a valid integer respectively. This can serve as a much more reliable validation check on top of the javascript validation.

 

You will see the usefulness of this method when you know that field types in Mosets Tree also accepts file uploads. So instead of just storing plaintext, you can create field types that accept file uploads, manipulate the file before storing it.

 

The parameter passed depends on the type of input a field accepts. If it is a scalar input field (ie: Text, Select List, button, Weblink, E-mail, Year, Multi-lin Textbox and Number), a string parameter will be passed. If it is an array input field (Select Multiple, Checkbox and Date), an array will be passed. In the case of a file upload field, $value will contain an array of all the uploaded file information as documented in PHP Documentation on Handling file uploads.

 

By default if not overrided, parseValue will check for the type of parameter passed. If it is an array, it will be converted to string separating all array values with pipe character '|'.