Snap Document Events

• Feb 13, 2019
• 5 minutes to read

This topic describes the hierarchy and structure of specialized events in Snap.

In addition to rich text related events inherited from the Document interface, SnapDocument provides many events that you can handle to implement custom document templates.

For a code example on using Snap-specific events, see How to use SnapDocument events to customize the default templates of Snap lists and columns.

With the exception of the SnapDocument.ConnectionError event that assists the data connection process, the following events occur when dropping data fields from the Data Explorer onto a document, allowing you to modify the structure and formatting of the resulting table. These events correspond to the following user scenarios.

• Create a New List
• Add Columns to a List
• Insert a Nested List
• Add Fields to a List

Create a New List

The first group of events maintains the creation of a new list in a document.

• SnapDocument.BeforeInsertSnList

  Handle this event to customize the order in which fields are added and their position in a document.

  The nesting level of fields in the resulting document list depends only on the data source structure.

  Specifying an empty field set creates no new fields in the document.

• SnapDocument.PrepareSnList

  Based on the field set obtained, maintains the structure of a default list template (a regular table-like SnList). You can customize the resulting template using the Snap API.

  For example, you can add custom text, or access a list by traversing its fields, to apply a custom ListHeader/ListFooter/RowTemplate or add group/sort/filter criteria. (For a code example, refer to How to use SnapDocument events to customize the default templates of Snap lists and columns.)

  The changes made to the list template will be applied to the document after all other event handlers expire.

• SnapDocument.AfterInsertSnList

  Fires after a new list has been added to a document. Maintains the document range of the added content.

  This event does not fire if a list was not added for any reason.

Add Columns to a List

The following image illustrates the creation of new columns in an existing list using the vertical hot zone.

The following three events maintain this scenario.

• SnapDocument.BeforeInsertSnListColumns

  Maintains the creation of a new set of columns in a document, and provides the following arguments.

  1. BeforeInsertSnListColumnsEventArgs.Target - specifies the list to which the columns are added.

  2. BeforeInsertSnListColumnsEventArgs.TargetColumnIndex - specifies the position in which the columns are added.

  For a table that consists of N columns, this parameter will get the following values:

  • 0 when inserting new columns to the left;

  • 1 when inserting new columns between the first and second columns;

  • N when inserting new columns to the right.

  3. BeforeInsertSnListColumnsEventArgs.DataFields - specifies the fields to add. You can customize the set and/or order of the fields. Specifying null or an empty field set creates no new fields in the document.

• SnapDocument.PrepareSnListColumns

  Fires as many times as there are new columns being added. The event arguments contain two default templates:

  • a column header template that only contains the field name;

  • a field template that contains the data records.

  Specifying null in this template creates no new column headers in the document. This can take place if no header is specified for the original table, or the specified header has an unacceptable structure.

• SnapDocument.AfterInsertSnListColumns

  Fires after all columns have been successfully created, and returns a resulting list in its arguments.

  This is the last chance to customize the list before document generation (for example, to implement grouping, sorting and/or filtering).

  This event does not fire if the add operation was not completed for any reason.

Insert a Nested List

The following image illustrates the creation of a new list (nested into an existing list) using the horizontal hot zone.

The following three events maintain this scenario (listed in the order in which they are triggered).

• SnapDocument.BeforeInsertSnListDetail

  Fires after dropping fields onto a document’s horizontal hot zone, and provides the following arguments.

  1. BeforeInsertSnListDetailEventArgs.Master - specifies the list to which a new list is added.

  2. BeforeInsertSnListDetailEventArgs.DataFields - specifies the fields to add. You can customize the set and/or order of the fields. Specifying null or an empty field set results in no fields being added.

• SnapDocument.PrepareSnListDetail

  Fires after automatic generation of the inserted nested list has finished, to allow its customization at runtime.

• SnapDocument.AfterInsertSnListDetail

  Fires after the nested list has successfully been added, and specifies the target list in its arguments.

  This event does not fire if the add operation was not completed for any reason.

Add Fields to a List

The following two events add fields to an existing list without using hot zones.

• SnapDocument.BeforeInsertSnListRecordData

  Fires when adding fields to a list without using hot zones (this is only possible if the target list has been previously converted to paragraphs). This event provides the following arguments.

  1. BeforeInsertSnListColumnsEventArgs.Target - provides access to the list to which the fields are being added. Making changes to the list during this event is only safe when passing it with a null set of fields (see below).

  2. BeforeInsertSnListColumnsEventArgs.TargetColumnIndex - indicates the column index to which the fields are added. (If the target list was previously converted to paragraphs, the value is -1.)

  3. BeforeInsertSnListColumnsEventArgs.DataFields - specifies the fields to add. You can customize the set and/or order of the fields. Specifying null or an empty field set results in no fields being added.

• SnapDocument.AfterInsertSnListRecordData

  Fires after new fields have successfully been added. In its arguments, indicates the document range to which the new content has been applied.

  This event does not fire if the add operation was not completed for any reason.

  During this event execution, the input focus belongs to the target list’s record, and the specified changes have not yet been applied to the entire document template (and therefore, not applied to other records). For this reason, refreshing the field result of the list during this stage will result in losing all changes made to the record.