- Publicity: Public Only All
richtext-procs.tcl
Rich text input widget and datatype for OpenACS templating system.
- Location:
- packages/acs-templating/tcl/richtext-procs.tcl
- Created:
- 2003-01-27
- Author:
- Lars Pind <lars@pinds.com>
Procedures in this file
- template::data::to_sql::richtext (public)
- template::data::transform::richtext (public)
- template::data::validate::richtext (public)
- template::util::richtext (public)
- template::util::richtext::acquire (public)
- template::util::richtext::create (public)
- template::util::richtext::format_options (public)
- template::util::richtext::formats (public)
- template::util::richtext::get_property (public)
- template::util::richtext::get_tag (public)
- template::util::richtext::initialize_widget (public)
- template::util::richtext::register_editor (public)
- template::util::richtext::render_widgets (public)
- template::util::richtext::set_property (public)
- template::widget::richtext (public)
Detailed information
template::data::to_sql::richtext (public)
template::data::to_sql::richtext value
Handle richtext transformations using a standardized naming convention.
- Parameters:
- value
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::data::transform::richtext (public)
template::data::transform::richtext element_ref
Transform the previously-validated submitted data into a two-element list as defined by the richtext datatype.
- Parameters:
- element_ref - Reference variable to the form element
- Returns:
- Two-element list defined by the richtext datatype
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::data::validate::richtext (public)
template::data::validate::richtext value_ref message_ref
Validate richtext after form submission.
- Parameters:
- value_ref - Reference variable to the submitted value
message_ref - Reference variable for returning an error message
- Returns:
- True (1) if the submitted data is valid, false (0) if not
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext (public)
template::util::richtext command [ args... ]
Dispatch procedure for the richtext object
- Parameters:
- command
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::acquire (public)
template::util::richtext::acquire type [ value ]
Create a new richtext value with some predefined value Basically, create and set the richtext value
- Parameters:
- type
value (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::create (public)
template::util::richtext::create [ contents ] [ format ]
Create a richtext widget
- Parameters:
- contents (optional) - The text content of the widget
format (optional) - How that text is formatted (text, html, etc)
- Returns:
- Two-element list of the joined parameters
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::format_options (public)
template::util::richtext::format_options
Returns a formatting option list
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::formats (public)
template::util::richtext::formats
Returns a list of valid richtext formats
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::get_property (public)
template::util::richtext::get_property what richtext_list
Get a property of the richtext datatype. Valid properties are:
- Parameters:
- what - the name of the property. Must be one of:
- contents (synonyms content, text) - returns the actual contents of the textarea field
- format (synonym mime_type) - returns the mimetype, e.g. 'text/plain'
- html_value - returns the content converted to html format, regardless of the format the content is actually in. In case it is already text/html no conversion will be applied.
richtext_list - a richtext datatype value, usually created with ad_form.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::get_tag (public)
template::util::richtext::get_tag [ -options options ]
Return tag name for the markup; normally a "textarea", but some editors might use e.g. a "div". If the function is defined for the editor, call it.
- Switches:
- -options
(optional)- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::initialize_widget (public)
template::util::richtext::initialize_widget [ -form_id form_id ] \ [ -text_id text_id ] [ -editor editor ] [ -options options ]
Initialize a single text input (textarea with the id "text_id" part of a form with "form_id") for the specified richtext editor via a richtext-editor plugin (e.g. ckeditor4, tinymce, or xinha)
- Switches:
- -form_id
(optional)- ID of the form containing the textarea
- -text_id
(optional)- ID of the textarea
- -editor
(optional)- Editor, which should be used. Will default to that specified in acs-templating RichTextEditor parameter when not specified.
- -options
(optional)- Options passed in from the widget spec
- Returns:
- On success, this function returns a dict with success 1
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::register_editor (public)
template::util::richtext::register_editor editor
Make an rich-text editor known to the templating system.
- Parameters:
- editor - Editor to be registered
- Returns:
- List of editors registered so far
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::render_widgets (public)
template::util::richtext::render_widgets
Render all rich-text editors with their widget specific code. Every editor might have multiple instances on the page, which are accessible to "render_widgets" via the global variable acs_blank_master__htmlareas. This function can be used to perform a single (customization) operation relevant for multiple widgets.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::util::richtext::set_property (public)
template::util::richtext::set_property what richtext_list value
Set a property of the richtext datatype.
- Parameters:
- what - One of
- contents (synonyms content, text)
- format (synonym mime_type)
richtext_list - the richtext list to modify
value - the new value
- Returns:
- the modified list
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::widget::richtext (public)
template::widget::richtext element_reference tag_attributes
Implements the richtext widget, which offers rich text editing options. This version integrates support for the xinha and tinymce editors out of the box, but other richtext editors can be used including and configuring them in your custom template. If the acs-templating.UseHtmlAreaForRichtextP parameter is set to true (1), this will use the WYSIWYG editor widget set in the acs-templating.RichTextEditor parameter. Otherwise, it will use a normal textarea, with a drop-down to select a format. The available formats are:
- Enhanced text = Allows HTML, but automatically inserts line and paragraph breaks.
- Plain text = Automatically inserts line and paragraph breaks, and quotes all HTML-specific characters, such as less-than, greater-than, etc.
- Fixed-width text = Same as plain text, but conserves spacing; useful for tabular data.
- HTML = normal HTML.
You can also parameterize the richtext widget with a 'htmlarea_p' attribute, which can be true or false, and which will override the parameter setting.
The richtext widget can be extended with several plugins, which are OpenACS packages named richtex-EDITOR. Plugins are available e.g. for xinha, tinymce and ckeditor4. When the plugins are installed, one can use e.g. xinha by specifying 'editor xinha' in the options of the widget spec. The following options for xinha may be specified:
- editor: xinha
- height: height of the xinha widget (e.g. 350px)
- width: width of the xinha widget (e.g. 500px)
- plugins: Tcl list of plugins to be used in xinha. There is a special plugin for the oacs file selector available, called OacsFs. If no options are specified, the following plugins will be loaded:
GetHtml CharacterMap ContextMenu FullScreen ListType TableOperations EditTag LangMarks Abbreviation
These options are used by the OacsFs plugin
- folder_id: the folder from which files should be taken for the file selector. Can be used alternative with fs_package_id, whatever more handy in the application.
- fs_package_id: the package id of the file_storage package from which files should be taken for the file selector. Can be used alternative with folder_id, whatever more handy in the application. If nothing is specified, the globally mounted file-store is used.
- file_types: SQL match pattern for selecting certain types of files (e.g. pdf files). The match pattern is applied on the MIME type of the field. E.g. a value of %text/% allows any kind of text files to be selected, while %pdf% could be used for pdf-files. If nothing is specified, all file-types are presented.
- javascript: provide JavaScript code to configure the xinha widget and its plugins. The configure object is called
xinha_config
.Example to use xinha with only a few controls:
{options {editor xinha plugins {OacsFs} height 350px javascript { xinha_config.toolbar = [ ['popupeditor', 'bold','italic','createlink','insertimage','separator'], ['killword','removeformat'] ]; }}}Example for the use of the xinha widget with options:
text:richtext(richtext),nospell,optional {label Content} {options {editor xinha plugins OacsFs height 350px file_types %pdf%}} {html {rows 15 cols 50 style {width: 100%}}}Caveat: the three adp-files needed for the OpenACS file selector (insert-image, insert-ilink and file-selector) are currently part of the xowiki package, since acs-templating is per default not mounted. This is hopefully only a temporal situation and we find a better place.
Example for the use of the tinymce widget with options:
text:richtext(richtext),nospell,optional {label Biography} {options {theme simple plugins "oacsimage,oacslink,style"}} {html {rows 15 cols 50 style {width: 100%}}}See TinyMCE documentation for a full list of available options
Caveat: the scripts needed for the oacsimage and oacslink plugins require acs-templating to be mounted. This is a temporary situation until we find a better way to handle plugins.
Example for the use of a custom editor widget:
text:richtext(richtext),nospell,optional {label Biography} {options {editor custom ...custom configuration...}} {html {rows 15 cols 50 style {width: 100%}}}If provided with a WYSIWYG editor different than 'xinha' or 'tinymce', system will just collect formfield ids and supplied options for the richtext field and will provide them as-is to the blank-master environment. When using a custom editor, functional meaning of the options is totally up to the user.
Note that the richtext editors interact with
blank-master.tcl
andblank-master.adp
.Derived from the htmlarea richtext widget for htmlarea by lars@pinds.com
modified for RTE http://www.kevinroth.com/ by davis@xarg.net
xinha and ckeditor4 support by gustaf.neumann@wu-wien.ac.at
tinymce support by oct@openacs.org
- Parameters:
- element_reference
tag_attributes
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.