[Openinteract-commits] CVS: OpenInteract2/pkg/base_box/OpenInteract2/App BaseBox.pm,1.2,1.3

[Chris W. <la...@us...>]

Update of /cvsroot/openinteract/OpenInteract2/pkg/base_box/OpenInteract2/App
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv13339/OpenInteract2/App

Modified Files:
	BaseBox.pm 
Log Message:
OIN-58: add examples and more info about creating a box to
OI2::App::BaseBox; cleanup the boxes action; update message keys to lose the '.label'


Index: BaseBox.pm
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract2/pkg/base_box/OpenInteract2/App/BaseBox.pm,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** BaseBox.pm	10 Mar 2005 01:24:56 -0000	1.2
--- BaseBox.pm	29 Mar 2005 02:36:22 -0000	1.3
***************
*** 48,65 ****
  =head1 SYNOPSIS
  
!  # Deposit all boxes in the current location on the page:
   [% OI.action_execute( 'boxes' ) %]
   
-  # Define global box information in your server.ini
-  [box]
-  handler            = MyWebsite::Handler::Box
-  default_template   = base_box::main_box_shell
-  default_separator  = <br>
-  default_method     = run_box
-  system_box_handler = MyWebsite::Handler::SystemBoxes
-  system_box_method  =
-  custom_box_handler =
-  custom_box_method  =
-  
   # Define an OI action (in conf/action.ini) to be used for a box with
   # a class and method:
--- 48,55 ----
  =head1 SYNOPSIS
  
!  # Deposit all boxes accumulated during request in the current
!  # location on the page:
   [% OI.action_execute( 'boxes' ) %]
   
   # Define an OI action (in conf/action.ini) to be used for a box with
   # a class and method:
***************
*** 70,82 ****
   title    = Current Weather
   
!  # Add a box ('name' maps to the above OI action):
   my $zip = $self->request->auth_user->{zipcode};
!  my $box = { name   => 'current_weather_box',
!              weight => 2,
!              title  => "Weather in Zip Code $zip",
!              params => { zip_code => $zip };
!  $self->controller->add_box( $box );
   
!  # Add the same box from a template:
   [% user_zip = OI.login.zip_code;
      OI.box_add( 'current_weather_box',
--- 60,74 ----
   title    = Current Weather
   
!  # Add the box in code ('name' maps to the above OI action):
   my $zip = $self->request->auth_user->{zipcode};
!  my %box = (
!      name   => 'current_weather_box',
!      weight => 2,
!      title  => "Weather in Zip Code $zip",
!      params => { zip_code => $zip }
!  );
!  $self->controller->add_box( \%box );
   
!  # Add the box from a template:
   [% user_zip = OI.login.zip_code;
      OI.box_add( 'current_weather_box',
***************
*** 88,107 ****
   # template-only box:
   [frequent_links_box]
!  name       = frequent_links_box
!  template   = mypkg::box_frequent_links
!  weight     = 8
!  title      = Frequent Links
!  security   = no
   
!  # Add a template-only box, overriding weight and title:
!  my $box = { name   => 'frequent_links_box',
!              weight => 2,
!              title  => "Most visited sites" };
!  push $self->controller->add_box( $box );
   
!  # Add the same box from a template, overriding title:
   [% OI.box_add( 'frequent_links_box',
                  title  = 'Most visited sites' ) %]
   
   # Remove a box added in another part of the system
   $self->controller->remove_box( 'motd' );
--- 80,107 ----
   # template-only box:
   [frequent_links_box]
!  template  = mypkg::box_frequent_links
!  weight    = 8
!  title     = Frequent Links
!  security  = no
   
!  # Reference our template-only box, overriding weight and title:
!  my %box = (
!      name   => 'frequent_links_box',
!      weight => 2,
!      title  => "Most visited sites"
!  );
!  $self->controller->add_box( \%box );
   
!  # Reference the same template-only box from a template, overriding title:
   [% OI.box_add( 'frequent_links_box',
                  title  = 'Most visited sites' ) %]
   
+  # Add a non-specified template-only box:
+  my %box = (
+      name        => 'myapp::mytemplate',
+      is_template => 'yes',
+  );
+  $self->controller->add_box( \%box );
+ 
   # Remove a box added in another part of the system
   $self->controller->remove_box( 'motd' );
***************
*** 112,121 ****
  =head1 DESCRIPTION
  
! See docs in L<OpenInteract2::Action::Box|OpenInteract2::Action::Box>
! for everything you can do with boxes and how to configure them..
  
! =head1 OBJECTS
  
! No objects created by this package.
  
  =head1 ACTIONS
--- 112,405 ----
  =head1 DESCRIPTION
  
! Boxes are standalone parcels of content that conform to a particular
! format. The content of a box is simply the result of executing an
! OpenInteract2 action: that action may be a piece of code (method in a
! class) or it may just be a template.
  
! In either case the box handler (L<OpenInteract2::Action::Box>) sorts
! the boxes and places the content for each in a 'shell' so all the
! boxes look the same -- if you want them to. The standard box looks
! something like this:
  
!  ---------------------- <-- 'shell'
!  |      BOX TITLE     |
!  ----------------------
!  | Box content        |
!  | generated by an    |
!  | action goes here   |
!  ----------------------
! 
! But you can create your own shell for all boxes by setting the 'boxes'
! parameter 'default_box_template' or on a per-box basis with the
! parameter 'box_template'. Whichever you choose, the value should be a
! particular template (in the 'package::template_name' format).
! 
! =head1 BOX COLLECTION
! 
! =head2 Configuration
! 
! The L<OpenInteract2::Action::Box> action has a number of configuration
! parameters that define how the collection of boxes are organized and
! how they look. As with all L<OpenInteract2::Action> objects you can
! define these parameters in a configuration file (C<conf/action.ini> in
! the C<base_box> package) or in the object itself.
! 
! =over 4
! 
! =item *
! 
! B<default_box_template> ($) (optional)
! 
! This is the template into which every box content gets put unless it
! specifies otherwise. The default template is
! C<base_box::main_box_shell>, which as the name would indicate is also
! installed with this package.
! 
! B<default_box_separator> ($) (optional)
! 
! This is the string used to separate boxes. For instance, if you want
! to put a short horizontal rule between each line, you could set this
! to:
! 
!   default_box_separator = <hr width="50%" noshade/>
! 
! Or if you had a custom image you wanted to separate your boxes with:
! 
!   default_box_separator = <div align="center"><img src="/images/box_sep.gif" height="2" width="25"/></div>
! 
! This module defines the default separator as '<br />'.
! 
! =item *
! 
! B<default_box_weight> ($; optional)
! 
! Use as the box weight if unspecified.
! 
! =item *
! 
! B<system_box_class> ($) (optional)
! 
! Defines what we should run on every request to display system
! boxes. Typically this is C<OpenInteract2::Action::SystemBoxes>; see
! L<OpenInteract2::Action::SystemBoxes> for what this includes.
! 
! It is okay if you blank this out, you just will not get the 'login',
! 'templates used', 'admin tools' and other boxes on every page.
! 
! We call the C<handler()> method on whatever class is defined here.
! 
! =item *
! 
! B<custom_box_class> ($) (optional)
! 
! If you want to call a custom handler to run every time B<in addition
! to> the system handler named above, list the class here. We call the
! C<handler()> method on whatever class is defined here.
! 
! =back
! 
! =head1 BOX SAMPLES
! 
! An individual box also has a say as to how it will be rendered as well
! as the content it will have. We'll go through a few different use
! cases.
! 
! =head2 Sample: Standard action
! 
! Like we said above, every box is just an action in a different
! format. So say we have an action implementation like this:
! 
!  package OpenInteract2::Action::InsultUser;
!  
!  use base qw( OpenInteract2::Action );
!  use OpenInteract2::Context qw( CTX );
!  
!  sub insult {
!      my ( $self ) = @_;
!      my $user = CTX->request->auth_user;
!      my $first_name = $user->first_name;
!      return ( $user->id % 2 == 0 )
!               ? "$first_name, you stink of elderberries"
!               : "$first_name, your mother was a donkey";
!  }
!  
!  1;
! 
! And our configuration for the box action points to the class and
! method; here's the most basic configuration to which we'll add values
! to see how they're reflected (from the C<conf/action.ini>):
! 
!  [insult_box]
!  class = OpenInteract2::Action::InsultUser
!  task  = insult
! 
! We'd add the box from a template like this -- 'insult_box' is from the
! name of our action:
! 
!  [% OI.box_add( 'insult_box' ) %]
! 
! When invoked by the 'boxes' action this will generate something like:
! 
!  ----------------------
!  |   Generic Box      |
!  ----------------------
!  | Chris, you stink   |
!  | of elderberries    |
!  ----------------------
! 
! Well, 'Generic Box' doesn't really do our box justice. Let's set the
! title ourselves by adding a parameter to the action configuration:
! 
!  [insult_box]
!  class = OpenInteract2::Action::InsultUser
!  task  = insult
!  title = Your Insult
! 
! The box will now look like this:
! 
!  ----------------------
!  |   Your Insult      |
!  ----------------------
!  | Chris, you stink   |
!  | of elderberries    |
!  ----------------------
! 
! Surprisingly, our insults wind up attracting worldwide attention and
! people around the world want to see the title in their own
! language. (Our research hasn't yet shown that people actually want the
! insults in their own language...) So instead of hardcoding a title
! we'll use a localization key:
! 
!  [insult_box]
!  class     = OpenInteract2::Action::InsultUser
!  task      = insult
!  title_key = Your Insult
! 
! And in our localization files we'd have something like:
! 
!  myapp-en.msg:
!  Your Insult = Your Insult
! 
!  myapp-es.msg:
!  Your Insult = Su Insulto
! 
! So if I login with my browser's preferred language set to Spanish
! ('es') I'd see:
! 
!  ----------------------
!  |    Su Insulto      |
!  ----------------------
!  | Chris, you stink   |
!  | of elderberries    |
!  ----------------------
! 
! See below for all the other properties you can assign.
! 
! =head2 Sample: Template-only, no parameteters
! 
! The simplest case is a call:
! 
!  CTX->controller->add_box( 'mypkg::my_box_template' );
! 
! Which simply uses the scalar passed in as the template name and the
! box name, and uses all the defaults. However, you will likely get a
! box with a title 'Generic Box', which is probably not what you want.
! 
! Just in case you thought that template-only boxes were an exception to
! the 'every box is an action' rule: underneath the hood we create an
! action of type 'template_only' and just assign the parameter
! 'template' as the template name you pass in.
! 
! =head2 Sample: Template-only, parameters
! 
! Another example -- this time you have to set your template as the
! parameter 'template' since you've got other parameters:
! 
!  CTX->controller->add_box({
!      name   => 'mypkg::mybox',
!      weight => 1,
!      title  => 'My First Box'
!  });
! 
! =head1 BOX PROPERTIES
! 
! Every box can define the following properties:
! 
! B<name> ($)
! 
! Name of the action that will generate the content for this box or it
! may also be the name of the template for this box.
! 
! B<box_name> ($)
! 
! Solely used to identify the box; if not provided we use the 'name'
! parameter. This is useful if you've got two boxes referencing the same
! template but with different content.
! 
! For instance, say you had a box 'weather' that displayed weather
! information for a location. And that on one page you had boxes for two
! locations:
! 
!  [% OI.add_box( 'weather',
!                 box_name = 'pgh weather', zip = '15216');
!     OI.add_box( 'weather',
!                 box_name = 'silver spring weather', zip = '29010' }); %]
! 
! If you later wanted to remove one of the boxes you'd be able to delete
! only the first like this and leave the other untouched:
! 
!  [% OI.remove_box( 'pgh weather' ) %]
! 
! B<title> ($) (optional)
! 
! Display name of box used in the 'shell' wrapper, if you elect to use
! that.
! 
! B<title_key> ($) (optional)
! 
! Localization key to use for box title, generally used in place of
! 'title' and if both are present this will be used.
! 
! B<title_image_src> ($) (optional)
! 
! Display an image for the title to be used in the 'shell' wrapper.
! 
! B<title_image_src_key> ($) (optional)
! 
! Localization key to use for image title, generally used in place of
! 'title_image_src' and if both are present this will be used.
! 
! B<title_image_alt> ($) (optional)
! 
! Text to put in the 'alt' tag if using an image in the title.
! 
! B<title_image_alt_key> ($) (optional)
! 
! Localization key to use for the 'alt' tag in the image title,
! generally used in place of 'title_image_alt' and if both are present
! this will be used.
! 
! B<weight> ($)
! 
! Number between 1 (top) and 10 (bottom) indicating where you want the
! box to be. If you do not specify the weight the C<default_box_weight>
! action parameter will be used; if that's not defined the world is an
! uncertain place.
! 
! B<box_template> ($) (optional)
! 
! If you specify the keyword '_blank_' then your box content will be
! 'naked' and not wrapped by anything else. If you leave this empty you
! will use the template specified in the 'default_box_template' action
! parameter.
! 
! =item *
! 
! B<*> or B<\%params> (optional)
! 
! Any additional parameters, or parameters specified in C<\%params>,
! will be passed through to the action generating the box content.
! 
! =back
  
  =head1 ACTIONS
***************
*** 130,135 ****
  B<object_modify_box>
  
! Box for editing/removing an object. (Has aliases 'object_mod_box' and
! 'objectmodbox'.)
  
  B<login_box>
--- 414,418 ----
  B<object_modify_box>
  
! Generic box for editing/removing an object.
  
  B<login_box>
***************
*** 150,157 ****
  (mod_perl, Template Toolkit, OpenInteract).
  
- =head1 RULESETS
- 
- No rulesets created by this package.
- 
  =head1 AUTHORS
  
--- 433,436 ----