A couple of months ago, I created a Contact Your Agent scene that used Placeholders groups to show the preferred method to contact your agent - email, phone or Facebook messenger. Each contact method has its own rules when it is valid. A few days ago I got a PCB from Sky Real Estate asking to change the scene to show all valid contact methods - not just the first valid one (see image 1).
Building this looks easy at first - I can create 3 groups, assign of each them with really simple logic (the first icon and text will display the email, the second - phone, third - messenger) and that's it. But what if the phone number in the feed is not valid? Then I'll have this ugly empty space in the middle of my scene. I want the relevant options to be pushed to the top - I want the different contact methods to compete against each other on the free place holders that I have. The first valid contact method (according to the order I choose) will be displayed first, the second valid contact method will be displayed second, and so on.
Let's start from scratch. I create just one group - a typical "contactMethod" group of place holders that contain the contactIcon and contactText placeholders (image 2), then, in the left panel, I right-click the group and "Create a list" out of it (image 3). a Create New List dialogue appears (image 4). The name is automatically derived from the name of the group (ContactMethodList), but I can change it, and I can also pick the maximum number of Contact Methods I'd like to display on screen - 3 in my case.
Now, I set up my logic, very similar to a regular group (image 5). There are only two differences. First, instead of conditions, I use candidates, and I have to name them (Why? We'll see that later). Second, for each candidate, I can either define a "when" logic (so the candidate is only valid in some circumstances) or define to be alwaysvalid, by clicking the little down-arrow next to the when (see image X).
A List is an object that contains multiple entities of the same type. Each of these entities is called a Slot. The slots are numbered (Slot A, Slot B, Slot C, etc.). In a regular PH/Group logic, there's only one PH or Group, and multiple conditions. The first valid condition fills the PH. Here, we have multiple "copies" of the PH or the Group, so more than one valid "condition" can be used. These are called Candidates. The number of candidates can be equal to the number of slots or bigger - instead of just the first valid one, the first X valid candidates fill the slots (when X is the number of slots).
There's basically a two steps process: first, you create a new "type" or "object" (in the example above: a bullet which is composed of an icon and a text, grouped together) and then you determine how many times this new type appears (thus creating a bullet list).
- Right-click on a single placeholder or a group of placeholders
- Create a list
- Name the list and pick the number of slots (the maximum number of items that will be displayed on screen)
- Write the logic
The first click on a list will select the entire list. Actions you can perform on the entire list (image 6):
- Edit - to open a similar dialogue to Create New List in which you can rename the list and change the number of slots
- Remove list - this is the opposite action to "create new list" - It removes the list. The slots disappear, the logic is deleted (and the original logic is not restored), only the original placeholder or group remain, logic-less.
- Delete - to delete the entire list as well as all the placeholders that are part of it
The second click on a placeholder will select just this particular instance of a place holder. The right-panel stays the same - once a placeholder is part of a list, you cannot edit it individually. However, on the left panel, you can move and resize it (the slot and the list borders will adjust accordingly), and perform the following actions from the right-click context menu (image 7):
- Rename - to rename the selected placeholder
- Delete - to delete the placeholder. This will delete the placeholder from all the slots (see Pro Tip below for an exception)
All the slots must contain all of the placeholders. That's why you can't delete a placeholder from just one slot. But what if you want to keep the contactIcon empty in Slot B? Well, first, ask yourself - are you sure you want to keep the icon empty in Slot B regardless of Slot B content? Slot B can sometime show the agent's phone number, and sometimes - their Facebook Messenger details. If you'd like to not show the phone icon, the in the right panel, select "don't show" contactIcon for the phone candidate (image 8). If, for some reason, you really want to skip the 2nd slot's icon, regardless of its content, consult your animator - they can remove the image layer from the animation altogether.
There is one situation where deleting a placeholder from a slot will not delete it from all the other slots - that is, if there's more than one instance of the same placeholder in that slot. Check out this guide (not available yet) to learn more about instances.
Using Lists in other Placeholder's logic
Our agents in Sky Real Estate love their work, but they try to keep a healthy life-work balance, so I want to add a disclaimer, "during business hours only". But this disclaimer is only relevant to the phone contact method. So I create a text placeholder, and add a condition. When the phone is displayed, show the disclaimer. otherwise - don't show it.
Whether the phone is displayed or not depends on the data I'll get in real time. I want the disclaimer's condition to rely on the result of the logic calculation of the contactMethodList. So I click on "Choose" next to the first condition to choose a data element, and then, I go to the Data Structures tab. Up until now, this tab was called "Data Table". Now it contains another data structure, in addition to tables - lists (image 9).
I choose the contactMethodList. Now, I have two options - I can click OK to ask questions about the entire list in my "when" condition, or I can choose a particular slot (image 10). For this example, I need the list, so I just click OK.
I click on Choose again and I choose "includes" and then type in "phone" (image 11). This means that if the "phone" candidate wins any of the slots - the condition will be valid.
I can ask the following questions about a list to use in conditions (image 12):
- Is the number of valid slots equals to -or- greater than -or- smaller than N (where N is an integer)?
- Does the list include -or- does not include (in any of its slots) candidate X (where X is the candidate name)?
In addition, I can ask the following questions about a particular slot in a list (image 13):
- Is the slot filled?
- Is the slot empty?
- Is it filled with candidate X (where X is the candidate name)?
Why should I use this capability and not just use the same logic I used for defining the phone candidate as part of the list also as the condition for the disclaimer? In this example, you can defiantly do so, but this will require maintaining the same logic in two different places which is not recommended, especially when the logic is not trivial or expected to change in the future.
In other cases, duplicating the logic may even be impossible. If we had four candidates competing on three open slots, and phone was the lowest priority of them all, it would be possible that the phone candidate would be valid, yet wouldn't appear on screen, because all the slots would be filled with other valid candidates of higher priority.
Remember - for a candidate to fill a slot, being valid is not always sufficient.