Plugin API » Interfaces » StoreObject

StoreObject interface

A JavaScript object implementing the StoreObject interface is an object in the Object Store.

A StoreObject is not mutable. To modify and existing object, use mutableCopy to create a copy, modify it, then save the copy. This does not change any StoreObject in memory.

The interface has a core set of properties and functions, and then schema specific functions are added. These will be different for each application.

Construction

Use the load() function on Ref objects.

StoreQueryResults objects act as an array of store objects.

For creating new store objects, use StoreObjectMutable, constructed by O.object().

To create a “restricted view” of a store object, which only has the attributes that should be visible to a particular user, use the restrictedCopy function on an original unrestricted store object.

Interface

property ref

Use the ref property to find the object reference for an object. It has a Ref value, or null if the object has not been saved.

property labels

A LabelList object representing the labels applied to this object.

This property is read only. Use the relabel() function to change the labels on an object.

property deleted

true is the object has been deleted (that is, labelled with the DELETED label), false otherwise.

property version

Version number of the object.

property title

The first title attribute of this object, converted to a string. object.title is equivalent to object.firstTitle().toString().

property shortestTitle

The shortest title attribute of this object, converted to a string. Length is measured in characters. If two title attributes have the same length, this property has the string value of the first.

property descriptiveTitle

Returns the title of the object, suitable for displaying in a link to an object.

Descriptive titles may include the values of some of the attributes, if configured, to disambiguate objects. Use descriptive attributes in links where the object is out of context.

Use title to get the title of the object without any extra information, for use where space is constrained.

function url(asFullURL)

Returns the url of this object. If asFullURL is true, this will include the protocol and hostname, otherwise just the path on the server suitable for an intra-site link. Examples:

asFullURL	String returned
false, or omitted	/main/8y98z/example-object
true	http://clientname.example.com/main/8y98z/example-object

Only works if the object has been saved.

function isMutable()

Returns true if the object is mutable.

function mutableCopy()

Returns a mutable copy of this object, which is independent of this object. As well as implementing this interface, it also implements StoreObjectMutable.

Restricted objects cannot have mutable copies of them made.

function isRestricted()

Returns true if the object is restricted to only show attributes visible to a particular user.

function restrictedCopy(user)

Returns a restricted copy of this object, which only contains the attributes that are visible to the specified user (which will commonly be O.currentUser).

You cannot call this function on an already-restricted object.

function canReadAttribute(desc,user)

Returns true if the specified user is allowed to view the specified attribute (regardless of qualifier). These are the attributes that will still be present in a restricted copy of this object. Unless a plugin uses restrictedCopy to create a restricted version of the object with these attributes missing, they will still be able to access them through the StoreObject API; this restriction is honoured by the platform’s object rendering logic, and (through this function and restrictedCopy) made visible to plugins so that they can implement restrictions as they see fit.

function canModifyAttribute(desc,user)

Returns true if the specified user is allowed to modify the specified attribute (regardless of qualifier). There is no restriction on plugins creating a mutableCopy and editing this attribute through the StoreObject interface; this restriction is honoured by the platform’s object editor user interface, and (through this function) made visible to plugins so that they can implement restrictions as they see fit.

function relabel(labelChanges)

Relabel the object, using the changes specified by the LabelChanges object passed in. If the current user is not allowed to relabel this object, an exception will be thrown.

If the labelChanges wouldn’t actually change the labels on the object, this API may skip the relabel operation. In this case, there would be no audit trail entry for the operation.

function deleteObject()

Deletes this object from the store.

Note that this just labels the object as deleted, and it can still be loaded (subject to permission enforcement). Searches do not return deleted objects by default.

function render(style)

Returns an HTML representation of the object in the specified style. Omit the argument to use the generic style.

It’s usually better to use the std:object standard template when including the object in a generated web page.

function isKindOf(typeRef)

Returns true if this object is the type specified as typeRef, or one of it’s sub-types.

typeRef is a Ref. Use the schema TYPE constants.

If typeRef is null or undefined, then false will be returned.

function isKindOfTypeAnnotated(annotation)

Returns true is this object has a type which is annotated by annotation.

Type annotations are defined in requirements.schema files.

function first(desc, qual)

Returns the first value in the object described by desc and qual, or null if no value is present. Use the schema ATTR constants.

qual may be omitted. Use the schema QUAL constants.

Remember that a core strength of the Haplo data model is its universal support for multi-values. While it may be appropriate to use the first() function (and schema specific firstX() functions), you should really be using the every() function and using all values. If you find yourself using first(), make sure you shouldn’t really be using every().

function firstType(qual)

Shortcut for first(ATTR["dc:attribute:type"], qual)

function firstTitle(qual)

Shortcut for first(ATTR["dc:attribute:title"], qual)

function firstParent(qual)

Shortcut for first(ATTR["std:attribute:parent"], qual)

function every(desc, qual, ext, iterator)

All arguments are optional. desc and qual as for the first() function, ext is an AttributeExtension.

If the last argument is not a function, an array of all the values will be returned.

If the last argument is a function, it will be called for each matching value with the arguments (value, desc, qual).

function each(desc, qual, ext, iterator)

Alias for every().

function everyType(qual, iterator)

Shortcut for every(ATTR["dc:attribute:type"], qual, iterator)

function everyTitle(qual)

Shortcut for every(ATTR["dc:attribute:title"], qual, iterator)

function has(value, desc, qual)

Returns true if this object has an attribute with a given value, and false otherwise.

desc and qual are optional, although typically you would use desc to specify which attribute should be checked. If qual is specified, only attributes with that qualifier will be checked, otherwise the qualifier is ignored in the comparison.

This is more useful than code like (value === object.first(desc, qual)) as it takes account of multiple values in the attribute, and knows how to convert and compare values properly.

function attributeGroupHas(groupDesc, value, desc, qual)

Returns true if this object has an attribute-group at the given groupDesc with a given value, and false otherwise.

desc and qual are optional, although typically you would use desc to specify which attribute should be checked within the attribute group. If qual is specified, only attributes with that qualifier will be checked, otherwise the qualifier is ignored in the comparison.

function valuesEqual(object, desc, qual)

Compare the values in this object with those in another object. Returns true if the list of values, including their descriptors and qualifiers, are exactly equal in the two objects.

The values are sorted by descriptor, but the order of values in any given descriptor is preserved. This matches the behaviour you’d expect if you were comparing objects in the user interface.

desc and qual are optional. If desc is specified, then only values with that descriptor are compared. If qual is specified, then only values with the descriptor and qualifier are compared.

function extractAllAttributeGroups()

Decomposes the StoreObject into a JavaScript object with keys object and groups. groups is an array, containing for each attribute group on the StoreObject:

groupId	Corresponding to the AttributeExtension for the group
groupDesc	Corresponding to the AttributeExtension for the group
object	A temporary object containing the attributes in the group. This will have the appropriate type attribute for the group’s requirements.

function extractSingleAttributeGroupMaybe(groupId)

Returns a temporary object with the attributes contained within the attribute group for groupId.

function extractSingleAttributeGroup(groupId)

As above, but exceptions if no group is found.

function getAttributeGroupIds(desc)

Return the group IDs for attribute extension groups in this object, optionally only for groups with a given desc.

function attributeGroupIdForValue(groupDesc, value, desc, qual)

Returns the groupId of the first AttributeExtension with groupDesc, value, desc, and qual. desc and qual are optional. Returns null if no attribute group is found.

function reindex()

Re-indexes the object.

Hooks such as hPreIndexObject can change the indexed contents, and hooks like hLabelAttributeGroupObject can affect restrictions. When the results of these change, for example, when dependent data is updated, reindex() must be called to reflect the changes in the object store.

function reindexText()

Request that the text of the object is reindexed. This will happen in the background and may be delayed if there is other indexing activity.

In general, you shouldn’t need to use this, except if you’re doing exciting things with hPreIndexObject.

property creationUid

The user ID of the user who created this object. May be zero if it was created during initialisation of the application.

Use O.user() to retrieve user information.

property lastModificationUid

The user ID of the user who last modified this object. May be zero if it was created during initialisation of the application.

Use O.user() to retrieve user information.

property creationDate

The date and time at which the object was created, as a JavaScript Date object.

property lastModificationDate

The date and time at which the object was last modified, as a JavaScript Date object.

property history

An object implementing the JavaScript Array interface which contains all the previous versions of the object, ordered by version number ascending.

Note that if the labels on the object have changed over time, some versions may be omitted. Only versions with labels the user is permitted to read are included.