NAME
SYNOPSIS
METHODS
MODE HANDLERS
UTILITY FUNCTIONS
CUSTOM REBUILD OPTIONS
- $app->add_rebuild_option(\%param)
CALLBACKS
- Parametric Calllbacks
  - Parameters
POD ERRORS

NAME

MT::App::CMS

SYNOPSIS

The MT::App::CMS module is the primary application module for Movable Type. It is the administrative interface that is used to manage blogs, entries, comments, trackbacks, templates, etc.

METHODS

$app->init

Initializes the application, defining the modes that are serviced and core callbacks and itemset actions.

Initializes the application to handle the request. The CMS also does a schema version check to make certain the schema is up-to-date. If it is not, it forces a direct to the configured UpgradeScript application (typically mt-upgrade.cgi).

$app->init_plugins

Overrides MT::init_plugins to call init_core_callbacks before other plugins are run (since init_core_callbacks defines some remapped callback names plugins may rely on).

$app->apply_log_filter(\%param)

Returns terms suitable for filtering MT::Log based on the parameters given. 'filter', 'filter_val' and 'blog_id' are recognized parameters. 'filter' may be one of 'level' or 'class'. Valid 'filter_val' values for a 'filter' of 'level' is any number between 1 and 2^16, being a bitmask. Valid 'filter_val' values for a 'filter' of 'class' include any of the register MT::Log class names. See MT::Log for further information.

$app->build_author_table(%args)

$app->build_blog_table(%args)

$app->build_comment_table(%args)

$app->build_commenter_table(%args)

$app->build_entry_table(%args)

$app->build_group_table(%args)

$app->build_junk_table(%args)

$app->build_log_table(%args)

$app->build_ping_table(%args)

$app->build_tag_table(%args)

$app->build_template_table(%args)

Each of these routines have a similar interface and function. They load data for the <type>_table.tmpl application template. Parameters for these routine are:

param
The parameter hash to populate. This is eventually applied to the application template.
load_args
An array reference containing the terms and arguments that are to be passed on to Class->load_iter method to load the data.
iter
An existing iterator that can be used to load the records.
items
An array of objects used to populate the listing.

Only one of these arguments is allowed: param, load_args, iter. Upon return, the hashref provided in the 'param' element is populated with the data necessary to build the template.

These routines are called by their listing modes (where a 'load_args' parameter is given) and also from the search_replace mode when displaying search results (where it passes an 'items' element).

$app->build_page($tmpl_file, \%param)

Overridden method for MT::App::build_page that adds additional template parameters that are common to CMS application templates.

$app->build_plugin_table(%opt)

Populates template parameters necessary for rendering the cfg_plugin.tmpl for the blog-centric and system-overview views.

$app->do_search_replace

Utility method used to do the physical search and replace operation invoked with the 'search_replace' application mode. This method is also used by the 'listing' method when a 'search' parameter is sent in the request.

$app->get_newsbox_content

Handles the task of retrieving the "Movable Type News" from sixapart.com. This request is done at most once per day since the data is cached after retrieval. This operation can be disabled by setting the NewsboxURL to "disable".

$app->is_authorized

Determines if the active user is authorized to access the blog being requested. If a blog-level request is active, this method sets the permissions object for the current user and blog.

$app->list_actions($which, $type, @param)

Utility method to handle the selection of itemset actions for a given $type. Any @param data given here is passed through to the itemset action's "condition" coderef, if registered.

$app->languages_list($lang)

Returns a list of supported languages in a format suitable for the edit_author.tmpl, edit_profile.tmpl and cfg_system_general.tmpl application templates. The $lang parameter pre-selects that language in the list.

$app->list_tag_for(%param)

Generates a listing screen for MT::Tag objects that are attached to a given 'taggable' package. The parameters for this method are:

Package
The Perl package name of a class that supports the MT::Taggable interface that the listing is for.
TagObjectType
The registered type (ie, 'entry' for MT::Entry objects) of data these tags are associated with.
TagObjectLabelPlural
Translated version of TagObjectTypePlural.

To list tags for the MT::Entry package, you would use this:

    $app->list_tag_for(
        Package => 'MT::Entry',
        TagObjectType => 'entry',
        TagObjectLabelPlural => $app->translate("entries")
    );

This method uses the list_tag.tmpl application template to render the tag listing view.

$app->load_default_entry_prefs

$app->load_entry_prefs

$app->load_list_actions

$app->list_pref($type)

Returns a hashref of listing preferences suitable for the pager.tmpl application template. It will also update new listing preference settings if it sees the current request is posting them.

$app->listing(\%param)

This is a method for generating a typical listing screen. It is configured through the parameter hash passed to it. The accepted parameters include:

Type
Specifies a data type to be processed. This is one of the types registered with the application (see the register_type method). Standard types include: blog, entry, author, comment, ping, template, notification, templatemap, commenter, banlist, category, ping_cat, log, tag, group, role, association.

The Type parameter provides a reference to the actual Perl package to be used for loading the data for the listing. MT::App::CMS uses it's model method to retrieve the package name and load the module if necessary. The module provided should be a MT::Object descendant.
Template
The application template filename to be used to generate the page. If unspecified, the default is named after the 'Type' parameter: "list_<type>.tmpl". Note that this parameter is not used when the 'NoHTML' parameter is specified.
Params
A hashref of parameters that will be passed to the application template without further modification.
Code
A coderef that is invoked for each row data displayed. This routine is passed two parameters: the object being processed and a hashref of parameter data for that row. This is typically used to further customize the row-level parameter data before the application template is processed.
Terms
This is a hashref that is passed to the load_iter method of the package that is providing the data for the listing. The Terms parameter provides a way of filtering the data retrieved. Refer to the MT::Object documentation of the load and load_iter methods for more information about this parameter.
Args
This is a hashref that is passed to the load_iter method of the package that is providing the data for the listing. The Args parameter can be used to specify a sort order, a join operation and other operations that are applied upon loading the data for the listing. Refer to the MT::Object documentation of the load and load_iter methods for more information about this parameter.
Iterator
The default value for this parameter is 'load_iter'. This is a standard method for all MT::Object type packages. So, for instance, if your 'Type' parameter is 'author', the package that will be used is 'MT::Author', so the listing method will call MT::Author->load_iter to fetch the data. But the MT::Author package provides some convenient iterators for fetching other things that are related to the author, such as roles they are assigned. So, for invoking the 'role_iter' iterator method, you'd specify 'role_iter' as the value for the Iterator parameter.
NoHTML
Specify this parameter (with a true value, such as '1') to cause the listing method to simply return the hashref of data it would have given to the application template to return.

The listing method is also aware of many of the query parameters common to the Movable Type CMS listings. It will automatically recognize the following query parameters:

offset
A number specifying the number of rows to skip when displaying the listing.
search
A string to use for a search query of the data displayed. This parameter is only useful for data types supported by the CMS search function: currently, blog, author, entry, comment, template, ping.
filter, filter_val
Used to filter the listing for a particular value. This will supplement the Terms parameter given to the listing method, adding a term for filter=filter_val.

The listing method is also aware of the list preferences saved for the 'Type' identified.

Examples

This will produce a listing page (using the "list_entry.tmpl" application template) of all entries created by the currently logged-in user.

    return $app->listing({
        Type => 'entry',
        Terms => {
            author_id => $app->user->id,
        },
    });

$app->load_template_prefs

Returns as hashref of the template edit screen preferences for the active user.

$app->make_blog_list(\@blogs)

Takes an array of blogs and returns an array reference of data that is suitable for the list_blog.tmpl and list_blog.tmpl application templates.

$app->object_edit_uri($type, $id)

A convenience method for returning an application URI that can be used to direct the user to an edit operation for the $type and object $id given. This method assumes the type given is serviced through the 'view' application mode.

$app->pre_run

Handles the menial task of localizing the stock "Convert Line Breaks" text filter for the current user.

$app->update_dynamicity($blog, $cache, $conditional)

When saving the blog's configuration settings regarding dynamic publishing, this method is called to update the blog's templates to match the dynamic configuration (if specifying no dynamic publishing, all templates are configured to be statically published, when specifying 'dynamic archives', archive templates are configured to be dynamically published and all other templates are set to static).

Also, the '.htaccess' file and 'mtview.php' file in the blog's root path is generated/updated to include rules that invoke the dynamic publishing engine. If this file cannot be written or updated, the user is notified of this problem.

$app->user_blog_prefs

Returns a hashref of the current user's blog preferences (such as their tag delimiter choice).

$app->user_can_admin_commenters

A utility method used by commenter-based itemset actions to condition their display based on whether or not the active user has permissions to administer commenters for the current blog.

$app->validate_magic

Verifies the 'magic_token' POST parameter that is placed in forms that are submitted to the application. This token is used as a safety device to protect against CSRF (cross-site request forgery) style attacks.

MODE HANDLERS

The CMS mode handlers typically do a permission test to verify the user has permission to invoke the mode, then process the request and return the response using an application template.

add_group
Adds a user to one or more groups. Returns to the list_groups mode upon success.
add_member
Adds one or more users to a group. Returns to the list_authors mode upon success.
add_tags_to_entries
Applies a set of tags to one or more entries.
approve_item
Approves a comment or trackback for publication.
ban_commenter
Bans a commenter for a particular blog.
ban_commenter_by_comment
Bans commenters on a blog based on a selection of one or more comments.
category_add
Displays the popup window (used on the entry composition screen) for adding a new category.
category_do_add
Processes the creation of a new category and returns the JavaScript that adds the category to the category drop down list on the entry composition screen.
cc_return
Handles the Creative Commons license data returned from their license selection process.
cfg_comments
Handles the display of the weblog comments settings screen.
cfg_trackbacks
Handles the display of the weblog trackback settings screen.
cfg_spam
Handles the display of the weblog spam settings screen.
cfg_entry
Handles the display of the weblog entries settings screen.
cfg_web_services
Handles the display of the weblog web services settings screen.
cfg_archives
Handler for the Blog Archives configuration screen.
cfg_blog
Handles the display of the general settings for the blog.
cfg_plugins
Handles the display of the "Plugins" tab of the blog setting screen.
cfg_prefs
Handles the display of the "Customize Entry display preferences" screen.
cfg_system_feedback
Handles the display of the "System-Wide Feedback Settings" screen.
cfg_system_general
Handles the display of the "System-Wide: General Settings" screen.
delete
Handles the deletion of registered data types.
dialog_grant_role
Handles display of the modal dialog for granting roles.
dialog_select_group
Handles display of the modal dialog for selecting one or more groups.
dialog_select_user
Handles the display of the modal dialog for selecting one or more users.
dialog_select_weblog
Handles the display of the modal dialog for selecting a blog.
disable_object
Handles the request to disable a user or group.
do_import
Handles the request to process entry import file(s).
draft_entries
Handles the request to unpublish existing entries.
edit_object
Handles the display of editing registered data types.
edit_role
Handles the display of editing a particular role.
empty_junk
Handles the request to empty the junk folder for comments or trackbacks.
enable_object
Handles the request to enable a user or group.
start_export
Handler for the display of the export screen.
export
Handles the request to export the data for a blog.
export_log
Handles the request to export activity log data in a CSV format.
grant_role
Handles the request from the "Grant Role" modal dialog to grant a role to an user or group.
handle_junk
Handles the request to junk a given comment or trackback.
handshake
Handles the response from TypeKey for assigning the TypeKey token to a particular blog.
itemset_action
Generic application mode handler used by all itemset actions. This handler will locate the actual coderef to be run to service the itemset action and if found, calls it.
js_tag_check
Ajax-style handler for testing whether a particular tag name exists or not.
js_tag_list
Ajax-style handler for returning the tags that exist on a particular blog.
list_assets
Handler for displaying a list of blog-level assets.
list_associations
Handler for displaying the associations listing (either all associations, associations for a particular user, group, role or blog).
list_authors
Handler for displaying a list of authors.
dashboard
Handler for the front screen of MT, where the user's associated blogs are listed.
list_category
Handler for displaying the categories for a particular blog.
list_commenter
Handler for displaying a list of authenticated commenters for a particular blog.
list_comments
Handler for displaying a list of comments (either blog-level or system-wide).
list_entries
Handler for displaying a list of entries (either blog-level or system-wide).
list_groups
Handler for displaying the group listing.
list_objects
Handler for displaying the installed templates for a particular blog (this used to be a routine called for most listings, but they have been broken out into separate handlers).
list_pings
Handler for displaying a list of trackbacks (either blog-level or system-wide).
cfg_system_plugins
Handler for displaying all installed plugins (the system-overview view of plugins).
list_roles
Handler for displaying the role listing.
list_tag
Handler for displaying a list of tags (either blog-level or system-wide).
logout
Handler for logging the active user out of the application, ending their session.
move_category
Handles the request for moving a category from one parent to another (or to the top level).
not_junk
Handler for approving previously junked comments or TrackBack objects.
pinged_urls
Handler for displaying the list of URLs that have been pinged for a particular entry.
plugin_control
Handler for the request to enable/disable a particular plugin or all plugins.
preview_entry
Handler for displaying an entry preview (invoked from the entry composition screen).
publish_entries
Itemset handler for the request to publish a selection of entries.
rebuild_confirm
Handler for displaying the list of rebuild options in the rebuild site popup window.
rebuild_new_phase
Displays the "rebuilding.tmpl" page and invokes a "rebuild_phase" mode request to process the rebuild of a set of entries/templates.
rebuild_pages
Primary rebuild handler for the rebuild site process.
rebuild_phase
Handler for rebuilding entries/templates selected from the listings. Rebuilds the requested set of items and returns to the originally viewed listing.
recover_password
Handler for displaying the password recovery screen.
recover_passwords
Handler for resetting the passwords for one or more users.
recover_profile_password
Handler for the password reset request invoked by a system administrator from the user profile screen.
reg_bm_js
Handler for returning the JavaScript code for displaying the QuickPost composition page for Internet Explorer users that have installed the QuickPost Windows registry file.
reg_file
Handler that returns the "mt.reg" for enabling a conext-menu QuickPost item that is suitable for Internet Explorer.
remove_group
Handler for removing one or more group associations from a particular user.
remove_member
Handler for removing one or more user associations from a particular group.
remove_tags_from_entries
Itemset handler for removing a list of tags from one or more entries.
rename_tag
Handler for renaming a MT::Tag, or merging with another tag if one exists by that name.
reset_blog_templates
Handler for resetting a given blogs templates back to their default configuration.
reset_log
Handler for resetting the system-wide activity log.
reset_password
reset_plugin_config
save_category
save_cfg_system_feedback
save_cfg_system_general
save_commenter_perm
save_entries
save_entry
save_entry_prefs
save_object
save_plugin_config
save_role
search_replace
send_notify
send_pings
set_item_visible
set_object_status
show_admin
show_entry_prefs
show_menu
show_upload_html
start_import
Handler for the display of the import screen.
start_rebuild_pages
start_recover
start_upload
start_upload_entry
synchronize
Handler for the request to synchronize the users or groups with the configured external directory.
asset_insert
asset_insert_text
start_upload_entry
list_blogs
Handler for the display of the system-wide list of blogs.
trust_commenter
trust_commenter_by_comment
unapprove_item
unban_commenter
unban_commenter_by_comment
untrust_commenter
untrust_commenter_by_comment
update_list_prefs
Handler for saving changes to the user's list preferences.
update_welcome_message
Handler for saving the change to the blog's welcome message.
upgrade
Transient mode handler used to redirect user to the mt-upgrade script for either installation of upgrade of their database.
upload_file
complete_insert
view_log
Handler for viewing the activity log (either blog-level or system-wide).
start_backup
Handler for the display of the backup screen.
start_restore
Handler for the display of the restore screen.
backup
Handler for the system backup function.
restore
Handler for the system backup function.

UTILITY FUNCTIONS

listify(\@array)

Utility function that takes an array reference of strings and returns an array reference of hashes. So this:

    listify(['a','b','c'])

yields this:

    [{name => 'a'},{name => 'b'},{name => 'c'}]

This is handy for presenting a simple list of things in an HTML::Template template.

$app->make_feed_link($view, $params)

Utility method for constructing an Activity Feed link based on the current view. This routine requires the user have an API password assigned to their profile.

$app->map_comment_to_commenter(\@comments)

Utility method for retrieving the unique set of commenter_id and blog_id values for the set of comments given. The return value from this method is an list of array references that each have the commenter_id and blog_id in them.

$app->ping_continuation

Utility method that returns a response to show the "Pinging..." status page (pinging.tmpl application template).

$app->rebuild_these(\%rebuild_set, %options)

Utility method for rebuilding a set of entries. If $options{how} is passed and it is set to the NEW_PHASE constant, the handler returns the 'rebuilding.tmpl' application template to kick off the actual rebuild operation with a separate request. Otherwise, the entries are rebuilt immediately.

$app->register_type($type, $package)

Registers a new "API" type that goes into the %API hash. This registry is used by the model method and other generic handlers that expect a '_type' parameter to be passed in the request.

RegistrationAffectsArchives($blog_id, $archive_type)

Private utility routine to test if a particular archive type is affected by changes to commenter registration settings. Returns true if particular tags are in use (namely, MTIfRegistrationRequired, MTIfRegistrationNotRequired, MTIfRegistrationAllowed).

$app->update_entry_status($new_status, @id_list)

Called by the draft_entries and publish_entries handlers to actually apply the updates to the entries identified and publish pages that are necessary. If DeleteFilesAtRebuild directive is set to 1, it also removes the previously published individual entry archive page if the new status for the entry is the one other than RELEASE.

CUSTOM REBUILD OPTIONS

The pop-up rebuild dialog that you see in Movable Type has a drop-down list of rebuild options. This list can be populated with custom options provided through a plugin. For example, a plugin might want to provide the user with an option to rebuild a template identified for creating user archives.

$app->add_rebuild_option(\%param)

label: The label to display in the list of rebuild options.
code: The code to execute when running the custom rebuild option.
key: An identifier unique to this option (optional, will derive from the label if unavailable).

In addition to this application method, there is also a rebuild_options callback that can be used to further customize the list of extra rebuild options. This callback is useful when needing to add items to the list that are unique to the active user or blog.

CALLBACKS

The application-level callbacks of the MT::App::CMS application are documented here.

rebuild_options

    callback($cb, $app, \@options)

The rebuild_options callback provides control over an array of additional custom rebuild options that are displayed in MT's rebuild window. The array is populated with hashrefs, each containing:

code: The code to execute when running the custom rebuild option.
label: The label to display in the list of rebuild options.
key: An identifier unique to this option (optional, will derive from the label if unavailable).

CMSPostSave.entry

Called when an entry has been saved, after all of its constituent parts (for example, category placements) have been saved. An CMSPostEntrySave callback would have the following signature:

    sub cms_post_entry_save($cb, $app, $entry, $original)
    {
        ...
    }

For backward compatibility, CMSPostEntrySave and AppPostEntrySave are aliases to CMSPostSave.entry.

Parametric Calllbacks

Every object "type" has a suite of callbacks defined for that type, as below. Each item in the list below forms a callback name by appending the object "type" after a period, e.g. CMSViewPermissionFilter.blog, CMSPostSave.template, etc. The "type" values come from the same space as passed to the CMS app's _type query parameter. If you're not sure what _type corresponds to a certain MT::Object subclass, consult the following list:

author => MT::Author
comment => MT::Comment
entry => MT::Entry
template => MT::Template
blog => MT::Blog
notification => MT::Notification
templatemap => MT::TemplateMap
category => MT::Category
banlist => MT::IPBanList
ping => MT::TBPing
ping_cat => MT::TBPing
group => MT::Group
role => MT::Role
association => MT::Association

Callbacks that apply to these object types are as follows:

CMSViewPermissionFilter

Calling convention is:

    callback($cb, $app, $id, $obj_promise)

Where $id is the ID of an object, if it already exists, or undef if the user will be creating a new object of this type.

$obj_promise is a promise for the object itself. You can use $obj_promise-force> to get ahold of the object, if you need it, but typically you won't need it. (See MT::Promise)

Return a false value to abort the operation and display a message to the user that s/he doesn't have permission to view the object.

CMSDeletePermissionFilter

    callback($cb, $app, $obj)

CMSSavePermissionFilter

Calling convention is:

    callback($cb, $app, $id)

Where $id is the ID of the object, if it already exists, or undef if it is a new object with this request.

Note that at this point, the object may not yet exist. The request can be understood through the query parameters of the app, accessible through $app->param(). A CMSSavePermissionFilter callback should be "safe"--it should not modify the database.

Return a false value to abort the operation and display a message to the user that s/he doesn't have permission to modify the object. The method is not called if the acting user is a superuser.

CMSSaveFilter

This callback gives you the chance to "decline" for reasons other than lack of permissions.

The routine is called as follows:

    callback($cb, $app)

Returning a false value will decline the request. It is advisibable to return an error via the $cb object in order to signal to the user what went wrong.

Note that the new object has not been constructed yet. The operation can be understood by examining the $app object's query parameters via $app->param()

A CMSSaveFilter callback should be "safe"--it should not modify the database.

CMSPreSave

    callback($cb, $app, $obj, $original)

$obj and $original hold the object which is about to be saved, and the object as it was when this request began, respectively. This allows the callback to determine what kind of changes are being attempted in the user's request. If the request is to create a new object, $original will be a valid object reference, but the object will be "blank": it will be just what is returned by the new method on that class.

CMSPostSave

    callback($cb, $app, $obj, $original)

$obj and $original hold the object which is about to be saved, and the object as it was when this request began, respectively. When the callback routine is called, the new object as $obj has already been committed to the database. This is a convenient time to trigger follow-up actions, such as notification and static-page rebuilds.

CMSPostDelete

    callback($cb, $app, $obj)

$obj holds the object that has just been removed from the database. This callback is useful when removing data that is associated with the object being removed.

CMSUploadFile

    callback($cb, %params)

This callback is invoked for each file the user uploads to the blog. It is called for each file, regardless of type. If the user uploads an image, both the CMSUploadFile and CMSUploadImage callbacks are invoked.

Parameters

File
The full file path of the file that has been saved into the blog.
Url
The URL of the file that has been saved into the blog.
Size
The length of the file in bytes.
Type
Either 'image', 'file' or 'thumbnail'.
Blog
The MT::Blog object the uploaded file is associated with.

CMSUploadImage

    callback($cb, %params)

This callback is invoked for each uploaded image. In the case the user creates a thumbnail for their uploaded image, this callback will be invoked twice-- once for the uploaded original image and a second time for the thumbnail that was generated for it.

File
The full path and filename for the uploaded file.
Url
The full URL for the uploaded file.
Size
The length of the uploaded image in bytes.
Type
Either "image" or "thumbnail" (for generated thumbnails).
Height
The height of the image in pixels (available if Image::Size module is present).
Width
The width of the image in pixels (available if Image::Size module is present).
ImageType
The image identifier as reported by the Image::Size module. Typically, 'GIF', 'JPG' or 'PNG'.
Blog
The MT::Blog object of the blog the image is associated with.

Rebuild

    callback($cb, $blog)

$blog holds the current blog which is being rebuilt. This callback is called whenever with the CMS a blog completes the process of rebuilding.

Movable Type 4 Beta

Search This Blog

Browse Site by Category

Subscribe to MT4 News

movabletype.org

Get Help

Get Updates