API Docs

Class: Registry

PD. Registry

new Registry()

A central repository for registering handlers, classes and SVG icons.

The registry allows host applications to arbitrarily customise handlers or extend various BIM classes, and have those customisations properly recognised in both the user interface and when saving and loading model data. It also allows host applications to be economical by only registering those specific classes they wish to support.

Author:
  • drajmarsh

Members

:Map

classMap <static>

Stores a map of all currently registered entity classes.

This map associates classes with string-based class names, allowing the application to create instances of user-generated or custom classes that it knows nothing about other than their registered name.

To be registered, a class must implement a static getClassName(), method, as well as className and iconName instance properties (typically as getters). This allows it to be properly registered together with an associated icon. Your entity class will typically derive from PD.Base, which already implements these for you.

Type
  • Map
Example
// Copy a component.
const class_name = myObject.typeComponent.className;
const new_component = PD.Registry.createEntity(class_name, 'BIM.Component');
:Map

iconMap <static>

Stores a map of all currently registered SVG icons.

This map associates an icon name with a simple object containing the SVG content of the icon and its viewBox definition. When registering an icon, the default viewBox is '0 0 1000 1000', which means that coordinates can be given as integers whilst maintaining reasonable resolution.

SVG icons are used within the user interface to provide a visual cue as to the nature and behaviour of building elements and components. Each BIM entity class registers its own icon so that it can be shown and identified in menus and selection lists.

Type
  • Map
Example
PD.Registry.registerIcon('icon-furniture-table', {
     content: '<path d="m500 95c-80 0-160 7-233 23s-131 37-173 64 ... z" />',
     viewBox: '0 0 500 500'
 });
:Map

sharedProjectData <static>

Stores a map of currently shared BIM components, materials and schedule.

Type
  • Map
:Map

userModeHandlerInstanceCache <static>

Stores a cache of current edit mode handler class instances.

Type
  • Map
:Map

userModeHandlerMap <static>

Stores a map of all currently registered edit mode handler classes.

Type
  • Map

Methods

addSelectionHandler(type, handler) <static>

Adds a new global PS.SELECTION type.

The new selection type must be an object of the form {name, description[, key]}. Using this method will add an additional handler property that references the handler argument.

Parameters:
Name Type Description
type object

An object of the form {name, description[, key, handler, etc]}.
handler PD.SelectionHandler

A selection handler instance.
Throws:

Throws an error if the selection type or handler instance is invalid.

Type
Error
Returns:

Returns the number of the new enumeration, or -1 if not added.

Type
number
Example
PD.Registry.addSelectionHandler(
    { key: 'BBOX', name: 'Bounding Box', description: 'A 3D bounding box is selected' },
    new MyBBox.SelectionHandler(PD.GlobalActions.selectionManager)
);

checkForAlias(name) <static>

Checks for an alias if the class name is not found.

This method allows the framework to rename classes and components but still maintain compatibility with older model versions.

Parameters:
Name Type Description
name string

The old name for a class.
Returns:

Returns the new alias for the name if found, otherwise the unmodified name.

Type
string

createEntity(classData, defaultClass [, config]) <static>

Attempts to create a new BIM entity from a data object or class name.

As users can easily extend the framework by registering their own custom BIM classes, there needs to be a way for new objects to be created as instances of the right class, particularly when (re)creating a model from JSON data.

This method first checks if the data object is a string or an object with a className property and attempts to find a matching class to either. If that class is registered, it attempts to create an instance of that class. If that fails, it creates an instance of the default class instead.

If the argument is an object, it will be used as the first argument sent to the class constructor.

Parameters:
Name Type Argument Description
classData string | object

A class name or an object containing a className property.
defaultClass string | object

The class or class name to use if no match for classData is found.
config object <optional>

An optional configuration data object as an argument to the constructor.
Returns:

Returns a new class instance, or null if no matching registered classes found.

Type
object | null

findClassesByName(name) <static>

Iterates through all registered classes searching for matching class names.

This method returns an array with each matching class given as a simple object with the following three string properties:

Type Type Description
className string The name of the class for use with createEntity.
description string A brief description of the class for display in the UI.
name string A human-readable name for the class.

String matching in this method is not case sensitive and simply uses the core indexOf method. To get component classes that are compatible with particular element types, use the findCompatibleClasses() method instead.

Parameters:
Name Type Description
name string

The name or search string to match.
Returns:

Returns an array of matching classes.

Type
Array

findCompatibleClasses(entity_type) <static>

Retrieves all component classes compatible with the given entity.

This method returns an array with each matching class given as a simple object with the following three string properties:

Type Type Description
className string The name of the class for use with createEntity.
description string A brief description of the class for display in the UI.
name string A human-readable name for the class.
Parameters:
Name Type Description
entity_type BIM.ENTITY | BIM.Entity

The entity/type to match component classes with.
Returns:

Returns an array of matching component classes.

Type
Array

getClass(classData) <static>

Retrieves the class for a data object or class name.

This method first checks if the data object is a string or an object with a className property and attempts to find a matching class to either. If no matching class is found, the method returns null.

Parameters:
Name Type Description
classData string | object

A class name or an object containing a className property.
Returns:

Returns a class (constructor) matching the name, or null if not registered.

Type
function | null

getClassesByEntityType(entityType) <static>

Iterates through all registered classes searching for matching entity types.

This method returns an array of classes whose static getEntityType() method matches the given entity type.

Parameters:
Name Type Description
entityType BIM.ENTITY

The entity type required.
Returns:

Returns an array of classes (constructors) matching the type.

Type
Array.<function()>

getSelectionHandler(nameOrValue) <static>

Retrieves the registered handler for the given selection type.

Parameters:
Name Type Description
nameOrValue string | number

A selection type.
Returns:

Returns the class instance for the given type, or null if not found.

Type
PD.SelectionHandler | null

getUserModeHandler(mode) <static>

Retrieves the registered handler for the given edit mode.

Parameters:
Name Type Description
mode PD.MODE | number

The edit mode.
Returns:

Returns the class instance for the given edit mode, or null if not found.

Type
PD.UserModeHandler | null

registerClass(entityClass [, icon]) <static>

Registers a BIM entity class in the central cache.

A BIM entity class must provide a static getClassName(), method, and may optionally provide an SVG icon to associate with the class name.

The PD.Base class also provides className and iconName instance properties (implemented as getters) that will automatically return the class and icon names from subclasses. See the PD.Base class for more details.

As the SVG content strings of some icons can be quite large, we don't really want to be passing large strings around as function arguments. Also, classes may wish to share the same icon without having to duplicate the SVG content string. To facilitate this, the icon data may be passed in as either a content string or an object with a content property, and an optional viewBox property if it is not based on size 1000x1000.

When passed in as an object, the object reference is stored as the associated icon, meaning that multiple classes can pass in the same object without any duplication of string content. This also means that only the object reference is passed to the method, again with no duplication of content strings.

When passing in the content as a string, a new object with content and viewBox properties will be created and stored. It is usually best to use an object as passing large strings directly as an argument may not always be optimised in some browsers, especially as the string will be passed on internally to the registerIcon() method.

Parameters:
Name Type Argument Description
entityClass PD.Base

A BIM class to add to the registry.
icon string | object <optional>

The SVG icon data to associate with this class.
Throws:

Throws an error if the class or class name is invalid.

Type
Error
Returns:

Returns true if the class was registered.

Type
boolean
Example
// Using a string argument.
PD.Registry.registerClass(BIM.Sensor.CO2,
    '<path d="m500 95c-80 0-160 7-233 23s-131 37-173 64 ... z" />'
);

/// Using an object argument.
PD.Registry.registerClass(BIM.Sensor.CO2, {
    content: '<path d="m50 25c-10 0-16 7-3 23s-31 37-17 60 ... z" />',
    viewBox: '0 0 64 64'
});

registerIcon(name, data [, viewBox]) <static>

Registers an icon in the central cache.

The data argument can be given as either a string or an object that must contain a content property and, optionally, a viewBox property. When given as an object, the actual object itself will be stored to allow multiple entries to reference the same icon without duplicating any of its string content. This is important as some SVG icons can be quite large when stored as a string.

When given as a string, a new object with content and viewBox properties will be created and stored. Passing large strings directly as function arguments may not always be optimised in some browsers.

The viewBox, when given as either a property of data or as a third argument, must be a string containing four space-separated numbers as per the SVG viewBox specification. If not given, it defaults to '0 0 1000 1000'.

Parameters:
Name Type Argument Description
name string

A unique name/id for the class.
data string | object

A string or object containing the SVG elements that generate the icon.
viewBox string <optional>

An SVG viewBox setting as four space-separated numbers, defaults to '0 0 1000 1000'.
Throws:

Throws an error if the icon name or its data is invalid.

Type
Error
Returns:

Returns true if the icon was registered.

Type
boolean
Example
PD.Registry.registerIcon('BIM.Sensor.CO2',
     '<path d="m500 95c-80 0-160 7-233 23s-131 37-173 64 ... z" />'
);

PD.Registry.registerIcon('BIM.Sensor.CO3', {
    content: '<path d="m50 25c-10 0-16 7-3 23s-31 37-17 60 ... z" />',
    viewBox: '0 0 64 64'
});

registerUserModeHandler(mode, handler) <static>

Registers a user interaction handler in the central cache.

The SelectionManager is responsible for handling user selection and interactive editing of the building model within the modelling canvas. It has a set of modes for handling particular interactions, such as adding new elements, measuring distances within the model, handling drag/drop event sequences and general model selection and editing.

The current edit mode handler is set using the PD.GlobalActions.setUserMode method or calling the setUserMode() on the current selection manager. You can either override any of the standard PD.MODE modes with your own handler or add a completely custom handler with its own mode.

Parameters:
Name Type Description
mode PD.MODE | number

The edit mode to associate this handler with.
handler PD.UserModeHandler

A PD.UserModeHandler subclass or class instance.
Throws:

Throws an error if the mode or handler class/instance is invalid.

Type
Error
Returns:

Returns true if the handler was successfully registered.

Type
boolean