NAME

Krang::ElementClass::TopLevel - base class for top-level element classes

SYNOPSIS

  package ElementSet::article;
  use Krang::ClassLoader base => 'ElementClass::TopLevel';

  # override new() to setup element class parameters
  sub new { 
      my $pkg = shift;
      my %arg = (name      => "article",
                 children  => [ 'deck', 'paragraph', 'image' ],
                 @_);
      return $pkg->SUPER::new(%arg); 
  }

  1;

DESCRIPTION

This class serves as the base class for top-level element classes. The root of an element tree must start with a sub-class of this class. The methods provided allow this special element to control some aspects of the Story or Category which contains it. For example, the build_url method allows element classes to determine how a story builds its URL.

Additionally, some methods make no sense for a top-level element class, and they are stubbed out with implementations that croak. For example, the input_form() method is useless for a top-level element because the UI does not allow top-level elements to recieve input.

INTERFACE

• $url = $class->build_url(story => $story, category => $category)
  
Builds a URL for the given story and category. The default implementation takes the category url and appends a URI encoded copy of the story slug. This may be overriden by top level elements to implement alternative URL schemes.
• $url = $class->build_preview_url(story => $story, category => $category)
  
Builds a preview-path URL for the given story and category. The default implementation takes the category url and appends a URI encoded copy of the story slug. This may be overriden by top level elements to implement alternative URL schemes. See Krang::ElementClass::Cover for an example.
• @fields = $class->url_attributes()
  
Returns a list of Story attributes that are being used to compute the url in build_url(). For example, the default implementation returns ('slug') unless slug_use() is set to 'prohibit'.
• @schedules = $class->default_schedules(element => $element, story_id ==> $story_id)
  
Called when a top-level object is created. May return a list of Krang::Schedule objects. The default implementation returns and empty list.
• $file_name = $class->filename()
  
Returns the filename (independant of the extension) to be used when writing to disk data generated by this element tree. Will return index unless overridden.
• $file_extension = $class->extension()
  
Returns the file extension (see filename()) to be used when writing to disk data generated by this element tree. Will return .html unless overridden.
• $class->versions_to_keep
  
This method can be used to override the number of versions kept in the database for stories of this type. The default implementation returns the value SavedVersionsPerStory from krang.conf, or, if that's undefined, 0 (which indicates that there is no maximum: all versions are kept).
• $class->save_hook(element => $element)
  
Called just before the story/category containing the element tree is saved. The default implementation does nothing.
• $class->delete_hook(element => $element)
  
Called just before the story/category containing the element tree is deleted. This routine can be used to do any necessary cleanup. The default implementation does nothing.
• $class->trash_hook(element => $element)
  
Called just before the story containing the element tree is moved to the trash bin. This routine can be used to do any necessary cleanup. The default implementation does nothing.
• $class->untrash_hook(element => $element)
  
Called just after the story containing the element tree is moved out of the trash bin. This routine can be used to do any necessary restoration. The default implementation does nothing.
• $class->retire_hook(element => $element)
  
Called just before the story containing the element tree is moved to the retired section. This routine can be used to do any necessary cleanup. The default implementation does nothing.
• $class->unretire_hook(element => $element)
  
Called just after the story containing the element tree is moved out of the retired section. This routine can be used to do any necessary restoration. The default implementation does nothing.
• $bool = $class->publish_check(element => $element)
  
This method is called before publishing the story via a scheduled publish job (not in the UI). If this method returns 0 (false) the publish won't happen. This may be used to implement a ``Holding'' desk where stories won't be automatically published, for example.

The default implementation just returns 1 (true) in all cases.

• $bool = $class->force_republish(element => $element)
  
This method is called at the beginning of the publish process. If true, all other checks are ignored and the story is published. If false, other versioning and sanity checks (see Krang::Publisher and Krang::Story) are made to determine whether or not to publish the story.

The default implementation returns 0 (false) in all cases.

• $bool = $class->use_category_templates(element => $element)
  
This method is called during the publish/preview process. If true, it will wrap the story output with the output of the category templates before writing the result to the filesystem. If false, the story output is the final output.

The default implementation returns 1 (true) in all cases.

• $bool = $class->publish_category_per_page(element => $element)
  
This method is called during the publish/preview process. If true, it will re-publish the category element for each page in the story, passing the current page number and total number of pages to the category element. The published output will be matched only with the current page.

If false, the category element will be published once, and its output will be matched up with each story page.

The default implementation returns 0 (false) in all cases.

Override this method to return 1 (true) if you want to generate content on category templates varies for each page in a story.

• $category_input = $class->category_input()
  
This method is used to determine whether the user needs to select a category when creating a New Story.

  It returns 1 of 3 values:
  'require'  - user must specify category 
  'allow'    - user may specify category 
  'prohibit' - user may not specify category

The default implementation returns 'require'.

=cut

sub category_input { return 'require'; }

• @category_ids = $class->auto_category_ids(cover_date => $cover_date, slug => $slug, title => $title);
  
This method auto-selects one or more category IDs based on cover_date, title, and/or slug. The default implementation simply returns the first category ID it can find. (Multiple values must be returned as an array, not an arrayref.)
• $validate = $class->validate_category(category => $category, cover_date => $cover_date, slug => $slug, title => $title);
  
This method validates whether a given category is acceptable for a story based on the story's cover_date, slug, and/or title. If so, it returns 1. If not, it returns a text error that is passed onto the user.

The default implementation returns 1 in all cases.

• $slug_use = $class->slug_use()
  
This method is used to determine slug behavior.

  It returns 1 of 4 values:
  'require'    - slug is required
  'encourage'  - slug field is present in New Story CGI, but can be left empty
  'discourage' - slug field is initially greyed-out in New Story CGI
  'prohibit'   - slug is prohibited

The default implementation returns 'encourage'.

=cut

sub slug_use { return 'encourage'; }

• $title_to_slug = $class->title_to_slug()
  
This method returns the Javascript necessary to dynamically convert a title to a slug in the New Story form. The default implementation returns nothing, causing the hard-coded Javascript to execute. If a particular story type requires a different approach, this method can be overridden in the story class. The Javascript returned should consist of an unnamed function, for example ``function(title) { return title.toLowerCase }''
• $bool = $class->hidden()
  
This method sets the value of Krang::Story>->hidden(). If true, stories of this class will not return in a call to < Krang::Story-find() >> unless the parameter show_hidden => 1 is set.

As an example: this is useful for story classes that aren't supposed to show up in most-recently-published lists. For example, the Krang RSS and HREF[Krang Sitemap|href://krang.sourceforge.net] addons republish nightly by default - neither of these story classes should show up in a cover displaying the most-recently-published stories.

This method is false by default.

• $file_mode = $class->file_mode($filename)
  
This method supplies the mode for a given file being published. The default implementation return undef which leaves the file with the default mode, determined by the process umask.
• publish_frontend_app_template()
  

  $self->publish_frontend_app_template(
      publisher         => $publisher,
      fill_with_element => $element,
      filename          => "search_results.tmpl",
      use_category      => 1,
      tmpl_data         => {Foo => 123, Bar => 456},
  );

This method is used to publish a template to the front-end of a website for use by a front-end CGI. It is expected to be called from within the fill_template() or publish() methods. This method takes the following parameters:

• publisher
  
The Krang::Publisher object. This parameter is required.
• filename
  
The name of the template file to publish. The template will be located via the category path as per Krang's normal template finding behavior. This parameter is required.
• output_filename
  
The name of the file that is published. If not given it will default to filename.
• use_category
  
Set to ``1'' to wrap this template in the category template. Defaults to ``0''.
• tmpl_data
  
If provided, this hashref will be used to populate any parameters in the template.
• fill_with_element
  
If supplied, this element will be used to populate the contents of the template. (In which case, the tmpl_data hashref will augment the output of the fill_template() process.

NOTE: Template vars, loops (etc.) which are needed by your front-end CGI should be named ``<dyn_*>'' instead of ``<tmpl_*>'', e.g.:

  <dyn_if some_boolean>
    <dyn_loop some_loop>
      <dyn_var foo1>
      <dyn_var foo2>
      <dyn_var foo3>
    </dyn_loop>
  </dyn_if>

This is to differentiate the template tags needed by the CGI from those needed by the Krang publishing process.

• publish_frontend_app_stub()
  

  $self->publish_frontend_app_stub(
      publisher  => $publisher,
      filename   => "myapp.pl",
      app_module => 'Foo::Bar::Baz',
      app_params => {Foo => 123, Bar => 456},
  );

Publish a CGI ``instance script'' which will invoke a CGI::Application-based module. This method takes the following parameters:

• publisher
  
The Krang::Publisher object. This parameter is required.
• filename
  
The name of the stub file to publish. This file will be made executable (mode 0755) so as to comply with mod_cgi, Apache::Registry, and ModPerl::Registry This parameter is required.
• app_module
  
The CGI::Application based (or compatible) module which will be instantiated via the application stub file. This parameter is required.
• app_params
  
These parameters will be passed to the application and made available via the $app->param() method. (See the CGI::Application documentation.)
• return_only
  
If true, then the text of the resulting script won't be published to the filesystem but will instead be returned. This is useful if you want to return the output as part of your publish() method. Defaults to false;