Index: openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp 27 Oct 2014 16:40:15 -0000 1.2 @@ -0,0 +1,649 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

Namespace content

Procedures for generating and processing content +content creation and editing forms..

Method Summary

+Listing of public methods:
+content::add_attribute_element
content::add_attribute_elements
content::add_basic_revision
content::add_child_relation_element
content::add_content
content::add_content_element
content::add_revision
content::add_revision_form
content::copy_content
content::get_attribute_enum_values
content::get_latest_revision
content::get_object_id
content::new_item
content::new_item_form
content::validate_name
+

Method Detail

+* indicates required

Public Methods:
+ +
content::add_attribute_element
+
Add a form element (possibly a compound widget) to an +ATS form object. for entering or editing an attribute +value.
+Parameters: + + + + + + + + + +
+form_name* +The name of the ATS form object to which the +element should be added.
+content_type* +The content type keyword to which this attribute +belongs.
+attribute* +The name of the attribute, as represented in the +attribute_name column of the acs_attributes table.
+attribute_data* +Optional nested list of parameter data for the the +attribute (generated by get_attribute_params).
+
+
+ +
content::add_attribute_elements
+
Add form elements to an ATS form object for all +attributes of a content type.
+
+Parameters: + + + + + + + +
+form_name* +The name of the ATS form object to which objects +should be added.
+content_type* +The content type keyword for which attribute +widgets should be added.
+revision_id* +The revision from which default values should be +queried
+
Returns:
The list of attributes that were added.
+
+
+ +
content::add_basic_revision
+
Create a basic new revision using the content_revision +PL/SQL API.
+
+Parameters: + + + + + + + +
+item_id* +
+revision_id* +
+title* +
+
Options:
+ + + + + + + + + +
description
mime_type
text
tmpfile
+
+
+ +
content::add_child_relation_element
+
Add a select box listing all valid child relation tags. +The form must contain a parent_id element and a content_type +element. If the elements do not exist, or if there are no valid +relation tags, this proc does nothing.
+
+Parameters: + +
+form_name* +The name of the form
+
Options:
+ + + + + +
section +none If present, creates a new form section +for the element.
label{Child relation tag} The label for the +element
+
+
+ +
content::add_content
+
Update the BLOB column of a revision with content +submitted in a form
+Parameters: + +
+revision_id* +The object ID of the revision to be updated.
+
+
+ +
content::add_content_element
+
Adds a content input element to an ATS form +object.
+Parameters: + + + + + +
+form_name* +The name of the form to which the object should be +added.
+content_method* +One of no_content, text_entry or file_upload
+
+
+ +
content::add_revision
+
Create a new revision for an existing item based on a +valid form submission. Queries for attribute names and inserts a +row into the attribute input view for the appropriate content type. +Inserts the contents of a file into the content column of the +cr_revisions table for the revision as well.
+Parameters: + + + + + +
+form_name* +Name of the form from which to obtain attribute +values. The form should include an item_id and revision_id.
+tmpfile* +Name of the temporary file containing the content +to upload.
+
+
+ +
content::add_revision_form
+
Adds elements to an ATS form object for adding a +revision to an existing item. If the item already exists, element +values default a previous revision (the latest one by default). If +the form does not already exist, creates the form object and sets +its enctype to multipart/form-data to allow for text entries +greater than 4000 characters.
+
Options:
+ + + + + + + + + + + + + + + +
form_nameThe name of the ATS form object. Defaults to { +new_item} .
content_typeThe content_type of the item. Defaults to { +content_revision} .
content_methodThe method to use for uploading the content body. +If the content type is text, defaults to text entry, otherwise +defaults to file upload.
item_idThe item ID of the revision. Defaults to null +(item_id must be set by the calling code).
revision_idThe revision ID from which to draw default values. +Defaults to the latest revision
attributesA list of attribute names for which to create form +elements.
actionThe URL to which the form should redirect +following a successful form submission.
+
+
+ +
content::copy_content
+
Update the BLOB column of one revision with the content +of another revision
+Parameters: + + + + + +
+revision_id_src* +The object ID of the revision with the content to +be copied.
+revision_id_dest* +The object ID of the revision to be updated. +copied.
+
+
+ +
content::get_attribute_enum_values
+
Returns a list of { pretty_name enum_value } for an +attribute of datatype enumeration.
+Parameters: + +
+attribute_id* +The primary key of the attribute as in the +attribute_id column of the acs_attributes table.
+
+
+ +
content::get_latest_revision
+
Get the ID of the latest revision for the specified +content item.
+Parameters: + +
+item_id* +The ID of the content item.
+
+
+ +
content::get_object_id
Grab an object ID for creating a new ACS +object.
+ +
content::new_item
+
Create a new item, including the initial revision, +based on a valid form submission.
+
+Parameters: + + + + + +
+form_name* +Name of the form from which to obtain item +attributes, as well as attributes of the initial revision. The form +should include an item_id, name and revision_id.
+tmpfile* +Name of the temporary file containing the content +to upload for the initial revision.
+
See Also:
add_revision -
+
+
+
+ +
content::new_item_form
+
Adds elements to an ATS form object for creating an +item and its initial revision. If the form does not already exist, +creates the form object and sets its enctype to multipart/form-data +to allow for text entries greater than 4000 +characters.
+
Options:
+ + + + + + + + + + + + + + + +
form_nameThe name of the ATS form object. Defaults to { +new_item} .
content_typeThe content_type of the item. Defaults to { +content_revision} .
content_methodThe method to use for uploading the content body. +Valid values are { no_content} , { text_entry} , and { file_upload} +. If the content type allows text, defaults to text entry, +otherwise defaults to file upload.
parent_idThe item ID of the parent. Defaults to null +(Parent is the root folder).
nameThe default name of the item. Default is an empty +string (User must supply name).
attributesA list of attribute names for which to create form +elements.
actionThe URL to which the form should redirect +following a successful form submission.
+
+
+ +
content::validate_name
+
Make sure that name is unique for the +folder
+
+Parameters: + +
+form_name* +The name of the form (containing name and +parent_id)
+
Returns:
0 if there are items with the same name, 1 otherwise
+
+

+Private Methods:
+

+ +
content::add_revision_dml
+
Perform the DML to insert a revision into the +appropriate input view.
+
+Parameters: + + + + + + + + + +
+statement* +The DML for the insert statement, specifying a +bind variable for each column value.
+bind_vars* +An ns_set containing the values for all bind +variables.
+tmpfile* +The server-side name of the file containing the +body of the revision to upload into the content BLOB column of +cr_revisions.
+filename* +The client-side name of the file containing the +body of the revision to upload into the content BLOB column of +cr_revisions
+
See Also:
add_revision -
+
+
+
+ +
content::attribute_insert_statement
+
Prepare the insert statement into the attribute input +view for a new revision (see the content repository documentation +for details about the view).
+Parameters: + + + + + + + + + +
+content_type* +The content type of the item for which a new +revision is being prepared.
+table_name* +The storage table of the content type.
+bind_vars* +The name of an ns_set in which to store the +attribute values for the revision. (Typically duplicates the +contents of {[ns_getform].}
+form_name* +The name of the ATS form object used to process +the submission.
+
+
+ +
content::get_attribute_params
+
Query for parameters associated with a particular +attribute
+Parameters: + + + + + +
+content_type* +The content type keyword to which this attribute +belongs.
+attribute_name* +The name of the attribute, as represented in the +attribute_name column of the acs_attributes table.
+
+
+ +
content::get_attributes
+
Returns columns from the acs_attributes table for all +attributes associated with a content type.
+Parameters: + + + + + +
+content_type* +The name of the content type (ACS Object Type) for +which to obtain the list of attributes.
+args* +Names of columns to query. If no columns are +specified, returns a simple list of attribute names.
+
+
+ +
content::get_default_content_method
+
Gets the content input method most appropriate for an +content type, based on the MIME types that are registered for that +content type.
+Parameters: + +
+content_type* +The content type for which an input method is +needed.
+
+
+ +
content::get_sql_value
+
Return the sql statement for a column value in an +insert or update statement, using a bind variable for the actual +value and wrapping it in a conversion function where +appropriate.
+Parameters: + + + + + +
+name* +The name of the column and bind variable (they +should be the same).
+datatype* +The datatype of the column.
+
+
+ +
content::get_type_attribute_params
+
Query for attribute form metadata
+
+Parameters: + +
+args* +Any number of object types
+
Returns:
A list of attribute parameters nested by object_type, +attribute_name and the is_html flag. For attributes with no +parameters, there is a single entry with is_html as null.
+
+
+ +
content::get_type_info
+
Return specified columns from the acs_object_types +table.
+Parameters: + + + + + + + +
+object_type* +Object type key for which info is required.
+ref* +If no further arguments, name of the column value +to return. If further arguments are specified, name of the array in +which to store info in the calling
+args* +Column names to query.
+
+
+ +
content::get_widget_param_value
+
Utility procedure to return the value of a widget +parameter
+Parameters: + + + + + +
+array_ref* +The name of an array in the calling frame +containing parameter data selected from the form metadata.
+content_type* +The current content {type;} defaults to +content_revision
+
+
+ +
content::prepare_content_file
+
Looks for an element named { content} in a form and +prepares a temporarily file in UTF-8 for uploading to the content +repository. Checks for a query variable named { content.tmpfile} to +distinguish between file uploads and text entry. If the type of the +file is text, then ensures that is in UTF-8. Does nothing if the +uploaded file is in binary format.
+
+Parameters: + +
+form_name* +The name of the form object in which content was +submitted.
+
Returns:
The path of the temporary file containing the content, or an +empty string if the form does not include a content element or the +value of the element is null.
+
+
+ +
content::set_attribute_values
+
Set the default values for attribute elements in ATS +form object based on a previous revision
+Parameters: + + + + + + + + + +
+form_name* +The name of the ATS form object containing the +attribute elements.
+content_type* +The type of item being revised in the form.
+revision_id* +The revision ID from where to get the default +values
+attributes* +The list of attributes whose values should be +set.
+
+
+ +
content::set_content_value
+
Set the default value for the content text area in an +ATS form object based on a previous revision
+Parameters: + + + + + +
+form_name* +The name of the ATS form object containing the +content element.
+revision_id* +The revision ID of the content to revise
+
+
+ +
content::string_to_file
+
Write a string in UTF-8 encoding to of temp file so it +can be uploaded into a BLOB (which is blind to character +encodings). Returns the name of the temp file.
+Parameters: + +
+s* +The string to write to the file.
+
+
+ +
content::update_content_from_file
+
Update the BLOB column of a revision with the contents +of a file
+Parameters: + + + + + +
+revision_id* +The object ID of the revision to update.
+tmpfile* +The name of a temporary file containing the +content. The file is deleted following the update.
+
+
+ +
content::upload_content
+
Inserts content into the database from an uploaded +file. Does automatic mime_type updating Parses text/html content +and removes tags
+Parameters: + + + + + + + + + +
+db* +A db handle
+revision_id* +The revision to which the content belongs
+tmpfile* +The server-side name of the file containing the +body of the revision to upload into the content BLOB column of +cr_revisions.
+filename* +The client-side name of the file containing the +body of the revision to upload into the content BLOB column of +cr_revisions
+
+

+* indicates required

+