Posy::Docs::ProgrammerGuide 0.99 review

Posy::Docs::ProgrammerGuide is a guide for programmers of Posy. How Posy Works Posy has two modules which drive the whole thing

License: Perl Artistic License File size: 69K Developer: Kathryn Andersen

0

Posy::Docs::ProgrammerGuide is a guide for programmers of Posy.

How Posy Works

Posy has two modules which drive the whole thing: Posy and Posy::Core. Posy has been set up so that, when you give it a list of plugin modules to use, it imports them as children of each other, so that each one overrides the methods of the previous one, and/or adds new methods of its own. (see "import" in Posy for more details).

What this boils down to is that, if you want to change Posy's behaviour, you can (a) write methods which override existing methods, simply by writing a method with the same name, and (b) add additional functionality to Posy by writing new methods, especially new Action methods.
Action methods? Okay, back to how Posy works.

Posy first sets up all the Plugins with its "import" method, and then it calls its "run" method, which (a) creates a new Posy object, (b) calls "init" on the object, (c) calls "do_actions" on the object.

The "do_actions" method in turn calls all the actions in the passed-in "actions" array, which should include the "do_entry_actions" method, which in turn calls all the actions in the passed-in "entry_actions" array. The entry actions are called once per entry; the "flow" actions are called once per run.

Flow actions?

Well, I had to have a name for them. They flow on, one after another. Posy doesn't always manipulate the Posy object itself when building up the final web page -- it manipulates the "flow-state" hash, which is passed to every flow-action. Until finally the "render_page" action takes all the separate parts of the page which have been built up (head, page_body and foot) and pastes them together and outputs them (to either a file or STDOUT).

Entry actions?

Entry actions are applied to each entry. One of the early flow-actions, "select_entries", picks the list of entries which are going to be in the final page, either one (for an "entry" page) or many (for a "category" or "chrono" page). Entry actions not only deal with the "flow_state" hash, but they have two other hashes that they manipulate, the "current_entry" hash, and the "entry_state" hash. The current_entry hash contains (as one would expect) information about the current entry, such as the raw content of the entry ($current_entry->{raw}) and the processed content of the entry (such as $current_entry->{body}, $current_entry->{title}) and so on.

What the entry actions do is build up the "page_body" part of the page (the flow actions deal with the head and the foot). Though, actually, "head_render" and "foot_render" could be considered dual-purpose actions.

Dual-purpose actions?

There are some actions which can be called as either "flow" actions or "entry" actions, and change their behaviour according to whether they are called as one or the other. See "head_render" in Posy::Core for an example. They aren't common, but can be useful in certain circumstances.

Requirements:
Perl