Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 39 and 401] [Versions 401 and 402] [Versions 401 and 403]

Generic exporter to take a stdClass and prepare it for return by webservice.

Copyright: 2015 Damyon Wiese
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 609 lines (26 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 2 classes


Class: exporter  - X-Ref

Generic exporter to take a stdClass and prepare it for return by webservice, or as the context for a template.

templatable classes implementing export_for_template, should always use a standard exporter if it exists.
External functions should always use a standard exporter if it exists.

__construct($data, $related = array()   X-Ref
Constructor - saves the persistent object, and the related objects.

param: mixed $data - Either an stdClass or an array of values.
param: array $related - An optional list of pre-loaded objects related to this object.

Class: is  - X-Ref

export(renderer_base $output)   X-Ref
Function to export the renderer data in a format that is suitable for a
mustache template. This means raw records are generated as in to_record,
but all strings are correctly passed through external_format_text (or external_format_string).

param: renderer_base $output Used to do a final render of any components that need to be rendered for export.
return: stdClass

get_format_parameters($property)   X-Ref
Get the format parameters.

This method returns the parameters to use with the functions external_format_text(), and
external_format_string(). To override the default parameters, you can define a protected method
called 'get_format_parameters_for_<propertyName>'. For example, 'get_format_parameters_for_description',
if your property is 'description'.

Your method must return an array containing any of the following keys:
- context: The context to use. Defaults to $this->related['context'] if defined, else throws an exception.
- component: The component to use with external_format_text(). Defaults to null.
- filearea: The filearea to use with external_format_text(). Defaults to null.
- itemid: The itemid to use with external_format_text(). Defaults to null.
- options: An array of options accepted by external_format_text() or external_format_string(). Defaults to [].
- striplinks: Whether to strip the links with external_format_string(). Defaults to true.

param: string $property The property to get the parameters for.
return: array

get_other_values(renderer_base $output)   X-Ref
Get the additional values to inject while exporting.

These are additional generated values that are not passed in through $data
to the exporter. For a persistent exporter - these are generated values that
do not exist in the persistent class. For your convenience the format_text or
format_string functions do not need to be applied to PARAM_TEXT fields,
it will be done automatically during export.

These values are only used when returning data via {@link self::export()},
they are not used when generating any of the different external structures.

Note: These must be defined in {@link self::define_other_properties()}.

param: renderer_base $output The renderer.
return: array Keys are the property names, values are their values.

read_properties_definition()   X-Ref
Get the read properties definition of this exporter. Read properties combines the
default properties from the model (persistent or stdClass) with the properties defined
by {@link self::define_other_properties()}.

return: array Keys are the property names, and value their definition.

format_properties($properties)   X-Ref
Recursively formats a given property definition with the default fields required.

param: array $properties List of properties to format
return: array Formatted array

properties_definition()   X-Ref
Get the properties definition of this exporter used for create, and update structures.
The read structures are returned by: {@link self::read_properties_definition()}.

return: array Keys are the property names, and value their definition.

define_other_properties()   X-Ref
Return the list of additional properties used only for display.

Additional properties are only ever used for the read structure, and during
export of the persistent data.

The format of the array returned by this method has to match the structure
defined in {@link \core\persistent::define_properties()}. The display properties
can however do some more fancy things. They can define 'multiple' => true to wrap
values in an external_multiple_structure automatically - or they can define the
type as a nested array of more properties in order to generate a nested
external_single_structure.

You can specify an array of values by including a 'multiple' => true array value. This
will result in a nested external_multiple_structure.
E.g.

'arrayofbools' => array(
'type' => PARAM_BOOL,
'multiple' => true
),

You can return a nested array in the type field, which will result in a nested external_single_structure.
E.g.
'competency' => array(
'type' => competency_exporter::read_properties_definition()
),

Other properties can be specifically marked as optional, in which case they do not need
to be included in the export in {@link self::get_other_values()}. This is useful when exporting
a substructure which cannot be set as null due to webservices protocol constraints.
E.g.
'competency' => array(
'type' => competency_exporter::read_properties_definition(),
'optional' => true
),

return: array

define_properties()   X-Ref
Return the list of properties.

The format of the array returned by this method has to match the structure
defined in {@link \core\persistent::define_properties()}. Howewer you can
add a new attribute "description" to describe the parameter for documenting the API.

Note that the type PARAM_TEXT should ONLY be used for strings which need to
go through filters (multilang, etc...) and do not have a FORMAT_* associated
to them. Typically strings passed through to format_string().

Other filtered strings which use a FORMAT_* constant (hear used with format_text)
must be defined as PARAM_RAW.

return: array

define_related()   X-Ref
Returns a list of objects that are related to this persistent.

Only objects listed here can be cached in this object.

The class name can be suffixed:
- with [] to indicate an array of values.
- with ? to indicate that 'null' is allowed.

return: array of 'propertyname' => array('type' => classname, 'required' => true)

get_context_structure()   X-Ref
Get the context structure.

return: external_single_structure

get_format_field($definitions, $property)   X-Ref
Get the format field name.

param: array $definitions List of properties definitions.
param: string $property The name of the property that may have a format field.
return: bool|string False, or the name of the format property.

get_format_structure($property, $definition, $required = VALUE_REQUIRED)   X-Ref
Get the format structure.

param: string $property   The name of the property on which the format applies.
param: array  $definition The definition of the format property.
param: int    $required   Constant VALUE_*.
return: external_format_value

get_create_structure()   X-Ref
Returns the create structure.

return: external_single_structure

get_read_structure($required = VALUE_REQUIRED, $default = null)   X-Ref
Returns the read structure.

param: int $required Whether is required.
param: mixed $default The default value.
return: external_single_structure

get_read_structure_from_properties($properties, $required = VALUE_REQUIRED, $default = null)   X-Ref
Returns the read structure from a set of properties (recursive).

param: array $properties The properties.
param: int $required Whether is required.
param: mixed $default The default value.
return: external_single_structure

get_update_structure()   X-Ref
Returns the update structure.

This structure can never be included at the top level for an external function signature
because it contains optional parameters.

return: external_single_structure