Knowledge Base

Overview

ResourceSpace has multiple metadata field types such as:

• Text box (single or multi line)
• Check box lists
• Dropdown lists
• Date fields
• Category trees
• Radio button lists
• And many more

Some of these fields can have their options defined by an administrator of the system. These fields are called fixed list fields. An up to date list of which fields are of fixed list type can be found in include/definitions.php, as $FIXED_LIST_FIELD_TYPES.

A fixed list field option is saved as a node internally and its value (ie node name) is broken down into keywords using the add_node_keyword_mappings().

Coding around nodes

All functions that affect nodes should live in include/node_functions.php.

Node structure

Whenever the code refers to a node, unless explicitly mentioned otherwise, always assume the node structure will be:

Array
(
    [ref] => 232
    [resource_type_field] => 3
    [name] => United Kingdom
    [parent] => 
    [orderby] => 30 
    [active] => 1
)

The "parent" type is null|int, where null represents a root node (for category trees).

Core node functions

The following are considered to be core functions for working with nodes:

• set_node() - Used for both creating and saving a node in the database. Use NULL for ref if you just want to insert a new record.
• delete_node()
• delete_nodes_for_resource_type_field()
• get_node() - Get a specific node by its ref
• get_nodes() - Get all nodes from the database for a specific metadata field or parent. Use $parent = NULL and recursive = TRUE to get all nodes for a field. IMPORTANT: recursive should only be used for category tree types.
• is_parent_node()
• get_tree_node_level() - Determine how many level deep a node is.
• get_root_node_by_leaf() - Find node ID of the root parent when searching by one of the leaves ID
• reorder_node()
• reorder_nodes()
• get_node_order_by() - Calculate the next order by for a new record
• add_node_keyword()
• remove_node_keyword()
• remove_all_node_keyword_mappings() - Removes all indexed keywords for a specific node ref
• check_node_indexed()
• add_node_keyword_mappings()
• remove_node_keyword_mappings()
• get_nodes_from_keywords()
• update_node_active_state (v10.4+)
• toggle_category_tree_nodes_active_state (v10.4+)
• node_is_active (v10.4+)

The core node functions MUST not check any form of access control as these functions are considered low level. They are used by other functions such as save_resource_data() which are aware of the context they run within and can easily determine the access level required.

Database model snippet

From a data model perspective, the resource_type_field can have multiple nodes associated with it.

Each node name is indexed and the keywords are associated with the node. This allows multiple nodes to be associated with keywords which drastically improves performance since keywords are indexed only once.

Deactivating nodes

From version 10.4+ nodes can be disabled by administrators.

Inactive nodes should not be processed (added/removed) from resources during save operations (e.g. save_resource_data or save_resource_data_multi), except:

• The drop-down and radio button field types because they can only hold one value so ResourceSpace will allow users to change the value for those fields but not directly remove the inactive value (i.e. unset value)
• Plugins (e.g. rse_version, csv_upload) or tools are allowed to overrule this logic
• As part of update_field() calls

Nodes deactivated will be rendered for the user in most cases (e.g. view page, api responses etc.). The edit page will not display them except for drop-down and radio button field types. When an option is disabled, it can still be updated, re-ordered and deleted.

Toggling nodes should be done by calling the toggle_active_state_for_nodes function as this will honour the rules governing category trees changing their active state. If you need fine grained control then you can use the update_node_active_state function instead.

Rules - active state changes

• Applicable only to fixed list fields
• For category trees:
  • If a parent is marked as disabled, then this automatically applies to all of its children;
  • If all child options are disabled, the parent can still be active.