get_all_pages()get_mapped_pages()fetch_libraries()fetch_library_content()get_templates()set_template()get_bodies()get_services()find_dcd()The Section class handles configuration, publication, and other management of website sections.
Formally, a section is a group of pages with similar publication and access control attributes. All static pages in a section publish into the same directory, and all member-only pages are accessible by the same group of members.
Many small websites are configured as a single section; therefore the terms ``section'', ``website'', and ``site'' are sometimes used interchangeably.
ExSite::Section is part of the ExSite content stack, so it inherits
from ExSite::Page, which in turn inherits from ExSite::Content,
ExSite::ContentData, and ExSite::ContentBase.
Note that sections have somewhat different behaviours, depending on their type:
new()(This method is actually inherited from ExSite::ContentBase.)
setup()
setupSection()Instantiate and/or configure a section object. %option includes the
the configuration parameters, described below.
Usage:
my $section = new ExSite::Section(%option);
$section->setup(%option);
$section->setupSection(%option);
setup and setupSection are synonymous; they are used to setup or
reconfigure an existing Section object. new() instantiates a new section
object (this method is actually inherited from ExSite::ContentBase).
%option is used to pass the section description information that
allows the object to be configured. It can include the following section
description parameters:
If the section is not set up with an actual section description, the object
will have limited functionality. The setup methods are normally invoked
automatically by the class constructor method new(), which receives the
same %option parameters.
filename()Returns the publication name of the section. This is only meaningful for native websites.
diskpath()Returns the full disk path where the section's files will be published. The disk path depends on the section's type and relationship to its parent section.
httppath()(DEPRECATED) Returns the path relative to the webroot where the section's files will be found.
get_url()Returns the URL to the section. The URL references the section
directory, which normally defaults to the index.html or equivalent
file published in that directory. The URL includes the hostname
and protocol information.
get_host()Returns just the machine name part of the URL, eg. ``www.mydomain.com''.
sectionpath()Sections can be nested to any depth. This method returns an array of section objects representing all sections in this path, from the root section to the current section.
sectionpath_url()Returns the sectionpath() as a simple string, of the format
``/section1/section2/...''. Native sections in the path will be named
for their publication location; stand-alone sections will be named
using their section ID. For instance:
/native1/2/native3
This might represent a native website ``native3'' that is a child of a stand-alone website (section ID 2), which is a child of a native website ``native1''. Note that this in turn may be a child of a native website with a blank publication directory. (The root section in a system is typically a native website with no publication directory, since it publishes to the default directory specified by the webserver.)
get_all_pages()Returns an array of page objects for all of the active pages in the section.
get_mapped_pages()Returns an ExSite::Tree object containing all of the section's
pages organized into a site map. The site map ignores the page
visibility attribute that determines whether to include the pages in
displayed site maps and menus, so code that constructs such menus
should consider the page's visibility when deciding whether to show
each page.
fetch_libraries()Returns an array of library records (not objects) that are accessible to the current section. This includes libraries in the current section, shared libraries in the the sectionpath, and public libraries anywhere in the system.
fetch_library_content()Returns an array of content objects for all of the content in all of the libraries returned by the previous method.
get_templates()Returns all templates available to the section, as an array of page records. This may include templates from other sections, depending on their privacy settings and relationship to the current section.
my @templates = $section->get_templates(%option)
%option can specify:
set_template()$section->set_template($template)
Changes the graphic design template for the section to $template (which
may be a page ID, or a page hashref). If allowed, the section's default
template is changed, and all of the regular pages are changed to use the
template. Nothing is returned.
If not allowed, an error message is returned, which can be issued directly to the browser.
get_bodies()Returns an array of content records, representing model page bodies that can be used by the current section. These can be used to initialize the body of any page in the current section.
get_services()Returns an array of services running on this section. A service is a special record connecting a section to a DCD (plug-in). It is used for authorizing access to restricted-access DCDs, and finding special service pages that should be used to handle all requests to a DCD.
find_dcd()Finds pages using a particular DCD (plug-in).
my @pages = $section->find_dcd($module);
Returns an array of page records representing those pages that contain
a tag invoking the DCD $module in the newest revision of their content.
WARNING: you need write access to the section's publication area to
publish files there. The webserver normally does not have this
access. Negotiating this access is normally done by the publish
program (ie. publish.cgi), which has special permissions. If you do
not have these permissions, then you have to ask publish.cgi to do
this task on your behalf, using ExSite::Util::run_publisher().
publish()$section->publish($opt);
Creates the section directories on disk, and publishes all publishable
pages and content to these directories. If $opt is set to
``nofiles'', then only the section's base directory is created, and
nothing is published to it. Otherwise, pages are recursively
published by instantiating page objects for each, and invoking the
publish() method on each.
If $config{search}{reindex_on_publish} is TRUE, then the section's
search index will also be rebuilt at this time.
The output of the publish method is printed direct to stdout, so that progress can be monitored in real time. Otherwise for large sections, long delays can be experienced as the lengthy publish output is buffered until completion. This is why publish progress screens are not templated.
unpublish()Removes a section's files from disk. Recursively unpublishes each
page by callings its unpublish() method, and recursively
unpublishes child sections as well.
validate()my @errors = $section->validate($sectiondata);
if (@errors == 0) { # section is OK }
Returns TRUE if the values in the the $sectiondata hashref comprise
a valid and legal page description. Returns an array of error
messages, which will be empty if the section data validates.
make()
make_section()
install()$section->make($sectiondata,$template,$approve_flag);
$section->install($sectiondata,$template);
Creates a new section using the attributes in the $sectiondata hashref.
The make() and make_section() versions perform validation and
permission checks on the section data first. The install() method
does the actual installation. $approve_flag can be used to pre-authorize
the section creation; use this if allowing unprivileged users to create
new sections on the system.
$template, if defined, is a section ID that points to a website template.
This is used to initialize the new section with preconfigured pages.
delete()Removes the current section from the system. Records are moved to the trash bin, and may be recovered from there. (However, large sections' trashballs may exceed the query size limit of the database.) Attempts to unpublish its files, as well.