Module Contents



A specialized relational bone for handling user references. Extends the functionality of

class core.bones.user.UserBone(*, creationMagic=False, updateMagic=False, visible=None, readOnly=False, **kwargs)

Bases: viur.core.bones.relational.RelationalBone

A specialized relational bone for handling user references. Extends the functionality of viur.core.bones.relational.RelationalBone to include support for creation and update magic.

  • creationMagic (bool) – If True, the bone will automatically store the creating user when a new entry is added.

  • updateMagic (bool) – If True, the bone will automatically store the last user who updated the entry.

  • visible (bool) – If True, the bone will be visible in the skeleton.

  • readOnly (bool) – If True, the bone will be read-only and its value cannot be changed through user input.

  • kwargs (dict) – Additional keyword arguments passed to the parent class constructor.


ValueError – If the bone has multiple set to True and a creation/update magic is set.

Initialize a new RelationalBone.

  • kind – KindName of the referenced property.

  • module – Name of the module which should be used to select entities of kind “type”. If not set, the value of “type” will be used (the kindName must match the moduleName)

  • refKeys – A list of properties to include from the referenced property. These properties will be available in the template without having to fetch the referenced property. Filtering is also only possible by properties named here!

  • parentKeys – A list of properties from the current skeleton to include. If mixing filtering by relational properties and properties of the class itself, these must be named here.

  • multiple – If True, allow referencing multiple Elements of the given class. (Eg. n:n-relation). Otherwise its n:1, (you can only select exactly one). It’s possible to use a unique constraint on this bone, allowing for at-most-1:1 or at-most-1:n relations. Instead of true, it’s also possible to use a :class:MultipleConstraints instead.

  • format

    Hint for the frontend how to display such an relation. This is now a python expression evaluated by safeeval on the client side. The following values will be passed to the expression

    param value:

    The value to display. This will be always a dict (= a single value) - even if the relation is multiple (in which case the expression is evaluated once per referenced entity)

    param structure:

    The structure of the skeleton this bone is part of as a dictionary as it’s transferred to the fronted by the admin/vi-render.

    param language:

    The current language used by the frontend in ISO2 code (eg. “de”). This will be always set, even if the project did not enable the multi-language feature.

  • updateLevel

    Indicates how ViUR should keep the values copied from the referenced entity into our entity up to date. If this bone is indexed, it’s recommended to leave this set to RelationalUpdateLevel.Always, as filtering/sorting by this bone will produce stale results.

    param RelationalUpdateLevel.Always:

    always update refkeys (old behavior). If the referenced entity is edited, ViUR will update this entity also (after a small delay, as these updates happen deferred)

    param RelationalUpdateLevel.OnRebuildSearchIndex:

    update refKeys only on rebuildSearchIndex. If the referenced entity changes, this entity will remain unchanged (this RelationalBone will still have the old values), but it can be updated by either by editing this entity or running a rebuildSearchIndex over our kind.

    param RelationalUpdateLevel.OnValueAssignment:

    update only if explicitly set. A rebuildSearchIndex will not trigger an update, this bone has to be explicitly modified (in an edit) to have it’s values updated

  • consistency

    Can be used to implement SQL-like constrains on this relation.

    param RelationalConsistency.Ignore:

    If the referenced entity gets deleted, this bone will not change. It will still reflect the old values. This will be even be preserved over edits, however if that referenced value is once deleted by the user (assigning a different value to this bone or removing that value of the list of relations if we are multiple) there’s no way of restoring it

    param RelationalConsistency.PreventDeletion:

    Will prevent deleting the referenced entity as long as it’s selected in this bone (calling skel.delete() on the referenced entity will raise errors.Locked). It’s still (technically) possible to remove the underlying datastore entity using db.Delete manually, but this must not be used on a skeleton object as it will leave a whole bunch of references in a stale state.

    param RelationalConsistency.SetNull:

    Will set this bone to None (or remove the relation from the list in case we are multiple) when the referenced entity is deleted.

    param RelationalConsistency.CascadeDeletion:

    (Dangerous!) Will delete this entity when the referenced entity is deleted. Warning: Unlike relational updates this will cascade. If Entity A references B with CascadeDeletion set, and B references C also with CascadeDeletion; if C gets deleted, both B and A will be deleted as well.

kind = 'user'
datafields = ['name']
performMagic(skel, key, isAdd, *args, **kwargs)

Perform the magic operation on the bone value.

If updateMagic is enabled or creationMagic is enabled and the operation is an addition, the bone will store the current user’s key.

  • skel (SkeletonInstance) – The skeleton instance to operate on.

  • key (str) – The key of the bone in the skeleton.

  • isAdd (bool) – If True, the operation is an addition. Otherwise, it is an update.

  • args – Additional positional arguments.

  • kwargs – Additional keyword arguments.


True if the magic operation was successful, False otherwise.

Return type: