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.