public class Field

class.field.php #13

The Field class represents a Symphony Field object. Fields are the building blocks for Sections. All fields instances are unique and can only be used once in a Symphony install. Fields have their own field table which records where instances of this field type have been used in other sections and their settings. They also spinoff other tbl_entry_data_{id} tables that actually store data for entries particular to this field.

Methods

void __construct(mixed $parent)

Construct a new instance of this field.

Parameters
  • $parent mixedThe class that created this Field object, usually the FieldManager, passed by reference.

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 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.

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 labelled 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.

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 arraythe supplied form data to use to construct the query from

  • $joins stringthe join sql statement fragment to append the additional join sql to.

  • $where stringthe where condition sql statement fragment to which the additional where conditions will be appended.

  • $andOperation boolean(optional) true if the values of the input data should be appended as part of the where condition. this defaults to false.

Returns

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

void buildDSRetrivalSQL(mixed $data, mixed $joins, mixed $where, bool $andOperation)
Deprecated

This function name has a typo that has withstood many versions of Symphony. The correct function is $this->buildDSRetrievalSQL.

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(mixed $selected, string $name, string $label_value, string $selection)

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
  • $selection string(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 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.

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.

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
void buildValidationSelect(XMLElement $wrapper, mixed $selected, string $name, string $type, string $selection)

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.

  • $selection 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'.

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 canImport()

Test whether this field can be imported. This default implementation prohibits importing. Subclasses should override this is importing is supported.

Returns

true if this can be imported, false otherwise.

Deprecated

This function will be removed in the next major release. It is unused by Symphony.

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 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.

boolean createSectionAssociation(integer $parent_section_id, integer $child_field_id, integer $parent_field_id, boolean $show_association)

Create an association between a section and a field.

Parameters
  • $parent_section_id integerThe linked section id.

  • $child_field_id integerThe field ID of the field that is creating the association

  • $parent_field_id integer(optional) The field ID of the linked field in the linked section

  • $show_association boolean(optional) Whether of not the link should be shown on the entries table of the linked section. This defaults to true.

Returns

true if the association was successfully made, false otherwise.

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.

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

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 mixed(optional) the input error collection. this defaults to null.

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

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

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

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.

  • $fieldnameSuffix 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 mixed(optional) the input error collection. this defaults to null.

See Also
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

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
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.

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 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.

void findDefaults(array $settings)

Allows a field to set default settings.

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

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.

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 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

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

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

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

Format this field value for display in the publish index tables. By default, Symphony will truncate the value to the configuration setting cell_truncation_length. This function will attempt to use PHP's mbstring functions if they are available.

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.

array processRawFieldData(mixed $data, integer $status, 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.

  • $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.

void removeSectionAssociation(integer $child_field_id)

Permanently remove a section association for this field in the database.

Parameters
  • $child_field_id integerthe field ID of the linked section's linked field.

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.

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 tableetc. 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 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 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.

Symphony • Open Source XSLT CMS

Server Requirements

  • PHP 5.3-5.6 or 7.0-7.3
  • PHP's LibXML module, with the XSLT extension enabled (--with-xsl)
  • MySQL 5.5 or above
  • An Apache or Litespeed webserver
  • Apache's mod_rewrite module or equivalent

Compatible Hosts

Sign in

Login details