The Holder widget

Holder widgets are mainly used to return miscellaneous information from the server. Timestamps, user names or user counts can be stored in hidden fields in the wrap. If problems occur, holder widgets may provide valuable debugging information. 

Holder widgets are similar to the holder cells created by the WrapLink, WrapLinkList and other widgets to enable offline testing inside Excel. In Excel, the holder widget provides a dummy value that other cells can use in their calculations. When converted to a Wrap, the holder widget’s dummy value is replaced with a live value from the ExcelWraps server.

The Holder widget is mainly for “internal use only”. It enables the developer to save information in the wrap that may become useful if a problem occurs.

  • For a wrap instance, a Holder widget can identify when the wrap instance was created or last saved, or by what user.
  • For a signature, a Holder widget can identify when the wrap instance was signed off, or by what user.
  • For a user role, a Holder widget can return the number of active users on the WrapSite that have this role.

Holder widgets rarely contain any information that the user of the Wrap is interested in. Most Holder widgets are hidden and thus invisible in the Wrap.

Example: Signatures made on instances of a previous version of a Wrap may have been signed with possibly different calculated values or the appearance of the Wrap may have changed. You can use simple logic for the signature enabling cell that ensures that both old instances and new instances always satisfy the appropriate cell enabling logic. The easiest way to do this is to use a Holder widget containing the last saved date for the Wrap instance. In the enabling cell, you can then use an =if() statement to use different enabling logic based on the last saved date for the Wrap instance. Learn more in Making changes to your Wraps.

More information about the holder cells that are used with other widgets can be found on the help page for the widget you will be working with, i.e. the holder cell used with WrapLink is described on the help page for the WrapLink widget.

Holder cells are essential when testing Wraps in Excel.

Insert a Holder widget

  1. Select the cell where you want the Holder widget to appear.
  2. Switch to the WrapCreator ribbon and click on Insert Widget.
  3. Select the Holder widget on the Widget tab in the task pane.
  4. Enter the required parameters on the Cell tab and press Apply.
  5. Verify that a default value has been inserted into the cell.

Parameters

Screenshot of the parameters for the Holder widget

Holder Item

Select the function of the Holder widget.

  • Wrap Creation – returns information related to when the wrap instance was created.
  • Wrap Last Modification – returns information about the most recent modification to the wrap instance.

Qualifier

Select the information you want the holder cell to return for the event selected as the Holder Item.

  • oadate – returns a timestamp for the event in the OADate format, ie. the way Excel stores date and time.
  • username – the name of the user that initiated the event.
  • nickname – the nickname (initials) of the user that initiated the event.
  • firstname – the given name or forename of the user that initiated the event.
  • lastname – the surname or family name of the user that initiated the event.
  • company – the company name of the user that initiated the event.
  • location – the location of the user that initiated the event.
  • workgroup – the workgroup of the user that initiated the event.
  • role – the role of the user that initiated the event.

Hidden

Tick this box if you want the contents of the holder widget to be invisible in the wrap.

Dummy value

This is the value that the holder widget will contain during testing in Excel. When the wrap is running on the server, real values from the database are used, and the dummy value has no meaning. There are three possible types of values you can put here, depending on the situation:

  • If the server will return a number, the holder widget must always contain a numeric value, also during testing in Excel. Example: 100
  • If the server will return a text string, you must enter a text string here, and it must be delimited with double-quotes. Example: “JaneDoe”
  • If the server will return a timestamp, you must enter a timestamp in the OADate (or OADateTime) format used by OLE Automation, i.e. as a decimal number. Example: 20376.5972222222.

Special rules for timestamps

The OADate format is easy to handle for Excel developers because it is the same as an ordinary Excel serial number, i.e. the standard decimal number that Excel uses for timestamps internally.  The integer part counts the number of days and the decimal part tells the time of day. When you use an OADate in a holder widget, it must be formatted as a decimal number, not using a date or time format.

Remove a Holder 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 Holder widget:

  1. Ensure that the task pane is visible.
  2. Select the widget’s cell.
  3. The task pane should now show the Holder 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. Locate the Remove button at the bottom of the widget settings and click on it.

Function reference

Screenshot of a Holder widget and its function call

Example

In this example, you want the Holder widget to return the timestamp for the most recent modification of the wrap instance. You provide a default value in the form of an Excel serial number. The Holder widget is hidden. This is what the function call looks like:

=HOLDER(LastModification, 20376.5972222222, TRUE, "oadate")

Format and parameters

=HOLDER(holder_item, dummy_value, hidden, qualifier)

holder_item defines the event you want to know more about. The possible values are

  • Creation – the creation of the wrap instance.
  • LastModification – the most recent modification to the wrap instance.
  • ActiveUser – the user most recently working with the wrap instance.

Note: these are actually cell names, not string values – no quote marks, please.

dummy_value contains a value you want the Holder widget to provide during testing in Excel – at runtime, real values from the server are used instead. Read more in the Parameters section above.

hidden if set to TRUE, makes the contents of the holder cell invisible in the wrap.

qualifier contains a key telling the server what it is you want to know about the event – the possible values are listed in the description of the holder cell parameters above.

=@HOLDER(ActiveUser, "JaneDoe", TRUE, "username")