view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    location, and process it's own way:

    1   If requested file exists then nothing happens. The handle declines
        request with "DECLINE".

    2   Otherwise the instance of Apache::JAF's descendant is created and
        "setup_handler" method is called. You must override this method and
        return determined handler's name. Usually it's the first part of URI
        or just "index". Also handlers from "Apache_JAF_Modules" folder is
        loaded into package's namespace if "$self->{debug_level}" > 0 or
        handlers were not loaded during module compilation.

    3   Then goes "site_handler" calling. If you have common tasks for each
        handler you can override it. "site_handler" calls your own handler.
        It's name is returned by "setup_handler". Usually this
        "mini-handler" is *very* simple. It have to be implemented as
        package method with "do_*<handler name>*" name. You have to fill
        "$self->{res}" hash with result and return Apache constant according
        to handler's logic ("OK", "NOT_FOUND", "FORBIDDEN" and so on). The
        sample is shown in "SYNOPSIS".

    4   If the previous step fulfills correctly, and "$self->{type}"
        property is "text/*" then result of processing template returns to
        client. If type of result is not like text, one more method is
        needed to implement: "on_send_*<handeler name>*_data". It must
        return binary data to client. This way you may create handlers for
        dynamic generation of images, M$ Excel workbooks and any other type
        of data.

  Apache::JAF methods
    setup_handler
        This method you must override in your Apache::JAF descendant. You
        must return handler's name (that will be called as *do_<handler
        name>* method later) from it depending on URI requested by user. You
        may set site-wide properties such as *debug_level*, *header* or
        *footer*, templates and includes extensions and so on. If handler
        name depends on application logic implemented in modeller then you
        have to create modeller in this method and store it in *m* property
        for later use. The primary *setup_handler* is shown in "SYNOPSIS".

    site_handler
        You can override this method to provide common tasks for each of
        your page-handlers. For example you may create instance of modeller
        class, provide some custom authorization/authentication or sessions
        handling and so on. You must call "$self>SUPER::site_handler" and
        return "$self->{status}" from it.

  Apache::JAF properties
    r   Current "Apache::Request" object.

    filter
        Using "Apache::Filter" flag.

    uri Reference to the array of current URI (splitted by slash). Usually
        you need to modify it in "setup_handler" method to determine page's
        handler name. Remained array will be passed to the page-handler
        method as a list of parameters.

    res Hash reference that holds page-handler results.

    expand_path
        Boolean flag for complex-name-handlers changes '_' to '/' in
        handler's name. It provides real-like document tree in the templates
        folder.

    debug_level
        Look at Apache_JAF_Debug in "CONFIGURATION" section.

    status
        Default handler status is "NOT_FOUND".

    type
        Default content-type is "text/html". You can call
        "$self->download_type()" for set unexisting MIME-type to force
        browser download content instead of viewing it.

    template_ext, include_ext
        Default template extension is ".html". Default include template
        extension is ".inc".

    default_include
        Site-wide include template. Default value is... "default".

    header, footer
        Site-wide pre- and post-include templates. Defalut values are
        "header" and "footer". *Note:*You must undef this properies if you
        want create page-template without it. For example for page in pop-up
        window ("disable_header", "disable_footer", and
        "disable_header_footer" methods).

    templates
        Path to the templates folder. You may have different sets of
        templates for different views of results generated by your
        page-handlers.

    handler
        Result of "setup_handler" method is stored here for later use.

    *other properites*
        For internal use only.

  Implementing handlers
    Page handlers are simple. Their methods are with "do_<handler name>"
    name. You have to analyse given parameters, fill out "$self->{res}" hash
    with handler results that will be processed with template and return one
    of "Apache::Constants". Usually it's "OK", but may be "NOT_FOUND" if
    parameters passed to handlers are invalid for some reason.

    Look into examples/* folder in the distribution package for some
    guidelines.

  Templates structure and syntax
    Template for a specific handler consists of:

    1 default.inc
        Common "[% BLOCK %]"s for all site templates. Processed before
        header and main tamplate.

    2 header.inc
        Header template. Processed before main handler's template.