Symphony.

void __construct()

Construct a new instance of this field.

boolean allowDatasourceOutputGrouping()

Test whether this field supports data source output grouping. This default implementation prohibits grouping. Data-source grouping allows clients of this field to group the XML output according to this field. Subclasses should override this if grouping is supported.

Returns

true if this field does support data source grouping, false otherwise.

boolean allowDatasourceParamOutput()

Test whether this field supports data source parameter output. This default implementation prohibits parameter output. Data-source parameter output allows this field to be provided as a parameter to other data sources or XSLT. Subclasses should override this if parameter output is supported.

Returns

true if this supports data source parameter output, false otherwise.

void appendAssociationInterfaceSelect(XMLElement $wrapper)

Append the html widget for selecting an association interface and editor for this field.

Parameters

• $wrapper XMLElementthe parent XML element to append the association interface selection to, if either interfaces or editors are provided to the system.

void appendFormattedElement(XMLElement $wrapper, array $data, boolean $encode, string $mode, integer $entry_id)

Append the formatted XML output of this field as utilized as a data source.

Since Symphony 2.5.0, it will defaults to prepareReadableValue return value.

Parameters

• $wrapper XMLElementthe XML element to append the XML representation of this to.

• $data arraythe current set of values for this field. the values are structured as for displayPublishPanel.

• $encode boolean(optional) flag as to whether this should be html encoded prior to output. this defaults to false.

• $mode stringA field can provide ways to output this field's data. For instance a mode could be 'items' or 'full' and then the function would display the data in a different way depending on what was selected in the datasource included elements.

• $entry_id integer(optional) the identifier of this field entry instance. defaults to null.

void appendRequiredCheckbox(XMLElement $wrapper)

Append and set a labeled html checkbox to the input XML element if this field is set as a required field.

Parameters

• $wrapper XMLElementthe parent XML element to append the constructed html checkbox to if necessary.

void appendShowAssociationCheckbox(XMLElement $wrapper, string $help)

Append the show association html widget to the input parent XML element. This widget allows fields that provide linking to hide or show the column in the linked section, similar to how the Show Column functionality works, but for the linked section.

Parameters

• $wrapper XMLElementthe parent XML element to append the checkbox to.

• $help string(optional) a help message to show below the checkbox.

void appendShowColumnCheckbox(XMLElement $wrapper)

Append the show column html widget to the input parent XML element. This displays a column in the entries table or not.

Parameters

• $wrapper XMLElementthe parent XML element to append the checkbox to.

void appendStatusFooter(XMLElement $wrapper)

Append the default status footer to the field settings panel. Displays the required and show column checkboxes.

Parameters

• $wrapper XMLElementthe parent XML element to append the checkbox to.

boolean buildDSRetrievalSQL(array $data, string $joins, string $where, boolean $andOperation)

Construct the SQL statement fragments to use to retrieve the data of this field when utilized as a data source.

Parameters

• $data arrayAn array of the data that contains the values for the filter as specified in the datasource editor. The value that is entered in the datasource editor is made into an array by using + or , to separate the filter.

• $joins stringA string containing any table joins for the current SQL fragment. By default Datasources will always join to the tbl_entries table, which has an alias of e. This parameter is passed by reference.

• $where stringA string containing the WHERE conditions for the current SQL fragment. This is passed by reference and is expected to be used to add additional conditions specific to this field

• $andOperation boolean(optional) This parameter defines whether the $data provided should be treated as AND or OR conditions. This parameter will be set to true if $data used a + to separate the values, otherwise it will be false. It is false by default.

Returns

true if the construction of the SQL was successful, false otherwise.

See Also

• toolkit.Datasource#__determineFilterType

void buildFilterSQL(string $filter, array $columns, string $joins, string $where)

Builds a basic NULL/NOT NULL SQL statement given a $filter. This function supports sql: NULL or sql: NOT NULL.

Parameters

• $filter stringThe full filter, eg. sql: NULL

• $columns arrayThe array of columns that need the given $filter applied to. The conditions will be added using OR.

• $joins stringA string containing any table joins for the current SQL fragment. By default Datasources will always join to the tbl_entries table, which has an alias of e. This parameter is passed by reference.

• $where stringA string containing the WHERE conditions for the current SQL fragment. This is passed by reference and is expected to be used to add additional conditions specific to this field

See Also

• https://dev.mysql.com/doc/refman/en/regexp.html

XMLElement buildFormatterSelect(string $selected, string $name, string $label_value)

Construct the html widget for selecting a text formatter for this field.

Parameters

• $selected string(optional) the currently selected text formatter name if there is one. this defaults to null.

• $name string(optional) the name of this field in the form. this is optional and defaults to "fields[format]".

• $label_value stringthe default label for the widget to construct. if null is passed in then this defaults to the localization of "Formatting".

Returns

An XMLElement representing a <select> field containing the options.

XMLElement buildLocationSelect(string|null $selected, string $name, string $label_value)

Build the location select widget. This widget allows users to select whether this field will appear in the main content column or in the sidebar when creating a new entry.

Parameters

• $selected string|null(optional) the currently selected location, if there is one. this defaults to null.

• $name string(optional) the name of this field. this is optional and defaults to fields[location].

• $label_value string(optional) any predefined label for this widget. this is an optional argument that defaults to null.

Returns

An XMLElement representing a <select> field containing the options.

void buildRegexSQL(string $filter, array $columns, string $joins, string $where)

Builds a basic REGEXP statement given a $filter. This function supports regexp: or not-regexp:. Users should keep in mind this function uses MySQL patterns, not the usual PHP patterns, the syntax between these flavours differs at times.

Parameters

• $filter stringThe full filter, eg. regexp: ^[a-d]

• $columns arrayThe array of columns that need the given $filter applied to. The conditions will be added using OR when using regexp: but they will be added using AND when using not-regexp:

• $joins stringA string containing any table joins for the current SQL fragment. By default Datasources will always join to the tbl_entries table, which has an alias of e. This parameter is passed by reference.

• $where stringA string containing the WHERE conditions for the current SQL fragment. This is passed by reference and is expected to be used to add additional conditions specific to this field

See Also

• https://dev.mysql.com/doc/refman/en/regexp.html

void buildSortingSQL(string $joins, string $where, string $sort, string $order)

Build the SQL command to append to the default query to enable sorting of this field. By default this will sort the results by the entry id in ascending order.

Extension developers should always implement both buildSortingSQL() and buildSortingSelectSQL().

Uses

• Field::isRandomOrder()

Parameters

• $joins stringthe join element of the query to append the custom join sql to.

• $where stringthe where condition of the query to append to the existing where clause.

• $sort stringthe existing sort component of the sql query to append the custom sort sql code to.

• $order string(optional) an optional sorting direction. this defaults to ascending. if this is declared either 'random' or 'rand' then a random sort is applied.

See Also

• Field::buildSortingSelectSQL()

string buildSortingSelectSQL(string $sort, string $order)

Build the needed SQL clause command to make buildSortingSQL() work on MySQL 5.7 in strict mode, which requires all columns in the ORDER BY clause to be included in the SELECT's projection.

If no new projection is needed (like if the order is made via a sub-query), simply return null.

For backward compatibility, this method checks if the sort expression contains ed.value. This check will be removed in Symphony 3.0.0.

Extension developers should make their Fields implement buildSortingSelectSQL() when overriding buildSortingSQL().

Uses

• Field::isRandomOrder()

Parameters

• $sort stringthe existing sort component of the sql query, after it has been passed to buildSortingSQL()

• $order string(optional) an optional sorting direction. this defaults to ascending. Should be the same value that was passed to buildSortingSQL()

Returns

an optional select clause to append to the generated SQL query. This is needed when sorting on a column that is not part of the projection.

See Also

• Field::buildSortingSQL()

XMLElement buildSummaryBlock(array $errors)

Construct the html block to display a summary of this field, which is the field Label and it's location within the section. Any error messages generated are appended to the optional input error array. This function calls buildLocationSelect once it is completed

Parameters

• $errors array(optional) an array to append html formatted error messages to. this defaults to null.

Returns

the root XML element of the html display of this.

See Also

• buildLocationSelect()

void buildValidationSelect(XMLElement $wrapper, string $selected, string $name, string $type, array $errors)

Append a validator selector to a given XMLElement. Note that this function differs from the other two similarly named build functions in that it takes an XMLElement to append the Validator to as a parameter, and does not return anything.

Parameters

• $wrapper XMLElementthe parent element to append the XMLElement of the Validation select to, passed by reference.

• $selected string(optional) the current validator selection if there is one. defaults to null if there isn't.

• $name string(optional) the form element name of this field. this defaults to "fields[validator]".

• $type string(optional) the type of input for the validation to apply to. this defaults to 'input' but also accepts 'upload'.

• $errors array(optional) an associative array of errors

boolean canFilter()

Test whether this field can be filtered. This default implementation prohibits filtering. Filtering allows the XML output results to be limited according to an input parameter. Subclasses should override this if filtering is supported.

Returns

true if this can be filtered, false otherwise.

boolean canPrePopulate()

Test whether this field can be prepopulated with data. This default implementation does not support pre-population and, thus, returns false.

Returns

true if this can be pre-populated, false otherwise.

boolean canPublishFilter()

Test whether this field can be filtered in the publish index. This default implementation prohibts filtering. Publish Filtering allows the index view to filter results. Subclasses should override this if filtering is supported.

Returns

true if this can be publish-filtered, false otherwise.

boolean canShowAssociationColumn()

Test whether this field can show the association column in the Publish Index.

Returns

true if this can, false otherwise.

boolean canShowTableColumn()

Test whether this field can show the table column.

Returns

true if this can, false otherwise.

boolean canToggle()

Test whether this field can be toggled using the With Selected menu on the Publish Index.

Returns

true if it can be toggled, false otherwise.

integer checkFields(array $errors, boolean $checkForDuplicates)

Check the field's settings to ensure they are valid on the section editor

Parameters

• $errors arraythe array to populate with the errors found.

• $checkForDuplicates boolean(optional) if set to true, duplicate Field name's in the same section will be flagged as errors. Defaults to true.

Returns

returns the status of the checking. if errors has been populated with any errors self::__ERROR__, self::__OK__ otherwise.

integer checkPostFieldData(array $data, string $message, integer $entry_id)

Check the field data that has been posted from a form. This will set the input message to the error message or to null if there is none. Any existing message value will be overwritten.

Parameters

• $data arraythe input data to check.

• $message stringthe place to set any generated error message. any previous value for this variable will be overwritten.

• $entry_id integer(optional) the optional id of this field entry instance. this defaults to null.

Returns

self::__MISSING_FIELDS__ if there are any missing required fields, self::__OK__ otherwise.

string cleanValue(mixed $value)

Clean the input value using html entity encode and the database specific clean methods.

Parameters

• $value mixedthe value to clean.

Returns

the cleaned value.

boolean commit()

Commit the settings of this field from the section editor to create an instance of this field in a section.

Returns

true if the commit was successful, false otherwise.

static XMLElement createAssociationsDrawerXMLElement(string $value, Entry $e, array $parent_association, string $prepopulate)

This is general purpose factory method that makes it easier to create the markup needed in order to create an Associations Drawer XMLElement.

Parameters

• $value stringThe value to display in the link

• $e EntryThe associated entry

• $parent_association arrayAn array containing information about the association

• $prepopulate stringA string containing prepopulate parameter to append to the association url

Returns

The XMLElement must be a li node, since it will be added an ul node.

XMLElement createCheckboxSetting(XMLElement $wrapper, string $setting, string $label_description, string $help)

Given the setting name and the label, this helper method will add the required markup for a checkbox to the given $wrapper.

Parameters

• $wrapper XMLElementPassed by reference, this will have the resulting markup appended to it

• $setting stringThis will be used with $this->get() to get the existing value

• $label_description stringThis will be localisable and displayed after the checkbox when generated.

• $help string(optional) A help message to show below the checkbox.

Returns

The Label and Checkbox that was just added to the $wrapper.

boolean createTable()

The default field table construction method. This constructs the bare minimum set of columns for a valid field table. Subclasses are expected to overload this method to create a table structure that contains additional columns to store the specific data created by the field.

See Also

• Field::requiresTable()

void displayDatasourceFilterPanel(XMLElement $wrapper, mixed $data, null $errors, string $fieldnamePrefix, string $fieldnamePostfix)

Display the default data source filter panel.

Parameters

• $wrapper XMLElementthe input XMLElement to which the display of this will be appended.

• $data mixed(optional) the input data. this defaults to null.

• $errors nullthe input error collection. this defaults to null.

• $fieldnamePrefix stringthe prefix to apply to the display of this.

• $fieldnamePostfix stringthe suffix to apply to the display of this.

void displayFilteringOptions(XMLElement $wrapper)

Inserts tags at the bottom of the filter panel

void displayPublishPanel(XMLElement $wrapper, array $data, mixed $flagWithError, string $fieldnamePrefix, string $fieldnamePostfix, integer $entry_id)

Display the publish panel for this field. The display panel is the interface shown to Authors that allow them to input data into this field for an Entry.

Parameters

• $wrapper XMLElementthe XML element to append the html defined user interface to this field.

• $data array(optional) any existing data that has been supplied for this field instance. this is encoded as an array of columns, each column maps to an array of row indexes to the contents of that column. this defaults to null.

• $flagWithError mixed(optional) flag with error defaults to null.

• $fieldnamePrefix string(optional) the string to be prepended to the display of the name of this field. this defaults to null.

• $fieldnamePostfix string(optional) the string to be appended to the display of the name of this field. this defaults to null.

• $entry_id integer(optional) the entry id of this field. this defaults to null.

void displaySettingsPanel(XMLElement $wrapper, mixed $errors)

Display the default settings panel, calls the buildSummaryBlock function after basic field settings are added to the wrapper.

Parameters

• $wrapper XMLElementthe input XMLElement to which the display of this will be appended.

• $errors mixedthe input error collection. this defaults to null.

See Also

• buildSummaryBlock()

boolean entryDataCleanup(integer|array $entry_id, array $data)

Remove the entry data of this field from the database.

Parameters

• $entry_id integer|arraythe ID of the entry, or an array of entry ID's to delete.

• $data array(optional) The entry data provided for fields to do additional cleanup This is an optional argument and defaults to null.

Returns

Returns true after the cleanup has been completed

boolean exists()

Checks that we are working with a valid field handle and field id, and checks that the field record exists in the settings table.

Returns

true if the field id exists in the table, false otherwise

See Also

• Field::tableExists()

void|integer fetchAssociatedEntryCount(mixed $value)

Fetch the count of the associated entries given a $value.

Parameters

• $value mixedthe value to find the associated entry count for, this usually comes from the fetchAssociatedEntrySearchValue function.

Returns

this default implementation returns void. overriding implementations should return an integer.

See Also

• toolkit.Field#fetchAssociatedEntrySearchValue()

void|array fetchAssociatedEntryIDs(mixed $value)

Fetch the Entry ID's associated with this field instance given a $value, where the $value can be anything. This function is unused by Symphony core but should be implemented by Fields that maintain relationships.

Parameters

• $value mixedthe value to find the associated entry ID's for.

Returns

this default implementation returns void. overriding implementations should return an array of the associated entry ids.

Deprecated

Since Symphony 2.5.0 this method is not called anymore in the core. Please use Field::findRelatedEntries and Field::findParentRelatedEntries instead. This method will be removed in Symphony 3.0

array|string fetchAssociatedEntrySearchValue(array $data, integer $field_id, integer $parent_entry_id)

Accessor to the associated entry search value for this field instance. This default implementation simply returns $data

Parameters

• $data arraythe data from which to construct the associated search entry value, this is usually Entry with the $parent_entry_id value's data.

• $field_id integer(optional) the ID of the field that is the parent in the relationship

• $parent_entry_id integer(optional) the ID of the entry from the parent section in the relationship

Returns

Defaults to returning $data, but overriding implementation should return a string

array fetchFilterableOperators()

Returns the keywords that this field supports for filtering. Note that no filter will do a simple 'straight' match on the value.

array fetchIncludableElements()

Default accessor for the includable elements of this field. This array will populate the Datasource included elements. Fields that have different modes will override this and add new items to the array. The Symphony convention is element_name : mode. Modes allow Fields to output different XML in datasources.

Returns

the array of includable elements from this field.

array fetchSuggestionTypes()

Returns the types of filter suggestion this field supports. The array may contain the following values:

• entry for searching entries in the current section
• association for searching entries in associated sections
• static for searching static values
• date for searching in a calendar

• parameters for searching in parameters

  If the date type is set, only the calendar will be shown in the suggestion dropdown.

void findDefaults(array $settings)

Allows a field to set default settings.

Parameters

• $settings arraythe array of settings to populate with their defaults.

array findParentRelatedEntries(integer $parent_field_id, integer $entry_id)

Find related entries for the current field. Default implementation uses column names entry_id and relation_id as with the Select Box Link

array findRelatedEntries(integer $entry_id, integer $parent_field_id)

Find related entries from a linking field's data table. Default implementation uses column names entry_id and relation_id as with the Select Box Link

null|mixed|array get(string $setting)

Accessor to the a setting by name. If no setting is provided all the settings of this Field instance are returned.

Parameters

• $setting string(optional) the name of the setting to access the value for. This is optional and defaults to null in which case all settings are returned.

Returns

the value of the setting if there is one, all settings if the input setting was omitted or null if the setting was supplied but there is no value for that setting.

array getAssociationContext()

Get association data of the current field from the page context.

XMLElement getExampleFormMarkup()

The default method for constructing the example form markup containing this field when utilized as part of an event. This displays in the event documentation and serves as a basic guide for how markup should be constructed on the Frontend to save this field

Returns

a label widget containing the formatted field element name of this.

string|array getParameterPoolValue(array $data, integer $entry_id)

Function to format this field if it chosen in a data source to be output as a parameter in the XML.

Since Symphony 2.5.0, it will defaults to prepareReadableValue return value.

Parameters

• $data arrayThe data for this field from it's tbl_entry_data_{id} table

• $entry_id integerThe optional id of this field entry instance

Returns

The formatted value to be used as the parameter. Note that this can be an array or a string. When returning multiple values use array, otherwise use string.

array getToggleStates()

Accessor to the toggle states. This default implementation returns an empty array.

Returns

the array of toggle states.

void groupRecords(array $records)

Default implementation of record grouping. This default implementation will throw an Exception. Thus, clients must overload this method for grouping to be successful.

Parameters

• $records arraythe records to group.

string handle()

Accessor to the handle of this field object. The Symphony convention is for field subclass names to be prefixed with field. Handle removes this prefix so that the class handle can be used as the field type.

Returns

The field classname minus the field prefix.

boolean isSortable()

Test whether this field can be sorted. This default implementation returns false.

Returns

true if this field is sortable, false otherwise.

boolean mustBeUnique()

Test whether this field must be unique in a section, that is, only one of this field's type is allowed per section. This default implementation always returns false.

Returns

true if the content of this field must be unique, false otherwise.

string name()

Accessor to the name of this field object. The name may contain characters that normally would be stripped in the handle while also allowing the field name to be localized. If a name is not set, it will return the handle of the the field

Returns

The field name

XMLElement prepareAssociationsDrawerXMLElement(Entry $e, array $parent_association, string $prepopulate)

Format this field value for display in the Associations Drawer publish index. By default, Symphony will use the return value of the prepareReadableValue function.

Parameters

• $e EntryThe associated entry

• $parent_association arrayAn array containing information about the association

• $prepopulate stringA string containing prepopulate parameter to append to the association url

Returns

The XMLElement must be a li node, since it will be added an ul node.

string prepareReadableValue(array $data, integer $entry_id, bool $truncate, string $defaultValue)

Format this field value for display as readable text value. By default, it will call Field::prepareTextValue to get the raw text value of this field.

If $truncate is set to true, Symphony will truncate the value to the configuration setting cell_truncation_length.

Parameters

• $data arrayan associative array of data for this string. At minimum this requires a key of 'value'.

• $entry_id integer(optional) An option entry ID for more intelligent processing. Defaults to null.

• $defaultValue string(optional) The value to use when no plain text representation of the field's data can be made. Defaults to null.

Returns

the readable text summary of the values of this field instance.

string prepareTableValue(array $data, XMLElement $link, integer $entry_id)

Format this field value for display in the publish index tables.

Since Symphony 2.5.0, this function will call Field::prepareReadableValue in order to get the field's human readable value.

Parameters

• $data arrayan associative array of data for this string. At minimum this requires a key of 'value'.

• $link XMLElement(optional) an XML link structure to append the content of this to provided it is not null. it defaults to null.

• $entry_id integer(optional) An option entry ID for more intelligent processing. defaults to null

Returns

the formatted string summary of the values of this field instance.

string prepareTextValue(array $data, integer $entry_id)

Format this field value for complete display as text (string). By default, it looks for the 'value' key in the $data array and strip tags from it.

Parameters

• $data arrayan associative array of data for this string. At minimum this requires a key of 'value'.

• $entry_id integer(optional) An option entry ID for more intelligent processing. defaults to null

Returns

the complete text representation of the values of this field instance.

array processRawFieldData(mixed $data, integer $status, string $message, boolean $simulate, mixed $entry_id)

Process the raw field data.

Parameters

• $data mixedpost data from the entry form

• $status integerthe status code resultant from processing the data.

• $message stringthe place to set any generated error message. any previous value for this variable will be overwritten.

• $simulate boolean(optional) true if this will tell the CF's to simulate data creation, false otherwise. this defaults to false. this is important if clients will be deleting or adding data outside of the main entry object commit function.

• $entry_id mixed(optional) the current entry. defaults to null.

Returns

the processed field data.

void remove(string $setting)

Unset the value of a setting by the key

Parameters

• $setting stringthe key of the setting to unset.

boolean requiresSQLGrouping()

Test whether this field requires grouping. If this function returns true SQL statements generated in the EntryManager will include the DISTINCT keyword to only return a single row for an entry regardless of how many 'matches' it might have. This default implementation returns false.

Returns

true if this field requires grouping, false otherwise.

boolean requiresTable()

Tells Symphony that this field needs a table in order to store data for each of its entries. Used when adding/deleting this field in a section or entries are edited/added, data as a performance optimization. It defaults to true, which force table creation.

Developers are encouraged to update their null create table implementation with this method.

Returns

true if Symphony should call createTable()

See Also

• Field::createTable()

void set(string $setting, mixed $value)

Fields have settings that define how that field will act in a section, including if it's required, any validators, if it can be shown on the entries table etc. This function will set a setting to a value. This function will set a setting to a value overwriting any existing value for this setting

Parameters

• $setting stringthe setting key.

• $value mixedthe value of the setting.

void setArray(array $array)

Add or overwrite the settings of this field by providing an associative array of the settings. This will do nothing if the input array is empty. If a setting is omitted from the input array, it will not be unset by this function

Parameters

• $array arraythe associative array of settings for this field

void setAssociationContext(XMLElement $wrapper)

Set association data for the current field.

void setFromPOST(array $settings)

Fill the input data array with default values for known keys provided these settings are not already set. The input array is then used to set the values of the corresponding settings for this field. This function is called when a section is saved.

Parameters

• $settings arraythe data array to initialize if necessary.

boolean tableExists()

Checks that we are working with a valid field handle and that the setting table exists.

Returns

true if the table exists, false otherwise

boolean tearDown()

Just prior to the field being deleted, this function allows Fields to cleanup any additional things before it is removed from the section. This may be useful to remove data from any custom field tables or the configuration.

array toggleFieldData(array $data, string $newState, integer $entry_id)

Toggle the field data. This default implementation always returns the input data.

Parameters

• $data arraythe data to toggle.

• $newState stringthe new value to set

• $entry_id integer(optional) an optional entry ID for more intelligent processing. defaults to null

Returns

the toggled data.