Semantic MediaWiki and related extensions
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
SMWDataValue Class Reference

Public Member Functions

 __construct ($typeid)
 
 setUserValue ($value, $caption=false)
 
 setDataItem (SMWDataItem $dataItem)
 
 setDataValueServiceFactory ($dataValueServiceFactory)
 
 setProperty (SMWDIProperty $property)
 
 getProperty ()
 
 setContextPage (SMWDIWikiPage $contextPage=null)
 
 getContextPage ()
 
 setOptions (Options $options=null)
 
 setOption ($key, $value)
 
 getOption ($key)
 
 isEnabledFeature ($feature)
 
 setCaption ($caption)
 
 getCaption ()
 
 getPreferredCaption ()
 
 setOutputFormat ($formatString)
 
 getOutputFormat ()
 
 addError ($error)
 
 addErrorMsg ($parameters, $type=null)
 
 clearErrors ()
 
 getQueryDescription ($value)
 
 getDataItem ()
 
 __toString ()
 
 getShortWikiText ($linked=null)
 
 getShortHTMLText ($linker=null)
 
 getLongWikiText ($linked=null)
 
 getLongHTMLText ($linker=null)
 
 getShortText ($outputformat, $linker=null)
 
 getLongText ($outputformat, $linker=null)
 
 getInfolinkText ($outputformat, $linker=null)
 
 getWikiValue ()
 
 getTypeID ()
 
 getInfolinks ()
 
 getHash ()
 
 isNumeric ()
 
 isValid ()
 
 canUse ()
 
 getExtraneousFunctionFor ($name, array $parameters=array())
 
 getErrorText ()
 
 getErrors ()
 

Static Public Member Functions

static prepareValue (&$value, &$comparator)
 

Public Attributes

const OPT_USER_LANGUAGE = 'user.language'
 
const OPT_CONTENT_LANGUAGE = 'content.language'
 
const OPT_QUERY_CONTEXT = 'query.context'
 
const OPT_QUERY_COMP_CONTEXT = 'query.comparator.context'
 
const OPT_DISABLE_INFOLINKS = 'disable.infolinks'
 

Protected Member Functions

 parseUserValue ($value)
 
 loadDataItem (SMWDataItem $dataItem)
 
 getServiceLinkParams ()
 
 checkAllowedValues ()
 
 getOptions ()
 

Protected Attributes

 $m_dataitem
 
 $m_property = null
 
 $m_contextPage = null
 
 $m_caption
 
 $m_typeid
 
 $m_outformat = false
 
 $dataValueServiceFactory
 

Detailed Description

Objects of this type represent all that is known about a certain user-provided data value, especially its various representations as strings, tooltips, numbers, etc. Objects can be created as "emtpy" containers of a certain type, but are then usually filled with data to present one particular data value.

Data values have two chief representation forms: the user-facing syntax and the internal representation. In user syntax, every value is (necessarily) a single string, however complex the value is. For example, a string such as "Help:editing" may represent a wiki page called "Editing" in the namespace for "Help". The internal representation may be any numerical array of strings and numbers. In the example, it might be array("Editing",12), where 12 is the number used for identifying the namespace "Help:". Of course, the internal representation could also use a single string value, such as in array("Help:Editing"), but this might be less useful for certain operations (e.g. filterng by namespace). Moreover, all values that are restored from the database are given in the internal format, so it wise to choose a format that allows for very fast and easy processing without unnecessary parsing.

The main functions of data value objects are:

In addition, there are a number of get-functions that provide useful output versions for displaying and serializing the value.

Author
Markus Krötzsch

Constructor & Destructor Documentation

SMWDataValue::__construct (   $typeid)

Constructor.

Parameters
string$typeid

Member Function Documentation

SMWDataValue::__toString ( )
Since
2.2
Returns
string
SMWDataValue::addError (   $error)

Add a new error string or array of such strings to the error list.

Note
Errors should not be escaped here in any way, in contradiction to what the docs used to say here in 1.5 and before. Escaping should happen at the output.
Parameters
mixed$errorA single string, or array of strings.
SMWDataValue::addErrorMsg (   $parameters,
  $type = null 
)

Messages are not resolved until the output and instead will be kept with the message and argument keys (e.g. [2,"smw_baduri","~*0123*"]). This allows to switch the a representation without requiring language context by the object that reports an error.

Since
2.4
Parameters
$parameters
integer | null$type
integer | null$language
SMWDataValue::canUse ( )

Whether a datavalue can be used or not (can be made more restrictive then isValid).

Note
Validity defines a processable state without any technical restrictions while usability is determined by its accessibility to a context (permission, convention etc.)
Since
2.2
Returns
boolean
SMWDataValue::checkAllowedValues ( )
protected

Check if property is range restricted and, if so, whether the current value is allowed. Creates an error if the value is illegal.

SMWDataValue::clearErrors ( )
Since
2.4
SMWDataValue::getCaption ( )
Since
2.4
Parameters
string$caption
SMWDataValue::getContextPage ( )
Since
2.4
Returns
DIWikiPage|null
SMWDataValue::getDataItem ( )

Get the actual data contained in this object or null if the data is not defined (due to errors or due to not being set at all).

Note
Most implementations ensure that a data item is always set, even if errors occurred, to avoid additional checks for not accessing null. Hence, one must not assume that a non-null return value here implies that isValid() returns true.
Since
1.6
Returns
SMWDataItem|SMWDIError
SMWDataValue::getErrors ( )

Return an array of error messages, or an empty array if no errors occurred.

Returns
array
SMWDataValue::getErrorText ( )

Return a string that displays all error messages as a tooltip, or an empty string if no errors happened.

Returns
string
SMWDataValue::getExtraneousFunctionFor (   $name,
array  $parameters = array() 
)
Since
2.3
Parameters
string$name
array$parameters
Returns
mixed
Exceptions
RuntimeException
SMWDataValue::getHash ( )

Return a string that identifies the value of the object, and that can be used to compare different value objects. Possibly overwritten by subclasses (e.g. to ensure that returned value is normalized first)

Returns
string
SMWDataValue::getInfolinks ( )

Return an array of SMWLink objects that provide additional resources for the given value. Captions can contain some HTML markup which is admissible for wiki text, but no more. Result might have no entries but is always an array.

SMWDataValue::getInfolinkText (   $outputformat,
  $linker = null 
)

Return text serialisation of info links. Ensures more uniform layout throughout wiki (Factbox, Property pages, ...).

Parameters
integer$outputformatElement of the SMW_OUTPUT_ enum
$linker
Returns
string
SMWDataValue::getLongHTMLText (   $linker = null)
abstract

Return the long textual description of the value, as printed for example in the factbox. If errors occurred, return the error message The result always is an HTML string.

The parameter $linker controls linking of values such as titles and should be some Linker object (or NULL for no linking).

SMWDataValue::getLongText (   $outputformat,
  $linker = null 
)

Return the long textual description of the value, as printed for example in the factbox. If errors occurred, return the error message. The output is in the specified format.

The parameter $linker controls linking of values such as titles and should be some Linker object (for HTML output), or NULL for no linking.

SMWDataValue::getLongWikiText (   $linked = null)
abstract

Return the long textual description of the value, as printed for example in the factbox. If errors occurred, return the error message The result always is a wiki-source string.

The parameter $linked controls linking of values such as titles and should be non-NULL and non-false if this is desired.

SMWDataValue::getOption (   $key)
Since
2.4
Parameters
string$key
Returns
mixed|false
SMWDataValue::getOptions ( )
protected
Since
2.5
Returns
Options
SMWDataValue::getOutputFormat ( )
Since
2.4
Returns
string
SMWDataValue::getPreferredCaption ( )

Returns a preferred caption and may deviate from the standard caption as a subclass is permitted to override this method and provide a more contextualized display representation (language or value context etc.).

Since
2.4
Returns
string
SMWDataValue::getProperty ( )

Returns the property to which this value refers.

Since
1.8
Returns
SMWDIProperty|null
SMWDataValue::getQueryDescription (   $value)

FIXME 3.0, allow NULL as value

See also
DataValueDescriptionDeserializer::deserialize
Note
Descriptions of values need to know their property to be able to create a parsable wikitext version of a query condition again. Thus it might be necessary to call setProperty() before using this method.
Parameters
string$value
Returns
Description
Exceptions
InvalidArgumentException
SMWDataValue::getServiceLinkParams ( )
protected

Overwritten by callers to supply an array of parameters that can be used for creating servicelinks. The number and content of values in the parameter array may vary, depending on the concrete datatype.

SMWDataValue::getShortHTMLText (   $linker = null)
abstract

Returns a short textual representation for this data value. If the value was initialised from a user supplied string, then this original string should be reflected in this short version (i.e. no normalisation should normally happen). There might, however, be additional parts such as code for generating tooltips. The output is in HTML text.

The parameter $linker controls linking of values such as titles and should be some Linker object (or NULL for no linking).

SMWDataValue::getShortText (   $outputformat,
  $linker = null 
)

Returns a short textual representation for this data value. If the value was initialised from a user supplied string, then this original string should be reflected in this short version (i.e. no normalisation should normally happen). There might, however, be additional parts such as code for generating tooltips. The output is in the specified format.

The parameter $linker controls linking of values such as titles and should be some Linker object (for HTML output), or NULL for no linking.

SMWDataValue::getShortWikiText (   $linked = null)
abstract

Returns a short textual representation for this data value. If the value was initialised from a user supplied string, then this original string should be reflected in this short version (i.e. no normalisation should normally happen). There might, however, be additional parts such as code for generating tooltips. The output is in wiki text.

The parameter $linked controls linking of values such as titles and should be non-NULL and non-false if this is desired.

SMWDataValue::getTypeID ( )

Return a short string that unambiguously specify the type of this value. This value will globally be used to identify the type of a value (in spite of the class it actually belongs to, which can still implement various types).

SMWDataValue::getWikiValue ( )
abstract

Return the plain wiki version of the value, or FALSE if no such version is available. The returned string suffices to reobtain the same DataValue when passing it as an input string to setUserValue().

SMWDataValue::isEnabledFeature (   $feature)
Since
2.4
Parameters
integer$feature
Returns
boolean
SMWDataValue::isNumeric ( )

Convenience method that checks if the value that is used to sort data of this type is numeric. This only works if the value is set.

Returns
boolean
SMWDataValue::isValid ( )

Return true if a value was defined and understood by the given type, and false if parsing errors occurred or no value was given.

Returns
boolean
SMWDataValue::loadDataItem ( SMWDataItem  $dataItem)
abstractprotected

Set the actual data contained in this object. The method returns true if this was successful (requiring the type of the dataitem to match the data value). If false is returned, the data value is left unchanged (the data item was rejected).

Note
Even if this function returns true, the data value object might become invalid if the content of the data item caused errors in spite of it being of the right basic type. False is only returned if the data item is fundamentally incompatible with the data value.
Since
1.6
Parameters
SMWDataItem$dataItem
Returns
boolean
SMWDataValue::parseUserValue (   $value)
abstractprotected

Initialise the datavalue from the given value string. The format of this strings might be any acceptable user input and especially includes the output of getWikiValue().

Parameters
string$value
static SMWDataValue::prepareValue ( $value,
$comparator 
)
static
Deprecated:
2.3
See also
DescriptionDeserializer::prepareValue

This method should no longer be used for direct public access, instead a DataValue is expected to register a DescriptionDeserializer with DVDescriptionDeserializerRegistry.

FIXME as of 2.3, SMGeoCoordsValue still uses this method and requires migration before 3.0

SMWDataValue::setCaption (   $caption)

Change the caption (the text used for displaying this datavalue). The given value must be a string.

Parameters
string$caption
SMWDataValue::setContextPage ( SMWDIWikiPage  $contextPage = null)

Specify the wiki page to which this value refers. This information is used to parse user values such as "#subsection" which only make sense when used on a certain page.

Since
1.7
Parameters
SMWDIWikiPage | null$contextPage
SMWDataValue::setDataItem ( SMWDataItem  $dataItem)

Set the actual data contained in this object. The method returns true if this was successful (requiring the type of the dataitem to match the data value). If false is returned, the data value is left unchanged (the data item was rejected).

Note
Even if this function returns true, the data value object might become invalid if the content of the data item caused errors in spite of it being of the right basic type. False is only returned if the data item is fundamentally incompatible with the data value.
Parameters
$dataitemSMWDataItem
Returns
boolean
SMWDataValue::setDataValueServiceFactory (   $dataValueServiceFactory)
Since
2.5
Parameters
DataValueServiceFactory$dataValueServiceFactory
SMWDataValue::setOption (   $key,
  $value 
)
Since
2.4
Returns
string $key
Parameters
mxied$value
SMWDataValue::setOptions ( Options  $options = null)
Since
2.4
Returns
Options|null $options
SMWDataValue::setOutputFormat (   $formatString)

Define a particular output format. Output formats are user-supplied strings that the datavalue may (or may not) use to customise its return value. For example, quantities with units of measurement may interpret the string as a desired output unit. In other cases, the output format might be built-in and subject to internationalisation (which the datavalue has to implement). In any case, an empty string resets the output format to the default.

There is one predefined output format that all datavalues should respect: the format '-' indicates "plain" output that is most useful for further processing the value in a template. It should not use any wiki markup or beautification, and it should also avoid localization to the current language. When users explicitly specify an empty format string in a query, it is normalized to "-" to avoid confusion. Note that empty format strings are not interpreted in this way when directly passed to this function.

Parameters
string$formatString
SMWDataValue::setProperty ( SMWDIProperty  $property)

Specify the property to which this value refers. Property pages are used to make settings that affect parsing and display, hence it is sometimes needed to know them.

Since
1.6
Parameters
SMWDIProperty$property
SMWDataValue::setUserValue (   $value,
  $caption = false 
)

Set the user value (and compute other representations if possible). The given value is a string as supplied by some user. An alternative label for printout might also be specified.

Parameters
string$value
mixed$caption

Member Data Documentation

SMWDataValue::$dataValueServiceFactory
protected
SMWDataValue::$m_caption
protected
SMWDataValue::$m_contextPage = null
protected
SMWDataValue::$m_dataitem
protected
SMWDataValue::$m_outformat = false
protected
SMWDataValue::$m_property = null
protected
SMWDataValue::$m_typeid
protected
const SMWDataValue::OPT_CONTENT_LANGUAGE = 'content.language'

Contains either the global "site" content language or a specified page content language invoked by the context page.

const SMWDataValue::OPT_DISABLE_INFOLINKS = 'disable.infolinks'

Option to disable an infolinks highlight/tooltip

const SMWDataValue::OPT_QUERY_COMP_CONTEXT = 'query.comparator.context'

Describes a state where a DataValue is part of a query condition and contains a comparator.

const SMWDataValue::OPT_QUERY_CONTEXT = 'query.context'

Describes a state where a DataValue is part of a query condition and may (or not) require a different treatment.

const SMWDataValue::OPT_USER_LANGUAGE = 'user.language'

Contains the user language a user operates in.


The documentation for this class was generated from the following file: