The <record-tree> element renders arbitrary javascript objects as nested child elements based on the provided object's properties.
In addition to rendering the structure of objects, it provides limited object editing to allow for removing properties from the object. It also provides a data collection function that composes a new object with only the unremoved properties.
The default rendering and functionality are intended to support the arrangement of imports and exports, but the element is customizeable to allow for more generic usage.
Basic Examples
The <record-tree> element is a renderer for a javascript object and, as such, does not render as anything before the setData() function has been called to provide an object to render.
Before the setData() function is called, the <record-tree> element will not be visible with default styling, due to collapsing to a height of zero.
When data has been provided, the <record-tree> element will render each of that object's properties either as a property, a collection, or an object.
Properties are typically rendered in a collapsible list at the start of an object's content. This keeps property names nearest to their parent object, for visual clarity. When rendering arrays, adding a second "properties" toggle-list is redundant, so each array element is rendered as a <div> element. If there are less than 10 properties on an object, the Properties element will be opened so the properties can immediately be viewed.
Collections are rendered as <details> elements that contain each of the array's values. The array items are rendered as properties.
Objects are also rendered as <details> elements, but nested objects are rendered identically to top-level objects, due to recursive functionality.
This example shows the default rendering of a complex object, including null/undefined values, binary values, and collection-type values:
Setting and Getting Data
The <record-tree> element provides editing functionality for removing properties from each object. By using the "remove" buttons, each property or collection can be removed from the object.
After calling setData() to populate the <record-tree> element, any changes made are represented either by the DOM tree itself, or by the "removed" class on properties, depending upon the current removal method.
Once the <record-tree> element has been modified, the getUpdatedData() function can be used to retrieve a representation of the modified object. For most properties, removing them will prevent them from being present in the returned object. For array elements, though, each removed element will be replaced with null in the returned object, as a way to preserve the indexes of the items that were removed.
Modify the contents of the example, below, by removing some of the properties. Then use the "Get Data" button to log the object that is returned by the getUpdatedData() function.
Log
Customization
The <record-tree> element allows complete customization for each element that is rendered by exposing all of its rendering functions, along with helper functions that can conditionally customize rendering.
The "custom renderer" functions are lower-level functions that require the developer to provide the entire structure of a property based on its property name, value, and placement in the heirarchy. These functions are useful for fine control over layout rendering.
The "custom generator" functions are higher-level functions that only require the developer to provide either the property name element or the property value element. These functions are useful for simple operations like text formatting.
All of the customization functions work by calling the "conditional" function which is a function that determines when to use the custom functionality. If you want the custom functionality to work on all properties, for example, you could set the conditional to always return true.
In this example, the default_image property is being rendered using the default value generation method, while the custom_image property is using a custom value generator that injects the image data into an <img> element. Likewise, the ugly_property_name property is using a custom renderer to render its name as "Custom Property Name".
Events
The <record-tree> element dispatches events whenever the object's properties are modified by a user. When a property is removed, either by class name or by removal from the DOM, the remove event is dispatched. If removal is being done by class name, the user has the ability to restore the property back to the object. When that occurs, the restore event is dispatched.
In this example, each of these events is handled by logging the event's detail object, in the log below.