NAME

       Jifty::View::Declare::Page::NewStyle - new style page wrapper to simplify customization
       and reuse.

DESCRIPTION

       This library is a replacement for Jifty::View::Declare::Page.  That is in Jifty for a
       while and can not be replaced with something completely different because of backwards
       compatibility.

       When you declare a Jifty::View::Declare template that is a page, for example:

           template 'news' => page {
               ...
           };

       Page classes come into game. First of all App::View::Page is loaded (it's not true and
       there is a way to define class for particular page, but lets leave it alone as interface
       is not settled enough to be discussed). If the app class doesn't exist then default
       Jifty::View::Declare::Page is used. Code block right after page token is used to render
       core of the page wrapped into some layout.  Page classes implement such layouts.

       It's very hard to extended Jifty::View::Declare::Page class as it's written in such a way
       that forces you to copy&paste some internals from the class to make overridden method work
       and don't break things.

       I think this implementation is much better thing. To use this class as a base for all your
       pages you can just add this plugin to your app and simple YourApp::View::Page will be
       generated for you. However, if you're here then you want to change layout, your
       App::View::Page should be something like:

           package MyApp::View::Page;
           use base qw(Jifty::Plugin::ViewDeclarePage::Page);
           use Jifty::View::Declare::Helpers;

           ...

           1;

DIFFERENCES FROM DEFAULT PAGE CLASS

       no calls into templates
           Yes, that's it. No call to show('/menu'), instead it's a method "render_navigation"
           here. Why? If it's subclassable then there is no need to split functionality between
           different modules. You can always return old behavior by using:

               sub render_navigation { show(/menu) }

       no render_pre_content_hook
           override "render_content".

       title is always rendered in page
           Even when there is no 'page_title is ...' in the content code, see
           "instrument_content" and "render_title_inpage".

       no html in title
           All HTML is just escaped. 99% of apps don't want to put tags inside title. Sure, it's
           wrapped into <h1> tag. See "render_title_inpage"

       new 'add rel ...' and 'add rev ...'
           Can be used in the content code to define feeds, relative links and other cool stuff.
           See "instrument_content" and "render_link_inpage".

       at last
           It's documented!

ACCESSORS

       content_code
           Code reference that renders the core of the page, this is code block right after page
           token in the following example:

               template 'news' => page {
                   ...
               };

           Is set by jifty during construction of the page object.

       _meta
           A hash reference that is set by jifty during construction of the page object. It's
           empty unless you use the following syntax:

               template my_page => page { some => 'value', ... } content {
                   ...
               };

           In this case _meta is a reference to the hash that goes right after page token and
           content_code is after content token.

       _title and _links
           These are internal temporary holders of corresponding data.

METHODS

   Initialization and rendering driver
       new

       Sets up a new page class. Called by Jifty with content_code and optional _meta.

       Calls "init" right before returning new instance of the class.

       init

       Sets _title accessor from 'title' in _meta if the latter is defined, so you can do the
       following if title of a page is static:

           template news => page { title => _('News') } content {
               ...
           };

       render

       Renders whole page from doctype till closing html tag. Takes no arguments.

       This method drives rendering of the page. Page is split into three major parts: header,
       body and footer. Each is implemented as corresponding method with 'render_' prefix.

       It worth to note that order of rendering is changed and header is rendered after the body
       to allow you define page title, RSS feeds and other things in content. Read more about
       this below in "render_header" and "instrument_content".

   Main blocks of the page
       render_header

       Renders an HTML "doctype" and complete <head> tag. Usually you don't want to override
       this. This method is rendered after body and main content of the page, so all things you
       need in head tag you can define in content.

       doctype
           Calls "render_doctype".

       "page_title is ..."
           You can define dynamic title using the following:

               template some => page {
                   my $page_title = ...;
                   ...
                   page_title is $page_title;
                   ...
               };

           Don't want to define dynamic title then as well you can use syntax described in "init"
           above.

           When 'page_title is' is used in the content code, "render_title_inpage" is called,
           read more in "instrument_content".

           "render_title_inhead" is called during rendering of the head tag, so you can change
           title there as well by subclassing that method.

       tag <link>, "add rel ..." and "add rev ..."
           You can add <link> tags right from the content using the following syntax:

               add rel "alternate",
                   type => "application/atom+xml",
                   title => _('Updated this week'),
                   href => '/feeds/atom/recent',
               ;

           When these constructions are used, "render_link_inpage" is called so you can add
           something right in the page content, for example RSS image with link to the feed. See
           also "instrument_content".

           "render_links_inhead" is called during rendering of the head tag.

       css and js
           Links to CSS and JS files are rendered for you using "include_css" in Jifty::Web and
           "include_js" in Jifty::Web functions.

           Read docs around those methods and Jifty::Manual on adding your own styles and
           scripts.

       meta
           Not implemented, but will be as soon as syntax will be defined.

       render_body

       Renders body tag, declares that we're in body and calls "render_page" that actually
       defines layout of the body. "render_page" method is better target for subclassing instead
       of this.

       render_footer

       Renders the page footer - </html> tag :)

   Body layout
       render_page

       Renders the skeleton of the page and then calls "instrument_content" to prepare and
       finally render "content_code" using "render_content".

       Default layout of the page is the following:

           <div>
             <div>
               this->render_salutation
               this->render_navigation
             </div>
             <div id="content"><div>
               this->instrument_content
               this->render_jifty_page_detritus
             </div></div>
           </div>

       instrument_content

       Something you don't want ever touch. However, does the following:

       setups local 'page_title is ...' handler which calls "render_title_inpage" if 'page_title
       is' is used.
       if 'page_title is' is not used then calls "render_title_inpage" after and put result into
       output stream before the content.
       setup handler for 'add rel ...' and 'add rev ...', that calls "render_link_inpage" and
       fills _links accessor.
       sure calls "render_content".

       render_content

       Renders content of the page - "content_code".

   Helpers
       render_doctype

       Renders default doctype (HTML5) and opening "<html>" tag

       render_title_inhead

       Should output nothing but a title tag what will be placed into the head.  Title is passed
       as only argument. Arguments are combined.

       render_title_inpage

       Renders the in-page title, followed by page navigation and jifty messages.

       See "render_title_inhead", "instrument_content" and "render_header".

       render_links_inhead

       Renders link tags which are passed as list of hashes.

       render_link_inpage

       Do nothing by default, but link as a hash is passed when content has 'add rel ...' or 'add
       rev ...'.

       Read more in "render_header" and "instrument_content".

       render_navigation

       Renders "navigation" in Jifty::Web as menu wrapped into a div with id 'navigation'. There
       is as well page_navigation in Jifty that is rendered in "render_title_inpage" by default.

       Called from "render_page".

       render_salutation

       Renders salutation for the current user wrapped into div with id equal to 'salutation'.
       Called from "render_page".

       render_jifty_page_detritus

       Renders admin mode warning, the wait message, the keybindings and PubSub javascript.
       Called from "render_page".