Index: branches/release-41/lib/MT.pm.pre =================================================================== --- branches/release-41/lib/MT.pm.pre (revision 2667) +++ branches/release-41/lib/MT.pm.pre (revision 2744) @@ -330,7 +330,4 @@ my $pkg = shift; - # if (!ref $pkg) { - # return $pkg->instance->registry(@_); - # } require MT::Component; my $regs = MT::Component->registry(@_); @@ -2829,5 +2826,5 @@ =back -=head2 $mt->init +=head2 $mt->init(%params) Initializes the Movable Type instance, including registration of basic @@ -2835,4 +2832,29 @@ and C methods. +=head2 $mt->init_core() + +A method that the base MT class uses to initialize all the 'core' +functionality of Movable Type. If you want to subclass MT and extensively +modify it's core behavior, this method can be overridden to do that. +The L module is a L that defines the core +features of MT, and this method loads that component. Non-core components +are loaded by the L method. + +=head2 $mt->init_paths() + +Establishes some key file paths for the MT environment. Assigns +C<$MT_DIR>, C<$APP_DIR> and C<$CFG_FILE> package variables. + +=head2 $mt->init_permissions() + +Loads the L class and runs the +MT::Permission->init_permissions method to establish system permissions. + +=head2 $mt->init_schema() + +Completes the initialization of the Movable Type schema following the +loading of plugins. After this method runs, any MT object class may +safely be used. + =head2 MT->instance @@ -2841,4 +2863,8 @@ MT->new() is now an alias to instance_of. +=head2 MT->app + +An alias for the 'instance' method. + =head2 $class->instance_of @@ -2853,4 +2879,19 @@ Assigns the active MT instance object. This value is returned when Cinstance> is invoked. + +=head2 MT->run_app( $pkg, $params ) + +Instantiates and runs a MT application (identified by C<$pkg>), passing +the C<$params> hashref as the parameters to the constructor method. This +method is a self-contained version found in L and will +eventually be the manner in which MT applications are run (eliminating +the need for the bootstrap module). The MT::import module calls this +method when the MT module is used with an 'App' parameter. So, you can +write a mt.cgi script that looks like this: + + #!/usr/bin/perl + use strict; + use lib $ENV{MT_HOME} ? "$ENV{MT_HOME}/lib" : 'lib'; + use MT App => 'MT::App::CMS'; =head2 $mt->find_config($params) @@ -2863,11 +2904,23 @@ =head2 $mt->init_config($params) -Reads the MT configuration settingss from the MT configuration file -and settings from database (L). +Reads the MT configuration settingss from the MT configuration file. The C<$params> parameter is a reference to the hash of settings passed to the MT constructor. -=head2 $mt->init_plugins +=head2 $mt->init_config_from_db($param) + +Reads any MT configuration settings from the MT database (L). + +The C<$params> parameter is a reference to the hash of settings passed to +the MT constructor. + +=head2 $mt->init_addons(%param) + +Loads any discoverable addons that are available. This is called from +the C method, after C method has loaded the +configuration settings, but prior to making a database connection. + +=head2 $mt->init_plugins(%param) Loads any discoverable plugins that are available. This is called from @@ -2875,5 +2928,10 @@ configuration settings. -=head2 $mt->init_tasks +=head2 $mt->init_callbacks() + +Installs any MT callbacks. This is called from the C method very, +early; prior to loading any addons or plugins. + +=head2 $mt->init_tasks() Registers the standard set of periodic tasks that Movable Type provides @@ -2885,4 +2943,13 @@ through L to run any registered tasks that are pending execution. See L for further documentation. + +=head2 MT->find_addons( $type ) + +Returns an array of all 'addons' that are found within the MT 'addons' +directory of the given C<$type>. What is returned is an array reference +of hash data. Each hash will contain these elements: 'label' (the name +of the addon), 'id' (the unique identifier of the addon), 'envelope' +(the subpath of the addon, relative to the MT home directory), and 'path' +(the full path to the addon subdirectory). =head2 MT->unplug @@ -3198,4 +3265,72 @@ C routine. +=head2 MT->handler_to_coderef($handler[, $delayed]) + +Translates a registry handler signature into a Perl coderef. Handlers +are in one of the following forms: + + $:::: + + :: + + -> + + sub { ... } + +When invoked with a '-E' operator, the subroutine is invoked as +a package method. + +When the handler is a string that starts with 'sub {', it is eval'd +to compile it, and the resulting coderef is returned. + +The coderef that is returned can be passed any parameters you wish. + +When the coderef is invoked, any component that was identified in +the handler signature becomes the active component when running the +code (this affects how strings are translated, and the search paths +for templates that are loaded). + +If the C<$delayed> parameter is given, a special coderef is constructed +that will delay the 'require' of the identified Perl package until +the coderef is actually invoked. + +=head2 MT->registry( @path ) + +Queries the Movable Type registry data structure for a given resource +path. The MT registry is a collection of hash structures that contain +resources MT and/or plugins can utilize. + +When this method is invoked, it actually issues a registry request +against each component registered with MT, then merges the resulting +hashes and returns them. See L for further details. + +=head2 MT->component( $id ) + +Returns a loaded L based on the requested C<$id> parameter. +For example: + + # Returns the MT 'core' component + MT->component('core'); + +=head2 MT->model( $id ) + +Returns a Perl package name for the MT object type identified by C<$id>. +For example: + + # Assigns (by default) 'MT::Blog' to $blog_class + my $blog_class = MT->model('blog'); + +It is a recommended practice to utilize the model method to derive the +implementation package name, instead of hardcoding Perl package names. + +=head2 MT->models( $id ) + +Returns a list of object types that are registered as sub-types. For +instance, the MT 'asset' object type has several sub-types associated +with it: + + my @types = MT->models('asset'); + # @types now contains ('asset', 'asset.image', 'asset.video', etc.) + =head2 MT->product_code @@ -3214,4 +3349,16 @@ and C methods as they report the API version information. +=head2 MT->VERSION + +Returns the API version of MT. When using the MT module with the version +requirement, this method will also load the suitable API 'compatibility' +module, if available. For instance, if your plugin declares: + + use MT 4; + +Then, once MT 5 is available, that statement will cause the C method +to attempt to load a module named "MT::Compat::v4". This module would contain +compatibility support for MT 4-based plugins. + =head2 MT->version_id @@ -3228,4 +3375,13 @@ Returns the version of the MT database schema. +=head2 $mt->id + +Provides an identifier for the application, one that relates to the +'application' paths of the MT registry. This method may be overridden +for any subclass of MT to provide the appropriate identifier. By +default, the base 'id' method will return an id taken from the +Perl package name, by stripping off any 'MT::App::' prefix, and lowercasing +the remaining string. + =head2 MT->version_slug @@ -3252,4 +3408,130 @@ An alias to L. See L for documentation of this method. + +=head2 $mt->rebuild_archives + +An alias to L. See +L for documentation of this method. + +=head2 $app->template_paths + +Returns an array of directory paths where application templates exist. + +=head2 $app->find_file(\@paths, $filename) + +Returns the path and filename for a file found in any of the given paths. +If the file cannot be found, it returns undef. + +=head2 $app->load_tmpl($file[, @params]) + +Loads a L template using the filename specified. See the +documentation for the C method to learn about how templates +are located. The optional C<@params> are passed to the L +constructor. + +=head2 $app->set_default_tmpl_params($tmpl) + +Assigns standard parameters to the given L C<$tmpl> object. +Refer to the L section for a +complete list of these parameters. + +=head2 $app->charset( [$charset] ) + +Gets or sets the application's character set based on the "PublishCharset" +configuration setting or the encoding of the active language +(C<$app-Ecurrent_language>). + +=head2 $app->build_page($tmpl_name, \%param) + +Builds an application page to be sent to the client; the page name is specified +in C<$tmpl_name>, which should be the name of a template containing valid +L markup. C<\%param> is a hash ref whose keys and values will +be passed to L for use in the template. + +On success, returns a scalar containing the page to be sent to the client. On +failure, returns C, and the error message can be obtained from +C<$app-Eerrstr>. + +=head3 How does build_page find a template? + +The C function looks in several places for an app +template. Two configuration directives can modify these search paths, +and application and plugin code can also affect them. + +The I config directive is an absolute path to the directory +where MT's core application templates live. It defaults to the I +plus an additional path segment of 'tmpl'. + +The optional I config directive is a path (absolute +or relative) to a directory where some 'override templates' may +live. An override template takes the place of one of MT's core +application templates, and is used interchangeably with the core +template. This allows power users to customize the look and feel of +the MT application. If I is relative, its base path +is the value of the Movable Type configuration file. + +Next, any application built on the C foundation can define +its own I parameter, which identifies a subdirectory of +TemplatePath (or AltTemplatePath) where that application's templates +can be found. I defaults to C. Most templates will +be found in this directory, but sometimes the template search will +fall through to the parent directory, where a default error template +is found, for example. I should rightly have been named +I, since it is application-specific. + +Finally, a plugin can specify its I, which +locates a directory where the templates for that plugin's own +interface are found. If the I is relative, it +may be relative to either the I, or the I; the former +takes precedence if it exists. (for a definition of I and +I, see L) + +Given these values, the order of search is as follows: + +=over 4 + +=item * I + +=item * I + +=item * IFI + +=item * I/I + +=item * I + +=back + +If a template with the given name is not found in any of these +locations, an ugly error is thrown to the user. + +=head2 $app->build_page_in_mem($tmpl, \%param) + +Used internally by the L method to render the output +of a L object (the first parameter) using the parameter +data (the second parameter). It additionally calls the L +method (to process any EMT_ACTIONE and EMT_X:YE marker tags) +and then L (to process any EMT_TRANSE tags). + +=head2 $app->process_mt_template($str) + +Processes the E__action tags that are present in C<$str>. These tags +are in the following format: + + <__action mode="mode_name" parameter="value"> + +The mode parameter is required (and must be the first attribute). The +following attributes are appended as regular query parameters. + +The MT_ACTION tag is a preferred way to specify application links rather +than using this syntax: + + ?__mode=mode_name¶meter=value + +C also strips the C<$str> variable of any tags in +the format of CMT_\w+:\w+E>. These are 'marker' tags that are +used to identify specific portions of the template page and used in +conjunction with the transformer callback helper methods C, +C, C, C. =head2 $mt->build_email($file, $param) @@ -3266,4 +3548,108 @@ entry that is scheduled for publishing. The return value is the timestamp in UTC time in the format "YYYY-MM-DDTHH:MM:SSZ". + +=head2 $mt->commenter_authenticator($id) + +Returns a specific comment authenication option using the identifier +C<$id> parameter. + +=head2 $mt->commenter_authenticators() + +Returns the available comment authentication identifiers that are +installed in the MT registry. + +=head2 $mt->core_commenter_authenticators() + +A method that returns the MT-supplied comment authentication registry +data. + +=head2 $mt->init_commenter_authenticators() + +Initializes the list of installed MT comment authentication options, +drawing from the MT registry. + +=head2 $mt->captcha_provider($id) + +Returns a specific CAPTCHA provider configuration using the identifier +C<$id> parameter. This is a convenience method that accesses the CAPTCHA +providers installed into the MT registry. + +=head2 $mt->captcha_providers() + +Returns the available CAPTCHA providers. This is a convenience method +that accesses the MT registry for available CAPTCHA providers (it also +invokes the 'condition' key for each provider to filter the list). + +=head2 $mt->core_captcha_providers() + +A method that returns the MT-supplied CAPTCHA provider registry data. + +=head2 $mt->init_captcha_providers() + +Initializes the list of installed CAPTCHA providers, drawing from +the MT registry. + +=head2 $mt->effective_captcha_provider() + +Returns the Perl package name for the configured CAPTCHA provider. + +=head2 $app->static_path() + +Returns the application's static web path. + +=head2 $app->static_file_path() + +Returns the application's static file path. + +=head2 MT::core_upload_file_to_sync + +A MT callback handler routine that forwards to the L +method. + +=head2 MT->upload_file_to_sync(%param) + +A routine that will make record of a file that is to be transmitted +to one or more servers (typically via rsync). This method runs when +the C MT configuration setting is configured. Normally +published files are automatically processed for syncing operations, +but this routine is used for files that are created through other +means, such as uploading an asset. + +=head2 MT->help_url( [ $suffix ] ) + +Returns a help URL for the application. This method is used to construct +the URL directing users to online documentation. If called without any +parameters, it returns the base URL for providing help. If a parameter is +given, the URL is appended with the given subpath. The base URL by default +is 'http://www.movabletype.org/documentation/'. This string is passed +through MT's localization modules, so it can be changed on a per-language +basis. The C<$suffix> parameter, however, is always appended to this base URL. + +=head2 MT->get_timer + +Returns an instance of L for use in timing MT's +operations. + +=head2 MT->log_times + +Used as part of Movable Type's performance logging framework. This method +is called internally, once at the startup of Movable Type, and once as it +is shutting down. + +=head2 MT->time_this($string, $code) + +Utility method to time a particular routine. This will log the execution +time of the C<$code> coderef with the identifying phrase C<$string> using +MT's performance logging framework. + +=head2 MT::refresh_cache($cb) + +A callback handler that invalidates the cache of MT's caching driver. +See L. + +=head2 MT->register_refresh_cache_event($callback) + +Registers a callback that will cause the MT cache to invalidate itself. +See L. =head1 ERROR HANDLING