Index: openacs-4/packages/acs-templating/www/doc/TclDocs/publish.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/publish.html,v diff -u -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/publish.html 27 Oct 2014 16:40:17 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/publish.html 22 Jun 2016 07:48:44 -0000 1.2.2.1 @@ -7,7 +7,7 @@

Namespace publish

-  by Stanislav Freidin The procs in this namespace are useful for publishing items, including items inside other items, and writing items to the filesystem.

Specifically, the content, child and relation tags are defined here. +  by Stanislav Freidin The procs in this namespace are useful for publishing items, including items inside other items, and writing items to the filesystem.

Specifically, the content, child and relation tags are defined here.

@@ -62,13 +62,13 @@

Method Detail

-

+

* indicates required

-Public Methods:
-
+Public Methods:
+ @@ -79,19 +79,19 @@
- Parameters: + Parameters:
publish::get_html_body
- -
html + html * + The html to be processed
-
Returns: +
Returns:
Everything between the <body> and the </body> tags if they exist; the unchanged HTML if they do not @@ -101,34 +101,34 @@

-
+
publish::get_mime_handler
-Return the name of a proc that should be used to render items with the given mime-type. The mime type handlers should all follow the naming convention
proc publish::handle::mime_prefix::mime_suffix
If the specific mime handler could not be found, get_mime_handler looks for a generic procedure with the name
proc publish::handle::mime_prefix
If the generic mime handler does not exist either, get_mime_handler returns { } +Return the name of a proc that should be used to render items with the given mime-type. The mime type handlers should all follow the naming convention
proc publish::handle::mime_prefix::mime_suffix
If the specific mime handler could not be found, get_mime_handler looks for a generic procedure with the name
proc publish::handle::mime_prefix
If the generic mime handler does not exist either, get_mime_handler returns { }
- Parameters: + Parameters: - -
mime_type + mime_type * + The full mime type, such as { text/html} or { image/jpg}
-
Returns: +
Returns:
The name of the proc which should be used to handle the mime-type, or an empty string on failure. -
See Also: +
See Also:
proc - publish::handle_item
@@ -137,7 +137,7 @@

-
+ @@ -148,11 +148,11 @@
-
Returns: +
Returns:
The page root -
See Also: +
See Also:
proc - publish::get_publish_roots
publish::get_template_root
@@ -161,7 +161,7 @@
publish::get_page_root

-
+ @@ -172,11 +172,11 @@
-
Returns: +
Returns:
A list of all the publish roots -
See Also: +
See Also:
proc - publish::get_page_root
publish::get_template_root
@@ -185,7 +185,7 @@
publish::get_publish_roots

-
+ @@ -196,11 +196,11 @@
-
Returns: +
Returns:
The template root -
See Also: +
See Also:
proc - content::get_template_root,
@@ -209,7 +209,7 @@
publish::get_template_root

-
+ @@ -220,66 +220,66 @@
- Parameters: + Parameters:
publish::handle_binary_file
- - - - + required The name of the variable in the calling frame that will recieve the revision_id whose content blob was written to the filesystem. - - - -
item_id + item_id * + The id of the item to handle
revision_id_ref + revision_id_ref * + - required The name of the variable in the calling frame that will recieve the revision_id whose content blob was written to the filesystem.
url_ref + url_ref * + The name of the variable in the calling frame that will recieve the relative URL of the file in the file system which contains the content blob
error_ref + error_ref * + The name of the variable in the calling frame that will recieve an error message. If no error has ocurred, this variable will be set to the empty string { }
-
Returns: +
Returns:
- The HTML resulting from merging the item with its template, or " " if no template exists or the -no_merge flag was specified + The HTML resulting from merging the item with its template, or " " if no template exists or the -no_merge flag was specified -
Options: +
Options: - - + + Signifies that the content should be embedded directly in the parent item. -embed is required for this proc, since it makes no sense to handle the binary file in any other way. - - + - - +
embed +
embed - Signifies that the content should be embedded directly in the parent item. -embed is required for this proc, since it makes no sense to handle the binary file in any other way.
revision_id +
revision_id - default The live revision for the item; + default The live revision for the item; The revision whose content is to be used
no_merge +
no_merge If present, do NOT merge with the template, in order to prevent infinite recursion in the {<content>} tag. In this case, the proc will return the empty string { }
-
See Also: +
See Also:
proc - publish::handle::image
@@ -288,41 +288,41 @@

-
+
publish::item_include_tag
-Create an include tag to include an item, in the form
include src=/foo/bar/baz item_id=item_id param=value param=value ...
+Create an include tag to include an item, in the form
include src=/foo/bar/baz item_id=item_id param=value param=value ...
- Parameters: + Parameters: - - - - + {} A list of extra parameters to be passed to the include tag, in form {name value name value ...}
item_id + item_id * + The item id
extra_args + extra_args * + - {} A list of extra parameters to be passed to the include tag, in form {name value name value ...}
-
Returns: +
Returns:
The HTML for the include tag -
See Also: +
See Also:
proc - item::item_url
publish::html_args
@@ -331,7 +331,7 @@

-
+ @@ -342,13 +342,13 @@
- Parameters: + Parameters:
publish::mkdirs
- - @@ -360,7 +360,7 @@
path + path * + The path to the file that is about to be saved

-
+ @@ -371,26 +371,26 @@
- Parameters: + Parameters:
publish::proc_exists
- - - -
namespace_name + namespace_name * + The fully qualified namespace name, such as { template::util}
proc_name + proc_name * + The proc name, such as { is_nil}
-
Returns: +
Returns:
1 if the proc exists in the given namespace, 0 otherwise @@ -400,42 +400,42 @@

-
+
publish::publish_revision
-Render a revision for an item and write it to the filesystem. The revision is always rendered with the -embed option turned on. +Render a revision for an item and write it to the filesystem. The revision is always rendered with the -embed option turned on.
- Parameters: + Parameters: - -
revision_id + revision_id * + The revision id
-
Options: +
Options: - - +
root_path +
root_path - default All paths in the PublishPaths parameter; + default All paths in the PublishPaths parameter; Write the content to this path only.
-
See Also: +
See Also:
proc - item::get_extended_url
publish::get_publish_paths
publish::handle_item
@@ -444,7 +444,7 @@

-
+ @@ -455,19 +455,19 @@
- Parameters: + Parameters:
publish::schedule_status_sweep
-
interval + interval - default 3600; + default 3600; The interval, in seconds, between the sweeps of all items in the content repository. Lower values increase the precision of the publishing/expiration dates but decrease performance. If this parameter is not specified, the value of the StatusSweepInterval parameter in the server's INI file is used (if it exists).
-
See Also: +
See Also:
proc - publish::set_publish_status
publish::track_publish_status
publish::unschedule_status_sweep
@@ -476,7 +476,7 @@

-
+ @@ -487,40 +487,40 @@
- Parameters: + Parameters:
publish::set_publish_status
- - - - - - -
db + db * + The database handle
item_id + item_id * + The item id
new_status + new_status * + The new publish status. Must be { production} , { expired} , { ready} or { live}
revision_id + revision_id - default The live revision; + default The live revision; The revision id to be used when publishing the item to the filesystem.
-
See Also: +
See Also:
proc - publish::publish_revision
publish::unpublish_item
@@ -529,49 +529,49 @@

-
+
publish::unpublish_item
-Delete files which were created by publish_revision +Delete files which were created by publish_revision
- Parameters: + Parameters: - -
item_id + item_id * + The item id
-
Options: +
Options: - - + - - +
revision_id +
revision_id - default The live revision; + default The live revision; The revision which is to be used for determining the item filename
root_path +
root_path - default All paths in the PublishPaths parameter; + default All paths in the PublishPaths parameter; Write the content to this path only.
-
See Also: +
See Also:
proc - publish::publish_revision
@@ -580,7 +580,7 @@

-
+ @@ -591,7 +591,7 @@
-
See Also: +
See Also:
proc - publish::schedule_status_sweep
@@ -600,7 +600,7 @@
publish::unschedule_status_sweep

-
+ @@ -611,47 +611,47 @@
- Parameters: + Parameters:
publish::write_content
- -
revision_id + revision_id * + The id of the revision to write
-
Returns: +
Returns:
The relative URL of the file that was written, or an empty string on failure -
Options: +
Options: - - + - - + - - +
item_id +
item_id - default The item_id of the revision; + default The item_id of the revision; Specifies the item to which this revision belongs (mereley for optimization purposes)
text +
text If specified, indicates that the content of the revision is readable text (clob), not a binary file
root_path +
root_path - default All paths in the PublishPaths parameter; + default All paths in the PublishPaths parameter; Write the content to this path only.
-
See Also: +
See Also:
proc - content::get_content_value
publish::get_publish_roots
@@ -665,8 +665,8 @@

-Private Methods:
-
+Private Methods:
+ @@ -677,19 +677,19 @@
- Parameters: + Parameters:
publish::delete_multiple_files
- -
url + url * + Relative URL of the file to write
-
See Also: +
See Also:
proc - publish::get_publish_roots
publish::write_multiple_blobs
publish::write_multiple_files
@@ -698,7 +698,7 @@

-
+ @@ -709,33 +709,33 @@
- Parameters: + Parameters:
publish::foreach_publish_path
- - - - -
url + url * + Relative URL to append to the roots
code + code * + Execute this code
root_path + root_path - default The empty string; + default The empty string; Use this root path instead of the paths specified in the INI file
-
See Also: +
See Also:
proc - publish::get_publish_roots
@@ -744,7 +744,7 @@

-
+ @@ -755,11 +755,11 @@
-
Returns: +
Returns:
the main item id -
See Also: +
See Also:
proc - publish::get_main_revision_id
publish::pop_id
publish::push_id
@@ -768,7 +768,7 @@
publish::get_main_item_id

-
+ @@ -779,11 +779,11 @@
-
Returns: +
Returns:
the main item id -
See Also: +
See Also:
proc - publish::get_main_item_id
publish::pop_id
publish::push_id
@@ -792,7 +792,7 @@
publish::get_main_revision_id

-
+ @@ -803,62 +803,62 @@
- Parameters: + Parameters:
publish::handle_item
- - - -
item_id + item_id * + The id of the item to be rendered
context + context * + The context for the item (default public)
-
Returns: +
Returns:
The rendered HTML for the item, or an empty string on failure -
Options: +
Options: - - + - - + - - + - - + + Signifies that the content should be statically embedded directly in the HTML. If this option is not specified, the item may be dynamically referenced, f.ex. using the {<include>} tag - - +
revision_id +
revision_id - default The live revision; + default The live revision; The revision which is to be used when rendering the item
no_merge +
no_merge Indicates that the item should NOT be merged with its template. This option is used to avoid infinite recursion.
refresh +
refresh Re-render the item even if it exists in the cache. Use with caution - circular dependencies may cause infinite recursion if this option is specified
embed +
embed - Signifies that the content should be statically embedded directly in the HTML. If this option is not specified, the item may be dynamically referenced, f.ex. using the {<include>} tag
html +
html Extra HTML parameters to be passed to the item handler, in format {name value name value ...}
-
See Also: +
See Also:
proc - publish::handle::image
publish::handle::text
publish::handle_binary_file
@@ -867,34 +867,34 @@

-
+
publish::html_args
-Concatenate a list of name-value pairs as returned by set_to_pairs into a list of { name=value} pairs +Concatenate a list of name-value pairs as returned by set_to_pairs into a list of { name=value} pairs
- Parameters: + Parameters: - -
argv + argv * + The list of name-value pairs
-
Returns: +
Returns:
An HTML string in format " name=value name=value ..." -
See Also: +
See Also:
proc - publish::set_to_pairs
@@ -903,51 +903,51 @@

-
+
publish::merge_with_template
-Merge the item with its template and return the resulting HTML. This proc is simlar to content::init +Merge the item with its template and return the resulting HTML. This proc is simlar to content::init
- Parameters: + Parameters: - -
item_id + item_id * + The item id
-
Returns: +
Returns:
The rendered HTML, or the empty string on failure -
Options: +
Options: - - + - - +
revision_id +
revision_id - default The live revision; + default The live revision; The revision which is to be used when rendering the item
html +
html Extra HTML parameters to be passed to the ADP parser, in format {name value name value ...}
-
See Also: +
See Also:
proc - publish::handle_item
@@ -956,7 +956,7 @@

-
+ @@ -967,11 +967,11 @@
-
Returns: +
Returns:
The popped item id, or the empty string if the string is already empty -
See Also: +
See Also:
proc - publish::get_main_item_id
publish::get_main_revision_id
publish::push_id
@@ -980,37 +980,37 @@
publish::pop_id

-
+
publish::process_tag
-Process a child or relation tag. This is a helper proc for the tags, which acts as a wrapper for render_subitem. +Process a child or relation tag. This is a helper proc for the tags, which acts as a wrapper for render_subitem.
- Parameters: + Parameters: - - + Either child or relation - -
relation_type + relation_type * + - Either child or relation
params + params * + The ns_set id for extra HTML parameters
-
See Also: +
See Also:
proc - publish::render_subitem
@@ -1019,37 +1019,37 @@

-
+
publish::push_id
-Push an item id on top of stack. This proc is used to store state between child, relation and content tags. +Push an item id on top of stack. This proc is used to store state between child, relation and content tags.
- Parameters: + Parameters: - - -
item_id + item_id * + The id to be put on stack
revision_id + revision_id - default { }; + default { }; The id of the revision to use. If missing, live revision will most likely be used
-
See Also: +
See Also:
proc - publish::get_main_item_id
publish::get_main_revision_id
publish::pop_id
@@ -1058,7 +1058,7 @@

-
+ @@ -1069,72 +1069,72 @@
- Parameters: + Parameters:
publish::render_subitem
- - - - + Either child or relation. Determines which tables are searched for subitems. - - - - + The relative index of the subitem. The subitem with lowest order_n has index 1, the second lowest order_n has index 2, and so on. - - + If { t} , the child item may be embedded directly in the HTML. Otherwise, it may be dynamically included. The proc does not process this parameter directly, but passes it to handle_item - - - + If { t} , merge_with_template may be used to render the subitem. Otherwise, merge_with_template should not be used, in order to prevent infinite recursion. -
main_item_id + main_item_id * + The id of the parent item
relation_type + relation_type * + - Either child or relation. Determines which tables are searched for subitems.
relation_tag + relation_tag * + The relation tag to look for
index + index * + - The relative index of the subitem. The subitem with lowest order_n has index 1, the second lowest order_n has index 2, and so on.
is_embed + is_embed * + - If { t} , the child item may be embedded directly in the HTML. Otherwise, it may be dynamically included. The proc does not process this parameter directly, but passes it to handle_item
extra_args + extra_args * + Any additional HTML arguments to be used when rendering the item, in form {name value name value ...}
is_merge + is_merge - default t; + default t; - If { t} , merge_with_template may be used to render the subitem. Otherwise, merge_with_template should not be used, in order to prevent infinite recursion.
context + context - default public; + default public;
-
Returns: +
Returns:
The rendered HTML for the child item -
See Also: +
See Also:
proc - publish::handle_item
publish::merge_with_template
@@ -1143,7 +1143,7 @@

-
+ @@ -1154,26 +1154,26 @@
- Parameters: + Parameters:
publish::set_to_pairs
- - - -
params + params * + The ns_set id
exclusion_list + exclusion_list * + {} A list of keys to be ignored
-
Returns: +
Returns:
A list of name-value pairs representing the data in the ns_set @@ -1183,7 +1183,7 @@

-
+ @@ -1194,7 +1194,7 @@
-
See Also: +
See Also:
proc - publish::schedule_status_sweep
@@ -1203,7 +1203,7 @@
publish::track_publish_status

-
+ @@ -1214,33 +1214,33 @@
- Parameters: + Parameters:
publish::write_multiple_blobs
- - - - - -
db + db * + A valid database handle
url + url * + Relative URL of the file to write
revision_id + revision_id * + Write the blob for this revision
-
See Also: +
See Also:
proc - publish::get_publish_roots
publish::write_multiple_files
@@ -1249,7 +1249,7 @@

-
+ @@ -1260,26 +1260,26 @@
- Parameters: + Parameters:
publish::write_multiple_files
- - - -
url + url * + Relative URL of the file to write
text + text * + A string of text to be written to the URL
-
See Also: +
See Also:
proc - publish::get_publish_roots
publish::write_multiple_blobs
template::util::write_file
@@ -1288,24 +1288,24 @@

-
+
-Implements the child tag which renders a child item. See the Developer Guide for more information.
The child tag format is
{<child} tag=tag index=n embed {args>}
+Implements the child tag which renders a child item. See the Developer Guide for more information.
The child tag format is
{<child} tag=tag index=n embed {args>}
- Parameters: + Parameters: - - @@ -1317,24 +1317,24 @@
params + params * + The ns_set id for extra HTML parameters

-
+
-Implements the content tag which renders the content of the current item. See the Developer Guide for more information.
The content tag format is simply {<content>.} The embed and no_merge parameters are implicit to the tag. +Implements the content tag which renders the content of the current item. See the Developer Guide for more information.
The content tag format is simply {<content>.} The embed and no_merge parameters are implicit to the tag.
- Parameters: + Parameters: - - @@ -1346,24 +1346,24 @@
params + params * + The ns_set id for extra HTML parameters

-
+
-Implements the relation tag which renders a related item. See the Developer Guide for more information.
The relation tag format is
{<relation} tag=tag index=n embed {args>}
+Implements the relation tag which renders a related item. See the Developer Guide for more information.
The relation tag format is
{<relation} tag=tag index=n embed {args>}
- Parameters: + Parameters: - - @@ -1377,7 +1377,7 @@

-

+

* indicates required

params + params * + The ns_set id for extra HTML parameters