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.

Also see:

namespace
item

Method Summary

Listing of public methods:
publish::get_html_body
publish::get_mime_handler
publish::get_page_root
publish::get_publish_roots
publish::get_template_root
publish::handle_binary_file
publish::item_include_tag
publish::mkdirs
publish::proc_exists
publish::publish_revision
publish::schedule_status_sweep
publish::set_publish_status
publish::unpublish_item
publish::unschedule_status_sweep
publish::write_content

Method Detail

* indicates required

Public Methods:
publish::get_html_body
Strip the {<body>} tags from the HTML, leaving just the body itself. Useful for including templates in each other.
Parameters:
html * The html to be processed
Returns:
Everything between the <body> and the </body> tags if they exist; the unchanged HTML if they do not

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 { }
Parameters:
mime_type * The full mime type, such as { text/html} or { image/jpg}
Returns:
The name of the proc which should be used to handle the mime-type, or an empty string on failure.
See Also:
proc - publish::handle_item

publish::get_page_root
Get the page root. All items will be published to the filesystem with their URLs relative to this root. The page root is controlled by the PageRoot parameter in CMS. A relative path is relative to {[ns_info} pageroot\] The default is {[ns_info} pageroot\]
Returns:
The page root
See Also:
proc - publish::get_publish_roots
publish::get_template_root

publish::get_publish_roots
Get a list of all page roots to which files may be published. The publish roots are controlled by the PublishRoots parameter in CMS, which should be a space-separated list of all the roots. Relative paths are relative to publish::get_page_root. The default is {[list} {[publish::get_page_root]]}
Returns:
A list of all the publish roots
See Also:
proc - publish::get_page_root
publish::get_template_root

publish::get_template_root
Get the template root. All templates are assumed to exist in the filesystem with their URLs relative to this root. The page root is controlled by the TemplateRoot parameter in CMS. The default is /web/yourserver/templates
Returns:
The template root
See Also:
proc - content::get_template_root,

publish::handle_binary_file
Helper procedure for writing handlers for binary files. It will write the blob of the item to the filesystem, but only if -embed is specified. Then, it will attempt to merge the image with its template.
This proc accepts exactly the same options a typical handler.
Parameters:
item_id * The id of the item to handle
revision_id_ref * required The name of the variable in the calling frame that will receive the revision_id whose content blob was written to the filesystem.
url_ref * The name of the variable in the calling frame that will receive the relative URL of the file in the file system which contains the content blob
error_ref * The name of the variable in the calling frame that will receive an error message. If no error has occurred, this variable will be set to the empty string { }
Returns:
The HTML resulting from merging the item with its template, or " " if no template exists or the -no_merge flag was specified
Options:
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 default The live revision for the item; The revision whose content is to be used
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:
proc - publish::handle::image

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 ...
Parameters:
item_id * The item id
extra_args * {} A list of extra parameters to be passed to the include tag, in form {name value name value ...}
Returns:
The HTML for the include tag
See Also:
proc - item::item_url
publish::html_args

publish::mkdirs
Create all the directories necessary to save the specified file
Parameters:
path * The path to the file that is about to be saved

publish::proc_exists
Determine if a procedure exists in the given namespace
Parameters:
namespace_name * The fully qualified namespace name, such as { template::util}
proc_name * The proc name, such as { is_nil}
Returns:
1 if the proc exists in the given namespace, 0 otherwise

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.
Parameters:
revision_id * The revision id
Options:
root_path default All paths in the PublishPaths parameter; Write the content to this path only.
See Also:
proc - item::get_extended_url
publish::get_publish_paths
publish::handle_item

publish::schedule_status_sweep
Schedule a proc to keep track of the publish status. Resets the publish status to { expired} if the expiration date has passed. Publishes the item and sets the publish status to { live} if the current status is { ready} and the scheduled publication time has passed.
Parameters:
interval 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:
proc - publish::set_publish_status
publish::track_publish_status
publish::unschedule_status_sweep

publish::set_publish_status
Set the publish status of the item. If the status is live, publish the live revision of the item to the filesystem. Otherwise, unpublish the item from the filesystem.
Parameters:
db * The database handle
item_id * The item id
new_status * The new publish status. Must be { production} , { expired} , { ready} or { live}
revision_id default The live revision; The revision id to be used when publishing the item to the filesystem.
See Also:
proc - publish::publish_revision
publish::unpublish_item

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

publish::unschedule_status_sweep
Unschedule the proc which keeps track of the publish status.
See Also:
proc - publish::schedule_status_sweep

publish::write_content
Write the content (blob) of a revision into a binary file in the filesystem. The file will be published at the relative URL under each publish root listed under the PublishRoots parameter in the server's INI file (the value returnded by publish::get_page_root is used as the default). The file extension will be based on the revision's mime-type.
For example, an revision whose mime-type is { image/jpeg} for an item at { Sitemap/foo/bar} may be written as /web/your_server_name/www/foo/bar.jpg
Parameters:
revision_id * The id of the revision to write
Returns:
The relative URL of the file that was written, or an empty string on failure
Options:
item_id default The item_id of the revision; Specifies the item to which this revision belongs (mereley for optimization purposes)
text If specified, indicates that the content of the revision is readable text (clob), not a binary file
root_path default All paths in the PublishPaths parameter; Write the content to this path only.
See Also:
proc - content::get_content_value
publish::get_publish_roots

Private Methods:
publish::delete_multiple_files
Delete the specified URL from the filesystem, for all revisions
Parameters:
url * Relative URL of the file to write
See Also:
proc - publish::get_publish_roots
publish::write_multiple_blobs
publish::write_multiple_files

publish::foreach_publish_path
Execute some Tcl code for each root path in the PublishRoots parameter
Parameters:
url * Relative URL to append to the roots
code * Execute this code
root_path default The empty string; Use this root path instead of the paths specified in the INI file
See Also:
proc - publish::get_publish_roots

publish::get_main_item_id
Get the main item id from the top of the stack
Returns:
the main item id
See Also:
proc - publish::get_main_revision_id
publish::pop_id
publish::push_id

publish::get_main_revision_id
Get the main item revision from the top of the stack
Returns:
the main item id
See Also:
proc - publish::get_main_item_id
publish::pop_id
publish::push_id

publish::handle_item
Render an item either by looking it up in the temporary cache, or by using the appropriate mime handler. Once the item is rendered, it is stored in the temporary cache under a key which combines the item_id, any extra HTML parameters, and a flag which specifies whether the item was merged with its template.
This proc takes the same arguments as the individual mime handlers.
Parameters:
item_id * The id of the item to be rendered
context * The context for the item (default public)
Returns:
The rendered HTML for the item, or an empty string on failure
Options:
revision_id default The live revision; The revision which is to be used when rendering the item
no_merge Indicates that the item should NOT be merged with its template. This option is used to avoid infinite recursion.
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 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 Extra HTML parameters to be passed to the item handler, in format {name value name value ...}
See Also:
proc - publish::handle::image
publish::handle::text
publish::handle_binary_file

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

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

publish::pop_id
Pop the item_id and the revision_id off the top of the stack. Clear the temporary item cache if the stack becomes empty.
Returns:
The popped item id, or the empty string if the string is already empty
See Also:
proc - publish::get_main_item_id
publish::get_main_revision_id
publish::push_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.
Parameters:
relation_type * Either child or relation
params * The ns_set id for extra HTML parameters
See Also:
proc - publish::render_subitem

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

publish::render_subitem
Render a child/related item and return the resulting HTML, stripping off the headers.
Parameters:
main_item_id * The id of the parent item
relation_type * Either child or relation. Determines which tables are searched for subitems.
relation_tag * The relation tag to look for
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 * 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 * Any additional HTML arguments to be used when rendering the item, in form {name value name value ...}
is_merge 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 default public;
Returns:
The rendered HTML for the child item
See Also:
proc - publish::handle_item
publish::merge_with_template

publish::set_to_pairs
Convert an ns_set into a list of name-value pairs, in form {name value name value ...}
Parameters:
params * The ns_set id
exclusion_list * {} A list of keys to be ignored
Returns:
A list of name-value pairs representing the data in the ns_set

publish::track_publish_status
Scheduled proc which keeps the publish status updated
See Also:
proc - publish::schedule_status_sweep

publish::write_multiple_blobs
Write the content of some revision to multiple publishing roots.
Parameters:
db * A valid database handle
url * Relative URL of the file to write
revision_id * Write the blob for this revision
See Also:
proc - publish::get_publish_roots
publish::write_multiple_files

publish::write_multiple_files
Write a relative URL to the multiple publishing roots.
Parameters:
url * Relative URL of the file to write
text * A string of text to be written to the URL
See Also:
proc - publish::get_publish_roots
publish::write_multiple_blobs
template::util::write_file

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:
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.
Parameters:
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>}
Parameters:
params * The ns_set id for extra HTML parameters

* indicates required