Scripts.pm

NAME

Communiware::Scripts - miscellaneous utilities for Communiware scripts

SYNOPSIS

   $cgi->header(text_html());
   start_html(TITLE=>...);
   ...
   end_html();

DESCRIPTION

This module contain procedures which are common for all scripts (or at least some of them)

GENERAL FUNCTIONS

script_start

 $cgi = script_start(%opts) or return;
 ($cgi, %ctxs) = script_start(%opts) or return;

The function is usually called at the very beginning of scripts. It performs following:

  • Creates new global context as well as new CGI object.

  • Determines current server as SERVER attribute, 'default' otherwise, and creates site context.

  • If current Communiware user is authorized then creates user context, anonymous user context otherwise.

  • If there is an ITEM_ID attribute in the global context then the document item context is created.

  • Performs access checking for the user. By default user must have SUPERUSER status or be a developer of the site.

In scalar context function returns created CGI object keeping query parameters. In list context it returns hache having following keys: cgi, global, site, user, item, site_id, user_id, site_id. site and other are contextes and site_id and other are item ids.

If access check fails then the function raises Communiware::Exception::HTTP or dies with other error message. script_fail function (see below) is intended for these errors processing. Thus typical script beginning is like

 use Communiware::Script;
 main();
 sub main {
   my $cgi = script_start();
   . . .
 }

Options change behaviour of script_start. How?

script_fail

 script_fail($cgi, $@) if $@;

Internal function is called from script_start, if any stages of contexts initializing fail.

text_html

Returns correct string for Content-Type: header field depending of support of recoding in underying Apache

VIRTUAL INCLUDE HANDLING

start_html

prints start of html or invokes standard script include, if virtual_server has one. Standard script include is item which should be TEMPLATE with TEMPLATE_TYPE='INCLUDE' and should be listed in SPECPAGES table for given virtual with pagetype 'script_top' or

Syntax

   start_html(args)

See CGI.pm documentation for description of possible args. Note, you should not pass cgi reference here. It is obtained from cummuniware context.

If virtual item 'script_top' is found, it is invoked and nothing else printed to the client's html. Otherwise standard HTML header is printed and arguments to procedure are passed to it.

end_html

invokes include listed in SPECPAGES as script_bottom for given server or prints HTML closing if no templates found

Syntax:

end_html();

CGI object is obtained from Communiware context

get_virtual_include

Converts name of virtual include like 'scripts_top' to name of actual template.

make_include

private procedure which recives template_id and invokes appropriate template for given server and includes it

Adds attribute SCRIPT to the current context so template can behave differently in script and page context.

Also sets global variable $Communiware::Scripts::is_in_script to true value. This variable can be checked from security critical code like Authentify dynamic element, becouse in difference of SCRIPT attribute it cannot be set by user in URL.

MAIL CC:

show_mailto

Print fragment of the form, which lists recipients to mail item to Syntax

  show_mailto (cgi_object,filter,noedit)

where filter is Communiware filter specification optionally followed by ``*''. Creates list of checkboxes, each corresponding by title of given item (which should be of type AUTHOR) and value of E-Mail of this author.

If ``*'' is specified, (like All_Items(AUTHOR)+) all checkboxes are initially checked.

If noedit have some true value, hidden fields are created instead of checkboxes. If noedit equal to 'hidden', addressee names are not printed.

INTERNATIONALIZED MESSAGES EDITING

show_message

Syntax:

  show_message ($cgi,$prefix,$msg_id,$long)

Displays fragment of HTML form for editing interntationalized message (such as attribute type name. Upon submitting a form message should be processed by the Communiware::Ontology::update_message manpage function.

$cgi
Reference to CGI object.

$prefix
Prefix of names for created fields. Should be unique for given form. Same prefix would be passed to update_message later.

$msg_id
Message ID to edit. Can be undef, in which case new message would be created.

$long
If false or undef, one-line text input field would be created for each language. If true, multiline textarea would be created.

display_message

Replaces show_message.

message_from_cgi

        ($msg_id,\%lang_msg) = message_from_cgi($cgi, $field_prefix, [$msg_id])
        Receives C<$cgi> object and prefix for C<$cgi> parameter used to extract message text. Deletes it from C<$cgi> afterwards.

clear_message

Cleares cgi variables associated with given message Syntax clear_message($cgi,$prefix)

TYPEEDIT & LINKEDIT UTILITIES

show_menu

syntax:

show_menu($cgi,$field,$entity)

Shows all values of given entity as links to the same script with parameter $field set to value of $field in the table $entity of the database. get_msg(msg_id) is used for menu text. If there is parameter $field in the $cgi object, its menu position wouldn't be a link and would be printed in boldface. Otherwisse, this parameter would be set to first found value Works at least for item types, link types and attributes.

loc_show_menu

syntax:

loc_show_menu($cgi,$field,$entity)

Shows all values of given entity as links to the same script with parameter $field set to value of $field in the table $entity of the database. get_msg(msg_id) is used for menu text. If there is parameter $field in the $cgi object, its menu position wouldn't be a link and would be printed in boldface. Otherwisse, this parameter would be set to first found value Works at least for item types, link types and attributes. Differs from show_menu adding possibility of creating metaobject

display_allowed

Syntax

   display_allowed ($cgi,$ref_script,@list)

Displays table of checkboxes to edit correspondence between link and item types. @list should contain all available values of link types if called for particular item type and vice versa refscript should be name of script to show link types or item types. and currentl set values should be stored in parameters ACTIVE and PASSIVE pf $cgi object

CACHE CONTROL

invalidate_cache

syntax

    invalidate_cache()

Records date of last change of metainformation (such as attributes, linktypes etc). Should be called immediately before commiting any changes to metadata from moderater interface. It would cause all apache copies to reread metadata upon next init_context.

ontology_menu

Syntax

  ontology_menu($cgi[,$current])

Displays links to ontology viewer scripts. Optional second parameter specifies current script, if it is called from one. It may be one of ``Types'', ``Links'', ``Filters'', ``Virtual pages'' and ``Attributes''.

If it is specified, then corresponding link would be disabled.

attribute_link

Syntax 


  attribute_link($cgi,attribute_name[,'Values']);

Displays link to attribute viewer script to view specified attribute. If third parameter is non-empty, would point to list of possible attribute values, instead of general description, and use value of this parameter as text of the link.

type_link

Syntax:

  type_link ($cgi,$type)

Displays link to type-viewer with appropriate page.

link_link

Syntax:

  link_link($cgi,$linktype)

Displays a link to linktype viewer to show specified linktype.

template_link

Syntax:

  template_link($cgi,$template)

Displays a link to specified template

item_link

Syntax

  item_link($cgi,$id,$text);

Displays link to the specified item with specified text.

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