- Symphony 2.2.3
-
› assets
11 -
› boot
9 -
› core
22 -
› email-gateways
3 -
› toolkit
67 -
› Unknown
33 - Delegates87
- Deprecated30
Versions
- 2.7.9
- 2.7.8
- 2.7.7
- 2.7.6
- 2.7.5
- 2.7.3
- 2.7.2
- 2.7.10
- 2.7.1
- 2.7.0
- 2.6.9
- 2.6.8
- 2.6.7
- 2.6.6
- 2.6.5
- 2.6.4
- 2.6.3
- 2.6.2
- 2.6.11
- 2.6.10
- 2.6.1
- 2.6.0
- 2.5.3
- 2.5.2
- 2.5.1
- 2.5.0
- 2.4
- 2.3.6
- 2.3.5
- 2.3.4
- 2.3.3
- 2.3.2
- 2.3.1
- 2.3
- 2.2.5
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2
Options
public class Field
class.field.php #13The 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(
$parent)
Construct a new instance of this field.
Parameters
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, $data, $encode, $mode, $entry_id)
Append the formatted xml output of this field as utilized as a data source.
Parameters
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
void appendShowAssociationCheckbox(XMLElement $wrapper, $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
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
boolean buildDSRetrievalSQL(
$data, $joins, $where, $andOperation)
Construct the SQL statement fragments to use to retrieve the data of this field when utilized as a data source.
Parameters
Returns
true if the construction of the sql was successful, false otherwise.
void buildDSRetrivalSQL(
$data, $joins, $where, $andOperation)
Deprecated
This function name has a typo that has withstood many versions of Symphony. The correct function is $this->buildDSRetrievalSQL
.
XMLElement buildFormatterSelect(
$selected, $name, $label_value)
Construct the html widget for selecting a text formatter for this field.
Parameters
Returns
An XMLElement representing a <select>
field containing the options.
XMLElement buildLocationSelect(
$selected, $name, $label_value, $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
Returns
An XMLElement representing a <select>
field containing the options.
void buildSortingSQL(
$joins, $where, $sort, $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
XMLElement buildSummaryBlock(
$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
Returns
the root xml element of the html display of this.
See Also
void buildValidationSelect(XMLElement $wrapper, $selected, $name, $type, $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
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(
$errors, $checkForDuplicates)
Check the field's settings to ensure they are valid on the section editor
Parameters
Returns
returns the status of the checking. if errors has been populated with any errors self::__ERROR__
, self::__OK__
otherwise.
integer checkPostFieldData(
$data, $message, $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
Returns
self::__MISSING_FIELDS__
if there are any missing required fields, self::__OK__
otherwise.
string cleanValue(
$value)
Clean the input value using html entity encode and the database specific clean methods.
Parameters
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(
$parent_section_id, $child_field_id, $parent_field_id, $show_association)
Create an association between a section and a field.
Parameters
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, $data, $errors, $fieldnamePrefix, $fieldnamePostfix, $fieldNamePrefix, $fieldNameSuffix)
Display the default data-source filter panel.
Parameters
void displayPublishPanel(XMLElement $wrapper, $data, $flagWithError, $fieldnamePrefix, $fieldnamePostfix, $entry_id, $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
void displaySettingsPanel(XMLElement $wrapper, $errors)
Display the default settings panel, calls the buildSummaryBlock
function after basic field settings are added to the wrapper.
Parameters
See Also
boolean entryDataCleanup(
$entry_id, $data)
Remove the entry data of this field from the database.
Parameters
Returns
Returns true after the cleanup has been completed
void|integer fetchAssociatedEntryCount(
$value)
Fetch the count of the associated entries given a $value
.
Parameters
Returns
this default implementation returns void. overriding implementations should return an integer.
See Also
void|array fetchAssociatedEntryIDs(
$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
Returns
this default implementation returns void. overriding implementations should return an array of the associated entry ids.
array|string fetchAssociatedEntrySearchValue(
$data, $field_id, $parent_entry_id)
Accessor to the associated entry search value for this field
instance. This default implementation simply returns $data
Parameters
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(
$settings)
Allows a field to set default settings.
Parameters
null|mixed|array get(
$setting)
Accessor to the a setting by name. If no setting is provided all the settings of this Field instance are returned.
Parameters
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(
$data, $entry_id)
Function to format this field if it chosen in a data-source to be output as a parameter in the XML
Parameters
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(
$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
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(XMLElement $link, $entry_id)
$data,
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
Returns
the formatted string summary of the values of this field instance.
array processRawFieldData(
$data, $status, $simulate, $entry_id)
Process the raw field data.
Parameters
Returns
the processed field data.
void remove(
$setting)
Unset the value of a setting by the key
Parameters
void removeSectionAssociation(
$child_field_id)
Permanently remove a section association for this field in the database.
Parameters
boolean requiresSQLGrouping()
Test whether this field requires grouping. This default implementation returns false.
Returns
true if this field requires grouping, false otherwise.
void set(
$setting, $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
void setArray(
$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
void setFromPOST(
$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
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(
$data, $newState, $entry_id)
Toggle the field data. This default implementation always returns the input data.
Parameters
Returns
the toggled data.