[docs] xmldocs - docelic modified 10 files
docs at icdevgroup.org
docs at icdevgroup.org
Wed Jul 27 13:19:13 EDT 2005
User: docelic
Date: 2005-07-27 17:19:13 GMT
Modified: refs/init_page synopsis
Modified: refs/post_page synopsis
Modified: refs/pre_page synopsis
Added: refs AdminSub AliasTable AutoEnd Autoload CatalogUser
Added: CodeRepository CookieName
Log:
Moving on; little fixes and new items
Revision Changes Path
1.1 xmldocs/refs/AdminSub
rev 1.1, prev_rev 1.0
Index: AdminSub
===================================================================
__NAME__ purpose
specify global subroutines that can be used only by catalogs listed under AllowGlobal
directive
__END__
__NAME__ missing
__END__
__NAME__ see also
AllowGlobal
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain' rep='repeat'><replaceable>subroutine_name</replaceable></arg>
</group>
__END__
__NAME__ description
Specify global subroutines that may only be used by catalogs which are listed under
the &conf-AllowGlobal; directive.
</para><para>
Otherwise, in a normal course of action, global subroutines can be used
by all catalogs.
__END__
__NAME__ example: Defining AdminSub
<programlisting>
AdminSub dangerous1 dangerous2
</programlisting>
__END__
1.1 xmldocs/refs/AliasTable
rev 1.1, prev_rev 1.0
Index: AliasTable
===================================================================
__NAME__ purpose
specify database that contains page aliases ("redirect" instructions)
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain'><replaceable>database_name</replaceable></arg>
</group>
__END__
__NAME__ description
The directive specifies Interchange &glos-database; that
contains page aliases (default database name is
<literal>alias</literal>).
</para><para>
This way, flypages can be aliased and redirected to different locations
without performing file lookup cycles.
</para><para>
Primary applications include content management and creation of
pseudo-paths.
__END__
__NAME__ notes
__END__
__NAME__ example: Creating AliasTable database
<programlisting>
<xi:include parse='text' href='../files/various/alias.txt'/>
</programlisting>
You might notice that the fields names and values in the tables
above are not properly aligned. This is an unfortunate nature of
<glossterm linkend="tab_delimited">TAB-delimited</glossterm> files.
</para><para>
In our example database, a flypage for the item SKU
<literal>4595</literal> redirects back to the index page.
</para><para>
To minimize the chance of confusion, you can download properly composed
<ulink url="files/various/alias.txt">alias.txt</ulink>.
__END__
__NAME__ example: Defining AliasTable
<programlisting>
Database alias alias.txt TAB
AliasTable alias
</programlisting>
</para><para>
With the above in &ccf;, a visit to the page <literal>4595.html</literal>
should redirect you to the index page.
__END__
TODO : describe cgi passing of control:
"Allows initialization of CGI inputs via base_control field."
TODO: produce working example
1.1 xmldocs/refs/AutoEnd
rev 1.1, prev_rev 1.0
Index: AutoEnd
===================================================================
__NAME__ purpose
specify actions to be executed automatically at the end of every page access
__END__
__NAME__ see also
AutoEnd,Autoload
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain' rep='repeat'><replaceable>subroutine_name_or_ITL_code</replaceable></arg>
</group>
__END__
__NAME__ description
Specify actions (in form of &PERL; subroutines or &glos-ITL; tags)
that are to be invoked automatically, on the end of every
page access. This step is performed after any page parsing occurs,
just before the whole transaction ends.
</para><para>
In other respects, it behaves the same as its closely related
directive &conf-Autoload;.
__END__
__NAME__ notes
__END__
__NAME__ example:
__END__
1.1 xmldocs/refs/Autoload
rev 1.1, prev_rev 1.0
Index: Autoload
===================================================================
__NAME__ purpose
specify actions to be executed automatically at the beginning of every page access
__END__
__NAME__ see also
AutoEnd
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain' rep='repeat'><replaceable>subroutine_name_or_ITL_code</replaceable></arg>
</group>
__END__
__NAME__ description
Specify actions (in form of &PERL; subroutines or &glos-ITL; tags)
that are to be invoked automatically, on every
page access. This step is performed before any page parsing occurs,
and before the action or page is even determined.
</para><para>
The directive can be set to the name of a subroutine (&conf-Sub; or
&conf-GlobalSub;), or to a string containing &glos-ITL; tags.
The return value from the code run is discarded.
__END__
__NAME__ notes
__END__
__NAME__ example: Simple Autoload example
Put the following in &gcf;:
<programlisting><![CDATA[
GlobalSub <<EOR
sub simple_gsub {
open OUT, "> /tmp/out";
print OUT scalar localtime, "\n";
close OUT;
}
EOR
]]></programlisting>
Put the following in &ccf;:
<programlisting>
Autoload simple_gsub
</programlisting>
Now, at each page visit, the file <filename>/tmp/out</filename> will
contain the access time. This example is pretty useless and does not
convey good programming practice (the file opening part), but it does
show a practical, stand-alone example.
__END__
__NAME__ example: Redirect page accesses
Let's say that a new page visit is "triggered" as a result of users
submitting a &glos-HTML; form. At that point, <mv>mv_nextpage</mv>
contains the name of the page to display next, of course.
</para><para>
The following would redirect accesses from
directory <filename class='directory'>public/</filename> to
directory <filename class='directory'>private/</filename>:
<programlisting><![CDATA[
Autoload [perl] $CGI->{mv_nextpage} =~ s:^public/:private/:; [/perl]
]]></programlisting>
__END__
__NAME__ example: Temporary change of configuration directives
As you might know, on each page access, all catalog
&glos-configuration; directives (global and catalog) are "re-instantiated",
and valid for the current page. This particularly convenient feature
allows us to change (modify, add or delete) configuration directives
as we see fit, without worrying about them being persistent, and consequently,
even without the need to re-set them back to original values.
</para><para>
The following example (put in &ccf;) displays a different flypage for
Opera web browsers:
<programlisting><![CDATA[
Autoload <<EOA
[perl]
if ($Session->{browser} =~ /opera/i) {
$Config->{Special}->{flypage} = 'opera_flypage';
}
[/perl]
EOA
]]></programlisting>
Please note that &conf-SpecialPage; is the corresponding directive in
the catalog &glos-configuration; (and not <literal>Special</literal> as
we see above). This is an exceptional case — the hash keys otherwise
have the same name as the catalog configuration directives themselves.
__END__
1.1 xmldocs/refs/CatalogUser
rev 1.1, prev_rev 1.0
Index: CatalogUser
===================================================================
__NAME__ purpose
specify catalog-specific usernames to use when accessing files with absolute pathnames
__END__
__NAME__ synopsis
<group choice='req' rep='repeat'>
<arg choice='plain'><replaceable>catalog_name username</replaceable></arg>
</group>
__END__
__NAME__ description
The directive specifies catalogs and the corresponding usernames
which will be used in accessing files with absolute pathnames.
Actually, the file access itself is still performed under the &IC;
server username, but the &conf-CatalogUser; values are used for
a "would-be" kind of check.
</para><para>
This directive is only honored when &conf-NoAbsolute; is enabled.
Then, the situation is as follows:
<itemizedlist>
<listitem><para>
&IC; allows the file to be read or written if the absolute pathname
points somewhere in the catalog directory (&glos-CATROOT;) or
&conf-TemplateDir;.
</para></listitem>
<listitem><para>
&IC; allows the file to be read if the appropriate catalog's
&conf-CatalogUser; is file owner, or belongs to a user group that
can read the file. (The same analogy is used for write access).
</para></listitem>
</itemizedlist>
__END__
__NAME__ notes
__END__
__NAME__ example: Defining CatalogUser
<programlisting>
CatalogUser foundation joe
CatalogUser reports jane
</programlisting>
__END__
1.1 xmldocs/refs/CodeRepository
rev 1.1, prev_rev 1.0
Index: CodeRepository
===================================================================
__NAME__ purpose
specify directory containing code that can be included in the running installation when needed
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain'><replaceable>directory_name</replaceable></arg>
</group>
__END__
__NAME__ description
There is a huge base of &IC; code included in the default installation.
Much of it is not needed in even the '&std-catalog;' catalog with full
user interface (UI). This causes a larger memory profile than necessary.
</para><para>
Furthermore, it is difficult to determine from the &IC; pages what code is
needed (especially when an &glos-ITL; tag can call <code>$Tag->{}</code>
can call a filter can call some sort of action —
you see the point).
</para><para>
A feature was needed to allow building catalogs with a more optimal
set of code than just "everything". And as we'll see in a second,
&conf-CodeRepository; does just that.
</para><para>
&conf-CodeRepository; depends on a related directive, &conf-AccumulateCode;.
If &conf-AccumulateCode; is disabled, operation is traditional and everything
gets loaded. (There have
been some code initialization changes and routine calling changes,
but the data structures are identical and no difference in operation
should be seen).
</para><para>
It's when you enable &conf-AccumulateCode; that things get interesting.
&IC; starts looking into &conf-CodeRepository; for pieces it is
missing (&glos-ITL; tags, &glos-ActionMap;s, &glos-filter;s, widgets, etc.)
and compiles these as needed, in runtime!
The code is sent to the master process for compilation and
incorporation, so that the next iteration of a page (after
&conf-HouseKeeping; seconds expire) will find the code already compiled
and ready to go.
</para><para>
It also copies the code file to the <literal>code/</literal>
(<varname>$Global::TagDir</varname> actually) directory, in the
<filename class='directory'>Accumulated</filename> subdirectory tree.
When you restart &IC; the next time, these code blocks will be found,
read normally and need not be recompiled on the fly again.
</para><para>
Over time, as you access pages and routines, a full set of tags
will be developed and you can then disable &conf-AccumulateCode;.
(Infact, &code-AccumulateCode; is recommended for development and should
really be turned off in production systems).
__END__
__NAME__ notes
There can be failures due to calling <code>$Tag->{...}</code> from within
embedded
&PERL; for the first time, particularly when it uses a "MapRoutine" or
calls another <code>$Tag->{...}</code> within. This is due to
<classname>Safe</classname>, and there is probably
not much to be done about it. The good news is that the error should
go away after &conf-HouseKeeping; seconds, when the tag gets compiled by the
master.
The &tag-area;, &tag-tmp;, &tag-tmpn;, and &tag-image; tags are known to
fail in this manner in the '&std-catalog;' catalog.
Tags that are frequently called
in this fashion should probably be placed in directory
<filename class='directory'>code/Vital/</filename> directory and not
be accumulated.
This "failure" could be avoided if the catalog is listed under the
&conf-AllowGlobal; directive, and it
might be possible to make a directive that turns on &conf-AllowGlobal; for
the catalog only when in &conf-AccumulateCode; mode.
</para><para>
Another nice feature is that you can easily add a tag simply
by adding its code to the &conf-CodeRepository; directory and having it
compiled.
It might also
be possible to remove code from the master and recompile it on next access
on-the-fly, but this has yet to be looked at.
</para>
<warning>
<para>
Nice features are often dangerous! Don't run this in
production — you have been warned!
</para><para>
&conf-OrderCheck; is not yet implemented, and a full audit has
not been done on all compiled code directives.
</para><para>
Not fully tested in &conf-PreFork; mode, and really not intended for
that mode.
</para><para>
Including multiple tags in a code definition file may have unpredictable
behavior. You should try to keep related Alias and tag things in
the same file.
</para><para>
This feature only applies to global code — catalog-based code
is not affected and behaves as usual.
</para>
</warning>
<para>
__END__
__NAME__ see also
AccumulateCode
__END__
__NAME__ author
&mheins;
__END__
__NAME__ example: Enabling CodeRepository
Put the following in &gcf;:
<programlisting>
AccumulateCode Yes
CodeRepository /usr/interchange/code.pool/
</programlisting>
To prepare the <filename class='directory'>code.pool/</filename>
directory, you can do something like this:
<programlisting>
$ mkdir /usr/interchange/code.pool/
$ mv /usr/interchange/code/* /usr/interchange/code.pool/
</programlisting>
__END__
1.1 xmldocs/refs/CookieName
rev 1.1, prev_rev 1.0
Index: CookieName
===================================================================
__NAME__ purpose
specify Interchange session cookie name
__END__
__NAME__ see also
CookieLogin,SessionExpire
__END__
__NAME__ synopsis
<arg choice='plain'><replaceable>cookie_name</replaceable></arg>
__END__
__NAME__ description
The directive sets the name of the &IC; session ID cookie.
The default value is <literal>MV_SESSION_ID</literal>.
__END__
__NAME__ notes
__END__
__NAME__ example: Redefining CookieName
<programlisting>
CookieName SESSIONID
</programlisting>
__END__
1.5 +1 -1 xmldocs/refs/init_page/synopsis
rev 1.5, prev_rev 1.4
Index: synopsis
===================================================================
RCS file: /var/cvs/xmldocs/refs/init_page/synopsis,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- synopsis 24 Sep 2004 21:01:01 -0000 1.4
+++ synopsis 27 Jul 2005 17:19:13 -0000 1.5
@@ -1 +1 @@
- <arg choice='req'><replaceable>subroutine name</replaceable></arg>
+ <arg choice='req'><replaceable>subroutine_name</replaceable></arg>
1.5 +1 -1 xmldocs/refs/post_page/synopsis
rev 1.5, prev_rev 1.4
Index: synopsis
===================================================================
RCS file: /var/cvs/xmldocs/refs/post_page/synopsis,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- synopsis 24 Sep 2004 21:01:02 -0000 1.4
+++ synopsis 27 Jul 2005 17:19:13 -0000 1.5
@@ -1 +1 @@
- <arg choice='req'><replaceable>subroutine name</replaceable></arg>
+ <arg choice='req'><replaceable>subroutine_name</replaceable></arg>
1.5 +1 -1 xmldocs/refs/pre_page/synopsis
rev 1.5, prev_rev 1.4
Index: synopsis
===================================================================
RCS file: /var/cvs/xmldocs/refs/pre_page/synopsis,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- synopsis 24 Sep 2004 21:01:02 -0000 1.4
+++ synopsis 27 Jul 2005 17:19:13 -0000 1.5
@@ -1 +1 @@
- <arg choice='req'><replaceable>subroutine name</replaceable></arg>
+ <arg choice='req'><replaceable>subroutine_name</replaceable></arg>
More information about the docs
mailing list