Postinternals.pod

NAME

Communiware Posting Internals - documents protocol of interaction between posting form and posting handler.

PREFACE

This document describes how Communiware forms communicate with Communiware server. You may use this information if you want to generate forms without aid of Input and EditField dynamic elements, i.e using client-side scripting.

Information in this document is applicable either to posting forms, generated using <:Post:> dynamic element, or to ``special'' forms generated with <:Form:> dynamic element with type=special

FORM STRUCTURE

HTTP request, processed with submit-time handler (AKA Posting handler) should have special set of fields.

It includes

global fields
These fields indicate global form proprietes. This include __form_auth field, REFERER and RETURN fields. 

C<REFERER> contains URL of page which user come to form from.
Upon initital display of form this field is filled from C<HTTP_REFERER>
environment variable. Value of this field should be passed unchanged
through as many user-server interactions as there would be.

It must be preserved if there was posting error, and if after successful posting user wasn't redirected to another page.

RETURN field specifies where user should be transferred after successful posting. It may be full URL or one of keywords new or back. Keyword new means that user should be redirected to the default view of created/modified item (not applicable to multiposting) and back means that there should be redirect to URL, specified in the REFERER field.

Submit time substitution is allowed in the value of this variable.

In case of multiposting all substitutied variables should be explicitely prefixed with name of context. All non-prefixed variables are considered global context attributes. SERVER field may also be global.

Actions also may be specified as global fields (see POSTING ACTIONS).

Context specific fields
Rest of the fields in the form are grouped into several submit-time contexts.

Context data are identificated by presense of special fields Posting or Process, which contain list of context prefixes.

Individual hidden field in the form should correspond to each context to be processed.

All fields, which are part to each submit-time context to be processed should be named as context prefix.attribute name, where context prefix - name of some submit-time context, which is listed in Posting or Process fields.

Context names can be numeric or alphanumeric and are case-sensitive (as anything in Communiware).

Dynamic element Item allows to specify context name explicitely.

For anonymous Item containers and single postings numeric identifiers are assigned.

Dynamic element Form always uses prefix F.

Name of current posting container can be obtained in the template using context function DOM_ID(posting).

One HTTP request may contain either Posting or Process field. If both are present, results are unspecified as of version 0.97, but most likely error would be raised upon processiong of non-posting context.

While it is known which template was used to display given form (because Post form are always submitted to the same URL they were retrieved from), this information is not curtently used by posting handler. It has at its disposal only set of form parameters.

Form parameters are parsed by CGI.pm code invoked from global context constructor, so several input elements with same name are viewed as one parameter with perl list as value.

TYPES OF SUBMIT-TIME CONTEXT

There are three main types of submit-time contexts:

  1. Context of special form. Such contexts are created by submitting a form, created by Form type=special dynamic element.

    These contexts always have ITEM_ID attribute, which is Id of item in which context form was created, and typically no other item attributes.

    Typically there is only one such context per form, and it is named 'F'.

    There are no actions in special form context. Only dynamic elements MailTo, Subscribe, Check and Do are processed.

    Cookies also can be set via Input submit.

    Use dynamic elements can be used to compute values, which would be used in submit-time substitution in the parameters of these DE.

  2. Updating/deleting/renaming existing item

  3. Creating new item

GENERIC CONVENTIONS

PASSING OF ORDERED LIST

This protocol assumes that order of fields in HTTP request is unspecified and have no relation with order of appearance of the correspding HTML tags in the form.

If it is nesseccary to pass ordered list via some field (i.e. list of operands and operators of Communiware expression), they are passed as single string value using ASCII Field Separator character \0x37 as item delimiter.

SUBMIT-TIME SUBSTITUTION

It is often nesseccary to compute values of some form fields depending on values of other (i.e. user-entered fields).

Submit-time substitution used to achieve this.

Submit-time subsitution is much like visualisation time substitution which is used in the dynamic element parameters.

Main difference is that % sign is used to indicate substitution instead of @ sign, which allows two-level substitution - first upon visualisation of form, second upon submit.

Other difference is that context modifier can be used with attribute (but non context function) name i.e %context.ATTR which allows to reference attributes of one posting container from another.

Submit time subsitution is never performed on the data which are entered by user in the form input fields, i.e. item attributes, actions and datatype processing modifiers, and always (unless specified otherwise) performed on the special fields.

Use <:Use:> dynamic element to calculate value of item attribute.

Submit time (%) substitution is performed when processing various submit-time expressions (Use, Check, Item condititons, Do parameters) and also on the RETURN parameter produced by dynamic element Post.

Typically it is possible to determine context prefix from the expression (see above). In this case submit-time substitutions without explicit context prefix are resolved relatively to current context.

If it is not possible to determine context prefix (Do postpost in the multiposting outside Item container, and RETURN in multiposting), only attributes, explicitely qualified with context would be resolved.

REPRESENTATION CONVERSION

Some attributes can be passed from form to Communiware handler in different representation.

Dates can be represented in the user-defined format. Any format, acceptable by strftime which don't use textual month names is allowed.

RICHTEXT attributes can be passed either in their internal (HTML-tagged) representation or in representation with simpilified markup.

Special hidden fields, indicating representation are generated in both these cases.

<:Input date:> generates two fields ATTRNAME.FMT (formatted date) and ATTRNAME.PKT (format picture).

<:EditField ATTRNAME_R:> generates field ATTRNAME which contains data in user-defined representation and hidden field ATTRNAME.REPR with values Text or Html.

Conversion of these pairs to attribute values in Communiware internal representation is handled transparently by Communiware::Context::Global object, so all your code (dynamic elements, procedurals and perl filters) would see only internal representation.

Main item content (TEXT attribute) is not considered usial RICHTEXT attribute in this case.

It can be fetched from either TEXT or UPLOAD form parameter, and its representation is determined automatically from content of this parameter. So, only complete HTML documents (starting with <HTML> or <!DOCTYPE> would be considered Html representation. UPLOAD field also supports RTF representation.

These conversions are not performed transparently by global context object, they are functions of Communiware::Datatype::HTML module, so they work only in posting forms.

If both TEXT and UPLOAD fields present in the form, uploaded file have precedence over content of text input field, which assumed to be filled by old value, when upload of file is always explicit user action.

DEFINITION OF SUBMIT-TIME CONTEXTS

Posting form can create edit or delete several items. We'll call a posting context set of form parameters, related to one item.

Posting form should provide a parameter named Posting, which lists names of all posting containers. Dynamic elements Post and Item produce approprate hidden inputs.

All parameters which do not have context prefix are considered global.

There is global parameter RETURN which is generated by Post from its third parameters. Global parameters are never used for submit-time substitution or filling out item attributes.

List of contexts in current from is placed into hidden field Posting for posting form and Process for special form.

Submit time context can be either Posting context, which perform database modification, or non-posting (i.e. generated by DE Form with type=special and listed in the Process field) context.

ACTIONS

There are parameters which typically correspond with submit buttons in the form and define actions which would be performed on submitted items. For non-posting contexts concept of action is irrelevant and submit buttons can have any names.

Actions are:

SAVE
Saves changes entered by user into item, either creating new one or updating existing.

DELETE
Deletes item

SKIP
Doesn't perform any actions at all. Proceed to normal return behavoir

BACK
Schedules redirect to URL, contained in the REFERER global field (i.e. page from which we came to page containing posting form) rather than to page specified in the RETURN parameter.

If posting is not single-posting and BACK action is not applicable to all containers in this posting, it is considered an error.

RENAME
Requires presense of NEW_ITEM_ID field and renames given item specified by ITEM_ID attribute of this context to new id.

FIXME: - it is not clear how special handlers, such as MailTo, Subscribe etc should behave in case of RENAME actions.

Action attributes may be either qualified by context, or be global. If there exist global action and context-specific action, context-specific takes precedence. Thus you can make multiposting where most containers would perform SAVE action, and some - DELETE.

If there exist parameters action_name.x and action_name.y they are considered as equivalent of parameter action_name with true value. It allows to use HTML <input type=image> tag for global actions.

SPECIALLY PROCESSED FIELDS

There are several dynamic elements which request special actions upon submit.

They all generate hidden fields with reserved names, which are processed by posting handler specially.

Form type=special always should contain one of such dynamic elements, because otherwise no operation would be performed.

Typically, all special fields are subject of submit-time substitution.

RETURN_ON_DELETE

If some container contains this field (which should evaluate to the full URL after submit-time substitution) and action of this container is DELETE, than URL, specified in this field overrides URL, specified in RETURN global field.

If two or more containers contain RETURN_ON_DELETE with different URL, behavoir is undefined.

Link Types and _FOR

Traditionaly, link types are not treated as attributes in Communiware context. But in postings, where there no way to specify some item property, link types look much like attributes of special type.

Values of these attributes can be comma-separated lists of item-ids, which would be linked to current item via this link type (specified by name of attribute). If there is more then one field with this name in container, they would be concatenated.

Link should have M:N or N:1 relation type to allow multiple items to be linked.

Modified item would act as passive in the link type if attribute name is equal to link type.

If posting context contain field named after some link type, only items, specified in this field would be linked with modified item after successful posting. Thus specifying empty value effectively removes all links of given type.

It is also possible to modify links where given item acts as active. Attribute of posting context should have name consisting of link type with suffix _FOR appended. I.e.

  AUTHOR_FOR=article1,article2,article3

means that this item (probably PERSON) is author for three specified items and nothing more.

PICn

Attributes PIC1, PIC2 ... PIC9 should be uploaded files which would be stored in illustration area of modified item. Additional attributes PICWIDTHn, PICHEIGHTn and PICFORMATn would exist in posting context if real picture is uploaded. See also PICNAMEn

PICNAMEn

If attribute with this name is sent from client to server along with corresponging PICn attribute, picture would be stored under name, specified in this attribute, rather than under its original name on clients machine (which is default). If asterisk is specified instead of file extension, extension would be replaced with original extension of uploaded file. I.e if PICNAME1=logo.* then picture uploaded as PIC1 would be stored as logo.gif if it has GIF format and logo.jpg if it has JPEG format.

If there exists logo.jpg and GIF file was uploaded with PICNAME logo.*, logo.gif would be saved and logo.jpg - deleted.

I.e. all existing files matching specified PICNAME would be deleted before new file is saved.

In the posting context PICNAMEn attribute is always defined if corresponding PICn is defined and set to the name under which picture would be stored on the server disk.

PIC_DEL

This attribute specifies list of already existing illustration filenames to delete from item. Each filename must be passed via form via separate input element, i.e. checkbox.

VIRTUAL

This is not really an item attrubute or link type, but looks quite simular. If posting is processed in the context of some site (i.e. attribute SERVER in global context is equal to ID of this site) and action is SAVE, current item would be assigned to role, which name is specified by VIRTUAL attribute (if ontology allows this item to play this role). Role should be one of values of the PAGETYPE field of SPECPAGE_TYPE handler.

This assignment is allowed in cross-site postings. See CROSS-SITE POSTINGS below.

One item can play multiple roles on same site, so this attribute can have list value. It is treated same way as link types, i.e. all values would be split by comma and concatenated together.

After successiful posting with VIRTUAL parameter present, item would play only roles specified with this parameter on the site, specified in global context. Roles of this item on other sites wouldn't be affected.

Use dynamic element

All attributes which should be calculated in submit time, i.e. specified by Use dynamic element should be listed in the parameter named Use. Each list element of it contains context prefix and attribute name.

Expressions are passed via form using parameters named

  context.NAME.EXPR

If there are several Use's with same name in the same container, attribute NAME in given context would be a list containing result of all Use expressions in unspecified order.

If there present both ready-to use (context.NAME) and calculatable (context.NAME.EXPR) values, ready-to use one is ignored.

Check dynamic element

There are three things to pass for each Check dynamic element:

action
``fail'' or ``warn''

message
Message which would be added to value of WARINING/ERROR attribute if Check expression evaluates to true.

expression
Logical expression

ATTRIBUTE=Value
If this parameter is passed, than given attribute would be placed into global context and retained after Posting handler completed.

Value of this attribute is not nesseccary available during posting handler execution

Do dynamic element

Do dynamic element produces following parameter:

context.Do.time

where time is prepost, preedit, posteditor postpost.

Value of this parameter is a list, which first element is name of module or function to execute and rest are paremeters to pass to the function.

If there are more then one fields with this name in the form, procedurals are executed in unspecified order.

MailTo dynamic element

context.MailSpec

Contains list of all mail specification in the current context (one specification per dynamic element MailTo).

Specification consists of template, filter, format and conditon, Format may be plain or html. Condition is Communiware logical expression, and therefore occupies more than one list element.

If condition is not specified, mail will be send unconditionally.

If condition is specified, mail is sent only if condition is evaluated to true.

Subscribe dynamic element

List of subscriptions which should be modified, is stored in the context_prefix.Subscribe field. Each Subscribe dynamic element in the container generates additional hidden field with that name, so resulting value is unordered list.

Each element in this list is unique identifier which consist of context prefix and unique number within context, separated by period.

All other fields, related to given subscription are prefixed with this identifier.

Following fields are generated for each Subscribe dynamic element (submit time substitution is allowed on all fields)

prefix.SUBS.ITEM
Item to subscribe to

prefix.SUBS.ADDR
Filter specifiation for subscribers. Should return list of items of types AUTHOR and USER_GROUP which should be subscribed or unsubscribed.

prefix.SUBS.VARIANT
Item of type DIGEST_VARIANT to use for subscription

prefix.SUBS.PERIOD
Subscription period. May be any of values, specified in PERIOD field of SUBSCRIPTION_PERIOD table, or special value NEVER which means that subscription(s) which matches all other field should be removed.

prefix.SUBS.FORMAT
Format of letters to send. Should be one of values, specified in FORMAT_ID field of MAIL_FORMAT table.

prefix.SUBS.TMPL
Item of type DIGEST_TEMPLATE used to format mail.

Cookie specification

Cookie specifications may be set either using <:Input submit:> or using Cookie dynamic element.

context.Set-Cookie

Contents of this variable is the same as content of Set-Cookie HTTP header would become, short of submit time-substitution which would be performed on them.

Conditions in Item dynamic element

Are passed same way as Use expresision in the fields named

  context._cond

where b<_cond> is literal.

AUTHORIZATION

Posting handler allows several level of authorization, which are specified in the global __form_auth field.

free
Posting is processed regardless of combinations of authentication cookies. Special context 'user' is temporarily set to anonymous.

any
If no authentication cookies present, posting is processed as for anonymous user.

If there is weak auth, but no strong auth, redirect to login form is performed.

If there is strong auth, posting is processied with identity of the current user

registered
Posting is processed only if strong auth is present. If no auth cookie or only weak auth cookie is present, redirect to login form is performed.

any other value, including empty string or absense of field
Posting is processed only if strong auth is present, and current user has WRITES right for current item.

If strong auth present, but user do not have enough rights, 403 error code is returned.

It is possible to avoid redirect to login form by including password field with name PASSWORD in the form.

If correct password for user, specified by weak authentication cookie would be provided, strong authentication would be set before other processing.

ORDER OF PROCESSING

Following order of operations is used to process forms

  1. Authentication checking. If check fails, then either redirect to login form is performed or 403 (FORBIDDEN) HTTP error returned

  2. Building list of contexts to process. On this step _cond fields of each context is evaluated and list of contexts which have no _cond or _cond evaluated to true is build. Contextes with _cond evaluated as false are totally excluded from all subsequent actions.

    Order of contexts in this list is unspecified.

  3. Check expressions are evaluated and either WARINING attribute of global context is filled, or posting is aborted and ERROR is filled.

  4. Procedurals of prepost time are executed.

  5. Transaction is started. All following steps up to step 12 are then done for each context sequentually inside the transaction.

    If error happens on some stage before commit, all actions done within transaction are rolled back

  6. Procedural of preedit time is executed.

  7. If action not DELETE, then action is performed, i.e. all item attributes are calculated and database alteration is performed. Deletion of items is delayed, because some of subsequent stages i.e. mailing require item to exist.

  8. MailSpec is evaluated and mail messages to send are prepared.

  9. Subscriptions are altered.

  10. Set-Cookie is evaluated and cookies are stored in global context

  11. Deletion is performed if action is DELETE

  12. Procedurals of postedit are executed

  13. Transaction is commited, if there is something to commit, and any prepared mail is sent.

    If there was any errors, entire transaction rolled back and mail is not sent.

  14. Procedurals of postpost time are executed

  15. Redirect URL is computed, if posting was successfull, and cookies are set into HTTP responce.

    If posting is not successfull (ERROR attribute set and transaction is rolled back), no redirect is made and form is redisplayed.

CROSS-SITE POSTINGS

Typically, item can only be edited in the context of its own site. I.e. site as can be deduced from form URL as well as SERVER attribute of the global context should be equal to the SERVER attribute of edited item.

There are following exceptions from this rule:

Moving item from site to site

If SERVER attribute of item in the database is equal to SERVER in the global context and in the posting context there is attribute SERVER with another valid value, posting would succeed if:

  • Current user has WRITE right on given item

  • Current user has WRITE right on the target site (item of type SERVER itself)

  • No links of the modified item would be illegal on new site.

Assigning virtual page

If SERVER attribute of stored item is not equal to SERVER in global context, than posting would succeed if no item attributes is modified, but VIRTUAL pseudo-link is set. Current user should have DEVELOPER right on the current (i.e. global context) site, and item should be exportable from originating site and trust relationship (USE_TEMPLATES link) exists between these two sites.

16 октябрь 2007 13:45