The Conditional Input widget

The Conditional Input widget allows you to lock a wrap field for user input unless certain conditions are met. You evaluate these conditions in a separate “enabling” cell which must return TRUE to open the locked field for input. The logged-in user must also have a designated role.

The Conditional Input widget ensures that the currently logged in user has a qualifying user role and that an enabling cell returns TRUE. If so, the field is opened for input. Otherwise, the cell remains locked and cannot be modified.

Example: A signature has an associated comment field. A comment can only be entered when the Wrap instance is ready to be signed, and only by a person qualified also to sign the Wrap instance.

The Conditional Input widget is a visual guide that helps you insert a cinput() function into the current cell.

Insert a Conditional Input widget

  1. Select the cell where you want the locked input field to appear.
  2. Switch to the WrapCreator ribbon and click on Insert Widget.
  3. Select the CInput widget on the Widget tab in the task pane.
  4. Enter the required parameters and press Apply.
  5. Verify that a =cinput() function has been inserted into the cell.

Parameters

Screenshot of a CINPUT function

Cell Name

You must always name all input fields. It adds clarity to the spreadsheet but more importantly names the database column where each input field is saved.

Enabling cell

The enabling cell usually contains a formula that unlocks the locked field. It must return TRUE when the cell that contains the Conditional Input widget can be edited. In the example above, a Signed() function in F5 is used to unlock a comment field when a section of a wrap instance has been signed off.

To select the enabling cell, click on the small pen, then on the enabling cell.

Regardless of the enabling cell, the field will always be locked if the current user does not have the selected role.

Edit permission

Select a user role that is required to unlock the locked field.

To test the widget in Excel, verify your setting for the Test Role on the Wrap tab.

Default value

Enter a default value that the locked field returns if it hasn’t been unlocked and edited.

The default value must have the same data type as the value that the user will enter into the field when it is unlocked – use numbers for number fields, or text for text fields.

Remove a Conditional Input widget

To delete a field, widget, wrap function or signature that has been stored at least once in the live production database is not a trivial task. The instructions below are only applicable during the initial development of a wrap, before it has ever been used in production. Read more about making changes to your wraps.

To remove a Conditional Input widget:

  1. Ensure that the task pane is visible.
  2. Select the widget’s cell.
  3. The task pane should now show the CInput widget’s settings on the Cell tab. If it doesn’t, you may have selected the wrong cell, or already removed the widget by mistake.
  4. Note the location of the Enabling Cell.
  5. Locate the Remove button at the bottom of the widget settings and click on it.

If the enabling cell was used only to lock/unlock the input field, you may now want to remove it. Before you do, you may want to make certain that it has no other function within the wrap.

To remove the enabling cell:

  • Select the enabling cell and press the Del key on the keyboard, or right-click on the enabling cell and select Clear contents.

Function reference

Screenshot of a CINPUT function

Example

In the example above, the enabling cell F5 must evaluate to TRUE and the logged-in user must have the User role for the input field to be unlocked.

A default text string is inserted to describe what the user needs to do to unlock the field.

The following cell formula is inserted into the cell.

=@CInput(F5;"User";"You can only fill me in after signing above.")

Format and parameters

=@CINPUT(enabling_cell, "user_roles", default_value)

enabling_cell

The cell is only open for input when the enabling_cell returns TRUE.

“user_roles”

Select the user role that is required to unlock the locked field.

default_value

The third parameter sets an initial value for the conditional input field.