NAME

XAO::DO::Web::FS - XAO::Web front end object for XAO::FS

SYNOPSIS

<%FS uri="/Categories/123/description"%>

<%FS mode="show-list"
     base.clipboard="cached-list"
     base.database="/Foo/test/Bars"
     fields="*"
     header.path="/bits/foo-list-header"
     path="/bits/foo-list-row"
     default.path="/bits/foo-list-default"
%>

<%FS mode="search"
     uri="/Orders"
     index_1="status"
     value_1="submitted"
     compare_1="wq"
     expression="1"
     orderby="place_time"
     fields="*"
     header.path="/bits/admin/order/list-header"
     path="/bits/admin/order/list-row"
     footer.path="/bits/admin/order/list-footer"
     default.path="/bits/foo-list-default"
%>

DESCRIPTION

Web::FS allows web site developer to directly access XAO Foundation Server from templates without implementing specific objects.

SEARCH MODE

Accepts the following arguments:

uri => '/Customers'

Database object path.

index_1..N => 'first_name|last_name'

Name of database field(s) to perform search on. Multiple field names are separated by | (pipe character) and treated as a logical 'or'.

value_1..N => 'Ann|Lonnie'

Keywords you want to search for in field(s) of corresponding index. Multiple sets of keywords are separated by | (pipe character) and treated as a logical 'or'.

compare_1..N => 'ws'

Comparison operator to be used in matching index to value. Supported comparison operators are: eq True if equal.

ge  True if greater or equal.

gt  True if greater.

le  True if less or equal.

lt  True if less.

ne  True if not equal.

gtlt True if greater than             'a' and less than 'b'

gtle True if greater than             'a' and less than or equal to 'b'

gelt True if greater than or equal to 'a' and less than             'b'

gele True if greater than or equal to 'a' and less than or equal to 'b'

wq  (word equal) True if contains given word completely.

ws  (word start) True if contains word that starts with the given string.

cs  (contains string) True if contains string.

expression => [ [ 1 and 2 ] and [ 3 or 4] ]

Logical expression, as shown above, that indicates how to combine index/value pairs. Numbers are used to indicate expressions specified by corresponding index/value pairs and brackets are used so that only one logical operator (and, or) is contained within a pair of brackets.

orderby => '+last_name|-first_name'

Optional field to use for sorting output. If field name is preceded by - (minus sign), sorting will be done in descending order for that field, otherwise it will be done in ascending order. For consistency and clarity, a + (plus sign) may precede a field name to expicitly indicate sorting in ascending order. Multiple fields to sort by are separated by | (pipe character) and are listed in order of priority.

distinct => 'first_name'

This eliminates duplicate matches on a given field, just like SQL distinct.

limit => 10

Allows to limit the number of matches to a specified number.

start_item => 40

Number indicating the first query match to fetch.

items_per_page => 20

Number indicating the maximum number of query matches to fetch.

Example:

<%FS mode="search
     uri="/Customers"
     fields="*"

     index_1="first_name|last_name"
     value_1="Linda|Mary Ann|Steven"
     compare_1="wq"

     index_2="gender"
     value_2="female"
     compare_2="wq"

     index_3="age"
     value_3="21|30"
     compare_3="gelt"

     expression="[ [ 1 and 2 ] and 3 ]"
     orderby="age|first_name+desc"
     start_item="40"
     items_per_page="20"

     header.path="/bits/admin/order/list-header"
     path="/bits/admin/order/list-row"
     footer.path="/bits/admin/order/list-footer"
     default.template="No matches found."
%>

CONFIGURATION VALUES SUPPORTED IN SEARCH MODE

default_search_args

The value of this configuration value is a reference to a hash. In this hash each key is a database (object) path (name) whose corresponding value is a reference to a hash containing the default arguments for searching on the specified of data. These default arguments are added unless they are specified by input arguments.

METHODS

FS provides a useful base for other displayable object that work with XAO::FS data.

get_object (%)

Returns an object retrieved from either clipboard or the database. Accepts the following arguments:

base.clipboard     clipboard uri
base.database      XAO::FS object uri
uri                XAO::FS object URI relative to `base' object
                   or root if no base.* is given

If both base.clipboard and base.database are set then first attempt is made to get object from the clipboard and then from the database. If the object is retrieved from the database then it is stored in clipboard. Next call with the same arguments will get the object from clipboard.

Here is the list of accepted 'mode' arguments and corresponding method names. The default mode is 'show-property'.

delete-property => delete_property (%)

Deletes an object or property pointed to by `name' argument.

Example of deleting an entry from Addresses list by ID:

<%FS
  mode="delete-property"
  base.clipboard="/IdentifyUser/customer/object"
  uri="Addresses"
  name="<%ID/f%>"
%>

show-hash => show_hash (%)

Displays a XAO::FS hash derived object. Object location is the same as described in get_object() method. Additional arguments are:

fields     comma or space separated list of fields that are
           to be retrieved from each object in the list and
           passed to the template. Field names are converted
           to all uppercase when passed to template. For
           convenience '*' means to pass all
           property names (lists be passed as empty strings).

path       path to the template that gets displayed with the
           given fields passed in all uppercase.

extra_sub  reference to a subroutine that creates additional
           parameters for the template and returns them in
           a hash reference. For use in derived class
           methods.

Example:

<%FS mode="show-hash" uri="/Customers/c123" fields="firstname,lastname"
     path="/bits/customer-name"%>

Where /bits/customer-name should be something like:

Customer Name: <%FIRSTNAME/h%> <%LASTNAME/h%>

'show-list' => show_list (%)

Displays an index for XAO::FS list. List location is the same as described in get_object() method. Additional arguments are:

fields             comma or space separated list of fields that are
                   to be retrieved from each object in the list and
                   passed to the template. Field names are converted
                   to all uppercase when passed to template. For
                   convenience '*' means to pass all
                   property names (lists be passed as empty strings).
header.path        header template path
path               path that is displayed for each element of the list
footer.path        footer template path
default.path       default template path, shown instead of  header,
                   path and footer in the case where there are no
                   items in list

Show_list() supplies 'NUMBER' argument to header and footer containing the number of elements in the list.

At least 'ID' and 'NUMBER' are supplied to the element template. Additional arguments depend on 'field' content.

show-property => show_property (%)

Displays a property of the given object. Does not use any templates, just displays the property using textout(). Example:

<%FS uri="/project"%>

METHODS

No publicly available methods except overriden display().

EXPORTS

Nothing.

AUTHOR

Copyright (c) 2000-2002 XAO, Inc.

Andrew Maltsev <am@xao.com>, Marcos Alves <alves@xao.com>.

SEE ALSO

Recommended reading: XAO::Web, XAO::DO::Web::Page.