API Reference

AbstractComponentPlugin

The base class AbstractComponentPlugin, which all editor plugins inherit from, provides the following methods and member variables. Methods which are not overridden will get the default behavior described below.

Public member variables

RoxenModule module_self;

Reference to the module from which the plugin was loaded.

string get_component_name();

The user-presentable name for this component.

string get_component_tag();

The name of the XML element which this editor implements, e.g. "foo-component" for <foo-component>...</foo-component>.

Public methods

int(0..1) get_component_allow_multiple()

Returns a boolean flag indicating whether it's ok to insert more than one component of this type in a single page. Defaults to true.

int(0..1) get_component_allow_delete()

Returns a boolean flag indicating whether this component type may be deleted from the page. Defaults to true.

int(0..1) get_component_need_preview()

Returns a boolean flag indicating whether the XSLT output from this component should be included as a hidden part of the editor page while the input form is visible. This is only necessary when other components require access to the HTML data at all times. Defaults to false.

int(0..1) get_component_allow_content_type(string ct)

Returns a boolean flag indicating if the given component is applicable to the given file content type. Defaults to true for all pages of type "sitebuilder/xml-page-editor" (CMS Page Editor).

int(0..1) get_component_allow_file(SBFile file)

Returns a boolean flag indicating if the given component is applicable to the given file object. Defaults to true for all files.

array(string) get_component_fields()

Returns the field names handled by this component. Default value is an empty array. Note that if layout variants are used the "variant" field should be declared explicitly.

array(string) get_all_component_fields()

Same as get_component_fields() but also includes the internal <id> field.

multiset(string) get_unquoted_fields()

Returns the names of those fields which should be written to the XML file without applying HTML quoting for characters such as "<" and "&". If the component wants to store something other than plain text into a component field (e.g. proper HTML markup) it must register that field using this method. Extra fields that occur in the component element but aren't registered by get_all_component_fields() are unquoted by default; all other fields default to HTML quoting.

The component module must call set_field() with unquoted strings representing the field value when save_variables() is invoked.

mapping(string:string) get_component_fields_defaults()

Returns a mapping from field names to default values. These values will be treated as defaults when instantiating a component where not all fields have a value. If the component plugin overrides this method it should call the inherited method in the abstract base class and then modify the result to ensure that internal fields such as <id> always get proper initialization.

multiset(string) get_default_hidden_fields()

Returns field names that should be hidden in the edit view. Defaults to no fields. The actual set of hidden fields can be controlled by the site administrator in the module settings page.

mapping(int:string) get_component_variants()

Returns a mapping from variant number to user-presentable description. Defaults to no variant choices. The actual variant choices may be redefined by the site administrator in the module settings page.

array(int) get_component_display_order()

When variants are defined, the menu that displays the corresponding description strings will be sorted in accordance to the array returned in this method. Defaults to ascending order.

void create(RoxenModule mod_self, program instance_class_ref)

The constructor method. If overridden, be sure to call the inherited method as well.

AbstractComponentInstance

The base class AbstractComponentInstance, which all plugin instances inherit from, provides the following methods and member variables. Methods which are not overridden will get the default behavior described below.

Public member variables

AbstractComponentPlugin plugin;

Reference to the editor module which created this instance.

Public methods

array(string) get_field_names()

Returns all the fields that the component tag actually contains, in the order they occurred. Duplicate fields are only listed once. If there are duplicate fields then only the first instance is editable.

string get_field(string field)

Returns the string value of a field in the component, or the empty string if the field is missing. Any HTML quoting and unquoting will be handled automatically in accordance to the component's get_unquoted_fields() method.

string low_get_field (string field)

Same as get_field() but returns zero if the field is missing.

Node get_field_node(string field)

Returns the node from the XML tree representing the field in this component. This should be treated as read-only data, but is very useful in case the editor wants to read the subtree within the field for non-string data types.

Note that this returns the node from the last save state, not the current editing state. The node tree is not rebuilt during normal editing.

mapping(string:string) get_field_attributes(void|string field)

Returns all XML attributes present on the field tag. If the field is 0 it returns attributes defined for the component instance tag.

int(0..1) get_field_lock(void|string field)

Returns a boolean flag indicating whether the field or the instance has a rxml:edit-lock="yes" attribute. This attribute signals that the page editor should prevent all types of editing, including all calls to set_field() from the module itself. If field is 0 it returns the lock status for the instance element. Defaults to false.

int(0..1) get_delete_lock()

Returns a boolean flag indicating whether component deletion should be blocked. Defaults to false.

void set_field(string field, string data)

Sets a new value for the given field. The data must be provided in string form. When the file is eventually saved this string will be inserted into the field. The string value will be properly HTML quoted in the page if quote_fields() returns true for the field.

int quote_field (string field)

Returns non-zero if the field is to be treated as a string and be quoted. Otherwise it's assumed to contain wellformed XML and is inserted as-is. Defaults to quoting for all fields registered by get_all_component_fields() but not by get_unquoted_fields().

string render_field(string field, mapping data, RequestID id)

Callback to be used when render_editor() is invoked. It adds a field to the editing form using the standard layout. If the field is declared as locked it will receive a padlock icon in order to indicate editing restrictions. The different parameters allowed in the data mapping is described in the section Implementation. This method is normally not overridden in a component.

string render_editor(string var_prefix, RequestID id);

Requests drawing of the component editor. The editor should create proper input widgets for editing the component instance, e.g. by calling render_field(). Any form variables that it uses must be named using the given variable prefix string. The editor will automatically add buttons such as OK and Cancel and handle their actions.

void save_variables(string var_prefix, RequestID id);

Called when the user accepts the form presented in the component instance editor. Your component should now save the field values posted in the current request by calling set_field() for each one. The variable prefix must be added to form variable names when accessed in the request object (specifically, in the id->variables mapping). This method is normally not overridden in a component.

int merge_change (AbstractComponentInstance other, AbstractComponentInstance old);

If defined, this method will be called when the automerge identifies a change conflict in this component instance. This instance is the one changed locally by the user, other is the one changed in the site, and old is the common ancestor. old might be zero if no common ancestor exists for the component instance. other and old are always instances of the same plugin.

This function should try to merge in the changes from other into this instance and return true if successful. If it returns zero (or isn't defined at all) then the components will be presented side-by-side as usual to let the user resolve the situation manually.

void notify_close(RequestID id, void|object/*SBFileData*/ sbfd)

Callback used just before the instance is destroyed and the file is saved. This gives the component a last chance of updating variables (e.g. page footer containing the last editing date). Note that this method will not be called if the user cancels the page editing.

Unlike other editor methods you are allowed interact with the version-controlled file object directly via the sbfd parameter. For example, this enables you to set metadata.

void create(AbstractComponentPlugin p, string|Node xml_data, void|object /*SBFileData*/ sbfd, void|RequestID id, void|mixed arg, void|int dont_generate_id)

The constructor method. If overridden, be sure to call the inherited method as well.

Link management

Components that work with web links or file references need to be aware of link management functionality introduced in Roxen CMS version 5.0. There is a new call that converts from UUID-styled link form to traditional paths and another for generating a UUID-style link for an existing path.

Please see the Link Management section of the Roxen CMS Administrator manual for a background on how link management works, and the section Implementation in this manual to get an understanding for when these calls are necessary.

string resolve_permlink(string permlink, RequestID id)

Resolves a link on the format /__uuid/... to the corresponding path in the site repository, taking the current user's edit area into account. If the link cannot be resolved it is returned in unmodified form.

Any additional path segments (for directory references only) or query parameters in the given link will be appended to the resulting path.

string get_permlink_for_path(string path, RequestID id)

Returns a link on the format /__uuid/... representing the file or directory that path points to. If no valid file/directory exists or the path already appears to be a URL the input data will be returned unchanged.