# Copyright 2002-2008 Josh Clark and Global Moxie, LLC. This code cannot be 
# redistributed without permission from globalmoxie.com.  For more
# information, consult your Big Medium license.
#
# $Id: CP.pm 3043 2008-03-31 14:00:38Z josh $

package BigMed::Plugin::CP;
use base qw(BigMed::Plugin);
use Carp;
$Carp::Verbose = 1;
use strict;
use utf8;

my %Nav_Item;
sub nav_items { %Nav_Item; }
sub add_nav_item {
    my $self = shift;
    my %param = @_;
    my $name = $param{name} or croak 'add_nav_item requires a name parameter';
    ref $param{url} eq 'HASH'
      or croak 'add_nav_item requires a url parameter (hash reference)';
    
    my @accept = ('belongs_to', 'priority', 'url', 'no_site', 'label');
    my %set_item;
    @set_item{@accept} = @param{@accept};
    $Nav_Item{$name} = \%set_item;
}

1;

__END__

=head1 Name

=head2 BigMed::Plugin::CP

A subclass of BigMed::Plugin that enables the addition of navigation menu
items to the Big Medium control panel for application subclasses of
BigMed::Web::CP.

=head1 Synopsis

The following should go into the plug-in instance script in the
moxiebin/plugins directory.

    use BigMed::Plugin::CP;
    use strict;
    
    #add a top-level menu item
    BigMed::Plugin::CP->add_nav_item(
        name     => 'FooBar',                   #internal reference name
        priority => 30,                         #sets the item's order
        url      => { plugin => 'foo.cgi' },    #params submitted to build_url
        label    => 'PLUGIN_FooBar',            #the language lexicon key
        no_site  => 1,                          #no site required
    );

    #add a subnav item
    BigMed::Plugin::CP->add_nav_item(
        name       => 'FooBarMenu',
        belongs_to => 'FooBar',                 #selects the parent item
        priority   => 99,
        url   => { plugin => 'foo.cgi', args => ['menu'] },
        label => 'PLUGIN_FooBar_Menu',
    );

=head1 Methods

=over 4

=item * C<add_nav_item>

Adds or changes a navigation item in the control-panel menu. If a menu
item of the same name was previously registered, or is part of the default
set, that older item will be replaced with the new item.

The method accepts a hash of parameters with the following key/value pairs:

=over 4

=item * name => 'internal_name',

Required. The unique id name for this navigation item. Also used in the
html as the id for the menu item.

=item * url = \%url_parameters

Required. This hash is passed to BigMed::Web's build_url method to generate
the URL for the item.

=item * belongs_to => 'internal_name'

If true, assigns the menu item as a subnavigation item for the named
menu item.

BigMed::Web::CP currently supports only a single level of
subnavigation, so items whose belongs_to points to another subnavigation
item will be ignored. (This may change in the future).

=item * priority => $number,

Determines the sort order of the item relative to other menu items in the
same group.  The higher the priority, the higher in the list the item
appears. (If not priority is assigned, the priority will be zero).

Items with the same priority level are sorted by their name parameter.

Also, subnavigation items are grouped by priority so that items that belong in
the same "ten" unit (e.g. 60-69, 50-59, 0-9, etc) will be visually
grouped together.

=item * label => 'language lexicon key'

The key to be passed to BigMed::App's language method for localization.
If not supplied, the label will be the name value, prepended by
BM_CP_NAVLABEL_

    BigMed::Plugin::CP->add_nav_item(
        name => 'foobar',
        url  => { plugin => 'foobar.cgi' },
    );

    #is the same as...
    BigMed::Plugin::CP->add_nav_item(
        name  => 'foobar',
        url   => { plugin => 'foobar.cgi' },
        label => 'BM_CP_NAVLABEL_foobar',
    );

=back

=back

=head1 AUTHOR & COPYRIGHTS

This module and all Big Medium modules are copyright Josh Clark
and Global Moxie. All rights reserved.

Use of this module and the Big Medium content
management system are governed by Global Moxie's software licenses
and may not be used outside of the terms and conditions outlined
there.

For more information, visit the Global Moxie website at
L<http://globalmoxie.com/>.

Big Medium and Global Moxie are service marks of Global Moxie
and Josh Clark. All rights reserved.

=cut