XML Overlays

XML Overlays are composed in the View Editor window.  They contain elements and attributes which overwrite and enhance elements in a View Base XML.

This article introduces the eight parent elements used in View Base and  XML Overlays.  These parent elements, as well as all child elements and their attributes are fully documented (and available for copy / paste)  in the Brick River XML Codex.
 

In order for the XML Overlay to customize the View Base - The XML Tree Structure and Element / Attribute names must match.

The only exception is the root element, which is <Table> for the View Base and <View> for the Overlay.

Within the <View> root:
<parent> element names must match between the Overlay and View Base
<child> element names must match.  If the Id attribute is used - and Id's must also match - or both must have no Id.


Parent Elements

View Overlays use eight <parent> elements to:

  1. Define the fields included on data records for that View, and
  2. Define the appearance of View in the Web Console

<Fields>

1 Fields is the most important element in View Base XML and XML Overlays.  Child tags within fields define the Fields to be included in the View.  There are dozens of attributes available to customize field visibility, appearance on screen, and behavior. 

A few important points:

  1. It is possible to remove fields from a View.  For example, if you are creating a view to define a type of Contacts called "Conference Rooms", it is appropriate to remove the First Name and Last Name fields since that information is irrelevant to rooms.  If these fields are removed from the <Fields> element - then they may not be used in other elements such as <Filters> and <Sort>.  If you need a View to sort by Last Name - but you don't want users to see that field when editing records - Last Name must be set to invisible - but not removed from <Fields>
  2. In addition to defining the appearance on screen - child elements of <Fields> also determines which fields are available when coding pages to retrieve records.  For example, a View called "Donors" may remove the Physical Address field from <Fields> - while the View "People" includes the Physical Address.  There may be many Contacts who are both "Donors" and "People" and their record appears in both Views.  However, when you use a @BRT Helper on a page to display Physical Address - the Helper must point to the "People" View, not the "Donor" View.

There are six child elements used within <Fields>

 

  • <FieldSet> - creates a logical group of fields and presents them on screen in a collapsible section.  The example above displays the XML elements that create the 'Name Fields' and 'Email and Phones' sections of the
  • <Column> - indicates a field that is currently defined in the View Base XML
  • <Custom> - creates a new field - one not defined by the View Base XML
  • <File> - indicates a field which links to a file such as an image or .pdf
  • <Category> - indicates a field that will be populated by choosing one or more values from a category list
  • <Relationship> - a field that will store a relationship to an external record.

Additional tag attributes define the order, visibility, size, default values (and many other aspects) of fields included on records presented in the View.


Elements which define the features and appearance of the View in the Web Console

<Filters>

2 Filter Tags define the records to be included in the View as well as the appearance of Filter controls on the View screen. The following <Filters> parent contains two child <Filter> tags.

<Filters>
<Filter Id="PeopleFilter" Type="Required">
<Eq Id="Type.Label" Value="People"/>
</Filter>
<Insert/>
<Filter Id="Visible" Type="SavedFilter" Name="Visible Contacts">
<Eq Id="HideOnline" Value="false"/>
</Filter>
</Filters>

<Filter Id="PeopleFilter"> defines a Required filter which limits the View to only display records where the Type field contains a value with the label: "People"

<Filter Id="Visible">  creates a control called "Visible Contacts" on the People View which defaults to display only records where the HideOnline field is "false".  Users may toggle this control in order to display records where HideOnline is "true".

<SortFields>

4 SortField Tags define the sort order of records presented in the View.  The following elements create a primary sort on LastName and a secondary sort on FirstName.

<SortFields>
<SortField Id="LastName"/>
<SortField Id="FirstName"/>
</SortFields>

<SearchFields>

5 SearchFields tags define the fields to be evaluated when a Search is performed.

<SearchFields>
<Ref Id="FirstName"/>
<Ref Id="PreferredName"/>
<Ref Id="LastName"/>
<Ref Id="Email"/>
</SearchFields>

If a User were to type "bri" in the search field the View would immediately filter to display only records that contain that string in one of the designated fields, such as Brian Crowley, Madeline Albright, or paulbrickriver.com.

<ListFields>

6 ListFields tages define the columns to be included in the view of records on screen.

<ListFields>
<Ref Id="FirstName"/>
<Ref Id="PreferredName"/>
<Ref Id="LastName"/>
<Ref Id="Email"/>
<Ref Id="Phone1"/>
<Ref Id="Phone2"/>
</ListFields>

Note that using the <Ref> tag points to a field using the field's Id.  The column headings on screen use the Name attribute of the associated field

<HandyFields>

7 HandyFields tags define fields to be available in the Web Console for instant filtering of View records.  The following creates a control on the Search view which allows for instant filtering based on a search of the Email Subscriptions linked to the record.

<HandyFields>
<Ref Id="Subscriptions"/>
</HandyFields>

The <Ref> tag points to the Relationship field with Id="Subscriptions".  The Handy field on screen uses the Name attribute of the associated field.

<Title> and <DedupFields>

<Title>

3 <Title> tags define the fields to be included the Title definition for the record.

<Title>
<Ref Id="FirstName"/>
<Ref Id="LastName"/>
</Title>

Titles serve a few functions. 

On a web page or layout a records Title can be retrieved using the Title label.

A relationship field uses record Titles to populate selection lists when linking parent records to child records.

<DedupFields>

8 DedupFields tags define the fields to be included when evaluating records during the de-duplication process.

<DedupFields>
<Ref Id="Name"/>
<Ref Id="FirstName"/>
<Ref Id="LastName"/>
<Ref Id="Email"/>
</DedupFields>

Brick River provides an automated process for consolidating information from duplicate records.  For example, based on the XML above, if a User ran a de-duplication on the People View and it found two records with identical Name, FirstName, LastName, Email address - if one of those records had Type = "Registrant", and had Type = "Donor" - it would leave a single record with Type values of "Donor, Registrant"


Understanding Tree Matching , Enhancing and Overwriting View Base XML

Seeing that Elements and Attributes in XML Overlays both add to and overwrite matching Elements and Attributes in View Base XML - it's important to understand how to use the Cmd attribute to control fields position and remove unwanted elements from Custom Views.

Controlling Field Position

Within the Parent <Fields> element all child elements appear (from top to bottom), according to the order of elements in the View Base XML.  When additional fields are defined in an XML overlay, they are added after the final element in the current parent tag.

For example the People View does not contain field for Title.  A custom field can easily be added within the 'NameFields' Fieldset,

 

<FieldSet Id="NameFields" Name="Name Fields" Important="true">

<Custom Id="Title" Name="Title" Type="VarChar" Length="255" />

<Column Id="FirstName" Name="First Name" Type="VarChar" Length="255" Important="true"/>
<Column Id="LastName" Name="Last Name" Type="VarChar" Length="255" Important="true"/>
<Column Id="PreferredName" Name="Preferred Name" Type="VarChar" Length="255"/>
<Column Id="MiddleName" Name="Middle Name" Type="VarChar" Length="255"/>
<Column Id="NameSuffix" Name="Name Suffix" Type="VarChar" Length="255"/>
</FieldSet> 

 

The position of the <Custom> tag appears to position the Title field before the First Name field.  It will actually position the field after NameSuffix - the last element in the FieldSet.  To position it above the First Name field, the CMD attribute must be used, below:

 

<FieldSet Id="NameFields" Name="Name Fields" Important="true">

<Custom Id="Title" Name="Title" Type="VarChar" Length="255"  Cmd="Before:FirstName" />

<Column Id="FirstName" Name="First Name" Type="VarChar" Length="255" Important="true"/>
<Column Id="LastName" Name="Last Name" Type="VarChar" Length="255" Important="true"/>
<Column Id="PreferredName" Name="Preferred Name" Type="VarChar" Length="255"/>
<Column Id="MiddleName" Name="Middle Name" Type="VarChar" Length="255"/>
<Column Id="NameSuffix" Name="Name Suffix" Type="VarChar" Length="255"/>
</FieldSet> 

Removing Unwanted Elements

Removing elements or attributes from XML overlays will not remove elements from underlying View Base XML. 

Our Example above shows the columns included on the People View are the result of Base XML with the following elements:

<ListFields>
<Ref Id="FirstName"/>
<Ref Id="PreferredName"/>
<Ref Id="LastName"/>
<Ref Id="Email"/>
<Ref Id="Phone1"/>
<Ref Id="Phone2"/>
</ListFields>

 

To remove the phone and email columns from the View screen, the following is NOT sufficient:

<ListFields>
<Ref Id="FirstName"/>
<Ref Id="PreferredName"/>
<Ref Id="LastName"/>
</ListFields>

 

Those fields can only be removed from <ListFields> are removed using the Cmd attribute:

<ListFields>
<Ref Id="FirstName"/>
<Ref Id="PreferredName"/>
<Ref Id="LastName" />
<Ref Id="Email" Cmd="Remove" />
<Ref Id="Phone1" Cmd="Remove" />
<Ref Id="Phone2" Cmd="Remove" />
</ListFields>

Using Document Map to Remove Elements

The View Editor Window provides a Document Map button  to facilitate removing elements from the View Base XML.  In the View Editor, click 'Document map'.  Use the  X icon to select elements or sets of elements for removal.

For example, in the Conference Rooms View above, the Column Field: Name can be used for the name of the conference room.  All other Column Fields in the NameFields FieldSet can be removed.  The entire EmailPhoneFields FieldSet can be removed.

The result is an XML overlay with CMD="Remove" applied to the selected elements.

 <View Id="Conference Rooms" TableId="Contacts">
  <Fields>
    <Category Id="Type" Default="Conference Rooms" Invisible="true"/>
    <FieldSet Id="NameFields">
      <Column Id="FirstName" Cmd="Remove"/>
      <Column Id="LastName" Cmd="Remove"/>
      <Column Id="PreferredName" Cmd="Remove"/>
      <Column Id="MiddleName" Cmd="Remove"/>
      <Column Id="NameSuffix" Cmd="Remove"/>
    </FieldSet>
    <FieldSet Id="EmailPhoneFields" Cmd="Remove"/>
  </Fields>
  <Filters>
    <Filter Type="Required">
      <Eq FieldId="Type.Label" Value="Conference Rooms"/>
    </Filter>
  </Filters>
</View> 

Important Notes:

  1. In the above example the LastName field has been removed from <Fields>.  The LastName field is included in the <Filter> and <Sort> elements of the View Base XML.  If LastName is not removed from those tags - saving the View will trigger a failure alert.
  2. Document Map is a one way street.  It can not be used to restore multiple fields or fieldsets that have been removed.  Fields can be restored to the View by manually deleting the elements containing Cmd="Remove".

The use of the CMD is documented fully in XML Codex.

 

 

 

Want to learn more?

Call 800-924-5220 or

Free trial