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.



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).


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).


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.












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.


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


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.


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".


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.


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.


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:

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

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





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.


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.


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,


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


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.


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.


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


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.


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.


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 function that takes an array reference of strings and returns an array reference of hashes. So this:


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.


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.


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.


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.



The label to display in the list of rebuild options.


The code to execute when running the custom rebuild option.


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.


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

    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:


The code to execute when running the custom rebuild option.


The label to display in the list of rebuild options.


An identifier unique to this option (optional, will derive from the label if unavailable).


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:


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.

    callback($cb, $app, $obj)

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.


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.

    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.

    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.

    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.

    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.


  • 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.

    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.

    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.


Hey! The above document had some coding errors, which are explained below:

Around line 20041:

You forgot a '=back' before '=head3'

Around line 20067:

'=item' outside of any '=over'