The cloak/reveal/conceal system is the series of components in the forms framework that manages how the action of one button effects the visibility of another button.

The reveal family

Each reveal family entry in the array contains a key (either cloak, reveal, or conceal) and a value. The value is an arbitrary name that puts the key’s parent element into a reveal family that works together. For example, say a checkbox has a reveal key with a value of “myset”. Later a text field has a cloak key, also with the value of “myset”. The “myset” value defines the reveal family and connects the two objects so when the checkbox is clicked, it triggers the visibility of the text field.

Family names are really just CSS classes. So while they are used as values in the form array, they can actually be assigned as a class to any HTML tag and (with the addition of the class dot prefix) work as CSS selector. It is also possible to put multiple family names in one value (as in “myset yourset”). This allows for complex conceals and reveals to be coded into the form.

The cloak key

Any element that has a key named “cloak” will be given a “display:none” style and will initially not be displayed on the page. When an element with a reveal tag that has a matching family is triggered, the cloaked item is made visible on the page. If the cloaked item is already visible, a triggered reveal will hide the element with the matching reveal family.

The reveal key

The reveal key is used to specify what elements are revealed once the parent element is triggered. Specifies that this element can be used to reveal another element. The value of the key/value pair is the reveal family, which determines which elements will be revealed when the reveal element is triggered. When reveal is used with a select list, reveal is no longer a key with a scalar string value. Instead it is an array containing option values as keys and space-separated lists of reveal families as values. When a specified option value is selected, the reveal family elements are displayed.

The conceal key

Conceal is the opposite of reveal. The conceal key specifies the elements to be hidden once the element is triggered. For radio buttons and check boxes, conceal works as you’d expect: if this button is triggered, conceal elements of the specified family. However, when it comes to selection lists, conceal elements are not represented in an array. Rather, they become part of the parent div of the select and specify the families to be concealed. In practice the way this works is that when an option is selected, first all the matching conceal families are concealed and then the matching reveal families attached to the given select options are revealed.

Check and uncheck keys

Although not directly part of the reveal system, sometimes when you show a hidden radio or checkbox control, you’ll need to set the value of that control. The check and uncheck keys allow you to do that. You put the key into the control that does the reveal (a radio button or checkbox). When that control is activated (changed to a checked or selected value), it will also check or uncheck the control listed as the value of the check or uncheck key. It uses the id (the name of the element’s array) as the value of the item to check or uncheck.

So, for example, if you want to set radioA to selected when buttonB is checked, you would put check:radioA into buttonB. Note that it is not necessary that either control be hidden or have a reveal, but this feature was designed to work in that context primarily.

Example: the Seamless Donations Tribute form section

To understand how these keys work together, let’s look at the Seamless Donations Tribute form section. This is a complex section where various parts need to reveal and conceal based on live user input. Here are the actions:

The main “Check here to donate in honor or memory of someone” checkbox

This starts off visible, but unchecked. When it’s checked, we want to make the honoree’s name field show up as well as the two “send acknowledgement” radio buttons. Because “send acknowledgement via email” will be checked as the default, we also want the email name and address fields to be revealed when the checkbox is triggered. These fields are cloaked using the in-honor family, and a reveal:in-honor key is set to turn them on when the user checks the boxes.

We also want the other fields in this section to be initially hidden, but we don’t use the “in-honor” family because we don’t want them to turn on when the main checkbox is checked. We want them to turn on only if a later condition is met based on an action triggered with one of the initially-hidden controls. We’ll use conceal to hide families postal-acknowledgement, conceal-postcode, conceal-state, and conceal-province.

Honoree’s name text field

Initially hidden using cloak:in-honor-of.

“Send acknowledgement via email” radio button

Initially hidden using cloak:in-honor. When first made visible, the email destination name and email address text fields are made visible with it. But if selected later, after the postal mail radio button was triggered, the selection of this button must first hide the postal destination name and street address text fields, the country field, and state, province, and postal code fields.

When triggered by the user, this button uses reveal:email-acknowledgement to tell all divs in the email-acknowledgement family to appear. It uses conceal to hide families postal-acknowledgement, conceal-postcode, conceal-state, and conceal-province.

“Send acknowledgement via postal mail” radio button

Initially hidden using cloak:in-honor.  When this button is selected, the email destination name and email address text fields need to disappear and the postal destination name and street address text fields need to appear. In addition, the country field needs to appear and as it appears (based on the country option selected), determine whether to show state, province, and postal code fields.

When triggered by the user, this button uses reveal:postal-acknowledgement to tell all tags in the reveal:postal-acknowledgement family to appear. It uses conceal:email-acknowledgement to hide the email-related fields.

Email destination name and email address text fields

Initially hidden using cloak:in-honor and cloak:email-acknowledgement. Because the cloak key is used, the control is hidden. These fields can then be managed through both the in-honor and email-acknowledgement families.

Postal destination name and street address text fields

Initially hidden using cloak:postal-acknowledgement.

Country field selection list

Initially hidden using cloak:postal-acknowledgement. While coding, I’ve set the country field to reveal fields based only on few country options (US, Canada, and UK). Here’s the reveal array for country:

• UK: conceal-postcode
• US: conceal-postcode, conceal-state
• CA: conceal-postcode, conceal-province

The only reason I used “conceal-” as a prefix was because state and province may be too common as CSS classes and I didn’t want them triggered by other rogue classes or selectors.

This element also uses a conceal key to conceal the postcode, state, and province. When a new selection is made, a change is triggered, and first all three families are concealed and then, if the option is appropriate certain families are then revealed. But we don’t just want the conceal/reveal sequence to trigger only when an option is chosen. We also want it to trigger when the country field is displayed so the right supporting fields are shown when the country is made visible. Further, we want it to trigger when the country field is hidden. In the case of hiding the country, all three fields need to be hidden.

This means we need three trigger functions in JavaScript/jQuery. One that runs when a change event is noticed (which conceals, then reveals fields). Another function is called on element show, and it, too, conceals then reveals fields. Finally, a function is called on element hide, and it only needs to conceal fields.

State text field

This can’t be hidden using cloak:postal-acknowledgment. If it was, then the field would show up when the radio button was selected, and we don’t yet know if this field is meant to show. So it’s initially hidden using cloak:conceal-state.

Province text field

This can’t be hidden using cloak:postal-acknowledgment. If it was, then the field would show up when the radio button was selected, and we don’t yet know if this field is meant to show. So it’s initially hidden using cloak:conceal-province.

Postal code text field

This can’t be hidden using cloak:postal-acknowledgment. If it was, then the field would show up when the radio button was selected, and we don’t yet know if this field is meant to show. So it’s initially hidden using cloak:conceal-postcode.