• ExSite::Section - section and website management
• Configuration & Setup
• new()
• setup()
• setupSection()
• Section Address
• filename()
• diskpath()
• httppath()
• get_url()
• get_host()
• sectionpath()
• sectionpath_url()
• Content Management
• get_all_pages()
• get_mapped_pages()
• fetch_libraries()
• fetch_library_content()
• get_templates()
• set_template()
• get_bodies()
• get_services()
• find_dcd()
• Publishing
• publish()
• unpublish()
• Creating/Modifying Sections
• validate()
• make()
• make_section()
• install()
• delete()

---

ExSite::Section - section and website management

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:

stand-alone website

``Stand-alone'' means the section must explicitly specify its publication folder (as a complete directory path), and its domain name.

native website

``Native'' means the section implicitly infers its publication path and domain name from the parent section. If there is no parent, then these are inferred from the ExSite system configuration. The publication directory is simply a directory name.

website template

A website template is a model section, used to initialize new sections with the same pages that the website template has. Website templates do not publish.

---

Configuration & Setup

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:

id

The numeric section ID will be used to fetch the section description from the database.

section

The section record can be passed as a hash reference, if it has already been fetched.

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.

---

Section Address

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.)

---

Content Management

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:

section_id

This is the section to search under, if not the current section.

mode

This is an integer that determines which templates will be selected for inclusion:

``-1''

select all templates on the system (administrators only, otherwise treated as 0)

``0''

select templates useable by this site (default) (use when changing template of a site)

``1''

select templates useable by children of this site (use when creating a child site)

``2''

select public templates only (use when creating a new independent site)

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.

---

Publishing

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.

---

Creating/Modifying Sections

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.