View source for Documentation:OCLOperators RootObject

Use the '''RootObject''' operator in a ViewModel expression or action when you need to inspect or update the object instance that opened the current ViewModel.

== What RootObject returns ==
<code>selfVM.RootObject</code> returns the specific object instance used as the root when the current [[Documentation:ViewModel|ViewModel]] was opened.

The root reference is '''read-only''': while the ViewModel is open, you cannot change which object is its root. You can, however, change attributes on that root object.

For example, if the ViewModel was opened for a <code>Thing</code> object, RootObject refers to that particular <code>Thing</code> instance.

== Check whether the ViewModel has a root ==
Use <code>notEmpty</code> to test whether the ViewModel is rooted in an object:

<syntaxhighlight lang="csharp">
selfVM.RootObject->notEmpty
</syntaxhighlight>

This expression evaluates whether a root object is present. Use it when an action or expression must behave differently for a rooted ViewModel.

== Access attributes on the root object ==
RootObject is not typed as the model class that opened the ViewModel. Before accessing model-specific attributes or associations, cast it to the expected class with <code>safeCast</code>.

For example, to update <code>SomeString</code> on a root object that is a <code>Thing</code>:

<syntaxhighlight lang="csharp">
selfVM.RootObject->safeCast(Thing).SomeString := 'a new value'
</syntaxhighlight>

This changes the <code>SomeString</code> attribute of the existing root object. It does not replace the root object.

== Why a cast is required ==
[[Documentation:Learn OCL|OCL]] is statically typed: OCL must know an expression's type before it can validate access to an attribute such as <code>SomeString</code>.

<code>selfVM</code> is context-sensitive and available in all ViewModels. Different ViewModels can be opened with different root classes, so there is no one model-class type that RootObject can always have. In the context of a specific ViewModel, you know the expected root class; use <code>safeCast</code> to state that type before accessing its members.

{| class="wikitable"
! Goal
! Expression pattern
! Example
|-
| Test for a root object
| <code>selfVM.RootObject->notEmpty</code>
| <code>selfVM.RootObject->notEmpty</code>
|-
| Read or update a root-object member
| Cast RootObject, then access the member
| <code>selfVM.RootObject->safeCast(Thing).SomeString := 'a new value'</code>
|}

== Use RootObject in an action ==
# Identify the class that the ViewModel is expected to use as its root. In this example, it is <code>Thing</code>.
# Test <code>selfVM.RootObject->notEmpty</code> if the action can run without a root object.
# Cast RootObject with <code>selfVM.RootObject->safeCast(Thing)</code>.
# Read or update the required attribute or association on the cast object.

Keep the cast aligned with the ViewModel's expected root class. A cast to an unrelated class does not give RootObject that class's attributes.

== See also ==
* [[Documentation:Learn OCL|Learn OCL]]
* [[Documentation:OCL General Operators]]
* [[Documentation:OCL Boolean Operators]]

[[Category:Intermediate-Friendly]]
[[Category:OCL (Object Constraint Language)]]
[[Category:OCL Operators: Collection Navigation]]
[[Category:Priority 50]]