Field : Filter

Filter fields provide the basis for filter chips.

Description

They can be conditionally enabled by subject area using the case property - which is a space seperated list of Subject (subject area) names.An attribute can only have one field defined for it. e.g. you could not have two fields on the Entity class filter that are bound to the same firstName attribute. That said, the definition for that field may be overridden in a subclass filter.

Properties

association : string

Association path to the class attribute on which to filter. e.g. lastName

This is the most important property of a field. It determines the attribute to bind to and with which to filter. An attribute can only have one field defined for it. e.g. you could not have two fields on the Entity class filter that are bound to the same firstName attribute. That said, the definition for that field may be overridden in a subclass filter.

bounded : boolean

True if the input values are restricted to the set provided by the item collection

caption : string

Caption text expression

captions : string

Association path or expression to the caption of the items in the collection

Note that this property isn't a list of values. It is simply the association path, or expression, to the caption of the items.

It is called captions (plural) because it retrieves the caption(s) from the collection's item(s).

case : string

Query context value determining when the view becomes visible. "*" matches any value.

Space seperated list to determine when the field is visible. "*" means it always is visible.

conjunction : string

The name of the "any" group in the query

crop : boolean

True to crop icons

default : string

Default field value expression. If quasiquoted, it is expanded on client every time the filter is (re-)loaded.

Special local variable this (i.e the controller) is provided by the framework for the function

Example: Function returning default value:
`(default-user this)

In a library:
(define (default-user controller)
...
)

icon : string

Icon name expression

icons : string

Association list of association paths or constants to the icon properties of the items in the collection

Association list of association paths or constants: (image|data|type|icon|default|lock . <a1> ... <an>|"<const>")

Note that this isn't a list of values. It is simply the association path, or expression, to the icon of the items.

It is called icons (plural) because it retrieves the icon(s) from the collection's item(s).

Example: Configuring data table avatar for Entity.meta

<Table>
<Column ... icons="(image . image)(data . mimeData)(type . mimeType)(icon . icon)(default . "icon:person")(lock . locking)" .../>
...
</Table>

image - The name of the attribute that contains the image (usually of type Obj) from the current instance. The attribute name doesn't need to be called "image", but often is.
data - Obj'mimeData attribute of type binary returning the image data. Always mimeData if the image attribute is of type Obj.
type - Obj'mimeType attribute of type string returning mime type of the image data. Always mimeType if the image attribute is of type Obj.
icon - optional. The name of an attribute of type string returning an icon name if the image is null
default - optional. "icon:person" - A constant expression to fall back on if both image and icon are null
lock - optional. The name of the attribute returning the optimistic locking value. Always locking if the image attribute is of type Obj.

items : string

Displayed collection of items: (<view1> <a11> ... <a1N>) ... (<viewN> <aN1> ... <aNM>)|(@ <a1> ... <aN>)|(@@ <class>)

<empty> - the same as (@) in Forms; no data in other situations
(ViewName1 assoc1 ... assocN) ... (ViewNameM assoc1 ... assocX) - collection relative to the items of the specified views; constrained by all the association paths
(@ assoc1 ... assocN) - collection relative to the Layout's model items
(@@ ClassName) - instances of the class specified by ClassName

mode : string

Picker mode name. The "?" suffix, if any, is substituted by the field case value.

multi : boolean

Valid when a picker is specified. Determines whether multi or single picker field.

nullCaption : string

The caption text if the filter chip has not been set

Usually this is left blank, but could be used to have the chip read something like "Enter a Status" rather than just "Status"

operator : string

When set, overrides and hides the run-time operator selection UI. Custom operator configuration is possible with the OPERATORS static attribute on a metaclass and operators.scm. The attribute value is an association list, or a collection of lists with the following keys:

name – operator name
spec – operator specification. (x) – query association, (y) – first argument, (z) – second argument. If spec is a collection, each item corresponds to the following cases: x >= z, x < z, z unspecified, x unspecified.
caption – localizable operator caption
arity – 1, 2, 3; 2 (association field and 1 operator value) by default
format - value format

Example: Define the following constant in operators.scm:
(define ANNIVERSARY?
   '((name . "anniversary?")
      (spec . #(
         "(<=(date-part month(y))(date-part month(x))(date-part month(z)))"   ; y < z
         "(or(<=(date-part month(y))(date-part month(x)))(<=(date-part month(x))(date-part month(z))))"  ; z > y
         "(<=(date-part month(y))(date-part month(x)))"  ; z unspecified
         "(<=(date-part month(x))(date-part month(z)))"  ; y unspecified
      ))
      (caption . "ids.anniversaryOp")
      (arity . 3)
      (format . "MMM d")
   )
)
(EntityDate'OPERATORS) value returns (list ANNIVERSARY?)

order : string

Item order specification: ((<attr1> . #t|#f) ... (<attrN> . #t|#f)

List of attributes or attribute and boolean pairs to indicate ascending (#t) or descending (#f).

Example: ((name . #t) (company . #f))

pattern : string

Converter pattern

Examples include

date.m.f
currency.s
shortCurrency
percent
quantity
priceCurrency
shortDate
{0;choice;0||1|{$};*} - this syntax allows for different treatment of plurals
{@$.fullName;link;;@i}
time.m
datetime.m.f
{@$.fullName;string;}
integer
shortTimestamp
ids.conversationsTo
#,##0.##
date.l.f
longDate
{@$.userPerson.fullName;string;}
internationalPhone

persistent : boolean

True to make the field always present or visible, false to be able to hide the field

picker : string

Picker (.picker) definition name

Use this property if the values should be selected from a picker rather than just entered as a primitive type.

poly : boolean

Valid when a picker is specified. True if the picker returns dynamic fields

privilege : identifier

Access privilege

Valid values based on“string”.
:?[\p{L}_][\p{L}\p{N}_](:[\p{L}_][\p{L}\p{N}_])*	Value must begin with a letter or an underscore. Case and length are not restricted. Letters, numbers and underscores are allowed. Colon is used as a scope separator. Spaces and other punctuation characters are not allowed.

reader : string

Custom read event. [<class>]'<event> <arg1> ... <argN>

Specification: [<class>]'<event> <arg1> ... <argN>

<class> is an optional class symbol. When omitted, the items collection class is used. <event> is a read event symbol. <arg#> is an event argument value which can be either a constant or a scheme expression evaluating to a constant at run-time on the client, using special local variables provided by the framework: this (=controller), :node (=active node), :attributes, :where, :orderBy, :count, :offset, :xlock, or a UI initializer variable.

If arguments are not specified, a default list is supplied by the framework: :attributes :where :orderBy :count :offset :xlock

Examples:

a) Generate a request to 'readList event with default arguments: readList

b) Generate request to readList event with attributes, and orderBy argument values supplied by the framework. readList :attributes :orderBy

c) Generate request to Contact'readDetail with attributes supplied by the framework, and the contact argument calculated using (current-contact) client library function. Contact'readDetail :attributes (current-contact this :node)

In a library: (define (current-contact controller node) ... )

d) Generate request to 'read event with a constant attribute list: read '(lastName firstName) :where :orderBy :count :offset :xlock

section : string

Field section caption

sort : ComboSortType

Set to "server" to perform sort on the server, "client" to perform sort on the client when order expression is not supported by the data source

Valid values based on“string”.
client	The model will be sorted on the client.
server	The model will be sorted on the server.

tooltips : string

The attribute, association path, or a constant specifying tooltips.

type : string

Dynamic field type association path

unit : string

Converter unit association path or expression

utc : boolean

True to make datetime fields use UTC timezone for comparing dates, false to use local time. If the Field's type is set as 'date', the Field will set this property to true.

valueCaption : string

Value caption association path or expression

The association path to an attribute on this item or an expression that will be used as the caption.

Example: valueCaption="fullname"
or
valueCaption="`(string-affix ,(@ firstName) " " ,(@ lastName))"

valueIcon : string

Value icon association path or expression

Example: Configuring picker value avatar for Campaign.meta

<Picker valueIcon="(image . (manager image))(data . mimeData)(type . mimeType)(icon . (manager icon))(default . "icon:person")"/>

manager image - Association path from Campaign to Entity'image attribute of type Obj
mimeData - Obj'mimeData attribute of type binary returning the image data
mimeType - Obj'mimeType attribute of type string returning mime type of the image data
manager icon - Association path from Campaign to Entity'icon attribute of type string returning an icon name if the image is null
"icon:person" - A constant expression to fall back on if both image and icon are null

values : identifierList

Association path or expression to the value returned from the items in the collection

If blank, the value will be the object itself - not an attribute on the object.

Note that this property isn't a list of values. It is simply the association path, or expression, to the return value of the items.

It is called values (plural) because it returns the values(s) from the collection's item(s).

Valid values based on“token”.
(:?[\p{L}_][\p{L}\p{N}_](:[\p{L}_][\p{L}\p{N}_])\s+)(:?[\p{L}_][\p{L}\p{N}_](:[\p{L}_][\p{L}\p{N}_])*)?	Each element in the list must begin with a letter or underscore. Elements are space delimited.

where : string

Logical expression that the items must satisfy. If quasiquoted, it is expanded on the client every time the model is (re-)loaded.

Special local variable this (=controller) is provided by the framework for the function

Example: Constant where expression:
(= (@ firstName) "Joe")

Function returning where clause:
`(generate-where-clause this "EntityId")

In a library:
(define (generate-where-clause controller var)
...
)

Parents

Filter - Filter elements centralize the search configuration for a given class and are used by filter controls to present text search, filter tiles, and filter chips to end users.