{
    "content": [
        {
            "type": "text",
            "text": "# HTML::Mason::Subclassing (perldoc)\n\n## NAME\n\nHTML::Mason::Subclassing - Documentation on Subclassing Internal Mason classes\n\n## DESCRIPTION\n\nThis is the deep voodoo guide, for folks who want to create their own custom subclasses for\nparts of Mason, such as the Request or Interp objects.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **Class::Container**\n- **SUBCLASSABLE CLASSES**\n- **CONSTRUCTORS**\n- **Request** (2 subsections)\n- **Resolver and ComponentSource**\n- **Lexer**\n- **Compiler**\n- **ApacheHandler**\n- **USING SUBCLASSES**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "HTML::Mason::Subclassing",
        "section": "",
        "mode": "perldoc",
        "summary": "HTML::Mason::Subclassing - Documentation on Subclassing Internal Mason classes",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "Class::Container",
                "lines": 16,
                "subsections": []
            },
            {
                "name": "SUBCLASSABLE CLASSES",
                "lines": 42,
                "subsections": []
            },
            {
                "name": "CONSTRUCTORS",
                "lines": 15,
                "subsections": []
            },
            {
                "name": "Request",
                "lines": 66,
                "subsections": [
                    {
                        "name": "Subrequests",
                        "lines": 4
                    },
                    {
                        "name": "Examples",
                        "lines": 2
                    }
                ]
            },
            {
                "name": "Resolver and ComponentSource",
                "lines": 13,
                "subsections": []
            },
            {
                "name": "Lexer",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "Compiler",
                "lines": 12,
                "subsections": []
            },
            {
                "name": "ApacheHandler",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "USING SUBCLASSES",
                "lines": 43,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "HTML::Mason::Subclassing - Documentation on Subclassing Internal Mason classes\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This is the deep voodoo guide, for folks who want to create their own custom subclasses for\nparts of Mason, such as the Request or Interp objects.\n",
                "subsections": []
            },
            "Class::Container": {
                "content": "A number of modules in Mason are subclasses of \"Class::Container\". This module was originally\npart of the Mason core as \"HTML::Mason::Container\", but Ken Williams decided to release it\nseparately on CPAN.\n\nIt was created to encapsulate some common behaviors for Mason objects such as parameter\nvalidation and the creation of \"contained\" objects.\n\nBasically, any Mason object which takes parameters to its constructor must inherit from this\nmodule. Of course, since all of the classes that you might consider subclassing already inherit\nfrom \"Class::Container\", you won't need to inherit from it directly. However, you may need to\nuse some of its methods.\n\nSo before you go further we highly recommend familiarizing yourself with \"Class::Container\" and\nits methods. Also feel free to look at some of the Mason core modules to see how\n\"Class::Container\" is used within Mason itself.\n",
                "subsections": []
            },
            "SUBCLASSABLE CLASSES": {
                "content": "The following classes have been designed with subclassing in mind:\n\n*   HTML::Mason::Request\n\nThis object is your old friend $m. The request contains information about the current\nrequest context, and provides methods for calling other components.\n\n*   HTML::Mason::Resolver\n\nThe resolver's job is to translate a component paths into an actual component. Mason comes\nwith a single Resolver subclass, \"HTML::Mason::Resolver::File\", which is used to translate\ncomponent paths into filesystem paths.\n\n*   HTML::Mason::ComponentSource\n\nAn object of this class represents a component's source. These objects are instantiated by\nthe resolver when it finds a component matching a given path.\n\n*   HTML::Mason::Lexer\n\nThe lexer is responsible for parsing a component. Creating a new lexer would allow you to\nchange Mason's component syntax.\n\n*   HTML::Mason::Compiler\n\nThe compiler takes the parsed chunks from the lexer and gives them meaning. The default\ncompiler, \"HTML::Mason::Compiler::ToObject\", turns a Mason component into a Mason \"object\nfile\", which contains actual Perl code.\n\n*   HTML::Mason::ApacheHandler\n\nThe ApacheHandler class is the bridge between the modperl world and Mason, primarily\nMason's Interp class.\n\nIt also provides its own \"HTML::Mason::Request\" and \"HTML::Resolver::File\" subclasses which\nimplement some modperl specific behaviors and features.\n\n*   HTML::Mason::Interp\n\nThe Interp is the core of Mason, and is primarily responsible for making all the other\nobjects do their jobs.\n",
                "subsections": []
            },
            "CONSTRUCTORS": {
                "content": "If you choose to override the constructor, which is always \"new\" with Mason objects, that you\nmake sure to call the superclass's constructor and that you use the object returned by it. A\ngood boilerplate for an overridden constructor looks something like this:\n\nsub new\n{\nmy $class = shift;\n\nmy $self = $class->SUPER::new(@);\n\n$self->dosomeinit;\n\nreturn $self;\n}\n",
                "subsections": []
            },
            "Request": {
                "content": "What to Subclass?\nOne important thing to know about this class is that it is actually several classes. The first,\n\"HTML::Mason::Request\", is used when ApacheHandler is not loaded. The other,\n\"HTML::Mason::Request::ApacheHandler\", is loaded by ApacheHandler and used to provide some\nmodperl specific features. Similar, the CGIHandler class provides its own request subclass,\n\"HTML::Mason::Request::CGIHandler\".\n\nIt is impossible to know which one of these to subclass at compile time, since it is possible\nthat your subclass will be loaded before either ApacheHandler or CGIHandler.\n\nTo handle this, simply call the \"altersuperclass()\" method in your constructor, like this:\n\nsub new\n{\nmy $class = shift;\n\n$class->altersuperclass( $HTML::Mason::ApacheHandler::VERSION ?\n'HTML::Mason::Request::ApacheHandler' :\n$HTML::Mason::CGIHandler::VERSION ?\n'HTML::Mason::Request::CGI' :\n'HTML::Mason::Request' );\n\nmy $self = $class->SUPER::new(@);\n\n...\n\nreturn $self;\n}\n\nIt is quite important that you do this as these handler-specific subclasses provide important\nfunctionality. The \"altersuperclass()\" method is implemented in the \"HTML::Mason::Request\" base\nclass, and will do the right thing even in cases of multiple inheritance. It also cooperates\nwith \"Class::Container\" to make sure that it sees changes to the inheritance hierarchy.\n\nThe exec() method\nThe \"exec\" method is called in order to execute a request, and is the method that you are most\nlikely to want to override.\n\nHowever, if you do override it we suggest that you make sure to call the parent class's \"exec\"\nmethod to implement the actual component execution and there is no need for you to re-implement\nthem.\n\nSince the \"exec()\" method is scalar/list context-sensitive, your \"exec\" method will need to\npreserve that. Here is a boilerplate:\n\nsub exec\n{\nmy $self = shift;\n\n... # do something cool\n\nmy @r;\nif (wantarray)\n{\n@r = $self->SUPER::exec(@);\n}\nelse\n{\n$r[0] = $self->SUPER::exec(@);\n}\n\n... # maybe do some cleanup\n\nreturn wantarray ? @r : $r[0];\n}\n",
                "subsections": [
                    {
                        "name": "Subrequests",
                        "content": "Your custom request class will also be used to implement subrequests, which are implemented by\ncalling \"exec\" just like any other method. If you only want to do certain things in \"exec\" for\nthe first request, you can simply check the value of \"$self->issubrequest\".\n"
                    },
                    {
                        "name": "Examples",
                        "content": "See the \"MasonX::Request::WithApacheSession\" module on CPAN.\n"
                    }
                ]
            },
            "Resolver and ComponentSource": {
                "content": "The resolver takes a component path and figures out what component that path corresponds to.\n\nAll resolver classes must implement two methods, \"getinfo\" and \"globpath\". The first takes a\ncomponent path and returns a new \"HTML::Mason::ComponentSource\" object. This object contains\ninformation about the component, such as its last modified time and its source. See the\n\"HTML::Mason::ComponentSource\" documentation for more details.\n\nYou may choose to provide your own ComponentSource subclass as well, if your resolver\nimplementation can take advantage of it.\n\nThe \"globpath\" method is responsible for translating a component path like /foo/*/bar into a\nlist of component paths that match that glob pattern.\n",
                "subsections": []
            },
            "Lexer": {
                "content": "The rationale for providing your own lexer would be to extend or replace Mason's syntax.\n\nThe lexer is called by the compiler via its \"lex\" method. The arguments it receives are the\ncomponent name, source, and the compiler object. See the Compiler class documentation for\ndetails on what methods the lexer can call.\n",
                "subsections": []
            },
            "Compiler": {
                "content": "See the Compiler class documentation for details on what methods a subclass of this class needs\nto provide.\n\nIf you simply want to tweak Mason's existing behavior, you will probably want to subclass\n\"HTML::Mason::Compiler::ToObject\", which is the default Compiler class. For example, if you\nwanted to do something like make attributes dynamic, you could override the \"flagsorattr()\"\nmethod in ToObject.\n\nIf you want to drastically change the behavior, you can subclass \"HTML::Mason::Compiler\"\ninstead. An example of this would be creating a compiler that generates \"EmbPerl\" or\n\"Apache::ASP\" as output.\n",
                "subsections": []
            },
            "ApacheHandler": {
                "content": "The methods that you are most likely to want to subclass are documented in the \"ApacheHandler\nclass\" documentation.\n\nProviding an ApacheHandler subclass gives you a chance to do your own client parameter parsing,\nas well as the capability of providing a different way of handling requests.\n\nCGIHandler\nLike the ApacheHandler, you could subclass this module in order to provide your own argument\nprocessing or to step in and provide a different way to handle requests.\n",
                "subsections": []
            },
            "USING SUBCLASSES": {
                "content": "When using your custom subclasses, we recommend that you take advantage of Mason's ability to\nconstruct subclassed object on the fly.\n\nFor example, if you're subclassed the Interp object, you can still let the ApacheHandler object\ncreate the Interp object for you, as long as you give it the appropriate interpclass parameter.\nThis is important because Mason may internally set up certain defaults for contained objects.\nFor example, the ApacheHandler, by default, will tell the Interp object to use the\n\"HTML::Mason::Request::ApacheHandler\" Request subclass. If you create an Interp object manually\nand you want to use that Interp object with ApacheHandler, you'll have to specify the same\nRequest class.\n\nFor example:\n\nmy $interp =\nMy::Interp->new\n( requestclass  => 'HTML::Mason::Request::ApacheHandler',\nmynewinterpparam => 42,\n);\n\nmy $ah = HTML::Mason::ApacheHandler->new( interp => $interp );\n\nIt is far easier to simply do this:\n\nmy $ah =\nHTML::Mason::ApacheHandler->new\n( interpclass => 'My::Interp',\nmynewinterpparam => 42,\n);\n\nYour new parameter, \"mynewinterpparam\", will still be passed to the \"My::Interp\" constructor,\nbut this also gives ApacheHandler a chance to set various parameters for the Interp object. Of\ncourse, you can still override these defaults explicitly:\n\nmy $ah =\nHTML::Mason::ApacheHandler->new\n( interpclass => 'My::Interp',\nresolverclass => 'My::Resolver'.\nmynewinterpparam => 42,\n);\n\nIf you need access to the interp object's methods directly, it will be always be available via\n\"$ah->interp\".\n",
                "subsections": []
            }
        }
    }
}