Descendant XBRL classes

While use of the object-oriented features of PHP takes a back seat to arrays for reasons of performance, advantage of OO features is taken where it makes sense.

An example is the implementation of specific taxonomy support. The XBRL class handles most of of the requirements of all taxonomies but there can be some taxonomy specific features or omissions than need to be plugged. For example, the namespaces used are likely to be different as is the file structure of the taxonomies.

Even if the core XBRL class handles the needs of a specific taxonomy, having class for that taxonomy means it is named. At the time of writing the following taxonomy classes which inherit from XBRL have been created

Class	Comment
XBRL_UK_GAAP	UK GAAP taxonomy implementation
XBRL_UK_FRC	xbrl.frc.org.uk (2014) implementation
XBRL_UK_AE	UK Companies House Audit Exempt taxonomy
XBRL_US_GAAP_2015	Main US GAAP (SEC) taxonomy

###Creating a descendant class

The purpose of implementing a descendant is to make sure the taxonomy is processed correctly and that the correct XBRL instance type is created on demand when a request to load a taxonomy schema is received. This section reviews the customizations you can apply in a descendant class. There are two classes of customization: those that are mandatory and those that are optional.

###Mandatory

**Include XBRL**

Make sure the XBRL class is imported.

require_once('XBRL.php');

**Initialize**

The XBRL core implementation is called to load and compile taxonomies so it need to know which concrete instance to create to handle customizations.

A descendant XBRL implementation will call:

Function name	Comment
XBRL::add_namespace_to_class_map_entries	To identify the namespaces of all the taxonomies used (the main taxonomy may include dependent taxonomies)
XBRL::add_entry_namespace_to_class_map_entries	To specify which of the taxonomies are used as entry points and could be used by and extension taxonomy
XBRL::add_xsd_to_compiled_map_entries	This maps possible taxonomy schema file names to names used as compiled taxonomy files

The calls will usually be implemented before the class is defined. By way of an example, here is the implementation of these functions in the UK Audit Exempt (because they are simple!).

$entrypoint_namespaces = array(
	"http://www.companieshouse.gov.uk/ef/xbrl/uk/fr/gaap/ae/2009-06-21",
);

XBRL::add_namespace_to_class_map_entries( array(
	"http://www.xbrl.org/uk/fr/gcd/2004-12-01",
	"http://www.xbrl.org/uk/fr/gaap/pt/2004-12-01",
	"http://www.companieshouse.gov.uk/ef/xbrl/uk/fr/gaap/ae/2009-06-21",
	"http://www.xbrl.org/uk/fr/gaap/ci/2004-12-01",
) + $entrypoint_namespaces, "XBRL_UK_AE" );
XBRL::add_entry_namespace_to_class_map_entries( $entrypoint_namespaces, "XBRL_UK_AE" );

XBRL::add_xsd_to_compiled_map_entries( array( "uk-gaap-ae-2009-06-21.xsd" ), "uk-ae" );

**Constructor**

This is an opportunity to set any specific number formatting options

public function __construct()
{
	parent::__construct();

	// Display numbers with accuracy to 100K as millions to 1 decimal place.
	$this->setDisplayRoundingFactor( -5, 6, 'm' );
	$this->setDisplayRoundingFactor( -8, 9, 'b' );
}

Optional

The XBRL class implements several functions descendant classes can implement to modify how taxonomies are processed.

**accumulateCommonHypercubesForNode**

Provides a descendant implementation a chance to define whether or not common hypercubes should be accumulated for a node.

• @param array $nodes An array of presentation hierarchy nodes
• @param string $roleRefKey
• @return bool True if primary items are allow (default: true)

protected function accumulateCommonHypercubesForNode( $node, $roleRefKey )
{
	return parent::accumulateCommonHypercubesForNode( $node, $roleRefKey );
}

**afterMainTaxonomy**

Provides an opportunity for a descendant class implemenentation to take action when the main taxonomy is loaded

protected function afterMainTaxonomy()
{
}

**beforeDimensionalPruned**

This function is overridden to prevent dimensions being removed from presentation linkode. Generally dimensions are not useful in presentation linkbases.

• @param array $dimensionalNode A node which has element 'nodeclass' === 'dimensional'
• @param array $parentNode The parent node so it can be updated
• @return bool True if the dimensional information should be deleted

protected function beforeDimensionalPruned( $dimensionalNode, &$parentNode )
{
	return parent::beforeDimensionalPruned( $dimensionalNode, $parentNode );
}

**displayNode**

Return false if the node should not be displayed. May delegate to the taxonomy instance.

• @param array $node
• @return bool

public function displayNode( $node )
{
	return return parent::displayNode( $node );
}

**excludeFromOutput**

Returns True if the $key is for a row that should be excluded from a report.

• @param string $key The key to lookup to determine whether the row should be excluded
• @param string $type The type of the item being tested (defaults to null)
• @return boolean

public function excludeFromOutput( $key, $type = null )
{
	return parent::excludeFromOutput( $key, $type );
}

**formattedValue**

Returns the value of $element formatted according to the type defined in the taxonomy

• @param array $element A representation of an element from an instance document
• @param XBRL_Instance $instance An instance of an instance class related to the $element

public function formattedValue( $element, $instance = null )
{
	return parent::formattedValue( $element, $instance );
}

**getDefaultCurrency**

Get the default currency

public function getDefaultCurrency()
{
	return "USD";
}

**getProxyPresentationNodes**

Returns an array of locator(s) and corresponding presentation arc(s) that will be substituted for the $from in the $role

• @param string $roleUri A role Uri to identify the base presentation link base being modified.
• @return array An array of locators and links

public function getProxyPresentationNodes( $roleUri )
{
	return parent::getProxyPresentationNodes( $roleUri );
}

**getTaxonomyDescriptionForId**

Returns a description for an element identified by href

• @param string $href The id of the element for which a description is to be retrieved. If only the fragment is provided, its assumed to be from the current taxonomy.
• @param null|array[string] (optional) $roles If true include the element text in the result. If the argument is an array it will be an array of preferred labels.
• @param null|string $lang (optional) a language locale
• @return bool|string A description string or false

public function getTaxonomyDescriptionForId( $href, $roles = null, $lang = null )
{
	return parent::getTaxonomyDescriptionForId( $href, $roles, $lang );
}

**getValidDimensionMembersForNode**

Provides this implementation an opportunity to provide a list of valid dimension members for a node. Doing this allows the use of elements in an instance document to be disambiguated. This function will be overridden in descendants.

• @param array $node The node of the element being processed
• @param array $ancestors An array containing the ids of the nodes leading to and including the current node
• @return array Returns an empty array

public function getValidDimensionMembersForNode( $node, $ancestors )
{
	return parent::getValidDimensionMembersForNode( $node, $ancestors );
}

**importSchema**

This allows a descendant to add extra schemas. For example, in the US GAAP implementation import schema is overrridden to import currency and country schemas which are referenced but not imported by us-types-2015-01-31.xsd

• @param string $schemaLocation The location of the schema file being loaded
• @param int $depth (optional) The nesting depth
• @param bool $mainSchema True if the schema being loaded is the main DTS schema (entry point)

protected function importSchema( $schemaLocation, $depth = 0, $mainSchema = false )
{
	parent::importSchema( $schemaLocation, $depth, $mainSchema );
}

**primaryItemsAllowed**

Provides a descendant implementation a chance to define whether or not primary items are allowed for a node in a presentation hierarchy. In US-GAAP taxonomies, primary items are only relevant when there is a statement table. Without this check, invalid hypercubes and dimensions can be added.

• @param array $nodes An array of presentation hierarchy nodes
• @param string $roleRefKey
• @return bool True if primary items are allow (default: true)

protected function primaryItemsAllowed( $nodes, $roleRefKey )
{
	return parent::primaryItemsAllowed( $nodes, $roleRefKey );
}

**sanitizeText**

This function provides an opportunity for a taxonomy to sanitize and/or translate a string

• @param string $text The text to be sanitized
• @param string $type An optional element type such as num:integer
• @param string $language An optional language locale
• @return string The sanitized string

public function sanitizeText( $text, $type = null, $language = null )
{
	return parent::sanitizeText( $text, $type = null, $language = null );
}

**treatAsText**

Returns true if the element value with the $key is defined as one to display as text

• @param string $key The key to lookup to determine whether the row should be treated as text
• @param string $type The type of the element
• @return boolean Defaults to false

public function treatAsText( $key, $type )
{
	return parent::treatAsText( $key, $type );
}

**treatAsLabel**

Returns true if the element value with the $key is defined as one that should be used as a label - usually in tuple

• @param string $key The key to lookup to determine whether the row should be treated as a label
• @return boolean Defaults to false

public function treatAsLabel( $key )
{
	return parent::treatAsText( $key );
}

**useAllRoles**

Whether all roles should be used when collecting primary items,

• @return bool True if all roles are to be used as the basis for collecting primary items

protected function useAllRoles()
{
	return parent::useAllRoles();
}

**valueAlignmentForNamespace**

Gets the alignment for the element based on the type

• @param string $namespace
• @param string $name
• @return string The alignment to use

public function valueAlignmentForNamespace( $namespace, $name )
{
	return parent::valueAlignmentForNamespace( $namespace, $name );
}