Element Visibility

In this Lesson

You will

  • Learn more about the line of authority between the engineering and design teams
  • Learn about element binding properties
  • Learn how to control element visibility
  • Learn how errors are presented when nodes with errors are not displayed in the scene


The elements you have been placing in your scenes up to this point are always visible. This is the default behavior for any element. There are times, however, when you may want an element to appear (or disappear) in response to a given set of conditions. For example, you may want a button named ‘Approve Shipment’ to appear only if the shipment is actually eligible for approval.

The conditional visibility of an element is always based on one or more pieces of data contained in the system.
It is typically expressed in software like this

At the surface this looks pretty simple and easily done, however, the surface of the water can be deceiving. Before you commit to jumping in you should peer below the surface to see what awaits you. As we look beneath the surface we see two completely different fish mixing it up in the pool of meaning.

What we have is a curiously unhealthy mixture of data control logic and display options.
[ i see leakage! ]

Lines of Authority

Who is responsible for handling this apparently simple situation?

Should the engineer be responsible?
Making the engineer responsible forces them to overstep their responsibility and make decisions for the presentation layer. Should the button be hidden or simply be disabled when approvals are not allowed? Should the user experience guide the customer through a series of shipment review steps before allowing approval? These are decisions the engineer should not have to make.

Why should the engineer care how or when the option is presented? All they should care about is 1) is approval allowed? and 2) how do I approve a shipment when asked?

  • The engineer should never overstep their bounds by assuming there is a visual layer or by thinking they have any control over it if one does exist.
    [ what? no ‘visual’ layer? so, perhaps another program could call the agent as a service? interesting…]
  • The engineer should never allow others to take over their responsibility.
    They must protect the data by always doing the right thing – regardless of who is asking or when they are making the request.
Never Trust the Caller
Engineers must never trust the caller to know when it is safe to do something. Agents must always verify that an event is allowed before processing the event. What if the state of the shipment changed after the button was displayed to the customer but before they pressed it?

Should the designer be responsible?
Making the designer responsible forces them to overstep their responsibility and make decisions for the data control aspects of the solution. They would need to know if approval is allowed. It would require an understanding of the data model and how to protect the information it contains – along with all the programming syntax that accompanies the task.
[ wait just a minute … that would make them an engineer! even i can see that and my bulb is not fully lit.]

The designer does not need to be concerned with why something is allowed.

  • The designer should be concerned with what is allowed and then present the option to the customer in the best possible way.
  • The designer should retain authority over what is presented to the customer and when it is shown.

The Greatest Harm

Overstepping one’s area of responsibility causes an erosion of the team’s human fabric.

We are always better together.
No one is excellent at everything but a person can be superb in selected disciplines. A rich cross-discipline team where individuals with focused expertise bring their ‘A’ game to each party is a wonderful thing.

  • Respecting the responsibilities of each discipline allows people to use their best skills and be actively involved in pulling the product through the software factory and onto the showroom floor.
  • Overstepping those responsibilities may cause individuals to be side-lined from the production process or force them to work in their areas of weakness instead of contributing their areas of strength.
    • As a result the production line slows down and the risk of causing harm to the product increases.
    • It becomes more difficult to decompose the tasks and allow multiple people to work in parallel.

This erosion of human fabric is harmful but it is not the greatest harm – especially if the team is very small. [ yep, i AM the team most of the time ]

The greatest harm is increased complexity. This strikes at the core of the product itself – regardless of team size.

Data control logic can be a daunting task all by itself. The same could be said of creating an excellent visualization and process flow. Mixing all of these concerns into the same bucket and then giving them a good stir can do unhealthy things to the complexity meter. Giving that brew to a single person is nasty. Feeding it to a team can be toxic.

  • Systems are harder to create
  • Systems are harder to maintain
  • Things are more likely to go wrong
  • When things go wrong they are harder to discover and resolve
  • The system becomes brittle and difficult to adapt to changing business requirements
  • Costs and timelines get out of control

On the bright side – these problems may give you the opportunity to re-write the solution at some point.
[ hey, there is NOT a bright side ]

Shared Responsibility

Element visibility is one example of how Soiree uses shared responsibility to accomplish a task. Two issues need to be addressed: control logic and display options. One cannot work without the other.

Shared responsibility

  • Allows the designer to remain in control of how the scene works
  • Allows the engineer to remain in control of the data and its integrity

This shared responsibility could be two separate people coordinating their work or it could be a single person working in both layers of the technology stack. Either way you end up with a well structured relationship between the logic and presentation layers.

Element Visibility

Soiree provides a simple communication mechanism for element visibility

  • The engineer provide hints to the designer about the state of the data in the system.
    This is done adding a boolean node to a scheme. The name of the node describes the hint that is being offered. In our example we would create a node named shipmentApprovalAllowed. The agent would set the node true or false according to the status of the shipment.
  • The designer may use these boolean hints to impact their design or they may ignore them entirely.
    You can control the visibility of an element by binding a boolean node to it. The value of the node determines whether or not the element should be visible. You have the option of making the element visible when the boolean is true and hidden when it is false, or you may choose to make the element visible when the boolean is false and hidden when it is true.
Another Sealant
This clear separation of concerns is another sealant against leakage across layers of responsibility. Soiree enforces the separation by not allowing code to be introduced in the visual layer and by not allowing the agent to have control of an element. In Soiree you cannot intermix the control logic and display options even if you wanted to.

Element Binding Properties

Elements may have more than one node bound to them – each node serving a different purpose for the element. Each purpose is called a binding property. The exact type or quantity of binding properties offered by an element can vary according to the capabilities of the element and the type of node being dragged to the element.

When you drag a node over an element a list containing the available binding properties is displayed above the mouse pointer. One of the binding properties in the list will be highlighted as the one to be used when the node is dropped on the element. You can select a different binding property in the list by pressing the alt (Windows) or option (OS X) key as you are dragging the node.

Here are a few examples

The best way to discover what binding properties are available for an element is to drag various node types over it.

Lesson Exercise

In this lesson you will modify the solution to display the theme field only when the ACME tenant is using the product.

Element visibility – providing the hint

You will now add a boolean node to the PartyTheme agent. It will be used to let the designer know if the current tenant requires a theme.

  1. Open the PartyTheme item
  2. Add a boolean node named themeRequired

  3. Build the agent

  4. Open the PartyTheme class

  5. Declare this property at the top of the class (after logger and before the PartyTheme constructor method)
    private static final Integer THEME_TENANT = new Integer(0);
  6. Override the prepareForAddOrReplicateMode method

  7. Add the following syntax to the method
  8. Your PartyTheme class should now look like this

  9. Save the file

Element visibility – using the hint

You will now use the themeRequired node to control the visibility of the theme text field and its label.

  1. Open the PartyDefinition scene
  2. Select the add layer
  3. Switch to the Agent Binding perspective
  4. Bind the themeRequired node to both the theme label and text field elements.

  5. Open the theme text field’s binding properties to see the two nodes bound to the element.

  6. Save the item

Test the scene

  1. Start the solution
  2. Advance to the ‘Create a Party’ layer
    Notice the theme label and text field are displayed. That is because the current tenant is zero and we defined ACME as tenant zero.

  3. Close the Soiree client
  4. Set the ACME tenant to 1 in the PartyTheme agent

  5. Save the PartyTheme agent
  6. Restart the server
  7. Start the solution
  8. Advance to the ‘Create a Party’ layer
    Notice the theme label and text field are no longer displayed.

  9. Press the OK button without entering any values

    Notice The PartyTheme agent is still requiring a theme to be provided. This is because the agent is ignoring its own hint: it should not require or capture a theme unless the ACME tenant is using the product. You will resolve this issue in the next lesson.

    I'm Still Here
    Agents in the active layers are still part of the conversation – even if you choose to ignore what they have to say.

    Welcome to the end of another lesson.