Customize views

Views are special saved queries that retrieve data by using a specific filter. They also contain information about how the data in the view should be displayed in the application. Views are SavedQuery records that you can create programmatically. You can also define them as XML, and import them with an unmanaged solution.

A SavedQuery view is different from a UserQuery. A user query, called a Saved view in the application, is owned by an individual user, can be assigned and shared with other users, and can be viewed by other users depending on the query's access privileges. This is appropriate for frequently used queries that span table types and queries that perform aggregation. More information: Saved queries

You can also use the customization tool to customize views. More information: Create and edit views

Types of views

The following table lists the five types of views that are supported for customization. The type code of a view is stored in the SavedQuery.QueryType parameter.

When views are defined for a specific table, the SavedQuery.ReturnedTypeCode parameter returns the table logical name.

Create views

To create a public view, specify the following properties:

• SavedQuery.Name: A unique identifier for the saved query.

• SavedQuery.ReturnedTypeCode: Matches the logical name of the table.

• SavedQuery.FetchXml: See Query data using FetchXml.

• SavedQuery.LayoutXml: See the layoutxml element in the Customization solutions file schema for the valid elements.

• SavedQuery.QueryType: Must always be zero (0).

  The following sample creates a new public view for the opportunity:

  System.String layoutXml =
  @"<grid name='resultset' object='3' jump='name' select='1' 
    preview='1' icon='1'>
    <row name='result' id='opportunityid'>
    <cell name='name' width='150' /> 
    <cell name='customerid' width='150' /> 
    <cell name='estimatedclosedate' width='150' /> 
    <cell name='estimatedvalue' width='150' /> 
    <cell name='closeprobability' width='150' /> 
    <cell name='opportunityratingcode' width='150' /> 
    <cell name='opportunitycustomeridcontactcontactid.emailaddress1' 
        width='150' disableSorting='1' /> 
    </row>
  </grid>";
  
  System.String fetchXml =
  @"<fetch version='1.0' output-format='xml-platform' 
    mapping='logical' distinct='false'>
    <entity name='opportunity'>
    <order attribute='estimatedvalue' descending='false' /> 
    <filter type='and'>
        <condition attribute='statecode' operator='eq' 
        value='0' /> 
    </filter>
    <attribute name='name' /> 
    <attribute name='estimatedvalue' /> 
    <attribute name='estimatedclosedate' /> 
    <attribute name='customerid' /> 
    <attribute name='opportunityratingcode' /> 
    <attribute name='closeprobability' /> 
    <link-entity alias='opportunitycustomeridcontactcontactid' 
        name='contact' from='contactid' to='customerid' 
        link-type='outer' visible='false'>
        <attribute name='emailaddress1' /> 
    </link-entity>
    <attribute name='opportunityid' /> 
    </entity>
  </fetch>";
  
  var sq = new SavedQuery
    {
      Name = "A New Custom Public View",
      Description = "A Saved Query created in code",
      ReturnedTypeCode = "opportunity",
      FetchXml = fetchXml,
      LayoutXml = layoutXml,
      QueryType = 0
    };                  
  _customViewId = service.Create(sq);
  Console.WriteLine("A new view with the name {0} was created.", sq.Name);
  

Update views

If the SavedQuery.IsCustomizable managed property allows the view to be updated, you can use the IOrganizationService.Update method or the UpdateRequest message to update the view.

Delete views

You should only delete saved queries that you have created. A solution component or part of the application may depend on a specific saved query. If there are queries you do not want to appear in the application, you should deactivate them.

Retrieve views

Use a RetrieveMultipleRequest or IOrganizationService.RetrieveMultiple to retrieve saved query records.

The following sample retrieves all the public views for the opportunity:

var mySavedQuery = new QueryExpression
       {
           ColumnSet = new ColumnSet("savedqueryid", "name", "querytype", "isdefault", "returnedtypecode", "isquickfindquery"),
           EntityName = SavedQuery.EntityLogicalName,
           Criteria = new FilterExpression
           {
               Conditions =
{
   new ConditionExpression
   {
       AttributeName = "querytype",
       Operator = ConditionOperator.Equal,
       Values = {0}
   },
   new ConditionExpression
   {
       AttributeName = "returnedtypecode",
       Operator = ConditionOperator.Equal,
       Values = {Opportunity.EntityTypeCode}
   }
}
           }
       };
       RetrieveMultipleRequest retrieveSavedQueriesRequest = new RetrieveMultipleRequest { Query = mySavedQuery };

       RetrieveMultipleResponse retrieveSavedQueriesResponse = (RetrieveMultipleResponse)service.Execute(retrieveSavedQueriesRequest);

       DataCollection<Entity> savedQueries = retrieveSavedQueriesResponse.EntityCollection.Entities;

       //Display the Retrieved views
       foreach (Entity ent in savedQueries)
       {
           SavedQuery rsq = (SavedQuery)ent;
           Console.WriteLine("{0} : {1} : {2} : {3} : {4} : {5},", rsq.SavedQueryId, rsq.Name, rsq.QueryType, rsq.IsDefault, rsq.ReturnedTypeCode, rsq.IsQuickFindQuery);
       }

Deactivate views

If you do not want a public view to appear in the application, you can deactivate it. You cannot deactivate a public view that is set as the default view. The following sample deactivates the Closed Opportunities in Current Fiscal Year view for the Opportunity:

System.String SavedQueryName = "Closed Opportunities in Current Fiscal Year";
QueryExpression ClosedOpportunitiesViewQuery = new QueryExpression
{
   ColumnSet = new ColumnSet("savedqueryid", "statecode", "statuscode"),
   EntityName = SavedQuery.EntityLogicalName,
   Criteria = new FilterExpression
   {
       Conditions =
       {
           new ConditionExpression
           {
               AttributeName = "querytype",
               Operator = ConditionOperator.Equal,
               Values = {0}
           },
           new ConditionExpression
           {
               AttributeName = "returnedtypecode",
               Operator = ConditionOperator.Equal,
               Values = {Opportunity.EntityTypeCode}
           },
                           new ConditionExpression
           {
               AttributeName = "name",
               Operator = ConditionOperator.Equal,
               Values = {SavedQueryName}
           }
       }
   }
};

RetrieveMultipleRequest retrieveOpportuntiesViewRequest = new RetrieveMultipleRequest { Query = ClosedOpportunitiesViewQuery };

RetrieveMultipleResponse retrieveOpportuntiesViewResponse = (RetrieveMultipleResponse)service.Execute(retrieveOpportuntiesViewRequest);

SavedQuery OpportunityView = (SavedQuery)retrieveOpportuntiesViewResponse.EntityCollection.Entities[0];
_viewOriginalState = (SavedQueryState)OpportunityView.StateCode;
_viewOriginalStatus = OpportunityView.StatusCode;


SetStateRequest ssreq = new SetStateRequest
{
   EntityMoniker = new EntityReference(SavedQuery.EntityLogicalName, (Guid)OpportunityView.SavedQueryId),
   State = new OptionSetValue((int)SavedQueryState.Inactive),
   Status = new OptionSetValue(2)
};
service.Execute(ssreq);

Edit filter criteria or configure sorting

To edit the filter or edit how the data is sorted, you must set the SavedQuery.FetchXml parameter. More information: Query data using FetchXml.

Edit columns

The columns that you want to display in views can be taken from the table or related tables. For more information about how to specify the columns to display, see the layoutxml element in the Customization solutions file schema.

Add custom icons with tooltip for a column

You can add custom icon with tooltip text to display in a column depending on the column value; you can also specify localized tooltip text. This can be done by adding the custom icons as image web resources in your instance and then using a JavaScript web resource to add JavaScript code for a column to display the icons depending on the column value.

Two new parameter, imageproviderwebresource and imageproviderfunctionname, are added to the cell element of the layoutxml of savedquery that lets you specify the name of a web resource and a JavaScript function name to display custom icons and tooltip text for a column. The JavaScript code gets executed when the page loads.

You can also use the new Web Resource and Function Name in the Column Properties page while modifying the property of a column in a view definition to specify the web resource name and JavaScript function name.

The following sample code demonstrates how you can programmatically specify a web resource and a JavaScript function name for adding custom icons and tooltip for the opportunityratingcode column in layoutxml:

System.String layoutXml =  
@"<grid name='resultset' object='3' jump='name' select='1'  
  preview='1' icon='1'>  
  <row name='result' id='opportunityid'>  
    <cell name='name' width='150' />  
    <cell name='customerid' width='150' />  
    <cell name='estimatedclosedate' width='150' />  
    <cell name='estimatedvalue' width='150' />  
    <cell name='closeprobability' width='150' />  
    <cell name='opportunityratingcode' width='150' imageproviderwebresource='new_SampleWebResource'  
          imageproviderfunctionname='displayIconTooltip' />  
    <cell name='opportunitycustomeridcontactcontactid.emailaddress1'  
        width='150' disableSorting='1' />  
  </row>  
</grid>";  

The JavaScript function for displaying custom icons and tooltip text expects the following two arguments: the entire row object specified in layoutxml and the calling user's Locale ID (LCID). The LCID parameter enables you to specify tooltip text for the icon in multiple languages. For more information about the languages supported, see Enable additional languages and Install or upgrade language packs. For a list of locale ID (LCID) values that you can use in your code, see Locale IDs assigned by Microsoft.

Assuming you will most likely be adding custom icons for a choice type of column as it has a limited set of predefined options, make sure you use the integer value of the options instead of label to avoid breaking the code due to changes in the localized label string. Also, in your JavaScript function, specify just the name of an image web resource that you want to use as an icon for a value in the column. The image should be of 16x16 pixels size; larger images will be automatically scaled down to 16x16 pixels size.

The following sample code displays different icons and tooltip text based on one of the values (1: Hot, 2: Warm, 3: Cold) in the opportunityratingcode (Rating) column. The sample code also shows how to display localized tooltip text. For this sample to work, you must create three image web resources each with 16x16 images (, , and ) in your instance with the following names respectively: new_Hot, new_Warm, and new_Cold.

function displayIconTooltip(rowData, userLCID) {      
    var str = JSON.parse(rowData);  
    var coldata = str.opportunityratingcode_Value;  
    var imgName = "";  
    var tooltip = "";  
    switch (parseInt(coldata,10)) {
        case 1:  
            imgName = "new_Hot";  
            switch (userLCID) {  
                case 1036:  
                    tooltip = "French: Opportunity is Hot";  
                    break;  
                default:  
                    tooltip = "Opportunity is Hot";  
                    break;  
            }  
            break;  
        case 2:  
            imgName = "new_Warm";  
            switch (userLCID) {  
                case 1036:  
                    tooltip = "French: Opportunity is Warm";  
                    break;  
                default:  
                    tooltip = "Opportunity is Warm";  
                    break;  
            }  
            break;  
        case 3:  
            imgName = "new_Cold";  
            switch (userLCID) {  
                case 1036:  
                    tooltip = "French: Opportunity is Cold";  
                    break;  
                default:  
                    tooltip = "Opportunity is Cold";  
                    break;  
            }  
            break;  
        default:  
            imgName = "";  
            tooltip = "";  
            break;  
    }  
    var resultarray = [imgName, tooltip];  
    return resultarray;  
}  

This results in displaying the values in the Rating column with appropriate icons depending on the value, and icon tooltip text when you hover over the icons.

Set as default

Only one active public view can be set as the default view. To make a view the default view, set the IsDefault property to true.