References

Properties of the Self section from the Properties panel have additional configurations that can be used to fully customize the component.

When can use parametrization with also the possibility of using contextual parameters:

Also, we can use references to gain more control. Properties that accept references have a bull's-eye icon on the right:

When the target icon is clicked, a dialog will appear:

By default, the field type is General. To use a reference change the type:

A reference is composed of three parts:

Target: Defines a component where some action is going to be executed.
Action: Defines the action to execute.
Parameters: Defines the parameters of the action.

Target

Defines a component where some action is going to be executed. It can be the current component of any parent component of the hierarchy. A component is referenced using its private Id.

For example, let's see the NavBar component defined in the Deck component:

It has the Visible property defined by reference:

The actual value of the visible property is obtained by calling the inState action in the deck component and passing the slides parameter. The private Id of the Deck component has been defined accordingly:

The Deck component implements the inState action that receives a parameter. When the parameter is slides, it will return true if the pickzen is in the slides state (started and not completed). So, the result will be that the Navbar component will be only visible if the pickzen is in the slides state.

Internally all references are converted to expressions. For example, the above reference would be:

deck.inState(slides)

Special parameters, starting with $, can be used in the references, for example, the $index parameter:

In this example, we have selected the SelectableText component which is any of the answers. It is contained in a Repeater that will iterate over a list of items and will render a SelectableText component for each of them. Once rendered, we need to know which one has been selected, to change its state for example, and highlight it. For that, we have defined a custom property named Selected that is defined as a reference:

In this case, the Selected property will be true if the isSelectedOption action of the slide component returns true. We can see the parameter is $index, and it will be resolved in this case, as the index of the iterating item. The Repeater component will inject a number for each $index parameter of its SelectableText children:

This way, each isSelectedOption will be called with a number, 0 to N, depending on the number of answers (iterated items). Also in this example, the slide target is the private Id of the QuestionSlide:

The component QuestionSlide defines the action isSelectedOption that is used to know if a pickzen answer has been selected by the user.

When a property is configured by reference, an arrow will appear at the left of the field:

Values resolution

The first step to resolve a reference is to check if it is a contextual value. For that, the slide params and properties objects are checked. If the resolves to null, next steps are evaluated.

Next, expression parameters are taken out. For example, in the expression slide.isSelectedOption(3) the unique parameter 3 is taken out being evaluated subsequently the expression slide.isSelectedOption.

If a parameter starts with a $ symbol, it will be resolved as an independent expression. For example, in the slide.isSelectedOption($index) expression, the parameter $index will be resolved as a independent expression index.

Once parameters are taken out, the remaining expression is split by the point symbol. For example the container.dropdown.items.isSelected expression will be resolved as executing the isSelected action in the items object inside the dropdown object inside the container object.

Each part of the expression will be fetched from the context where the hiearchy of the current component belongs to. For example, if a child component property is being resolved in the context will appear the parent object and the child one with their Private Ids as keys.

Each part of an expression can be objects itself or actions. For example in the expression container.getChildren.delete(3), the second part of the expression is an action that will be executed to get the children objects.

In the case of getters, the get prefix can be removed so the expressions container.getChildren.delete(3) and container.children.delete(3) are identical.

Special methods

exists: Returns true if the expression once resolved exists
hasContent: Returns true if the expression once resolved has content. In case of HTML, all tags are removed to evaluate, so expressions like <div class=my-class"></div> will return false.
setting: Returns a global theme using the expression once resolved as key.