UPGRADE GUIDE for Mason Hints about upgrading to various major revisions of Mason. To be completely safe, always read carefully through the Changes file and upgrade first on a test server. VERSION 1.3x (1.4?) - The minimum version of mod_perl is now 1.24. VERSION 1.1x Installation and Configuration - *** Don't use PerlFreshRestart! *** Please see the FAQ, which details a variety of error messages you might get when using PerlFreshRestart. Turn it off and check out Apache::Reload instead. - The HTML::Mason::Parser class no longer exists. If you were creating one with the default options in your handler.pl file, you can remove the Parser-related code entirely. Otherwise see the HTML::Mason::Compiler and HTML::Mason::Compiler::ToObject documentation for more details. - If you use a handler.pl that creates an Interp object and then passes that object to the ApacheHandler constructor, this will no longer work. Instead, simply pass all of the parameters for both the Interp and ApacheHandler to the ApacheHandler constructor. So this: my $interp = HTML::Mason::Interp->new( comp_root => ..., data_dir =>... ); my $ah = HTML::Mason::ApacheHandler->new( interp => $interp ); becomes this: my $ah = HTML::Mason::ApacheHandler->new( comp_root => ..., data_dir =>... ); - The use_reload_file parameter has been removed. See the documentation on the static_source parameter, which is intended to provide a similar performance enhancement. - Previous versions of Mason split the POD documentation into separate .pod files from the code, which was in .pm files. Now, these have been combined into one file, the .pm file. However, perldoc will look for a .pod file before a .pm file. During the install, we try to find these old .pod files and delete them. However, if that isn't successful, you may see the old documentation for the following modules: HTML::Mason::Interp, HTML::Mason::Request, HTML::Mason::ApacheHandler, HTML::Mason::Component. If you are experiencing this problem after installing this new version of Mason, you will need to delete the old .pod files manually. - The taint_check parameter no longer exists in any form. We now automatically detect taint mode and act appropriately to untaint component source and object files. - The use_autohandlers, use_dhandlers, and allow_recursive_autohandlers parameters have been removed, and the autohandler_name and dhandler_name parameters no longer accept undef as a valid value. - The top_level_predicate parameter has been removed. If you would like to filter requests you can do this via the new prepare_request method, which will give you a Request object that you can manipulate before deciding to serve a request. - The error_mode parameter has been replaced with two parameters, error_format and error_mode, allowing more control over how errors are processed. - The args_method parameter has changed from being an import parameter, as in use HTML::Mason::ApacheHandler (args_method => 'mod_perl'); to a regular constructor parameter, as in my $ah = HTML::Mason::ApacheHandler->new(args_method => 'mod_perl'); You should preload the Apache::Request or CGI module in your handler or httpd.conf, in order to save memory. - The default HTTP argument processor is now Apache::Request instead of CGI.pm. This entails several differences: - Apache::Request treats parameters case-insensitively for purposes of grouping. This would only be a problem if you expect two arguments that differ only by case (e.g. "mode" and "MODE"). - Apache::Request always parses the query string, even for POST requests. - The out_mode parameter (batch vs. stream) has been replaced with the autoflush parameter, which is a much simpler version of the same idea. See the Request class documentation for details. - The ApacheHandler module now requires a minimum of mod_perl 1.22 (though using something more up to date is highly recommended). - The ApacheHandler module will take care of chown'ing files created during server startup, when needed. If you have a line like chown (Apache->server->uid, Apache->server->gid, $interp->files_written); in your handler.pl, it is now unnecessary (but harmless). - The MasonMultipleConfig parameter is no longer needed, and will cause an error if given. Mason can now figure out for itself whether or not multiple ApacheHandler objects should be created. - The debug file feature has been removed, as it could not accurately support multiple versions of the Apache API. Use Apache::DB to run your server through the debugger. - The Previewer feature has been removed, as it relied on specific internals that were changed. It will hopefully return better and stronger in a future release. Data Caching Data caching has been completely rebuilt on top of Cache::Cache. This means: - The syntax of $m->cache and $m->cache_self have changed. However, the original API can still be used for a while by setting data_cache_api to '1.0'. - Cache files have a different pathname and format; old cache files can be removed. - The access_data_cache utility is no longer supported. See "Accessing a Cache Externally" in the Developer's manual for instructions on how to replace access_data_cache. Semantics - In older versions of Mason, calls to $m->flush_buffer were ineffective when output needed to go through a <%filter>. In 1.1x, the filter may be called multiple times, each time with new output. Component Syntax - The "mc_" style commands, deprecated in 0.8, are no longer supported. You will need to update to $m methods. The utility bin/convert0.8.pl can help with this. - The "perl_" prefix for Mason tags (like <%perl_args>), deprecated in 0.6, is no longer supported. You will need to remove this prefix. The utility bin/convert0.6.pl can help with this. - The |h escape flag now uses HTML::Entities::encode instead of just encoding <, >, ", and &. This module escapes control and high-ascii characters properly for ISO-8859-1 pages. However, it will wreak havoc with different encodings. You can get the 1.0x behavior with $ah->interp->set_escape( h => \&HTML::Mason::Escapes::basic_html_escape ); - The backslash character now eliminates a newline at the end of any line, not just before %-lines and section tags. - The run_count and first_time component object methods have been deprecated, as they cannot be implemented reliably (see bug #209). Use a manual counter variable declared in <%once> instead. - $m->top_args and $m->top_comp have been renamed to $m->request_args and $m->request_comp, respectively. The old method names have been deprecated but will continue to work for a while. - The Component class's create_time method has been renamed to load_time, which better reflects its semantics. create_time is deprecated but will continue to work for a while. - The Interp class's time method and current_time parameters are deprecated but will continue to work for a while. VERSION 0.85 - Autohandlers are now recursive by default. If your site uses directory-specific autohandlers depending on the default value of allow_recursive_autohandlers=0, you must explicitly pass allow_recursive_autohandlers=>0 when creating the Interp. - All applicable autohandlers now get a chance to run. If your site has multiple autohandlers in parent/child directories, you'll likely get display problems when upgrading (e.g. multiple templates showing up per page). For a short-term fix, place <%flags> inherit=>undef </%flags> in every autohandler. Ideally, in the long-term you'll be able to make the autohandlers work well together. - When calling components, base_comp now gets set to the called components, _unless_ you call a component with a component object or your component call starts with SELF: or PARENT:. So a call like this: <& /some/comp, foo => 1 &> causes the return value of $m->base_comp to be the "/some/comp" component object inside the "/some/comp" component. But this: <& $some_comp_obj, foo => 1 &> does not change what $m->base_comp returns. VERSION 0.8 - Version 0.8 sports a new request API. $m now contains the current request object, and all mc_ commands have been incorporated into $m methods. The utility bin/convert0.8.pl converts existing components to use the new syntax. See Commands.pod for a manual conversion guide and a list of rare conversion problems.