- Symphony 2.6.5
-
› assets
14 -
› boot
14 -
› core
23 -
› cryptography
4 -
› data-sources
6 -
› email-gateways
3 -
› events
3 -
› global
61 -
› interface
9 -
› toolkit
60 - Delegates92
- Deprecated26
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()
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
void appendFormattedElement(XMLElement $wrapper, $data, $encode, $mode, $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
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
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.
See Also
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)
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 buildRegexSQL(
$filter, $columns, $joins, $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
See Also
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, $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
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(
$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.
static XMLElement createAssociationsDrawerXMLElement(Entry $e, $parent_association, $prepopulate)
$value,
This is general purpose factory method that makes it easier to create the markup needed in order to create an Associations Drawer XMLElement.
Parameters
Returns
The XMLElement must be a li node, since it will be added an ul node.
XMLElement createCheckboxSetting(XMLElement $wrapper, $setting, $label_description, $help)
Given the setting name and the label, this helper method will add
the required markup for a checkbox to the given $wrapper
.
Parameters
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.
void displayDatasourceFilterPanel(XMLElement $wrapper, $data, $errors, $fieldnamePrefix, $fieldnamePostfix)
Display the default data-source filter panel.
Parameters
void displayFilteringOptions(XMLElement $wrapper)
Inserts tags at the bottom of the filter panel
void displayPublishPanel(XMLElement $wrapper, $data, $flagWithError, $fieldnamePrefix, $fieldnamePostfix, $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
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.
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(
$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 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 sectionassociation
for searching entries in associated sectionsstatic
for searching static valuesdate
for searching in a calendarparameters
for searching in parametersIf the date type is set, only the calendar will be shown in the suggestion dropdown.
void findDefaults(
$settings)
Allows a field to set default settings.
Parameters
array findParentRelatedEntries(
$field_id, $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(
$entry_id, $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(
$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.
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(
$data, $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
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(
$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
XMLElement prepareAssociationsDrawerXMLElement(Entry $e, $parent_association, $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
Returns
The XMLElement must be a li node, since it will be added an ul node.
string prepareReadableValue(
$data, $entry_id, $truncate, $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
Returns
the readable text summary of the values of this field instance.
string prepareTableValue(XMLElement $link, $entry_id)
$data,
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
Returns
the formatted string summary of the values of this field instance.
string prepareTextValue(
$data, $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
Returns
the complete text representation of the values of this field instance.
array processRawFieldData(
$data, $status, $message, $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
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(
$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 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
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 setAssociationContext(XMLElement $wrapper)
Set association data for the current field.
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.