Introduction to value editors

Each condition in query consists of 3 parts: attribute (field), operator and values (one or more). By default when user clicks on ”[enter value]” link in condition he/she is presented with an edit box to actually type the value. EasyQuery allows you to assign a value editor for each attribute or operator in your model - so your users will be able to use other methods of entering values instead of just typing in a text box. For example, value editor allows you to define a list of available values - so your users will be able to select the value from a drop-down list.

• Auto (or no value editor defined) - EasyQuery will automatically use the most appropriate editor for that attribute.
• Text editor - simple text box where user can type necessary value. It's possible to define the type of entered values for pre-validation
• Date/time editor - textbox combined with a date/time picker dialog
• List of constants - you can define the list of available items and user will be able to select from that list when build query. Each item has 'id' and 'text' properties. The values of 'text' property will be shown to users in drop-down list. The value of 'id' for selected item will be placed into generated SQL.
• Custom list - works the similar way as previous but the list of items is defined at run-time in ListRequest event handler according to list name (can be specified in data model via Data Model Editor).
• SQL List - works exactly the same was as “Custom list”. This value editor has special name “SQL” and can hold some SQL expression in additional property. ListRequest event handler is responsible for executing that SQL statement and returning the result list back to visual control (widget).
• Custom - raises CustomValue event. You can handle this event, show some special dialog and return back a pair “value-text” according to data entered by user in that dialog. This value editor is not processed in MVC edition of EasyQuery.

You can define value editor for some attribute in your model using one of the following method

• Run Data Model Editor (DME)
• Open your model XML file
• Go to “Entities” tab and select the entity attribute you what to define editor for.
• On the right panel for selected attribute open “Value Editors” tab
• Select the type of editor from drop-down list
• Press “Settings…” button to define additional parameters for selected editor.
• Save your model and close DME

Here is an example how you can specify CustomList value editor for some attribute in your model:

//find entity attribute
EntityAttr attr = model.EntityRoot.FindAttribute(EntityAttrProp.Expression, "Customers.Country");
 
//create editor object
var editor = new CustomListValueEditor();
editor.ListName = "MyCustomList";
 
//assign new editor to attribute
attr.DefaultEditor = editor;

*Custom list” and “SQL list” value editor raises ListRequest event to get the list of available values. In case of MVC application this event can be processed both on client and server side. To process it on client side you need to assign a function to listRequestHandler property in easyQuerySettings object:

window.easyQuerySettings = {
    serviceUrl: "/EasyQuery",
    loadDefaultModel: true,
    .   .   .   .   .   .   .  
    listRequesHandler: function (params, onResult) {
        var processed = true;
        if (params.listName == "RegionList") {
            var query = EQ.client.getQuery();
            var country = query.getOneValueForAttr(query, "Customer.Country");
            if (country == "Canada") {
                onResult([
                    { id: "BC", text: "British Columbia" },
                    { id: "Quebec", text: "Quebec" }
                ]);
 
            }
            else {
                onResult([
                    { id: "CA", text: "California" },
                    { id: "CO", text: "Colorado" },
                    { id: "OR", text: "Oregon" },
                    { id: "WA", text: "Washington" }
                ]);
            }
        }
        else
            processed = false;
 
        return processed;
    }
 
};

The code above is quite straightforward and self-explanatory. The only note we should make is about the returned value. If it's true the list request is considered as “processed” and no further actions are performed. Otherwise - EasyQuery.JS will initiate GetList AJAX request to the server passing list name and other value editor properties (if necessary) as request parameters. To process this request the default template of EasyQueryController has GetList action method. This action handler just calls corresponding GetList method of EqServiceProviderDb object and returns the result back to the client:

[HttpPost]
public ActionResult GetList(ListRequestOptions options) {
    return Json(eqService.GetList(options));
}

All other editions of EasyQuery (WinForms, WebForms, WPF or Silverlight) has ListRequest event in QueryPanel control which is raised when user adds an attribute (or operator) with Custom List or SQL list value editor assigned to that attribute/operator. You need to handle that event and return the list of available values via event's parameters (according to list name and/or SQL statement). Here is an example of such event handler:

private void QPanel_ListRequest(object sender, ListRequestEventArgs e) {
    if (e.ListName == "SQL") {
        CheckConnection();
        string sql = e.Data.ToString();
        OleDbDataAdapter resultDA = new OleDbDataAdapter(sql, DbConnection);
 
        DataSet tempDS = new DataSet();
        try {
            resultDA.Fill(tempDS, "Result");
 
            StringWriter strWriter = new StringWriter();
            tempDS.WriteXml(strWriter);
            e.ListItems.LoadFromXml(strWriter.ToString());
 
        }
        catch {
            e.ListItems.Clear();
        }            
    }
    else if (e.ListName == "RegionList") {
        e.ListItems.Clear();
        countryAttr = model.EntityRoot.FindAttribute(EntityAttrProp.Expression, "Customers.Country");
        string country = query.GetOneValueForAttr(countryAttr);
 
        if (country == "Canada") { 
            e.ListItems.Add("British Columbia", "BC");
            e.ListItems.Add("Quebec", "Quebec");
 
 
        }
        else if (country == "USA") {
            e.ListItems.Add("California", "CA");
            e.ListItems.Add("Colorado", "CO");
            e.ListItems.Add("Oregon", "OR");
            e.ListItems.Add("Washington", "WA");
        }
        else {
            e.ListItems.Add("California", "CA");
            e.ListItems.Add("Colorado", "CO");
            e.ListItems.Add("Oregon", "OR");
            e.ListItems.Add("Washington", "WA");
        }
 
    }
    else if (e.ListName == "YesNoList") {
        e.ListItems.Add("Yes", "1");
        e.ListItems.Add("No", "2");
    }
}

The example above is defined for WinForms edition but it will look very similar for other editions as well. First section of this handler processes the requests for “SQL List” value editors. We just execute SQL statement passed in event's parameter and return the result set (in a special format). All other else if sections return lists for particular lists according to the list names.

Please take a look at first else if section which populates items for “RegionList”. Here we show how you can filter the returned list according to the value specified for some other attribute. In this example we search our query for a condition like “Customer country is equal to {Some Country}”. If such condition is defined - we get the value (country code) from it and use that value as a filter for the list of regions. For more information about this approach please read: Dynamically populating lists by information from other conditions (WinForms)