JavaScript API

i·views 5.3

Class: SemanticElement

$k. SemanticElement

new $k.SemanticElement()

Represents an element of the semantic network.

Methods

static$k.SemanticElement.sort(semanticElements, sortDescriptions) : Array.<$k.SemanticElement>

Returns the elements sorted by the given properties and sort orders

Name Type Description
semanticElements Array.<$k.SemanticElement>
sortDescriptions Array.<object>

Property (type or internal name), optional language for attribute values and optional sort order (ascending)
Since:
  • 4.1.0
See:
Returns:
Type Description
Array.<$k.SemanticElement> The sorted elements
Example
$k.SemanticElement.sort(elements, [ {property: "dateOfBirth", language: "eng", ascending: false }, {property: "givenName" }])

attribute(type) : $k.Attribute

Returns the attribute of the type (including sub-attributes), or undefined if no attribute exists

Name Type Description
type

AttributeType or internal name
Throws:
Type Description
$k.exception.NotUnique

If there is more than one attribute of this type
Returns:
Type Description
$k.Attribute

attributes(type) : Array.<$k.Attribute>

Returns all attributes of the type (including sub-attributes).
Returns all attributes if the type is undefined

Name Type Description
type optional

AttributeType or internal name or undefined
Throws:
Type Description
$k.exception.SchemaError

If type is not an attribute
Returns:
Type Description
Array.<$k.Attribute>

attributeValue(type, language)

Returns the value of the attribute, or undefined if there is no such attribute

Name Type Description
type

AttributeType or internal name
language string optional

Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
Ignored if the attribute is not translated
Throws:
Type Description
$k.exception.NotUnique

If there is more than one attribute of this type
Returns:
The value of the attribute

attributeValueString(type, language) : string

Returns the value string of the attribute, or undefined if there is no such attribute

Name Type Description
type

AttributeType or internal name
language string optional

Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
Ignored if the attribute is not translated
Since:
  • 4.1.0
Throws:
Type Description
$k.exception.NotUnique

If there is more than one attribute of this type
Returns:
Type Description
string The value string of the attribute

callBehaviour(method, args)

Calls an internal behavior method

Name Type Description
method string

Name of the method
args Array.<object> optional

Arguments of the call
Throws:
Type Description
$k.exception.RuntimeError

When the behavior method raises an exception

changeLog() : Array.<object>

Get the change log object of this SemanticElement as object

Returns:
Type Description
Array.<object> A list of change log entries, each an conforming the below schema.
Null if no change log is present for the SemanticElement. {
"$schema" : "http://json-schema.org/draft-04/schema#",
"type" : "object",
"properties" :
{
"tag" : {
"type" : "string",
"enum" : ["AttributeEvent", "RelationEvent"],
"description" : "is this a change for an attribute or a relation"
},
"type" : {
"type" : "string",
"enum" : ["modify", "create", "delete", "executeMapping"],
"description" : "what kind of change is logged in this event"
},
"timestamp" : {
"type" : "string",
"description" : "time of the change; format: ISO 8601 timestamp string without timezone",
},
"topic" : {
"type" : "object",
"description" : "id and label of the changed object",
"properties" : {
"label" : { "type" : "string" },
"id" : { "type" : "string" }
}
},
"user" : {
"type" : "object",
"description" : "id and name of the user object which performed the change",
"properties" : {
"label" : { "type" : "string" },
"id" :{ "type" : "string" }
}
},
"property" : {
"type" : "object",
"description" : "id and label of the changed property type",
"properties" : {
"conceptId" : { "type" : "string" },
"label" : { "type" : "string" }
}
},
"value" : {
"type" : "string",
"description" : "string representation of the new value"
},
"language" : {
"type" : "string",
"description" : "language of the changed value; format: ISO639 3-letter code"
},
"oldValue" : {
"type" : "string",
"description" : "string representation of the previous value"
},
"target" : {
"type" : "object",
"description" : "id and label of the relation target object",
"properties" : {
"id" : { "type" : "string" },
"label" : { "type" : "string" }
}
},
"required" : [ "type", "tag", "timestamp", "topic" ]
}
}

core() : $k.SemanticElement

Returns the extended element, if this is an extension.
Returns the element itself otherwise

Returns:
Type Description
$k.SemanticElement

createAttribute(type, value, language) : $k.Attribute

Creates a new attribute with the given value

Name Type Description
type

AttributeType or internal name
value

Value of the attribute. Pass undefined for attribute types without value.
language string optional

Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
Ignored if the attribute is not translated
Throws:
Type Description
$k.exception.InvalidValue

If the value is not in the range of allowed values of the attribute
$k.exception.SchemaError

If type is not a possible attribute of the element, or if no additional attributes can be created.
$k.exception.NotUnique

If there is more than one attribute of this type
$k.exception.AccessDenied

If creating an attribute is not allowed
$k.exception.TransactionError

If no write transaction is active
Returns:
Type Description
$k.Attribute
Example
person.createAttribute("alias", "Tester");

createAttributeFromString(type, valueString, language) : $k.Attribute

Creates a new attribute and set the value from the string representation

Name Type Description
type

AttributeType or internal name
valueString string

String represantation of the value
language string optional

Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
Ignored if the attribute is not translated
Deprecated
  • Use setAttributeValue($k.ValueString(valueString), language) instead
    Throws:
    Type Description
    $k.exception.InvalidValue

    If the value is not in the range of allowed values of the attribute
    $k.exception.SchemaError

    If type is not a possible attribute of the element, or if no additional attributes can be created.
    $k.exception.NotUnique

    If there is more than one attribute of this type
    $k.exception.AccessDenied

    If creating an attribute is not allowed
    $k.exception.TransactionError

    If no write transaction is active
    Returns:
    Type Description
    $k.Attribute
    Example
    person.createAttributeFromString("dateOfBirth", "2.3.1968", "de");

    createRelation(type, target, inverse) : $k.Relation

    Creates a new relation

    Name Type Description
    type

    RelationType or internal name
    target $k.SemanticElement

    The relation target.
    inverse optional

    RelationType or internal name of the inverse Relation. The default inverse relation type will be used if this parameter is undefined.
    Throws:
    Type Description
    $k.exception.SchemaError

    If type is not a possible relation of the element, or if no additional relations can be created.
    $k.exception.AccessDenied

    If creating a relation is not allowed
    $k.exception.TransactionError

    If no write transaction is active
    Returns:
    Type Description
    $k.Relation

    element() : $k.SemanticElement

    Returns this element. Allows to send element() either to a $k.Hit or a semantic element

    Since:
    • 4.3.0
    Returns:
    Type Description
    $k.SemanticElement

    ensureAttributeValue(type, value, language) : $k.Attribute

    Returns an existing attribute with the given value. Otherwise creates and returns an additional attribute with the given value, or returns an existing attribute with modified value if the schema does not allow multiple occurrences.

    Name Type Description
    type

    AttributeType or internal name
    value

    The value that should be set.
    language string optional

    Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
    Ignored if the attribute is not translated
    Since:
    • 4.3.0
    Throws:
    Type Description
    $k.exception.InvalidValue

    If the value is not in the range of allowed values of the attribute
    $k.exception.SchemaError

    If type is not a possible attribute of the element
    $k.exception.AccessDenied

    If modifying is not allowed
    $k.exception.TransactionError

    If no write transaction is active
    Returns:
    Type Description
    $k.Attribute

    ensureRelationTarget(type, target, inverse) : $k.Relation

    Returns a existing relation to the target. Otherwise creates and returns an additional relation to the target, or returns an existing relation relocateded to the target if the schema does not allow multiple occurrences

    Name Type Description
    type

    RelationType or internal name
    target $k.SemanticElement

    The relation target.
    inverse optional

    RelationType or internal name of the inverse Relation. Only applies, if a new relation will be created. The default inverse relation type will be used if this parameter is undefined.
    Since:
    • 4.3.0
    Throws:
    Type Description
    $k.exception.SchemaError

    If type is not a possible relation of the element, or if no additional relations can be created.
    $k.exception.AccessDenied

    If creating a relation is not allowed
    $k.exception.TransactionError

    If no write transaction is active
    $k.exception.RemoveNotPossible

    If deleting the existing relation is not possible
    Returns:
    Type Description
    $k.Relation

    hasPossibleAttribute(type) : boolean

    Returns true if the type is a possible attribute of this element

    Name Type Description
    type

    AttributeType or internal name
    Returns:
    Type Description
    boolean

    hasPossibleRelation(type) : boolean

    Returns true if the type is a possible relation of this element

    Name Type Description
    type

    RelationType or internal name
    Returns:
    Type Description
    boolean

    icon(size, language) : blob

    Returns the icon of the element as blob

    Name Type Description
    size array optional

    Size of icon as array
    language string optional

    Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
    Ignored if the attribute is not translated
    Since:
    • 4.1.0
    Returns:
    Type Description
    blob

    iconAttribute(size, language) : attribute

    Returns the icon of the element as blob attribute

    Name Type Description
    size array optional

    Size of icon as array
    language string optional

    Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
    Ignored if the attribute is not translated
    Since:
    • 5.3.0
    Returns:
    Type Description
    attribute

    idNumber() : number

    Returns the element ID as 64 bit integer.
    Returns undefined for non-persistent elements (system relations etc.)

    Deprecated
    • Do not use due to 64 bit representation problems for numbers larger than 2^53 in JavaScript
      Returns:
      Type Description
      number

      idString() : string

      Returns the element ID as string (ID123_456).
      Returns undefined for non-persistent elements (system relations etc.)

      Returns:
      Type Description
      string

      inheritedAttribute(type) : $k.Attribute

      Returns the own attribute or the inherited attribute of the supertype(s).
      If there is more than one supertype, the attribute must be unique.
      If this is not a type, then this function is equivalent to attribute().

      Name Type Description
      type

      AttributeType or internal name
      Throws:
      Type Description
      $k.exception.NotUnique

      If there is more than one value of this type
      Returns:
      Type Description
      $k.Attribute The inherited attribute, or undefined if there is no attribute

      inheritedAttributeValue(type, language)

      Returns the value of the own attribute or of the inherited value of the supertype(s).
      If there is more than one supertype, the value must be unique.
      If this is not a type, then this function is equivalent to attribute(value).

      Name Type Description
      type

      AttributeType or internal name
      language string optional

      Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
      Ignored if the attribute is not translated
      Throws:
      Type Description
      $k.exception.NotUnique

      If there is more than one value of this type
      Returns:
      The inherited value, or undefined if there is no attribute

      isInvalid() : boolean

      True if the semantic element was deleted (e.g. by a rollback or remove()

      Returns:
      Type Description
      boolean

      kPathEvaluate(pathString)

      Name Type Description
      pathString

      locatorString(locatorTypes) : string

      Returns the element locator as string

      Name Type Description
      locatorTypes array optional
      Since:
      • 4.0.2
      Returns:
      Type Description
      string

      modificationNumber() : number

      Returns the modification number for the cluster conatining as 64 bit integer.
      Returns 0 for newly created topics that are not yet assigned to a cluster.
      Returns undefined for non-persistent elements (system relations etc.).
      An unchanged modification number indicates that the element is unchanged.
      A changed modification number does not necessarily indicate that the topic changed,
      because there might have been changes in other objects contained in the same cluster.

      Returns:
      Type Description
      number

      name(language) : string

      Returns the name of the element

      Name Type Description
      language string optional

      Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
      Ignored if the attribute is not translated
      Returns:
      Type Description
      string

      openInKnowledgeBuilder(user)

      Name Type Description
      user $k.User
      Version:
      • Experimental feature, might be removed at any time

      possibleProperties(filter) : Array.<$k.PropertyType>

      Returns the possible properties of this element.

      Name Type Description
      filter $k.PropertyFilter optional

      Optional filter that defines which properties are returned
      See:
      Returns:
      Type Description
      Array.<$k.PropertyType>
      Examples
      // Possible properties, excluding shortcut / system relations
      possibleProperties();
      // Possible properties, including system relations
      possibleProperties($k.PropertyFilter.setSystemRelations());
      // Same as above, using a literal object to define the filter
      possibleProperties({ systemRelations: true });

      primaryCore() : $k.SemanticElement

      Returns the primary element.

      • if the receiver is an instance or type, then the receiver itself is returned.
      • if the receiver is an extension, then the extended instance is returned.
      • if the receiver is a property, then the primary core of the source is returned.
      Since:
      • 4.2.0
      Returns:
      Type Description
      $k.SemanticElement

      properties(filter) : Array.<$k.Property>

      Returns all properties of the property type

      Name Type Description
      filter $k.PropertyFilter optional

      Filter that defines which properties are returned
      Returns:
      Type Description
      Array.<$k.Property>
      Examples
      // All properties
      properties();
      // All relations with internal name "contains", including sub-relations
      properties(new $k.PropertyFilter().setType("contains"));
      // All relations with internal name "contains", without sub-relations
      properties(new $k.PropertyFilter().setExact().setType("contains"));
      // Same as above, using a literal object to define the filter
      properties({ exact: true, type: "contains" });

      relation(type) : $k.Relation

      Returns the relation of the type (including sub-relations), or undefined if no relation exists

      Name Type Description
      type

      RelationType or internal name
      Throws:
      Type Description
      $k.exception.SchemaError

      If type is not a possible relation of the topic
      $k.exception.TypeError

      If type is not a relation type
      $k.exception.NotUnique

      If there is more than one relation of this type
      Returns:
      Type Description
      $k.Relation

      relations(type) : Array.<$k.Relation>

      Returns all relations of the type (including sub-relations).
      If type is undefined, all user relations (excluding inverse one way relations) are returned.

      Name Type Description
      type optional

      RelationType or internal name or undefined
      Throws:
      Type Description
      $k.exception.TypeError

      If type is not a relation type
      Returns:
      Type Description
      Array.<$k.Relation>

      relationTarget(type) : $k.SemanticElement

      Returns the target of the relation of the relation type, or undefined if there is no such relation

      Name Type Description
      type

      RelationType or internal name
      Throws:
      Type Description
      $k.exception.NotUnique

      If there is more than one relation of this type
      $k.exception.TypeError

      If type is not a relation type
      Returns:
      Type Description
      $k.SemanticElement

      relationTargets(type) : Array.<$k.SemanticElement>

      Returns the targets of the relations of the relation type. Each target is only returned once, even if multiple relations point to the same target.
      Returns all relation targets if the type is undefined

      Name Type Description
      type

      RelationType or internal name or undefined
      Throws:
      Type Description
      $k.exception.NotUnique

      If there is more than one relation of this type
      $k.exception.TypeError

      If type is not a relation type
      Returns:
      Type Description
      Array.<$k.SemanticElement>

      remove()

      Deletes the element and all attached properties

      Throws:
      Type Description
      $k.exception.AccessDenied

      If deleting the element or any property not allowed
      $k.exception.RemoveNotPossible

      If deleting the element is not possible, e.g. when trying to delete a system element

      render(context, keyFilter, detailFilter) : object

      Renders the element as a literal object using the associated view configuration.
      Uses the optional context topic to detect a suitable configuration

      Name Type Description
      context object optional

      Element that defines the context.
      keyFilter object optional

      Alternative 1: An array of strings defining a filter which property names to include.

      Alternative 2: An object with "include" and/or "exclude" keys

      {"exclude": ["key1", ...]}
      includes all but the listed properties, while 
      {"include": ["key1", ...]}
      or 
      ["key1", ...]
      includes only the listed properties.

      Non-optional properties are always included

      Alternative 3: A JSONRenderContext
      detailFilter object optional

      A filter to define the granularity of the JSON structure

      [ "schema" ]
      includes json with schema information
      Returns:
      Type Description
      object The rendered object

      renderJSON(context, excludedKeys, detailFilter) : object

      Render the element as a JavaScript object using the associated view configuration.
      Uses the optional context topic to detect a suitable configuration

      Name Type Description
      context $k.SemanticElement optional

      Element that defines the context.
      excludedKeys Array.<string> optional

      Collection of property names that are excluded
      detailFilter object optional

      A filter to define the granularity of the JSON structure

      [ "schema" ]
      includes json with schema information
      Deprecated
      • Use render(context, {"exclude": excludedKeys}) instead
        Returns:
        Type Description
        object The rendered JSON object

        renderTemplate(template, entity, conversion, variables)

        Render a document based on a given printtemplate

        Name Type Description
        template $k.SemanticElement

        the template that will be applied
        entity $k.NetEntity

        The render target
        conversion $k.SemanticElement optional

        the semantic element representing the document conversion
        variables object optional

        additional variables to pass to the template
        Since:
        • 4.4.0

        setAttributeFromString(type, valueString, language)

        Sets the value of the attribute from the string representation. Creates a new attribute if no such attribute exists

        Name Type Description
        type

        AttributeType or internal name
        valueString string

        String represantation of the value
        language string optional

        Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
        Ignored if the attribute is not translated
        Deprecated
        • Use setAttributeValue(type, $k.ValueString(valueString), language) instead
          Throws:
          Type Description
          $k.exception.InvalidValue

          If the value is not in the range of allowed values of the attribute
          $k.exception.SchemaError

          If type is not a possible attribute of the element
          $k.exception.NotUnique

          If there is more than one attribute of this type
          $k.exception.AccessDenied

          If modifying is not allowed
          $k.exception.TransactionError

          If no write transaction is active

          setAttributeValue(type, value, language)

          Sets the value of the attribute. Creates a new attribute if no such attribute exists

          Name Type Description
          type

          AttributeType or internal name
          value

          The value that should be set.
          language string optional

          Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
          Ignored if the attribute is not translated
          Throws:
          Type Description
          $k.exception.InvalidValue

          If the value is not in the range of allowed values of the attribute
          $k.exception.SchemaError

          If type is not a possible attribute of the element
          $k.exception.NotUnique

          If there is more than one attribute of this type
          $k.exception.AccessDenied

          If modifying is not allowed
          $k.exception.TransactionError

          If no write transaction is active

          setName(name, language)

          Sets the name of the element

          Name Type Description
          name string

          The name
          language string optional

          Language of the value. Either ISO 639-1 (2-letter code, e.g. "en") or ISO 639-2B (3-letter code, e.g. "eng"). If not defined, the current language will be used.
          Ignored if the attribute is not translated
          Throws:
          Type Description
          $k.exception.TypeError

          If the name is not a string
          $k.exception.TransactionError

          If no write transaction is active

          setRelationTarget(type, target, inverse)

          Sets the target of the relation. Creates a new relation if no such relation exists

          Name Type Description
          type

          RelationType or internal name
          target $k.SemanticElement

          The relation target.
          inverse optional

          RelationType or internal name of the inverse Relation. Only applies, if a new relation will be created. The default inverse relation type will be used if this parameter is undefined.
          Since:
          • 4.3.0
          Throws:
          Type Description
          $k.exception.SchemaError

          If type is not a possible relation of the element, or if no additional relations can be created.
          $k.exception.NotUnique

          If there is more than one relation of this type
          $k.exception.AccessDenied

          If creating a relation is not allowed
          $k.exception.TransactionError

          If no write transaction is active
          $k.exception.RemoveNotPossible

          If deleting the existing relation is not possible

          type() : $k.Type

          Returns the type of the element.
          If the topic is a type, the type itself is returned

          Returns:
          Type Description
          $k.Type

          updateMapping()

          Update the prototype after sending $k.mapInstances(). Only required if this element was referenced before setting the mapping.