API Docs

Class: Component

BIM. Component

The base class for shared BIM components.

Components are flexible objects that define the shape representation of all or part of a BIM.Element. They typically provide the parametric properties required to define the unique characteristics and physical shape of a particular element type or product, and the methods required to add that shape to the element's brep or shell, or sometimes directly to the host level's meshes.

Elements vs Components

In this framework, components are defined as separate and distinct classes, primarily so that they can be shared by multiple elements across a project. For example, a particular basin type may be used multiple times in several different bathroom cabinet elements, or a particular chair design used in the dining areas of multiple apartments within a large project. By sharing a common type component, each instance will be physically the same and any edits to the parameters of the shared component will apply to all elements that share it when they are rebuilt.

Also, components can store additional information such as supplier and/or manufacturer data, part and/or reference numbers, and even contact details for maintenance and/or reordering. Using shared components across a project can significantly reduce unnecessary duplication of this type of data.

How Elements Use Components

Different element types use and reference components in different ways. For example, a BIM.Wall element usually generates its own geometry, but has a BIM.Walls-based type component from which it gets its material layers, thickness, surface properties and path offsets. However, any of its path junctions can reference a different wall type if there is a material change, and can also store multiple BIM.Aperture components, all of which the wall element has to be able to understand and manage. Moreover, walls needs to be dynamically connected to and/or merged with other walls on the same level, or even on other levels if it projects over multiple storeys. This requires a tight and predictable relationship between the BIM.Wall and BIM.Level classes, which cannot be easily delegated to a potentially arbitrary wall type class. This is true of most core structural building elements.

A BIM.Chair element on the other hand, relies entirely on its BIM.Chairs type component to generate its geometry at each junction. This is because two different chair types can be completely different in form and appearance, so the chair type class needs much more control over its form generation. Chairs, as well as other BIM.Furnishing, BIM.Fixture, BIM.Appliance and BIM.Equipment elements, can be moved around relatively independently and don't need any special knowledge of other elements, so their type components can be afforded much greater level of control.

Changing Component Types

You can assign a new component type to an element at any time, and when the element is rebuilt, it will use the new component to generate its geometry. However, be aware that different component types may have different parameter requirements, so changing a component type may result in the loss of parameter data if the new component does not support the same parameters as the previous one. When you do change a component type, the previously assigned component is retained in the undo/redo queue, so you can always revert back to it if necessary.

The majority of components are designed to be used only by specific element types, and will not allow you to assign them to an incompatible element. Each component class provides both static and instance BIM.Component.isCompatibleWith methods that the framework uses to determine if a component can be used by a particular element. This is also used by the user interface when dragging and dropping type components onto elements in order to provide visual feedback on whether or not the component can be applied to the target element.

Parametric vs Static Components

Whilst most components are parametric in nature, meaning that they dynamically generate element geometry based on their parametric property values, some components are static, meaning that they simply store pre-defined geometry data that is either manually created by the user or imported from an external 3D modelling tool. Static components are usually used for bespoke furniture, appliances and/or equipment items that have a fixed form that is specified by the manufacturer or designer. They can also be used for any element that is engineered in consultants drawings to serve a specific purpose, or with a form that is not parametric in nature. Finally, they may also be used to allow the user to manually edit geometry that was originally generated by a parametric component.

Static components still have parametric properties, but are there to control the position, scale and rotation of the static geometry rather than regenerate it.

How Components Work

Components work by providing the necessary parametric properties and methods required to define and generate the geometry of a particular element type or product. In order to support components, elements have a typeComponent property that references a BIM.Component instance.

When an element is rebuilt, it checks for a valid type component and calls that component's rebuild() method, passing itself as the host element parameter. The component then uses the host element's properties, such as its path junctions and offsets, along with its own parametric properties, to generate the appropriate geometry and add it to the host element's brep and/or shell.

Given the vastly different nature of building elements and their geometry generation, the framework does not enforce any particular way for components to generate geometry. Instead, each component type is free to implement its own geometry generation logic within the rebuild() method as required. This allows for a high degree of flexibility and creativity in how type components define and generate forms.

The framework does offer basic infrastructure for storing and rendering geometry, using either PD.BRep or PD.Shell instances on the host element. When these are used, the base BIM.Element class knows how to render, highlight, interactively select and raytrace them. However, if the component uses some other geometry representation, such as THREE Meshes, then the component needs to also provide its own mounted, unmounted, render, highlight, findByRay and findByFrustum methods to handle this instead of the framework. Whilst these methods are not formally defined in the base BIM.Component class, the base BIM.Element classes do check for their existence within their core lifecycle methods and will call them if they are found.

This separation of concerns allows components to be reused across multiple elements, and for elements to be easily switched between different component types as needed.

new Component( [config] [, typeName])

Creates a new shared BIM component.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
name string <optional>

A human-readable name for this component.
uuid string <optional>

A universally unique identifier of this component.
productRef string <optional>

The product reference number or identifier..
description string <optional>

A brief product or type description.
supplier BIM.Supplier <optional>

An optional supplier details data object.
isLocked boolean <optional>

Whether or not this component's parameters are fixed.
typeName string <optional>

This additional parameter is typically used by subclasses to provide a default name without altering the config object.
Author:
  • drajmarsh

Extends

Members

:string

className <readonly>

The name of the subclass for this object instance.

This name must match the name of this class within the PD.Registry. Thus, the base implementation simply references this.constructor.getClassName() to ensure that this is always the case even for subclasses. As a result, there is rarely any need to override this method.

This property is used when copying, storing and exporting data for subclass instances to ensure that they are recreated as instances of the right class.

Type
  • string
Inherited From:
Overrides:
:string

description

A brief product or type description, defaults to an empty string.

This description is typically used to provide additional information about the product to other team members, such as its reasons for selection. important features, specifications and/or intended use.

Type
  • string
:string

displayName <readonly>

The name to display for this class within the user interface.

Type
  • string
Inherited From:
Overrides:
:string

iconName <readonly>

The name of the SVG icon to associate with this object instance.

This name should match the name of the icon associated with this class within the PD.Registry. Thus, the default implementation simply references this.constructor.getClassName() to ensure that this is always the case, even for subclasses. However, you can override this property if you want a different icon dependant on other properties of the class instance, as shown in the example below.

Type
  • string
Inherited From:
Overrides:
Example
// Overriding the icon name.

MyElements.Table = class extends PD.Base {
    /// ...
    get iconName() {
        if (this.hasRoundTop) return 'MyElements.Table.Round';
        return this.constructor.getClassName();
    };
    /// ...
 };
:boolean

isComponent <readonly>

A flag identifying this object as a shared BIM component.

Type
  • boolean
:boolean

isLocked

Whether or not this component's parameters are fixed.

This property is used by the UI and framework to indicate that the component's parameters are fixed and therefore not editable. It is typically set by a 3rd-party manufacturer or supplier on products that they can only provide in one configuration.

For example, there is no point specifying a particular manufacturer's fridge and then adjusting its width to fit a hole in your cabinetry if that manufacturer cannot actually supply a fridge of that width.

Thus, when this property is true, you will not be able to edit the parameters, but you can always duplicate the component (or its configuration), but without the supplier details if you really do want to modify it.

Type
  • boolean
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:string

productRef

The product reference number or identifier, defaults to an empty string.

The product reference is typically used to store a serial number, model number, SKU or other identifier provided by the manufacturer or supplier to uniquely identify this product.

Type
  • string
:number

subType <readonly>

An element-specific subtype.

Type
  • number
:string

supplier

The product supplier/manufacturer, defaults to null.

This property contains details of the supplier or manufacturer of this product or component. Multiple components can share the same supplier instance to avoid unnecessary duplication of data.

Type
  • string
:string

uuid

A universally unique identifier for the item instance.

Type
  • string
Inherited From:
Overrides:
:object

icon <static>

The icon associated with this class in the PD.Registry.

See PD.Base.icon for more information on this object format.

Type
  • object

Methods

checkDynamicParameter(param, group [, host])

Provides an opportunity to dynamically limit the value and/or range of each parameter.

This method is called whenever a dynamic parameter is interactively changed. The param argument gives access to the parameter being changed whilst the group argument gives access to other parameters within the same parameter group.

NOTE: Range validation in this method is not absolutely required, but doing so can prevent unnecessary model rebuilds due to out-of-range parameters being different from their previous values, even though the object's geometry will not actually change due to range constraints within the subclasses rebuild() method. Thus, it is usually best to do them here so that someone's future airport model is not entirely rebuilt each time they try to set a too-large length in your custom door handle component.

Parameters:
Name Type Argument Description
param PD.Parameter

The parameter that is being interactively changed.
group PD.ParamGroup

The group that the dynamic parameter belongs to.
host object <optional>

For components only, the parent or host object that called this method.
Inherited From:
Overrides:
Example
checkDynamicParameter(param, group, host) {

     switch (param.name) {

         case 'height':
             if (param.value < 1.0) param.value = 1.0;
             break;

         case 'width':
         case 'length':
             if (param.value < 100.0) param.value = 100.0;
             if (this.standardBedSize > 0) { // If not custom.
                 group.setParameterValue('standardBedSize', 0);
                 this.standardBedSize = 0; // Make it custom.
             }
             break;

         case 'standardBedSize': {
                 const std_bed = this.getStandardBedSize(Math.round(param.value));
                 if (std_bed != null) {
                     const [ width, length ] = (PD.DIMENSION.useImperial) ? std_bed.sizeImperial : std_bed.sizeMetric;
                     this.width = PD.Utils.toNumber(width, this.width);
                     group.setParameterValue('width', this.width);
                     this.length = PD.Utils.toNumber(length, this.length);
                     group.setParameterValue('length', this.length);
                 }
             } break;

       }

 };

clone()

Creates a copy of this instance with different name and uuid.

Inherited From:
Overrides:
Returns:

Returns a new instance with copied values.

Type
PD.Base | null

fromJSON(data)

Safely copy properties from a source object.

See the PD.Base#fromJSON method for more details.

Parameters:
Name Type Description
data object

The source object containing data to copy.
Inherited From:
Overrides:
Returns:

Returns this instance to support method chaining.

Type
BIM.Component
Example
// Overriding this method.

class MyElement extends PD.Element {

    /// ...

    fromJSON(data) {

        super.fromJSON(data);

        if ('myNewNumberProp' in data) {
            this.myNewNumberProp = PD.Utils.toNumber(data.myNewNumberProp, this.myNewNumberProp);
        }

        if ('myNewIntegerProp' in data) {
            this.myNewIntegerProp = PD.Utils.toInteger(data.myNewIntegerProp, this.myNewIntegerProp);
        }

        if ('myNewBooleanProp' in data) {
            this.myNewBooleanProp = PD.Utils.toBoolean(data.myNewBooleanProp, this.myNewBooleanProp);
        }

        if ('myNewVectorProp' in data) {
            PD.Utils.copyVector3(data.myNewVectorProp, this.myNewVectorProp);
        }

        if ('myNewColorProp' in data) {
            PD.Utils.copyColor(data.myNewColorProp, this.myNewColorProp);
        }

        return this;

    };

    /// ...

};

getDynamicParameters( [host])

Provides a list of dynamic parameter groups to the UI.

This list is typically requested by the front-end framework whenever something is selected in the model and used to generate DOM components that allow the user to interactively edit each parameter.

Override this method in any derived classes to specify your own custom parameters and parameter groups. The array must only contain PD.ParamGroup objects for it to display the parameters it contains, as shown in the example below.

When the user modifies any a parameters, the updateDynamicParameters() method on the owner is called. As long as the name property of each parameter corresponds exactly to a property on the custom element, the default implementation of the update method can be used. This simply does some type and tolerance checking to see if the value has changed, before assigning the new value and calling the rebuild() method on the element. If you need to use names other than property names, or need to do your own type and/or tolerance checking, then you will need to also override the PD.Base#updateDynamicParameters` method.

Parameters:
Name Type Argument Description
host object <optional>

For components only, the parent or host object that called this method.
Inherited From:
Overrides:
Returns:

Returns an array of zero or more PD.ParamGroup objects.

Type
Array
Example
getDynamicParameters(host) {
     return [
         new PD.ParamGroup({
             name: 'mainParams',
             title: 'Table Parameters',
             target: this,
             params: [
                 new PD.Parameter({ name: 'height', title: 'Table Height', value: this.height, paramType: PD.ParamType.SmallDistance, description: 'The height from floor level to the top of the table.' }),
                 new PD.Parameter({ name: 'size', title: 'Table Top Size/Diameter', value: this.size, paramType: PD.ParamType.Distance, description: 'The size of the table top when not defined by a closed path.' }),
                 new PD.Parameter({ name: 'thickness', title: 'Table Top Thickness', value: this.thickness, paramType: PD.ParamType.SmallDistance, description: 'The thickness of the table top surface.' }),
                 new PD.Parameter({ name: 'offset', title: 'Offset From Path', value: this.offset, paramType: PD.ParamType.SmallDistance, description: 'The offset distance from the table path.' }),
                 new PD.Parameter({ name: 'swapSides', title: 'Swap Sides', value: this.swapSides, paramType: PD.ParamType.Boolean, description: 'Reverse the direction of the table relative to its path.' }),
                 new PD.Parameter({ name: 'isRound', title: 'Round Table', value: this.isRound, paramType: PD.ParamType.Boolean, description: 'Whether or not the table surface is round.'  }),
             ]
         }),
         new PD.ParamGroup({
             name: 'legParams',
             title: 'Leg Parameters',
             target: this,
             params: [
                 new PD.Parameter({ name: 'legCount', title: 'Number of Legs', value: this.legCount, paramType: PD.ParamType.Integer, description: 'The number of legs on the table.' }),
                 new PD.Parameter({ name: 'legSize', title: 'Leg Size', value: this.legSize, paramType: PD.ParamType.SmallDistance, description: 'The thickness of each leg of the table.' }),
                 new PD.Parameter({ name: 'legInset', title: 'Leg Edge Inset', value: this.legInset, paramType: PD.ParamType.SmallDistance, description: 'The inset distance of each leg from the table edge.' }),
                 new PD.Parameter({ name: 'legOffset', title: 'Leg Edge Offset', value: this.legOffset, paramType: PD.ParamType.Fraction, description: 'The relative distance of the leg along each edge span.' }),
                 new PD.Parameter({ name: 'legSpan', title: 'Max. Distance Between Legs', value: this.legSpan, paramType: PD.ParamType.Distance, description: 'The maximum distance between legs along each edge span.' })
             ]
         })
     ];
 };

getNameAndSupplierParameters()

Provides a list of dynamic parameter groups for the component name, description and supplier.

See the PD.Base#getDynamicParameters method for more details.

Returns:

Returns an array of PD.ParamGroup objects.

Type
Array

hasMethod(component, methodName)

Determines if this component has a callable method with the given name.

This method is useful for checking if the component has a particular method before attempting to call it, thereby avoiding potential runtime errors. It is used within the framework to check for the presence of life-cycle methods in an element's type component before delegating them.

Parameters:
Name Type Description
component BIM.Component

The component to check.
methodName string

The case-sensitive name of the function/method to check for.
Returns:

Returns true if the component is valid and has the function name as a method, otherwise false.

Type
boolean

isCompatibleWith(obj)

Determines if this component can be added to the given entity.

Whilst a small number of components may be compatible with multiple entity types, most components are designed to be used only by a specific entity type, and will not allow you to assign them to an incompatible entity.

Parameters:
Name Type Description
obj BIM.ENTITY | BIM.Entity

The entity type or object instance to check for compatibility with.
Returns:

Returns true if the component can be added to the object, otherwise false.

Type
boolean

rebuild(element)

Rebuilds the geometry of this component ready for visualisation.

This is a placeholder method that should be overridden by subclasses to provide the necessary geometry generation logic for the component. Geometry is typically added to the host element's brep and/or shell based on its path.

Parameters:
Name Type Description
element BIM.Element

The element to rebuild.
Returns:

Returns this component instance to support method chaining.

Type
BIM.Component

toJSON( [data])

Converts the component instance to a simple POJO for JSON storage.

This method is used to copy, store and save the data for this component, so the returned object must have all the properties required be able to be able to fully rebuild it when passed to the class constructor.

See the PD.Base#toJSON method for more details.

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Inherited From:
Overrides:
Returns:

Returns a JSON object.

Type
object
Example
// Overriding this method.

class MyElement extends PD.Element {
    /// ...
    toJSON(data) {

        data = super.toJSON(data);

        data.myNewNumberProp = this.myNewNumberProp;
        data.myNewIntegerProp = this.myNewIntegerProp;
        data.myNewBooleanProp = this.myNewBooleanProp;
        data.myNewVectorProp = this.myNewVectorProp.toArray();
        data.myNewColorProp = this.myNewColorProp.toArray();
        return data;

    };
    /// ...
};

updateDynamicParameters(param, group)

Sets the dynamic parameter value and returns true if it changed.

Most subclasses don't need to override this method as it automatically detects changes and rebuilds the element/component and model when required. However, if you do need to add your own custom logic or intercept the return value, please read the following examples carefully and use whichever best suits your needs.

NOTE: When overriding this method, you may not want to call super.updateDynamicParameters(param, group) as the parent class may have added its own logic that may interfere with what you want to do. Instead, either use the static PD.Base.updateDynamicParametersOnHost method to check if the value changed, or base it on the third example which replicates the code in that static method.

Parameters:
Name Type Description
param PD.Parameter

The dynamic parameter that changed.
group PD.ParamGroup

The group that the dynamic parameter belongs to.
Inherited From:
Overrides:
Returns:

Returns true if the value actually changed.

Type
boolean
Examples
updateDynamicParameters(param, group) {

     /// When you want parent class to use its logic.
     if (super.updateDynamicParameters(param, group)) {
         if (param.name == 'i_am_special') this.doSomethingSpecial();
         return true;
     }

     return false;

 };
updateDynamicParameters(param, group) {

     /// When you don't want parent to handle parameter updates.
     if (PD.Base.updateDynamicParametersOnHost(param, group, this)) {

         /// Invalidate geometry.
         if (this.typeComponent) {
             ++this.typeComponent.updateIndex;
         }

         /// Rebuild element.
         this.hasChanged = true;
         this.update();

         /// Only update site mesh.
         if (this.onlyUsesSiteMesh) {
             const level = this.level;
             if (level) { // Don't trigger whole level update.
                 level.rebuildSiteMesh();
                 PD.GlobalActions.redrawAndUpdateSelection();
                 return false;
             }
         }

         return true;

     }

     return false;

 };
updateDynamicParameters(param, group) {

     /// The following three lines of code replicate
     /// `PD.Base.updateDynamicParametersOnHost()`, which you can
     /// use if you need to access `target` without having to call
     /// `group.getTarget() || this` twice.

     const target = group.getTarget() || this;
     target.checkDynamicParameter(param, group, this);
     if (param.setValueOnHostIfDifferent(target, group, this)) {

         /// You can now use `target`.
         if (target.myOwnMeshThatIsUpdatedDuringRebuild) {

             /// Rebuild element.
             this.hasChanged = true;
             this.update();

             /// If no level meshes or other elements are affected,
             /// simply update the target locally and return false.
             this.myOwnMeshThatIsUpdatedDuringRebuild.update();

             /// Update selection meshes if the
             /// element's highlight geometry changed.
             PD.GlobalActions.updateSelectionMeshes();
             return false;

         }

         return true;

     }

     return false;

 };

alignComponentWithElementJunction(component, element, junction, coords [, no_align]) <static>

Sets the local coordinates to an aligned and potentially rotated position.

This method assumes that the given type component has width, depth and height properties, and that the element has align, offsetX, offsetY and offsetZ properties. This is true of appliance, fixture and furnishing elements. It also factors in the junction's orientation and projection offset attributes if they are present and non-zero.

Parameters:
Name Type Argument Description
component BIM.Component

A type component with width, depth and height properties.
element BIM.Element

An element with align, offsetX, offsetY and offsetZ properties.
junction BIM.Junction

A path junction with optional orientation and projection offset attributes.
coords PD.LocalCoordinates

The local coordinate system to align.
no_align boolean <optional>

When true, alignment is ignored, defaults to false.

getClassDescription() <static>

A brief description of this class to accompany its icon.

Returns:

Returns a brief description.

Type
string

getHostElementClass() <static>

Retrieves the class of the host element for this component.

This method is primarily used by the host user interface when dragging and dropping components into a model or to create an instance of a component on a throw-away element when in the component editor.

This is typically handled by the base type component classes that derive from BIM.Component. However, if your component requires a specific element class as its host. you will need to override this method in order to provide that class.

Returns:

Returns the element class this component requires as a host.

Type
BIM.Element | null

hasMethod(component, methodName) <static>

Determines if the given component is valid and has a callable method with the given name.

This static method is useful for checking if a component instance has a particular method before attempting to call it, thereby avoiding potential runtime errors. It is used within the framework to check for the presence of life-cycle methods in an element's type component before delegating them.

Parameters:
Name Type Description
component BIM.Component

The component to check.
methodName string

The case-sensitive name of the function/method to check for.
Returns:

Returns true if the component is valid and has the function name as a method, otherwise false.

Type
boolean

isCompatibleWith(obj) <static>

Determines if this component can be added to the given object.

Parameters:
Name Type Description
obj BIM.ENTITY | BIM.Entity

The entity type or object to check for compatibility with.
Returns:

Returns true if the component can be added to the object, otherwise false.

Type
boolean

isComponent() <static>

Indicates that this is a BIM component class.

Returns:

Returns true when the class is a BIM component.

Type
boolean

subType() <static>

Retrieves the element-specific sub-type of this class.

Every BIM.Element subclass has a corresponding BIM.ElementType class that derives from BIM.Component. Many element types also have a corresponding enumeration that define various sub-types. Use this method to return that enumerator the specific sub-type a subclass represents.

This value is also accessible via the subType property of each instance of this class. A value of zero refers to the default type for that element.

Returns:

Returns the sub-type enumerator of this class.

Type
number