Version:

Query View Extension Specs

You can create query view extensions to modify existing query views that are available to end users in Blackbaud CRM as source views. Query view extension specs allow you to insert additional fields or remove fields from existing query views without directly modifying the specs for the existing query views.

When end users create queries in Blackbaud CRM, the source views they select determine the output fields that appear in the query designer. With query view extensions, you can modify the output fields that appear for a query view.

The query designer displays output fields based on the source view. Query view extensions can modify the output fields.

Starting with version 4.0, you can use the Query View Extension Spec template to create query view extension specs through the SDK. In previous versions, you can create query view extensions by inserting the QueryViewSpecExtension element as the root element on blank XMLspecs and then declaring namespaces for the QueryViewSpec.xsd and CommonTypes.xsd schemas.

Create Query View Extension Spec with the Template

  1. To create a query view extension spec with the Query View Extension Spec template, right-click your project within Solution Explorer in Visual Studio and select Add, New Item from the popup menu.

  2. On the Add New Item dialog window, select Blackbaud AppFx Catalog as the category and Query View Extension Spec as the template.

  3. In the Name field, update the default name as necessary.

  4. Click Add. The Query View Search screen appears.

  5. On the search screen, enter search criteria to locate the query view to extend.

  6. Click Select.

    Note: You can only extend query views that include the Extensibility element. If you select a query view that does not list tables to extend in the Extensibility element, then the search screen returns an error. To expose additional output fields for such a query view, you can add a child view instead. To do this, you create a separate query view and use the RelationshipOperations element's AddToParentView element to relate it to the existing query view. For information about the RelationshipOperations element, see RelationshipOperations Element.

    The new spec appears in Solution Explorer and in the XML Editor.

    <QueryViewSpecExtension
      xmlns="bb_appfx_queryview"
      xmlns:c="bb_appfx_commontypes"
      ID="8be058b8-956a-4047-a89e-94d694a24852"
      Name="Query View Extension Spec Query Extension"
      Description="An extension to the Addresses query view"
      Author="Technical Training"
      ExtendsViewName="V_QUERY_CONSTITUENTADDRESS"
      >

     <AddFields>
      <AddField>
       <TableField FieldName="REPLACE_WITH_FIELDNAME" AliasAs="REPLACE_WITH_ALIAS" TableNameOrAlias="REPLACE_WITH_TABLENAMEORALIAS" />
       <OutputField Name="REPLACE_WITH_NAME" Caption="REPLACE_WITH_CAPTION" Category="REPLACE_WITH_CATEGORY" />
      </AddField>
     </AddFields>
    </QueryViewSpecExtension>

  7. In the XML Editor, you can adjust the spec as necessary.

    Within the root QueryViewSpecExtension element, you can edit the default name, description, and author if necessary. The ExtendsViewName attribute provides the database name of the view for the query view that you selected on he Query View Search screen.

    The AddFields element is set up for you to add output fields to the parent query view.

    • In the TableField element, you can specify a database field to add to the parent query view. In the FieldName attribute, you enter the field name, and in the TableNameOrAlias attribute, you enter the name of its table. Meanwhile, in the optional AliasAs attribute, you can enter an alias name to use when selecting the field in the view. Keep in mind that if you provide an alias, it becomes the field name to refer to in the OutputField element.

    • In the OutputField element, you can provide metadata about how to display the output field. In the Name, Caption, and Category attributes, you provide the field name from the FieldName or AliasAs attribute, a friendly caption to display for the field in queries, and a category for grouping the output field on the query designer. Additional attributes are also available, just like on an OutputField element on a query view spec.

    • You can add the SelectClause element to represent a SQL SELECT statement that can be aliased as an available field in the view.

    In addition to the AddFields element that appears by default to add new fields to the parent query view, you can also include the RemoveFields element to remove existing output fields from the parent query view. Within the RemoveFields element, you can add RemoveField elements to specify the name of a field to exclude from the parent query view.

  8. Save the spec and then load it to extend the parent query view.

Create Query View Extension Spec from a Blank XML Spec

  1. To create a query view extension spec on a blank XML spec, right-click your project within Solution Explorer in Visual Studio and select Add, New Item from the popup menu.

  2. On the Add New Item dialog window, select Common Items as the category and XML File as the template.

  3. In the Name field, update the default name as necessary.

  4. Click Select. A blank spec appears in Solution Explorer and in the XML Editor.

  5. In the XML Editor, add the root QueryViewSpecExtension element and insert two xmlns attributes to declare namespaces for the QueryViewSpec.xsd and CommonTypes.xsd schemas.

    <QueryViewSpecExtension
      xmlns="bb_appfx_queryview"
      xmlns:c="bb_appfx_commontypes"
      >

    After you declare the namespace attributes, you can use IntelliSense to determine the valid options on the query view extension spec.

  6. Enter additional attributes for the QueryViewSpecExtension element.

    In the Name, Description, and Author attributes and enter a name, description, and author for the spec.

    In the ExtendsViewName attribute, enter the database name of the view for the parent query view that you want to extend.

    Tip: To find the view name in the Blackbaud CRM user interface, go to Administration, click Application, and then click Features. On the Features page, click Query view search under Features and locate the query view on the Query View Search screen. Select the query view, then copy the view name from the page summary's Implementation field.

    <QueryViewSpecExtension
      xmlns="bb_appfx_queryview"
      xmlns:c="bb_appfx_commontypes"
      ID="8be058b8-956a-4047-a89e-94d694a24852"
      Name="REPLACE_WITH_QUERY_VIEW_EXTENSION_NAME"
      Description="REPLACE_WITH_QUERY_VIEW_EXTENSION_DESCRIPTION"
      Author="REPLACE_WITH_CUSTOM_SPEC_AUTHOR"
      ExtendsViewName="REPLACE_WITH_VIEW_NAME_SUCH_AS_'V_QUERY_CONSTITUENTADDRESS'_"
      >

    Note: You can only extend query views that include the Extensibility element. If the ExtendsViewName attribute identifies a query view whose spec does not list tables to extend in the Extensibility element, then you cannot extend the query view and an error will occur if you load the spec. To expose additional output fields for such a query view, you can add a child view instead. To do this, you create a separate query view and use the RelationshipOperations element's AddToParentView element to relate it to the existing query view. For information about the RelationshipOperations element, see RelationshipOperations Element.

  7. To add an output field to the parent query view, insert the AddFields element and its child AddField element. Within the child AddField element, you describe the field to add.

    • In the TableField element, you can specify a database field to add to the parent query view. In the FieldName attribute, you enter the field name, and in the TableNameOrAlias attribute, you enter the name of its table. Meanwhile, in the optional AliasAs attribute, you can enter an alias name to use when selecting the field in the view. Keep in mind that if you provide an alias, it becomes the field name to refer to in the OutputField element.

    • In the OutputField element, you can provide metadata about how to display the output field. In the Name, Caption, and Category attributes, you provide the field name from the FieldName or AliasAs attribute, a friendly caption to display for the field in queries, and a category for grouping the output field on the query designer. Additional attributes are also available, just like on an OutputField element on a query view spec.

    • In the optional SelectClause element, you can provide a SQL SELECT statement that can be aliased as an available field in the view.

     <AddFields>
      <AddField>
       <TableField FieldName="REPLACE_WITH_FIELDNAME" AliasAs="REPLACE_WITH_ALIAS" TableNameOrAlias="REPLACE_WITH_TABLENAMEORALIAS" />
       <OutputField Name="REPLACE_WITH_NAME" Caption="REPLACE_WITH_CAPTION" Category="REPLACE_WITH_CATEGORY" />
      </AddField>
     </AddFields>

  8. To remove an output field from the parent query view, insert the RemoveFields element and the RemoveField element to specify the name of a field to exclude from the parent query view.

     <RemoveFields>
      <RemoveField FieldNameOrAlias="REPLACE_WITH_FIELDNAME_OR_ALIAS">
     </RemoveFields>

  9. After you finish your changes in the XML Editor, save the spec and then load it to extend the parent query view.

    <QueryViewSpecExtension
      xmlns="bb_appfx_queryview"
      xmlns:c="bb_appfx_commontypes"
      ID="8be058b8-956a-4047-a89e-94d694a24852"
      Name="Query View Extension Spec Query Extension"
      Description="An extension to the Addresses query view"
      Author="Technical Training"
      ExtendsViewName="V_QUERY_CONSTITUENTADDRESS"
      >

     <AddFields>
      <AddField>
       <TableField FieldName="REPLACE_WITH_FIELDNAME" AliasAs="REPLACE_WITH_ALIAS" TableNameOrAlias="REPLACE_WITH_TABLENAMEORALIAS" />
       <OutputField Name="REPLACE_WITH_NAME" Caption="REPLACE_WITH_CAPTION" Category="REPLACE_WITH_CATEGORY" />
      </AddField>
     </AddFields>

 <RemoveFields>
      <RemoveField FieldNameOrAlias="REPLACE_WITH_FIELDNAME_OR_ALIAS">
     </RemoveFields>

    </QueryViewSpecExtension>