/**
* Get a field value of the table row that is represented by this object.
*
* @param string $ps_field field name
* @param array $pa_options options array; can be omitted.
* It should be an associative array of boolean (except one of the options) flags. In case that some of the options are not set, they are treated as 'false'.
* Possible options (keys) are:
* BINARY: return field value as is
* FILTER_HTML_SPECIAL_CHARS: convert all applicable chars to their html entities
* DONT_PROCESS_GLOSSARY_TAGS: ?
* CONVERT_HTML_BREAKS: similar to nl2br()
* convertLineBreaks: same as CONVERT_HTML_BREAKS
* getDirectDate: return raw date value from database if $ps_field adresses a date field, otherwise the value will be parsed using the TimeExpressionParser::getText() method
* getDirectTime: return raw time value from database if $ps_field adresses a time field, otherwise the value will be parsed using the TimeExpressionParser::getText() method
* TIMECODE_FORMAT: set return format for fields representing time ranges possible (string) values: COLON_DELIMITED, HOURS_MINUTES_SECONDS, RAW; data will be passed through floatval() by default
* QUOTE: set return value into quotes
* URL_ENCODE: value will be passed through urlencode()
* ESCAPE_FOR_XML: convert <, >, &, ' and " characters for XML use
* DONT_STRIP_SLASHES: if set to true, return value will not be passed through stripslashes()
* template: formatting string to use for returned value; ^<fieldname> placeholder is used to represent field value in template
* returnAsArray: if true, fields that can return multiple values [currently only <table_name>.children.<field>] will return values in an indexed array; default is false
* returnAllLocales:
* delimiter: if set, value is used as delimiter when fields that can return multiple fields are returned as strings; default is a single space
* convertCodesToDisplayText: if set, id values refering to foreign keys are returned as preferred label text in the current locale
* returnURL: if set then url is returned for media, otherwise an HTML tag for display is returned
* dateFormat: format to return created or lastModified dates in. Valid values are iso8601 or text
* checkAccess = array of access values to filter results by; if defined only items with the specified access code(s) are returned. Only supported for table that have an "access" field.
* sort = optional field to sort returned values on. The field specifiers are fields with or without table name specified.
* sort_direction = direction to sort results by, either 'asc' for ascending order or 'desc' for descending order; default is 'asc'
*/
public function get($ps_field, $pa_options = null)
{
if (!$ps_field) {
return null;
}
if (!is_array($pa_options)) {
$pa_options = array();
}
$vb_return_as_array = caGetOption('returnAsArray', $pa_options, false);
$vb_return_with_structure = caGetOption('returnWithStructure', $pa_options, false);
$vb_return_all_locales = caGetOption('returnAllLocales', $pa_options, false);
$vs_delimiter = caGetOption('delimiter', $pa_options, ' ');
if (($vb_return_with_structure || $vb_return_all_locales) && !$vb_return_as_array) {
$vb_return_as_array = true;
}
$vn_row_id = $this->getPrimaryKey();
if ($vb_return_as_array && $vb_return_as_array) {
$vn_locale_id = $this->hasField('locale_id') ? $this->get('locale_id') : null;
}
$va_tmp = explode('.', $ps_field);
if (sizeof($va_tmp) > 1) {
if ($va_tmp[0] === $this->tableName()) {
//
// Return created on or last modified
//
if (in_array($va_tmp[1], array('created', 'lastModified'))) {
if ($vb_return_as_array) {
return $va_tmp[1] == 'lastModified' ? $this->getLastChangeTimestamp() : $this->getCreationTimestamp();
} else {
$va_data = $va_tmp[1] == 'lastModified' ? $this->getLastChangeTimestamp() : $this->getCreationTimestamp();
$vs_subfield = isset($va_tmp[2]) && isset($va_data[$va_tmp[2]]) ? $va_tmp[2] : 'timestamp';
$vm_val = $va_data[$vs_subfield];
if ($vs_subfield == 'timestamp') {
$o_tep = new TimeExpressionParser();
$o_tep->setUnixTimestamps($vm_val, $vm_val);
$vm_val = $o_tep->getText($pa_options);
}
return $vm_val;
}
}
//
// Generalized get
//
$va_field_info = $this->getFieldInfo($va_tmp[1]);
switch (sizeof($va_tmp)) {
case 2:
// support <table_name>.<field_name> syntax
$ps_field = $va_tmp[1];
break;
default:
// > 2 elements
// media field?
if ($va_field_info['FIELD_TYPE'] === FT_MEDIA && !isset($pa_options['returnAsArray']) && !$pa_options['returnAsArray']) {
$o_media_settings = new MediaProcessingSettings($va_tmp[0], $va_tmp[1]);
$va_versions = $o_media_settings->getMediaTypeVersions('*');
$vs_version = $va_tmp[2];
if (!isset($va_versions[$vs_version])) {
$va_available_versions = array_keys($va_versions);
$vs_version = $va_tmp[2] = array_shift($va_available_versions);
}
if (isset($va_tmp[3])) {
return $this->getMediaInfo($va_tmp[1], $vs_version, 'width');
} else {
if (isset($pa_options['returnURL']) && $pa_options['returnURL']) {
return $this->getMediaUrl($va_tmp[1], $vs_version, $pa_options);
} else {
return $this->getMediaTag($va_tmp[1], $vs_version, $pa_options);
}
}
}
if ($va_tmp[1] == 'parent' && $this->isHierarchical() && ($vn_parent_id = $this->get($this->getProperty('HIERARCHY_PARENT_ID_FLD')))) {
$t_instance = $this->getAppDatamodel()->getInstanceByTableNum($this->tableNum());
if (!$t_instance->load($vn_parent_id)) {
return $vb_return_as_array ? array() : null;
} else {
unset($va_tmp[1]);
$va_tmp = array_values($va_tmp);
if ($vb_return_as_array) {
if ($vb_return_all_locales) {
return array($vn_row_id => array($vn_locale_id => array($t_instance->get(join('.', $va_tmp)))));
} else {
return array($vn_row_id => $t_instance->get(join('.', $va_tmp)));
}
} else {
return $t_instance->get(join('.', $va_tmp));
}
}
} else {
if ($va_tmp[1] == 'children' && $this->isHierarchical()) {
$vb_check_access = is_array($pa_options['checkAccess']) && $this->hasField('access');
$va_sort = isset($pa_options['sort']) ? $pa_options['sort'] : null;
if (!is_array($va_sort) && $va_sort) {
$va_sort = array($va_sort);
}
if (!is_array($va_sort)) {
$va_sort = array();
}
$vs_sort_direction = isset($pa_options['sort_direction']) && in_array(strtolower($pa_options['sort_direction']), array('asc', 'desc')) ? strtolower($pa_options['sort_direction']) : 'asc';
unset($va_tmp[1]);
// remove 'children' from field path
$va_tmp = array_values($va_tmp);
$vs_childless_path = join('.', $va_tmp);
$va_data = array();
$va_children_ids = $this->getHierarchyChildren(null, array('idsOnly' => true));
if (is_array($va_children_ids) && sizeof($va_children_ids)) {
$t_instance = $this->getAppDatamodel()->getInstanceByTableNum($this->tableNum());
if ($va_tmp[1] == $this->primaryKey() && !$vs_sort) {
foreach ($va_children_ids as $vn_child_id) {
$va_data[$vn_child_id] = $vn_child_id;
}
} else {
if (method_exists($this, "makeSearchResult")) {
// Use SearchResult lazy loading when available
$vs_table = $this->tableName();
$vs_pk = $vs_table . '.' . $this->primaryKey();
$qr_children = $this->makeSearchResult($this->tableName(), $va_children_ids);
while ($qr_children->nextHit()) {
if ($vb_check_access && !in_array($qr_children->get("{$vs_table}.access"), $pa_options['checkAccess'])) {
continue;
}
$vn_child_id = $qr_children->get($vs_pk);
$vs_sort_key = '';
foreach ($va_sort as $vs_sort) {
$vs_sort_key .= $vs_sort ? $qr_children->get($vs_sort) : 0;
}
if (!is_array($va_data[$vs_sort_key])) {
$va_data[$vs_sort_key] = array();
}
if ($vb_return_as_array) {
$va_data[$vs_sort_key][$vn_child_id] = array_shift($qr_children->get($vs_childless_path, array_merge($pa_options, array('returnAsArray' => $vb_return_as_array, 'returnAllLocales' => $vb_return_all_locales))));
} else {
$va_data[$vs_sort_key][$vn_child_id] = $qr_children->get($vs_childless_path, array_merge($pa_options, array('returnAsArray' => false, 'returnAllLocales' => false)));
}
}
ksort($va_data);
if ($vs_sort_direction && $vs_sort_direction == 'desc') {
$va_data = array_reverse($va_data);
}
$va_sorted_data = array();
foreach ($va_data as $vs_sort_key => $va_items) {
foreach ($va_items as $vs_k => $vs_v) {
$va_sorted_data[] = $vs_v;
}
}
$va_data = $va_sorted_data;
} else {
// Fall-back to loading records row-by-row (slow)
foreach ($va_children_ids as $vn_child_id) {
if ($t_instance->load($vn_child_id)) {
if ($vb_check_access && !in_array($t_instance->get("access"), $pa_options['checkAccess'])) {
continue;
}
$vs_sort_key = $vs_sort ? $t_instance->get($vs_sort) : 0;
if (!is_array($va_data[$vs_sort_key])) {
$va_data[$vs_sort_key] = array();
}
if ($vb_return_as_array) {
$va_data[$vs_sort_key][$vn_child_id] = array_shift($t_instance->get($vs_childless_path, array_merge($pa_options, array('returnAsArray' => $vb_return_as_array, 'returnAllLocales' => $vb_return_all_locales))));
} else {
$va_data[$vs_sort_key][$vn_child_id] = $t_instance->get($vs_childless_path, array_merge($pa_options, array('returnAsArray' => false, 'returnAllLocales' => false)));
}
}
}
ksort($va_data);
if ($vs_sort_direction && $vs_sort_direction == 'desc') {
$va_data = array_reverse($va_data);
}
$va_sorted_data = array();
foreach ($va_data as $vs_sort_key => $va_items) {
foreach ($va_items as $vs_k => $vs_v) {
$va_sorted_data[] = $vs_v;
}
}
$va_data = $va_sorted_data;
}
}
}
if ($vb_return_as_array) {
return $va_data;
} else {
return join($vs_delimiter, $va_data);
}
}
}
break;
}
} else {
$va_rels = $this->getRelatedItems($va_tmp[0]);
$va_vals = array();
if (is_array($va_rels)) {
foreach ($va_rels as $va_rel_item) {
if (isset($va_rel_item[$va_tmp[1]])) {
$va_vals[] = $va_rel_item[$va_tmp[1]];
}
}
return $vb_return_as_array ? $va_vals : join($vs_delimiter, $va_vals);
}
// can't pull fields from other tables!
return $vb_return_as_array ? array() : null;
}
}
if (isset($pa_options["BINARY"]) && $pa_options["BINARY"]) {
return $this->_FIELD_VALUES[$ps_field];
}
if (array_key_exists($ps_field, $this->FIELDS)) {
$ps_field_type = $this->getFieldInfo($ps_field, "FIELD_TYPE");
if ($this->getFieldInfo($ps_field, 'IS_LIFESPAN')) {
$pa_options['isLifespan'] = true;
}
switch ($ps_field_type) {
case FT_BIT:
$vs_prop = isset($this->_FIELD_VALUES[$ps_field]) ? $this->_FIELD_VALUES[$ps_field] : "";
if (isset($pa_options['convertCodesToDisplayText']) && $pa_options['convertCodesToDisplayText']) {
$vs_prop = (bool) $vs_prop ? _t('yes') : _t('no');
}
return $vs_prop;
break;
case FT_TEXT:
case FT_NUMBER:
case FT_PASSWORD:
$vs_prop = isset($this->_FIELD_VALUES[$ps_field]) ? $this->_FIELD_VALUES[$ps_field] : null;
if (isset($pa_options["FILTER_HTML_SPECIAL_CHARS"]) && $pa_options["FILTER_HTML_SPECIAL_CHARS"]) {
$vs_prop = htmlentities(html_entity_decode($vs_prop));
}
//
// Convert foreign keys and choice list values to display text is needed
//
if (isset($pa_options['convertCodesToDisplayText']) && $pa_options['convertCodesToDisplayText'] && ($vs_list_code = $this->getFieldInfo($ps_field, "LIST_CODE"))) {
$t_list = new ca_lists();
$vs_prop = $t_list->getItemFromListForDisplayByItemID($vs_list_code, $vs_prop);
} else {
if (isset($pa_options['convertCodesToDisplayText']) && $pa_options['convertCodesToDisplayText'] && ($vs_list_code = $this->getFieldInfo($ps_field, "LIST"))) {
$t_list = new ca_lists();
if (!($vs_tmp = $t_list->getItemFromListForDisplayByItemValue($vs_list_code, $vs_prop))) {
if ($vs_tmp = $this->getChoiceListValue($ps_field, $vs_prop)) {
$vs_prop = $vs_tmp;
}
} else {
$vs_prop = $vs_tmp;
}
} else {
if (isset($pa_options['convertCodesToDisplayText']) && $pa_options['convertCodesToDisplayText'] && $ps_field === 'locale_id' && (int) $vs_prop > 0) {
$t_locale = new ca_locales($vs_prop);
$vs_prop = $t_locale->getName();
} else {
if (isset($pa_options['convertCodesToDisplayText']) && $pa_options['convertCodesToDisplayText'] && is_array($va_list = $this->getFieldInfo($ps_field, "BOUNDS_CHOICE_LIST"))) {
foreach ($va_list as $vs_option => $vs_value) {
if ($vs_value == $vs_prop) {
$vs_prop = $vs_option;
break;
}
}
}
}
}
}
if (isset($pa_options["CONVERT_HTML_BREAKS"]) && $pa_options["CONVERT_HTML_BREAKS"] || isset($pa_options["convertLineBreaks"]) && $pa_options["convertLineBreaks"]) {
$vs_prop = caConvertLineBreaks($vs_prop);
}
break;
case FT_DATETIME:
case FT_TIMESTAMP:
case FT_HISTORIC_DATETIME:
case FT_HISTORIC_DATE:
case FT_DATE:
$vn_timestamp = isset($this->_FIELD_VALUES[$ps_field]) ? $this->_FIELD_VALUES[$ps_field] : 0;
if ($vb_return_with_structure) {
$vs_prop = array('start' => $this->_FIELD_VALUES[$ps_field], 'end' => $this->_FIELD_VALUES[$ps_field]);
} elseif (caGetOption('GET_DIRECT_DATE', $pa_options, false) || caGetOption('getDirectDate', $pa_options, false) || caGetOption('rawDate', $pa_options, false)) {
$vs_prop = $this->_FIELD_VALUES[$ps_field];
} elseif (isset($pa_options['sortable']) && $pa_options['sortable']) {
$vs_prop = $vn_timestamp . "/" . $vn_timestamp;
} else {
$o_tep = new TimeExpressionParser();
if ($ps_field_type == FT_HISTORIC_DATETIME || $ps_field_type == FT_HISTORIC_DATE) {
$o_tep->setHistoricTimestamps($vn_timestamp, $vn_timestamp);
} else {
$o_tep->setUnixTimestamps($vn_timestamp, $vn_timestamp);
}
if ($ps_field_type == FT_DATE || $ps_field_type == FT_HISTORIC_DATE) {
$vs_prop = $o_tep->getText(array_merge(array('timeOmit' => true), $pa_options));
} else {
$vs_prop = $o_tep->getText($pa_options);
}
}
break;
case FT_TIME:
if ($vb_return_with_structure) {
$vs_prop = array('start' => $this->_FIELD_VALUES[$ps_field], 'end' => $this->_FIELD_VALUES[$ps_field]);
} elseif (caGetOption('GET_DIRECT_TIME', $pa_options, false) || caGetOption('getDirectTime', $pa_options, false) || caGetOption('rawTime', $pa_options, false)) {
$vs_prop = $this->_FIELD_VALUES[$ps_field];
} else {
$o_tep = new TimeExpressionParser();
$vn_timestamp = isset($this->_FIELD_VALUES[$ps_field]) ? $this->_FIELD_VALUES[$ps_field] : 0;
$o_tep->setTimes($vn_timestamp, $vn_timestamp);
$vs_prop = $o_tep->getText($pa_options);
}
break;
case FT_DATERANGE:
case FT_HISTORIC_DATERANGE:
$vs_start_field_name = $this->getFieldInfo($ps_field, "START");
$vs_end_field_name = $this->getFieldInfo($ps_field, "END");
$vn_start_date = isset($this->_FIELD_VALUES[$vs_start_field_name]) ? $this->_FIELD_VALUES[$vs_start_field_name] : null;
$vn_end_date = isset($this->_FIELD_VALUES[$vs_end_field_name]) ? $this->_FIELD_VALUES[$vs_end_field_name] : null;
if ($vb_return_with_structure) {
$vs_prop = array('start' => $vn_start_date, 'end' => $vn_end_date);
} elseif (!caGetOption('GET_DIRECT_DATE', $pa_options, false) && !caGetOption('getDirectDate', $pa_options, false) && !caGetOption('rawDate', $pa_options, false)) {
$o_tep = new TimeExpressionParser();
if ($ps_field_type == FT_HISTORIC_DATERANGE) {
$o_tep->setHistoricTimestamps($vn_start_date, $vn_end_date);
} else {
$o_tep->setUnixTimestamps($vn_start_date, $vn_end_date);
}
$vs_prop = $o_tep->getText($pa_options);
} elseif (isset($pa_options['sortable']) && $pa_options['sortable']) {
$vs_prop = $vn_start_date;
//."/".$vn_timestamp;
} else {
$vs_prop = $vn_start_date;
//array($vn_start_date, $vn_end_date);
}
break;
case FT_TIMERANGE:
$vs_start_field_name = $this->getFieldInfo($ps_field, "START");
$vs_end_field_name = $this->getFieldInfo($ps_field, "END");
$vn_start_date = isset($this->_FIELD_VALUES[$vs_start_field_name]) ? $this->_FIELD_VALUES[$vs_start_field_name] : null;
$vn_end_date = isset($this->_FIELD_VALUES[$vs_end_field_name]) ? $this->_FIELD_VALUES[$vs_end_field_name] : null;
if ($vb_return_with_structure) {
$vs_prop = array('start' => $vn_start_date, 'end' => $vn_end_date);
} elseif (!caGetOption('GET_DIRECT_TIME', $pa_options, false) && !caGetOption('getDirectTime', $pa_options, false) && !caGetOption('rawTime', $pa_options, false)) {
$o_tep = new TimeExpressionParser();
$o_tep->setTimes($vn_start_date, $vn_end_date);
$vs_prop = $o_tep->getText($pa_options);
} else {
$vs_prop = array($vn_start_date, $vn_end_date);
}
break;
case FT_TIMECODE:
$o_tp = new TimecodeParser();
$o_tp->setParsedValueInSeconds($this->_FIELD_VALUES[$ps_field]);
$vs_prop = $o_tp->getText(isset($pa_options["TIMECODE_FORMAT"]) ? $pa_options["TIMECODE_FORMAT"] : null);
break;
case FT_MEDIA:
case FT_FILE:
if ($vb_return_with_structure || $pa_options["USE_MEDIA_FIELD_VALUES"]) {
if (isset($pa_options["USE_MEDIA_FIELD_VALUES"]) && $pa_options["USE_MEDIA_FIELD_VALUES"]) {
$vs_prop = $this->_FIELD_VALUES[$ps_field];
} else {
$vs_prop = isset($this->_SET_FILES[$ps_field]['tmp_name']) && $this->_SET_FILES[$ps_field]['tmp_name'] ? $this->_SET_FILES[$ps_field]['tmp_name'] : $this->_FIELD_VALUES[$ps_field];
}
} else {
$va_versions = $this->getMediaVersions($ps_field);
$vs_tag = $this->getMediaTag($ps_field, array_shift($va_versions));
if ($vb_return_as_array) {
return array($vs_tag);
} else {
return $vs_tag;
}
}
break;
case FT_VARS:
$vs_prop = isset($this->_FIELD_VALUES[$ps_field]) && $this->_FIELD_VALUES[$ps_field] ? $this->_FIELD_VALUES[$ps_field] : null;
break;
}
if (isset($pa_options["QUOTE"]) && $pa_options["QUOTE"]) {
$vs_prop = $this->quote($ps_field, $vs_prop);
}
} else {
$this->postError(710, _t("'%1' does not exist in this object", $ps_field), "BaseModel->get()");
return $vb_return_as_array ? array() : null;
}
if (isset($pa_options["URL_ENCODE"]) && $pa_options["URL_ENCODE"]) {
$vs_prop = urlEncode($vs_prop);
}
if (isset($pa_options["ESCAPE_FOR_XML"]) && $pa_options["ESCAPE_FOR_XML"]) {
$vs_prop = caEscapeForXML($vs_prop);
}
if (!(isset($pa_options["DONT_STRIP_SLASHES"]) && $pa_options["DONT_STRIP_SLASHES"])) {
if (is_string($vs_prop)) {
$vs_prop = stripSlashes($vs_prop);
}
}
if (isset($pa_options["template"]) && $pa_options["template"]) {
$vs_template_with_substitution = str_replace("^" . $ps_field, $vs_prop, $pa_options["template"]);
$vs_prop = str_replace("^" . $this->tableName() . "." . $ps_field, $vs_prop, $vs_template_with_substitution);
}
if ($vb_return_as_array) {
if ($vb_return_all_locales) {
return array($vn_row_id => array($vn_locale_id => array($vs_prop)));
} else {
return array($vn_row_id => $vs_prop);
}
} else {
return $vs_prop;
}
}
