## 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 recieve the revision_id whose content blob was written to the filesystem.
`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` * | 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:
  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 neccessary 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 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 simlar 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