Swank::Page

This is the base class for all pages. It provides the default top-level actions and a few utility functions.

(Because it is made into a Swank::Classless object by Swank::Classless::Meta::declassify, it is untested whether subclassing this is useful or even possible.)

Requires:

Swank::Classless (parent class)

Swank::Compiler (for compiling values into methods)

Swank::Storage (for reading and writing pages)

Swank::RCS (for history)

Swank::RawUtil (for attachments)

Swank::IO

Provides:

compile( $method )

This method is used to compile a value into a method, because any value on a page can also be accessed as a method. This gives the value inheritance, and allows it to be overridden with complex calculations. This is invoked from Swank::Classless::can when it finds a value which does not yet have a corresponding method. The actual compiling is done by the Swank::Compiler class.

call( "page.action", [ args... ] )

This invokes a method on any named page in the system. This API is needed to access pages which may not have been loaded into the classless heirarchy yet. If you have a page object already (for example, from a search result), you can simply do $page->method. But if you only know the page name, you need to invoke it via $self->call("page.method") which will load the page into memory if needed. This also implements the magic behind [ % & page % ] tags.

Possible syntax variants for the "page.action" argument are:

call( "page" ) -- invokes the default method, called "wiki", so it is identical to call("page.wiki").
call( "page.action" ) -- invokes the named method on the named page.
call( "self.action" ) -- invokes the named method on the current page. (The perl6-ish ".method" syntax was found to cause problems and is not allowed.)
call( [ $page, $action ] ) -- this is used for compiling [ %& $page.method % ], when $page is a variable, and "method" is a string.

There are efforts made prevent infinite recursion. If the call stack exceeds a depth of 500, it will die. However, this does not prevent infinite recursion via $page->method().

action( $method, [ args... ] )

action simply invokes $method on the current page object. It is deprecated and will be removed eventually. (In the meantime, it is a convenient place to put a break when debugging.)

attachments_dir

Returns the path to where attachments are actually stored for this page. attachments_info is a better API for most uses.

attachments_info

This is mainly a support method for the top-level attach action, but can be useful it other circumstances as well. It returns a list of hashes with information on the files attached to this page. See the list_files method of Swank::RawUtil for details.

show_errors

Called by /site to show any errors from when a page is validated and saved.

Top-Level Actions

html

This is the top-level action when page.html (or simply "page" without any extension) is requested. It supports a "nohead" named argument to disable returning XHTML headers and footers, which are the <body> tags and everything outside them.

edit

Top-level action for "page.edit". It merely sets the $sys->mode to 'edit' and calls the html action. The 'edit' mode causes the /field objects called from the top-level page to be rendered for editing.

submit

When a page is edited, the changes are submitted via the "page.submit" action. (Note that it is planned to change this action to "save", and use submit for public forms which do not actually save their page data, such as the login form.)

It invokes the 'html' action with $sys->mode set to 'submit' to get the data from $io object to the page. Then it calls the 'validate' method to validate the new data. If the data is validated, it will redirect to "page". If exceptions are thrown or tossed, or compiling the new data fails, it will show the page in edit mode again (/site displays the errors).

If a page named "new" is saved, it will be renamed to whatever is in the "name" value, or given an autogenerated serial number (see getkey() in Swank::Storage).

delete

This deletes a page when "page.delete" is requested. After using Swank::Storage to do the deletion, it will redirect to the (now empty) page.

history

Implements the top-level action for "page.history". With no arguments, it shows the revision history. If a "revision" argument is given, it shows the page at that revision. If "diffa" and "diffb" arguments are given, it shows differences between the two revisions.

This action requires support from the Swank::RCS module. (It should eventually be plugged in from that module.) The revision history is provided by the /rcs/history page, and the differences are shown by the /rcs/diff page.

attach

This action is for manipulating page attachment, when "page.attach" is requested. The actual implementation is done in the /attachments/manage page.

Content Wrapping

These methods implement content wrapping, both for page templates, and /site style wrapping.

wrap

If you want a page to be wrapped, just call page.wrap. The default wrapper is given by the "swank_wrap" attribute.

Wrapping can be disabled using a nowrap argument. If nowrap is '1', it will disable all wrapping. If nowrap is a string, it will stop wrapping at the page named in the string. If nowrap is a regex, it will stop wrapping when the wrapping page matches the regex.

wrapper

wrapper is used internally in the wrapping process. (rename to _wrapper?)

A wrapping page should do [ % & self.next, @_ % ] at the spot where the wrapped page should appear.

This can also be done in perl code via "$io->print( $self->next(@_) )". It is easy to forget the $io->print, but that will result in nothing being output, since next, like all methods, returns data rather than outputting it directly.

There may be some confusion about the various "next" methods. $self->next is for unwrapping. $self->NEXT is for Classless page inheritance. $self->method::next is not for page objects; it is for Class::C3 inheritance used by the Swank system class heirarchy.

Default Actions

(These are stubs which do nothing but prevent an exception being thrown, so that these methods can be safely used on any page object.)

wiki -- The default action when "page" is invoked without naming a method.

title -- The displayed title for the page. Default is the value of the "name" attribute.

html_head -- returns data to be placed in the html <head> tag.

validate -- for validating data when a page is saved. By default, it simply makes sure there are no compilation errors.

Private methods

Methods beginning with an underscore are considered private.

Page attributes beginning with an underscore are never saved, but can be used for temporary request data. There are some virtual fields for indexing which begin with underscore. "_link" is used for indexing backlinks. "_code" is used for indexing code sections.

Document last modified: 04 Sep 2010 05:18pm