\SmartCell

__construct()

__construct(\SmartColumn  $Column, \SmartRow  $Row) : \SmartCell

Constructor

Parameters

Returns

__toString()

__toString() : string

Deprecated - Allows access to the value without having to explicitly use GetRawValue(). Example: echo $smartrow['columnname']

NOTE- Cell must be used in a string context so the value is returned as a string, otherwise you will be accessing the Cell directly.

Returns

The value of this cell through GetValue() as a string (PHP requires a string be returned)

GetValue()

GetValue(boolean  $returnOption1 = false) : mixed

Returns the value of the cell.

Note: if coming from a Row object named $row, you can use the shorthand array notation and invoke the Column/Cell directly:

//this shorthand is recommended:
$columnValue = $row['YOUR_COLUMN_NAME'](); //same thing as $row['YOUR_COLUMN_NAME']->GetValue();
$columnValue = $row['YOUR_COLUMN_NAME'](true); //same thing as $row['YOUR_COLUMN_NAME']->GetValue(true);

//NOTE: This is not recommended, but you can skip the function call (i.e. $row['YOUR_COLUMN_NAME']) when the returned value is used as a STRING ONLY! Otherwise, $row['YOUR_COLUMN_NAME'] gives you the actual SmartCell object. For example:
echo $row['YOUR_COLUMN_NAME']; //is fine and will echo the column value
if($row['YOUR_COLUMN_NAME'] == "my data"){} //is fine and will compare the column value to "my data"
if($row['YOUR_COLUMN_NAME'] == 3){} //is NOT fine since we're not doing string comparison. this statement will try to compare the actual SmartCell object with the int 3 and will lead to bad things.
if((string)$row['YOUR_COLUMN_NAME'] == 3){} //is fine
if($row['YOUR_COLUMN_NAME']() == 3){} //is fine and RECOMMENDED (just always invoke the Column/Cell directly like this)
if($row['YOUR_COLUMN_NAME']->GetValue() == 3){} //is fine

Once PHP allows overriding operators or toInt()/toFloat()/__toBool() etc., we will be able to handle this situation automatically so you don't need to worry about the above anymore, and won't need to even do the shorthand invoke on the Column/Cell. We may be able to look in to the SPL_Types php package for some of this stuff down the road?

Parameters

Returns

The value of the cell

GetRawValue()

GetRawValue() : mixed

You should almost always use GetValue() instead of this. GetRawValue() will return the RAW data of the cell (i.e. serialized/compressed data for array, object columns).

This is mostly used internally for db queries

Returns

The raw value of the cell

SetValue()

SetValue(mixed  $value) 

Sets the value of the Cell.

Date column values are run through PHP's strtotime() function by default to expand possible date input values

Note: if coming from a Row object named $row, you set the value with the shorthand array notation:

$row['YOUR_COLUMN_NAME'] = $yourNewValue;

Parameters

GetRelatedRows()

GetRelatedRows(string  $tableName, string  $columnName = null, array  $options = null) : array

Returns an array of all rows from $tableName whose $columnName value matches the value of this Cell. If there are no matching rows, an empty array is returned.

To execute this function, the related table must have a primary key.

Options are as follows:

$options = array(
    'sort-by'=>null, //Either a string of the column to sort ASC by, or an assoc array of "ColumnName"=>"ASC"|"DESC" to sort by. An exception will be thrown if a column does not exist.
    'return-assoc'=>false, //if true, the returned assoc-array will have the row's primary key column value as its key and the row as its value. ie array("2"=>$row,...) instead of just array($row,...);
    'return-next-row'=>null, //OUT variable. integer. if you set this parameter in the $options array, then this function will return only 1 row of the result set at a time. If there are no rows selected or left to iterate over, null is returned.
                          // THIS PARAMETER MUST BE PASSED BY REFERENCE - i.e. array( "return-next-row" => &$curCount ) - the incoming value of this parameter doesn't matter and will be overwritten)
                          // After this function is executed, this OUT variable will be set with the number of rows that have been returned thus far.
                          // Each consecutive call to this function with the 'return-next-row' option set will return the next row in the result set, and also increment the 'return-next-row' variable to the number of rows that have been returned thus far
    'limit'=>null, // With one argument (ie $limit="10"), the value specifies the number of rows to return from the beginning of the result set
                   // With two arguments (ie $limit="100,10"), the first argument specifies the offset of the first row to return, and the second specifies the maximum number of rows to return. The offset of the initial row is 0 (not 1):
    'return-count'=>null, //OUT variable only. integer. after this function is executed, this variable will be set with the number of rows being returned. Usage ex: array('return-count'=>&$count)
    'return-count-only'=>false, //if true, the return-count will be returned instead of the rows. A good optimization if you dont need to read any data from the rows and just need the rowcount of the search.
 }

Parameters

Returns

An array of all rows from $tableName whose $columnName value matches the value of this Cell. If there are no matching rows, an empty array is returned.

GetRelatedRow()

GetRelatedRow(string  $tableName, string  $columnName = null) : \SmartRow

Returns a Row instance from $tableName whose $columnName value matches the value of this Cell. If there is no match, an instance is still returned but ->Exists() will be false. The returned row will have the searched column=>value set by default (excluding auto-increment primary key columns)

To execute this function, the related table must have a primary key and the column $columnName must be unique.

Options are as follows:

Parameters

Returns

A Row instance from $tableName whose $columnName value matches the value of this Cell. If there is no match, an instance is still returned but ->Exists() will be false. The returned row will have the searched column=>value set by default (excluding auto-increment primary key columns)

OnSetValue()

OnSetValue(mixed  $callbackFunction, mixed  $functionScope = null) 

Adds a $callbackFunction to be fired when this column has been set (though not necessarily 'changed')

The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)

$eventObject in your $callbackFunction will be the ROW containing the Cell that is firing the event callback

$eventArgs in your $callbackFunction will have the following keys:

array(
    'cancel-event'=>&false,  //setting 'cancel-event' to true within your $callbackFunction will prevent the event from continuing
    'Cell'=>&$this, //a reference to the Cell that fired the event
    'current-value'=>object, //the current value of this column, BEFORE it has changed to 'new-value'
    'new-value'=>&object, //the value that this column is going to be set to, replacing the 'current-value'. Changing this value in your $callbackFunction will change the value that the column will be set to.
);

Parameters

OnBeforeValueChanged()

OnBeforeValueChanged(mixed  $callbackFunction, mixed  $functionScope = null) 

Adds a $callbackFunction to be fired right before this column has been changed.

The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs) $eventObject in your $callbackFunction will be the ROW containing the Cell that is firing the event callback $eventArgs in your $callbackFunction will have the following keys:

array(
    'cancel-event'=>&false,  //setting 'cancel-event' to true within your $callbackFunction will prevent the event from continuing
    'Cell'=>&$this, //a reference to the Cell that fired the event
    'current-value'=>object, //the current value of this column, BEFORE it has changed to 'new-value'
    'new-value'=>&object, //the value that this column is going to be set to, replacing the 'current-value'. Changing this value in your $callbackFunction will change the value that the column will be set to.
);

Parameters

OnAfterValueChanged()

OnAfterValueChanged(mixed  $callbackFunction, mixed  $functionScope = null) 

Adds a $callbackFunction to be fired right after this column has been changed.

The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)

$eventObject in your $callbackFunction will be the ROW containing the Cell that is firing the event callback

$eventArgs in your $callbackFunction will have the following keys:

array(
    'Cell'=>&$this, //a reference to the Cell that fired the event
    'current-value'=>object, //the current value of this column, AFTER it has been changed from 'old-value'
    'old-value'=>object, //the value that this column was set to before it was updated with the 'current-value'
);

Parameters

GetFormObject()

GetFormObject(string  $formObjectType = null, mixed  $param1 = null, mixed  $param2 = null, mixed  $param3 = null) : string

Returns a string of HTML representing a form textbox object for this Cell.

Parameters

"text" | "password" | "checkbox" | "select" | "textarea" | "hidden" | "radio" | "colorpicker" | "datepicker" | "slider"

Returns

string of HTML representing a form textbox object for this cell

GetTextFormObject()

GetTextFormObject(array  $customAttribs = null, array  $options = null) : string

Returns a string of HTML representing a form textbox object for this cell.

$options are as follows:

$options = array(
    'show-required-marker' => $this->IsRequired, //if true, a '*' will be appended to the end of the input field (note: default value may be set on the Column. use this field to overwrite the default value)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a form textbox object for this cell

GetPasswordFormObject()

GetPasswordFormObject(array  $customAttribs = null, array  $options = null) : string

Returns a string of HTML representing a form password input object for this cell.

$options are as follows:

$options = array(
    'show-required-marker' => $this->IsRequired, //if true, a '*' will be appended to the end of the input field (note: default value may be set on the Column. use this field to overwrite the default value)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a form password input object for this cell

GetCheckboxFormObject()

GetCheckboxFormObject(array  $customAttribs = null, array  $hiddenNotifierCustomAttribs = null, array  $options = null) : string

Returns a string of HTML representing a form checkbox input object for this cell.

$options are as follows:

$options = array(
    'show-required-marker' => $this->IsRequired, //if true, a '*' will be appended to the end of the input field (note: default value may be set on the Column. use this field to overwrite the default value)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a form checkbox input object for this cell

GetSelectFormObject()

GetSelectFormObject(mixed  $keyValuePairs = null, array  $customAttribs = null, array  $options = null) : string

Returns a string of HTML representing a select dropdown input object for this cell.

$options are as follows:

$options = array(
    'show-required-marker' => $this->IsRequired, //if true, a '*' will be appended to the end of the input field (note: default value may be set on the Column. use this field to overwrite the default value)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
    'print-empty-option' => !$this->IsRequired, //if true, an empty option will be the first option printed
    'force-selected-key' => null, //string. if set, the given key within $keyValuePairs will be forced as the selected option (if found. if not found, the browser's default choice will be selected, probably the first in the list)
    'use-possible-values' => false, //if true, this will populate the select object with the "PossibleValues" for this particular column (as defined in the xml db schema)
);

Parameters

- If $keyValuePairs is "true", this will populate the select object with the "PossibleValues" for this particular column (as defined in the xml db schema)
- If $keyValuePairs is an array- If an array- The key-value pairs that set the values for the input dropdown html tag. ie each key-value pair generates <option name="KEY">VALUE</option>

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a select dropdown input object for this cell

GetTextareaFormObject()

GetTextareaFormObject(array  $customAttribs = null, array  $options = null) : string

Returns a string of HTML representing a form textarea input object for this cell.

$options are as follows:

$options = array(
    'show-required-marker' => $this->IsRequired, //if true, a '*' will be appended to the end of the input field (note: default value may be set on the Column. use this field to overwrite the default value)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
    'value' => null, //the actual shown value of the text area (if not using the default value from this cell)
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a form textarea input object for this cell

GetHiddenFormObject()

GetHiddenFormObject(array  $customAttribs = null, array  $options = null) : string

Returns a string of HTML representing a form hidden input object for this cell.

$options are as follows:

$options = array(
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a form hidden input object for this cell

GetRadioFormObject()

GetRadioFormObject(string  $labelText = "", string  $formValue = "", array  $customAttribs = null, array  $options = null) : string

Returns string string of HTML representing a radio button input object for this cell.

If $customAttribs contains 'name', a custom name will be set for this form object. 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

$options are as follows:

$options = array(
    'force-checked' => false, //if true, this radio button will be checked regardless of the current Cell value. if false, this radio button will be checked only if the value matches the one currently in the Cell
    'checked-if-null' => false, //if true, this radio button will be checked only if the current Cell value for thi column is null. defaults to true if the current value is 0 or empty string
    'label-text' => "", //a string for the text of the label next to the radio button. if this field is left empty, no label will be included with the button
    'label-position' => "left", //can be "left" or "right", relative to the radio button (only if ['include-label']=true)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a radio button input object for this cell

MakeValidHtmlId()

MakeValidHtmlId(  $str) 

Strips out and returns any characters that are not valid for use as an HTML ID attribute

Parameters

GetColorpickerFormObject()

GetColorpickerFormObject(array  $customAttribs = null, array  $options = null) : string

Returns a string of HTML for use with the jQuery UI colorpicker (which may have been removed from jquery ui?). Uses appropriate the name/value for this SmartCell.

$options are as follows:

$options = array(
    'show-required-marker' => $this->IsRequired, //if true, a '*' will be appended to the end of the input field (note: default value may be set on the Column. use this field to overwrite the default value)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a form color picker input object for this cell

GetDatepickerFormObject()

GetDatepickerFormObject(array  $customAttribs = null, array  $options = null) : string

Returns a string of HTML for use with the jQuery UI date picker. Uses appropriate the name/value for this SmartCell.

$options are as follows:

$options = array(
    'show-required-marker' => $this->IsRequired, //if true, a '*' will be appended to the end of the input field (note: default value may be set on the Column. use this field to overwrite the default value)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a form date picker input object for this cell

GetSliderFormObject()

GetSliderFormObject(array  $customAttribs = null, array  $options = null) : string

Returns a string of HTML for use with the jQuery UI slider. Uses appropriate the name/value for this SmartCell.

$options are as follows:

$options = array(
    'show-required-marker' => $this->IsRequired, //if true, a '*' will be appended to the end of the input field (note: default value may be set on the Column. use this field to overwrite the default value)
    'custom-formatter-callback' =>null, //can be either: 1. array("functionName", $obj) if function belongs to $obj, 2. array("functionName", "className") if the function is static within class "classname", or 3. just "functionName" if function is in global scope. this function will be called when getting the form object and the value returned by it will be used as the form object's value. the callback's signiture is functionName($value), where $value is the current cell value
);

Parameters

If this array contains 'name', a custom name will be set for this form object, though 'name' should be left blank on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle getting/setting POST/GET values

Returns

string of HTML representing a form slider input object for this cell

GetFormObjectLabel()

GetFormObjectLabel(array  $options = null) : string

Returns a string of HTML representing a label for this cell's form input object.

$options are as follows:

$options = array(
    'for' => $this->Table->TableName.$this->ColumnName, //the id of the form object that this label is for. this should be left as default on most cases as the default name will be generated so it can be tracked by this class; custom names require you to handle organization of matching label names to form object ids
    'label-text' => $this->DisplayName, //the text or html of the label. empty will use the column's DisplayName (if set), otherwise uses the ColumnName
    'prefix' => "", //adds a text or html prefix to the label
    'suffix' => ": ", //adds a text or html suffix to the label
 'html-special-chars' => false //if true, will html-special-chars the prefix, label-text, and suffix
);

Parameters

Returns

a string of HTML representing a label for this cell's form input object

HasErrors()

HasErrors(array  $options = null) 

Returns a string of current errors that exist within this cell, or FALSE if no errors were found.

The row should not be committed until there are no more errors on any cell of the row

$options are as follows:

$options = array(
    'ignore-key-errors'=>false, //If true: does not validate the key columns. If false: validates all columns
    'only-verify-set-cells'=>false, //If true: only cells that have been set (i.e. isset()==true) will be verified (not recommended if this info will be committed to db). If false: all cells will be verified (should be used if this info will be committed to db).
    'error-message-suffix'=>"<br>\n" //appended to each error message
);

Parameters

count()

count() : integer

For the Countable interface, this allows us to do count($table) to return the number of rows in the table.

Returns

The number of rows in this table.

getIterator()

getIterator() : \Iterator

For the IteratorAggregate interface, this allows us to do foreach($SmartCell as $i=>$val)

Returns

ValueDiffers()

ValueDiffers(  $compareValue) : boolean

Checks the given $compareValue against the current value to see if the value is different. Returns true if the $compareValue is different from the current value, false if they are the same. Uses type casting.

Parameters

Returns

true if the $compareValue is different from the current value, false if they are the same.

FireCallback()

FireCallback(array  $callbackArr, array  $eventArgs = null) 

Fires all callbacks for the given callback array

Parameters

BuildAttribsHtml()

BuildAttribsHtml(array  $attribsAssoc) : string

Builds a string of HTML of the giben attribtutes. ie ' class="myclass" id="someId" disable="disabled"'

Parameters

Returns

HTML of the given attributes