From f289d82afbd6a316e9f83953408e0c75c738c4d0 Mon Sep 17 00:00:00 2001 From: John Cardinal Date: Wed, 19 Dec 2018 23:35:38 +0000 Subject: [PATCH] --- devdocs/todo.txt | 3 +- docs/8.0/ayanova/docs/api-request-format.md | 46 ++++++++++++++++++- .../ControllerHelpers/PagingOptions.cs | 3 -- 3 files changed, 46 insertions(+), 6 deletions(-) diff --git a/devdocs/todo.txt b/devdocs/todo.txt index 7353b659..258389b9 100644 --- a/devdocs/todo.txt +++ b/devdocs/todo.txt @@ -81,7 +81,8 @@ TODO CLIENT STUFF TODO SERVER STUFF - Docs: pagingOptions, sort and filter need to be documented for API - + + - Owner ID: where does it vet the owner ID is a valid existing owner when it's set for various objects?? ----------------- TODO AFTER CLIENT block ABOVE: diff --git a/docs/8.0/ayanova/docs/api-request-format.md b/docs/8.0/ayanova/docs/api-request-format.md index 44917e27..cfe7cb12 100644 --- a/docs/8.0/ayanova/docs/api-request-format.md +++ b/docs/8.0/ayanova/docs/api-request-format.md @@ -31,9 +31,19 @@ This parameter controls the paging offset and is expected to be an integer. If This parameter controls the number of items returned starting at the offset provided. The maximum allowed value is 1000, the default value is 25 if no value is specified. -### Sort +### DataFilterId - Sorting and Filtering -This parameter controls the sort order of the data returned. It is expected to be a JSON array of objects that contain two fields a `fld` property that contains the string name of the field to be sorted by and a `dir` property that controls the direction of sorting and is one of two values "+" for Ascending or "-" for Descending. Multiple objects may be specified to sort by multiple columns in order from first to last specefied in the array. +Sorting and filtering are accomplished by providing an Id value in the DataFilterId parameter of a list for a pre-created and saved `DataFilter` object. + +A DataFilter is created separately before it can be used with a list request via the DataFilter route (see the [API explorer console](api-console.md)). + +A DataFilter object contains properties for filtering and sorting as well as a name as displayed for selection in the user interface and also properties that control who can select and use the filter (public or just a single User). + +#### DataFilter.sort + +This parameter controls the sort order of the data returned. It is expected to be a JSON array of objects that contain two fields a `fld` property that contains the string name of the field to be sorted by and a `dir` property that controls the direction of sorting and is one of two values "+" for Ascending or "-" for Descending. Multiple objects may be specified to sort by multiple columns in order from first to last specified in the array. + +Note that this property of the DataFilter is expected to be a *string* representation of the JSON collection, not raw JSON. For example the following Sort array will sort a list by Name first in ascending order and then by StartDate second in descending order: @@ -43,4 +53,36 @@ To determine which field names are valid for a particular list you can make use If no sort parameter is provided the default is to sort by Id Descending so the most recently created objects appear first in the list. +#### DataFilter.filter +This parameter filters the data returned. It is expected to be a *string* representation of a JSON array of objects that contain three fields a `fld` property that contains the string name of the field to be sorted by, a `op` property that specifies what type of filter operation is required and optionally a `value` property when a comparison value is required such as a "Starts with" type of filter. + +The `fld` property must be a valid field for the list in question. To determine which field names are valid for a particular list you can make use of the `/FilterOptions` API route for that object which is available for any objects with sort and filterable lists. + +The `op` property must be a valid filter operation type. The 10 possible values for `op` are: + +| OP | MEANING | +| ----- | ------------------------------ | +| = | Equality, `fld` data must equal `value` specified to be included in list | +| > | Greater than, `fld` data must be greater than `value` specified to be included in list | +| >= | Greater than or equality, `fld` data must be greater than or equal to `value` specified to be included in list | +| < | Less than, `fld` data must be less than `value` specified to be included in list | +| <= | Less than or equality, `fld` data must be less than or equal to `value` specified to be included in list | +| != | Not equal, `fld` data must not equal `value` specified to be included in list | +| %- | Starts with, `fld` data must start with `value` specified to be included in list | +| -% | Ends with, `fld` data must end with `value` specified to be included in list | +| -%- | Contains, `fld` data must contain `value` specified to be included in list | +| !-%- | Not contains, `fld` data must not contain `value` specified to be included in list | + + +Note that not all op values are valid for all data types, for example a date doesn't support a Contains type operator. + +The `value` property + + +For example the following filter array JSON (in string format) will return only items where the Name starts with "Bob" and the Notes field exactly equals "Aardvark": + +`"filter": "[ {\"fld\": \"name\", \"op\": \"%-\", \"value\": \"Bob\" }, { \"fld\": \"notes\", \"op\": \"=\", \"value\": \"Aardvark\" }]" +}` + +If no filter parameter is provided no filtering will be done on the list diff --git a/server/AyaNova/ControllerHelpers/PagingOptions.cs b/server/AyaNova/ControllerHelpers/PagingOptions.cs index b04eb80a..37f6c918 100644 --- a/server/AyaNova/ControllerHelpers/PagingOptions.cs +++ b/server/AyaNova/ControllerHelpers/PagingOptions.cs @@ -18,9 +18,6 @@ namespace AyaNova.Api.ControllerHelpers [Range(1, MaxPageSize, ErrorMessage = "Limit must be greater than 0 and less than 1000.")] public int? Limit { get; set; } - public string Sort { get; set; } - public bool? Asc { get; set; } - //Data filter id to use with this list query //0 or less means no filter public long DataFilterId { get; set; }