Class coreui

CoreUI proxy view, extending the legacy HTML builder view proxy to include support for controls and dynamos (dynamic controls with the use of JavaScript).

Features the companion client-side CoreUI JavaScript Framework library to implement dynamic controls.

Evolution Summary from Legacy HTML Builder

IDs can no longer be defined individually but are auto-generated (enforces use of class names instead to identify elements or select input fields by name), element descriptors were updated to omit the ID field, input elements (including select boxes and text areas) feature a new first extra argument, the input name, placing the value argument second.

Resource Management

Resources are grouped into classes. A resource class is the primary type of a resource, i.e. image, CSS or JavaScript.

A resource group is basically a repository of resources that are themselves divided by their type.

Resource names are path and file base names separated by colons (":") or slashes ("/"). To simplify use of different categories of resources, a standard set of common categories is managed by the proxy that are used by controls or elements, i.e. setting an icon automatically uses the icon category for a group. A category acts as a prefix.

In summary, resource paths have the following structure:

'resourcePath/resourceGroup/resourceCategory/resourceName'

If a resource group is not specified, it defaults to the resource class. The file extension of the resource is automatically determined by the class and the existing resources, i.e. images are resolved by first testing for a PNG, then JPG and last GIF image.

Core\Object implements Core\Chainable

Core\Set implements Core\Accessor

Core\Set\Mutable implements Core\Mutator

Core\Field implements Core\Inquiry

Core\Field\Mutable implements Core\Variator

Core\View

Core\View\Driver\html

Core\View\Driver\coreui

Namespace: Core\View\Driver
Package: CoreUI
Link: CoreUI JavaScript Framework
Since: 3.1
Requires: PHP 5.3
Version: 1.0
Located at View/Driver/coreui.inc.php

Methods summary

`public`	# `__construct( Core\URI $uri )` Initialises a new View instance. Sets the HTML encoder as the default encoder if no encoder is specified in the URI. Sets the HTML encoder as the default encoder if no encoder is specified by the configuration URI, registers static dependencies and sets the application revision number to the constant `\Application\Revision` if it is defined, otherwise to the Core revision number `Core\Version\Revision`. Initialises a new View instance. Sets the HTML encoder as the default encoder if no encoder is specified in the URI. Sets the HTML encoder as the default encoder if no encoder is specified by the configuration URI, registers static dependencies and sets the application revision number to the constant `\Application\Revision` if it is defined, otherwise to the Core revision number `Core\Version\Revision`. Parameters `$uri` Driver configuration URI. Since 3.1 Overrides `Core\View\Driver\html::__construct`
`public Core\View\Driver\coreui\Element\|Core\View\Driver\coreui\Control`	# `append( $elementID )` Appends an element or control to the internal node buffer and returns the instance. Appends an element or control to the internal node buffer and returns the instance. Parameters `$elementID` description string, control module name or reference to an existing element or control instance. If a string is passed, a new control or module is created by delegating the description string to the `Core\View\Driver\coreui::spawn()` method. The resulting or provided element or control is added to the internal node buffer. Returns `Core\View\Driver\coreui\Element`\|`Core\View\Driver\coreui\Control` Reference to added element or control instance. Since 3.1 Overrides `Core\View\Driver\html::append`
`public`	# `appendVerbatim( mixed $data )` Adds an arbitrary object or string verbatim (without encoding) to the internal node buffer. Adds an arbitrary object or string verbatim (without encoding) to the internal node buffer. Parameters `$data` Object or string to append verbatim to the internal node buffer. If a reference to an object is provided, the object must support a to-string conversion, otherwise view rendering will fail with a fatal error. Since 3.1
`public`	# `clear( )` Resets the internal node buffer to an empty array. Resets the internal node buffer to an empty array. Since 3.1 Overrides `Core\View\Driver\html::clear`
`public string`	# `concatArray( $elementID, array $dataArray )` Returns a concatenated set of elements based on the same description string but different data sets. Returns a concatenated set of elements based on the same description string but different data sets. Deprecated Returning a string instead of a wrapper class instance is discouraged. For compatibility only. May be removed in future versions. Parameters `$elementID` description string used in spawning a node for each data array entry. `$dataArray` Array of element data sets. Returns string Concatenated element set. Elements are concatenated in the same order as their data sets appear in the `$dataArray` parameter. Since 3.1
`public`	# `js( string $js )` Adds a JavaScript block to the "dom:loaded" event. Adds a JavaScript block to the "dom:loaded" event. Parameters `$js` JavaScript block to add for "dom:loaded" event. Returns $this Since 3.1
`public`	# `observe( Core\View\Driver\coreui\Element\|Core\View\Driver\coreui\Control\|string $object, string $eventName, string $handler )` Registers an event handler on client-side for a given JavaScript event triggered by a given element or control. Registers an event handler on client-side for a given JavaScript event triggered by a given element or control. This method utilises the CoreUI JavaScript framework to register events once the `dom:loaded` event is fired. Parameters `$object` Reference to element or control instance or HTML DOM node ID to register event for. `$eventName` Event name (without "on" prefix) to register callback for. `$handler` Callback function body (JavaScript code) for the registered event. The code scope includes a set or common CoreUI short-aliased variables and a local variable `e` that is the event object. Returns $this Since 3.1
`public`	# `registerDependencies( string $resourceClass, array $targets )` Registers new CoreUI resource dependencies. Registered dependency resources are resolved via `Core\View\Driver\coreui::urlForResource()`. Registers new CoreUI resource dependencies. Registered dependency resources are resolved via `Core\View\Driver\coreui::urlForResource()`. Parameters `$resourceClass` Resource class to register dependencies for. `$targets` Array of target module names to register dependencies for. Returns $this See `Core\View\Driver\coreui::urlForResource()` Since 3.1
`public Core\View\Driver\coreui\Dynamo`	# `registerDynamo( Core\View\Driver\coreui\Dynamo $control )` Registers a control implementing the Dynamo interface for client-side use. Registers a control implementing the Dynamo interface for client-side use. Parameters `$control` Instance of `Core\View\Driver\coreui\Control` implementing the `Core\View\Driver\coreui\Dynamo` interface. Returns `Core\View\Driver\coreui\Dynamo` Reference to registered dynamo control. See `Core\View\Driver\coreui\Control` `Core\View\Driver\coreui\Dynamo` Since 3.1
`public boolean`	# `render( )` Renders page contents. This applies headers as necessary, formats the node buffer, replaces generic place holders and embeds client-side local JavaScript for dynamic controls. Expected placeholders are: Renders page contents. This applies headers as necessary, formats the node buffer, replaces generic place holders and embeds client-side local JavaScript for dynamic controls. Expected placeholders are: `HTMLHeader` Location of the HTML header area where additional headers will be added to. `HTMLFooter` Footer of HTML body (after contents) where generated JavaScript code is embedded in. Returns boolean Returns `true`. Since 3.1 Overrides `Core\View\Driver\html::render`
`public`	# `setHTMLHeader( $type, $header, $content )` Sets a HTML header. Sets a HTML header. Parameters `$type` type (tag descriptor). `$header` key. `$content` value. Returns $this Since 3.1
`public mixed`	# `spawn( $elementID )` Instantiates a new element or control. Instantiates a new element or control. Parameters `$elementID` description string or control module name. Returns mixed Instantiated element or control instance. See Control::derive() Element::derive() Since 3.1
`public`	# `setDataForUndefinedKey( string $key, mixed $value )` Adds a KDC value to the view. Additionally, if the key is the empty string, the value is added to the internal HTML buffer. This allows the use of the array-append operator to append values to the internal HTML buffer verbatim. Additionally, if key is the empty string, the value is added to the internal node buffer. This enables the use of the array-append operator to append values to the internal node buffer verbatim. Adds a KDC value to the view. Additionally, if the key is the empty string, the value is added to the internal HTML buffer. This allows the use of the array-append operator to append values to the internal HTML buffer verbatim. Additionally, if key is the empty string, the value is added to the internal node buffer. This enables the use of the array-append operator to append values to the internal node buffer verbatim. Parameters `$key` Data field key. `$value` Value to store. Throws Exception\UndefinedKey No data field identified by the given key exists. Since 3.1 Overrides `Core\View\Driver\html::setDataForUndefinedKey`
`public string`	# `resolveResource( $class, $name )` Resolves a server-side resource path relative to the application root. Resolves a server-side resource path relative to the application root. A resource group defines the subdirectory that is appended to the root source path for the requested resource file. If no resource group is defined, the resource class defines the resource group. Parameters `$class` class name (will be used a resource group as well) or array with resource group and class name. `$name` name to resolve path for or an array of resource category and resource name. Returns string See `Core\View\Driver\coreui::urlForResource()` Since 3.1
`public null\|string`	# `urlForResource( $class, $name, boolean $verifyFlag = null )` Resolves client-side URL for a specified resource. Resolves client-side URL for a specified resource. A resource group defines the subdirectory that is appended to the root source path for the requested resource file. If no resource group is defined, the resource class defines the resource group. Parameters `$class` class name (will be used a resource group as well) or array with resource group and class name. `$name` name to resolve path for. `$verifyFlag` Optional. If set to `true`, the existence of the resource is validated and `null` returned, if the resource does not exist. Defaults to `false` . Returns null\|string Resource URL string or `null`, if resource could not be resolved or validation was requested and resource does not exist. See `Core\View\Driver\coreui::resolveResource()` Since 3.1

Constants summary

`string`	`Version` CoreUI package version (same for client libraries and assets). This version can differ from the view driver module version. CoreUI package version (same for client libraries and assets). This version can differ from the view driver module version. Since 3.1	# `'1.0'`
`string`	`CoreUIResourceGroup` Resource group for control extensions subdirectory. Resource group for control extensions subdirectory. Since 3.1	# `'coreui'`
`string`	`CSSResourceClass` Resource class for Cascading Style Sheets (CSS). Resource class for Cascading Style Sheets (CSS). Since 3.1	# `'css'`
`string`	`ImageResourceClass` Resource class for images. Resource class for images. Since 3.1	# `'image'`
`string`	`JSResourceClass` Resource class for JavaScript modules. Resource class for JavaScript modules. Since 3.1	# `'js'`
`string`	`IconResourceCategory` Resource category for icons. Resource category for icons.	# `'icon'`

Constants inherited from Core\View

EncoderParameter

Constants inherited from Core\Object

AnyParameterType, AutochainParameterType, AutocreateParameterType, BooleanParameterType, CharParameterType, EnumParameterType, IntegerParameterType, RealParameterType, StringParameterType, UserParameterType

Properties summary

`protected integer`	`$_v_applicationRevision` KVC property. KVC property. Since 3.1	#
`protected array`	`$_v_controls` KVC property. KVC property. Since 3.1	# `array ()`
`protected array`	`$_v_dependencies` KVC property. KVC property. Since 3.1	# `array ()`
`protected array`	`$_v_htmlHeader` KVC property. KVC property. Since 3.1	# `array ()`
`protected array`	`$_v_js` KVC property. KVC property. Since 3.1	#
`protected array`	`$_v_nodes` KVC property. KVC property. Since 3.1	# `array ()`
`protected string`	`$_v_resourcePath` KVC property. KVC property. Since 3.1	# `'rsrc/'`
`protected ArrayObject`	`$_v_resourceCategoryPaths` Associative array of resource categories with their assigned path prefixes. Associative array of resource categories with their assigned path prefixes. Since 3.1	# `array ( self::IconResourceCategory => 'icon', )`
`protected array`	`$_v_staticDependencies` KVC property. KVC property. Since 3.1	# `array ( self::JSResourceClass => array ( 'coreui:coreui', ), self::CSSResourceClass => array ( 'coreui:coreui', ), )`

Properties inherited from Core\View\Driver\html

$_v_buffer, $_v_responseCode, $_v_responseCodes

Properties inherited from Core\View

$_encoder, $_v_parameters, $_v_proxy, $_v_renderers, $_v_translator, $_v_uri

Properties inherited from Core\Field\Mutable

$_v_masqueradedKeys

Properties inherited from Core\Field

$_v_data

Magic properties

`public read-only integer`	`$applicationRevision` Application revision number used as cache tags for resources (to force browsers to reload a resource if the application revision changed).
`public read-only array`	`$controls` Hash of registered dynamo controls, indexed by control ID. Values are references to the registered controls.
`public read-only array`	`$dependencies` Hash of registered dependencies, indexed by resource class and resource descriptor. Values are the resolved resource file names.
`public read-only array`	`$js` Sequential array of generated JavaScript statements that are inserted in order of their generation after client-side CoreUI initialisation.
`public read-only array`	`$htmlHeader` Array of HTML headers with header-type, key and value triples.
`public read-only array`	`$nodes` Sequential array of generated nodes.
`public read-only ArrayObject`	`$resourceCategoryPaths` Associative array of resource categories with their assigned path prefixes. Can be directly modified to change path prefixes. Retrieve all keys from array to determine which categories are supported by the current CoreUI version.
`public read-only string`	`$resourcePath` Path prefix for resources relative to the application root directory. The resource path *must* end in a directory delimiter.
`public read-only array`	`$staticDependencies` Hash of static dependencies, indexed by resource class. Values are arrays of resource descriptors that are automatically resolved within the constructor.

Magic properties inherited from Core\View\Driver\html

$buffer, $responseCode

Magic properties inherited from Core\View

$encoder, $parameters, $proxy, $renderers, $translator, $uri

Magic properties inherited from Core\Field\Mutable

$masqueradedKeys

Magic properties inherited from Core\Field

$data

Magic properties inherited from Core\Object

$hash, $uuid

Namespaces

Classes

Class coreui

Evolution Summary from Legacy HTML Builder

Resource Management

Methods summary

Parameters

Since

Overrides

Parameters

Returns

Since

Overrides

Parameters

Since

Since

Overrides

Deprecated

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

See

Since

Parameters

Returns

See

Since

Returns

Since

Overrides

Parameters

Returns

Since

Parameters

Returns

See

Since

Parameters

Throws

Since

Overrides

Parameters

Returns

See

Since

Parameters

Returns

See

Since

Methods inherited from Core\View\Driver\html

Methods inherited from Core\View

Methods inherited from Core\Field\Mutable

Methods inherited from Core\Field

Methods inherited from Core\Set\Mutable

Methods inherited from Core\Set

Methods inherited from Core\Object

Constants summary

Since

Since

Since

Since

Since

Constants inherited from Core\View

Constants inherited from Core\Object

Properties summary

Since

Since

Since

Since

Since

Since

Since