Posting.pm

NAME

Communiware::Posting - processes results of posting form in the template

VERSION

SYNOPSIS

  hidden_field($name,$value)
  posting_context ($item,[$name], attrlist)
  destroy_context($cgi)

DESCRIPTION

This module provides procedures to handle form submission, used as submit handlers in Communiware::DE::Post

It also provides functions hidden_field, posting_context and destroy_context to be used when generating forms.

INTERNAL FUNCTIONS

action

        $action = action($ctx);
  
Checks which action is applicable to specified posting context.

Checks if there are specific actions for this posting ID and if none found, checks for global actions.

Returns action if there is specific action for container, or if there is no specific action, and there is global action.

Action is one of keys of global hash %Communiware::Posting::Actions

Returns undef if cannott find out an action.

Raises an exception if more than one action are specified.

do_create

        do_create($ctx);

Performs creation of new item.

do_update

Syntax:

do_update $prefix,$cgi

Performs modification of existing item

prepare_text

        $error_message = prepare_text($context, \%attrs);

Performs preprocessing of Item text using pluggable datatypes. $context is the context of edited item (required to correctly rewrite links to pictures. %attrs is reference to hash of attributes, prepared by the parse_attrs manpage which is modified by this procedure by adding information of hyperlinks and used templates and filters.

parse_attrs

        parse_attrs($ctx, \%attrs);

Parses CGI variables, which correspond to given posting id and fills hash of attributes (passed by reference in $attrs).

If necessary, extracts info of old attributes values from database.

Values of links are placed as list references.

Two copies of password (produced by <:EditField PASSWD:> are compared and error is thrown if they do not match.

prepare_link_ordnum_params

        $item_id = prepare_link_ordnum_params($context, $specification, $linktype, \%attrs);

Receives dump-style specification of linktype item_id(ordnum), where ordnum may be empty, linktype name hash of item's attrs.

If ordnum is found, records about it are placed into $attrs. Virtual pages are expanded if any.

Returns expanded item_id.

get_link_params

        get_link_params($ctx, $link_name, $item_id);

Finds parameters for links in current posting context.

links_for

        links_for($ctx, \%attrs);

Sets links where current item is ACTIVE, specified by ${LINKTYPE}_FOR fields. Need %attrs from parse_attrs in order to check if links are allowed for this type of item. Modifies database directly. (should be separated into two procs, one of them in Communiware::DB?)

check_request_type_upload

        check_request_type_upload($ctx);

Checks whether request's content-type is valid for upload. Throws an exception if not.

do_pictures_upload

        $error_message = do_pictures_upload($ctx);

Process pictures specified by PIC.

process_virtual_pages

        process_virtual_pages($ctx);
   
If there exists attribute VIRTUAL in the submit context, tries
to do set virtual page named by value of this attribute on the CURRENT_SERVER
to current ITEM_ID. It is considered as item change, so it is not done when
processing special form.

If it is impossible, throws an exception.

FUNCTIONS TO PROCESS FORMS, OTHER THAN ITEM POSTINGS

subscribe

        subscribe($ctx);

Processes all the subscription requests for given submit-time context;

delay_links

        delay_links($item_id, %attrs)

When multiple posting creates interlinked items, posting may fail for some strange reason if some of items are not created yet.

So, we store IDs of not-yet created items in the %Communiware::Context::Posting::DelayedItems

and delay links to them storing info into $Communiware::Posting::DelayedLinks

delay_links scans passed hash for attributes which are links, and if they lead to not-yet created items, removes them and stores into %Communiware::Posting::delayed_links

create_delayed_links

        create_delayed_links($global_context);

Processes all links stored in %DelayedLinks.

PARAMETERS

This section gives brief overview of parameters which can occur in single-item posts or inside each Item container in multiitem post.

  1. Return to the calling page (according to REFERER)

  2. New/updated item would be displayed

  3. URL is directly specified in the RETURN parameter.

Upon unsuccessful action (error during transaction) control is always returned to the REFERRER page and value of ERROR attribute would be set to corresponding error message.

PARAMETERS

This script requires several parameters to be passed:

REFERRER
url of calling page (in order to return control to.

RETURN
May be one of 'item' ('new' is obsolete), 'back' and directly specified URL (starting with http:// or https://). Additionaly, value ``pic'' is allowed, meaning - redirect to pictures script if and only if preprocessed item text contain any references to pictures and to REFERER otherwise.

pic may be followed by explicit URL, separated by comma.

ITEM_ID
If set, script is going to modify existing item. If not set, new item would be created.

TYPE_ID
If new item is going to be created, TYPE_ID parameter should be specified.

SAVE
This parameter should be set to non-zero if action is to save changes Corresponding input element may be image. I.E. existence SAVE.x and SAVE.y with numeric values considered to be equivalent of non-empty SAVE.

DELETE
If specified along with ITEM_ID and without SAVE, it is request to delete specified item. Corresponding input element may be image;

AUTH
If action is to edit or delete already existing item, only moderators of current server are allowed to perform this action unless this parameter is specified. If specified, this should be Communiware filter which is executed in the context of item being altered, and should return name of current user among others.

If AUTH=anon and no ITEM_ID is specified then this is posting script, allowed for anonymous users.

NO_LINT
If this attribute is set to non-zero, syntax check is not performed on items with HTML content (i.e. anything but template).

UPLOAD
This, if exist, should be file upload field

TEXT
This, if exist, should be text area field.

SERVER
Specifies current virtual server used to check AUTH constraint and as server value for newly created item.

PARENT_ID
Specifies ID for parent item (typically, item_id of refering page) which can be used in auth check for scripts which create item.

INHERIT
Set to list of link types. For each link in the given list script would attempt to inherit these links from parent.

Inheriting THREAD is treated specially. THREAD would be inherited if and only if TITLE is equal to PARENT. Otherwise item would start its own thread.

PICn PICNAMEm (WARNING!!! Obsolete syntax, see UPLOAD_PIC_id)
where n is digit from 1 to 9. Field PICn must be a file upload field allows to upload files with following list of extensions: png,gif,jpg, css,js. These files would be uploaded to Communiware as pictures for current item.

If there exist corresponding PICNAMEn field, then file would be renamed to this name during upload. If PICNAMEn have an extension ``*'' then extension of uploaded file would be substituted.

UPLOAD_PIC_id UPLOAD_PIC_id_NAME
where 'id' is alphanumeric-word. Field UPLOAD_PIC_id must be a file upload field allows to upload files with following list of extensions: png,gif,jpg, css,js. These files would be uploaded to Communiware as pictures for current item.

If there exist corresponding UPLOAD_PIC_id_NAME field, then file would be renamed to this name during upload. If UPLOAD_PIC_id_NAME have an extension ``*'' then extension of uploaded file would be substituted.

PIC_DEL
Value of this field should be name of existing picture. This picture would be deleted. There could be multiplie fields with this name (i.e. checkbox group) do delete several pictures at once.

POSTPROCESS
Should contain name of perl module which would be called (more precisely, procedures create update from it) just after successiful creation/updating of item.

Module name is relative to Communiware::Postprocess.

Procedures would recieve new item id as first argument and list of name/value pairs same as was passed to create_item/update_item.

WARNING!!! POSPROCESS keyword is obsolete and not supported! Please use procedurals instead.

Besides these, any field with name equal to item attributes and linktypes are recognized as values of attributes to change and list of items linked upwardly with specified link types. For links M:N you may specify either comma separated list of item_ids as value of string attribute or multiple attributes with same name each of them bearing one item_id each.

 ${LINKTYPE}_FOR - links where given item is active. It can be
  1. Comma-separated list of item_id

  2. Multiple fields with same name, each of them with one item_id

  3. Any of above, but with item_id(ordnum) syntax instead of plain item_id.

POSTPROCESSOR API

Postprocessors are perl modules which are invoked after successful posting of item and perform any additional actions such as generating thumbnails of images or updating keyword index.

Postprocessors are implemented as perl modules installed under Communiware::Postprocess namespace (which prevents Communiware from running perl code not approved by site administrator). They should implement two functions: create and update, which recieve following arguments:

 create(item_id,attrs,parameters...)
 update(item_id,attrs,parameters...)

where item_id is item_id of created/updated item, attrs is hash of arguments, passed to create_item/update_item (see Communiware::DB), and parameters are parameters specified in the form.

WORD OF WARNING: Never, never, never use DBI commit and rollback methods within postprocessor. Use procedures start_transaction and end_transaction, provided by Communiware::DB module.

Reason is that postprocessor may be called inside more complex transaction such as multi-item posting, and should be rolled back properly if something fails later.

process_Check_DE

        process_Check_DE(@contexts);

Processes Check DEs in given posting contexts.

do_procedurals

        do_procedurals($stage, @context_list);

Finds all procedural fragment for given stage in given list of form contexts and executes them.

do_procedural

        do_procedural($context,$module,@params)

Invokes given module as procedural fragment.

expand_return_spec

        expand_return_spec($global_ctx);

Performs substitution in RETURN parameter. Does so in no context if there is more than one context, or in only context.

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