view release on metacpan or  search on metacpan

lib/DBIx/HTML/LinkedMenus.pm  view on Meta::CPAN

# -----------------------------------------------

sub javascript_for_on_load
{
	my($self) = @_;

	('onLoad' => 'dbix_init()');

}	# End of javascript_for_on_load.

# -----------------------------------------------

sub new
{
	my($caller, %arg)	= @_;
	my($caller_is_obj)	= ref($caller);
	my($class)			= $caller_is_obj || $caller;
	my($self)			= bless({}, $class);

	for my $attr_name ($self -> _standard_keys() )
	{
		my($arg_name) = $attr_name =~ /^_(.*)/;

		if (exists($arg{$arg_name}) )
		{
			$$self{$attr_name} = $arg{$arg_name};
		}
		else
		{
			$$self{$attr_name} = $self -> _default_for($attr_name);
		}
	}

	$self -> _validate_options();
	$self -> _read_data();

	$self = undef if (! $$self{'_size'});

	return $self;

}	# End of new.

# -----------------------------------------------

sub size
{
	my($self) = @_;

	$$self{'_size'};

}	# End of size.

# -----------------------------------------------

1;

__END__

=head1 NAME

C<DBIx::HTML::LinkedMenus> - Convert SQL to 2 linked HTML popup menus.

=head1 Synopsis

	use DBIx::HTML::LinkedMenus;

	my($linker) = DBIx::HTML::LinkedMenus -> new
	(
		dbh        => $dbh,
		base_sql   => 'select campus_id, campus_name, campus_id ' .
						'from campus order by campus_name',
		linked_sql => 'select unit_id, unit_code from unit where ' .
						'unit_campus_id = ? order by unit_code',
	);

	# Print as part of a form:

	print $q -> start_form...
	print $linker -> javascript_for_db();
	print $linker -> html_for_base_menu();
	print $linker -> html_for_linked_menu();
	print $linker -> javascript_for_init_menu(); # Either this...
	print $q -> end_form();

	# Alternately, print as part of a page:

	my(@on_load) = $linker -> javascript_for_on_load(); # Or these 2...

	print $q -> start_html({title => 'Linked Menus', @on_load}),
	print $q -> start_form...
	print $linker -> javascript_for_db();
	print $linker -> html_for_base_menu();
	print $linker -> html_for_linked_menu();
	print $q -> end_form();

=head1 Description

This module's constructor takes a db handle and 2 SQL statements, and executes the SQL.

The first SQL statement is used to create a pop-up menu - the base menu.

The constructor returns undef if the SQL for the base menu returns 0 items.

The second SQL statement is used to create another pop-up menu - the linked menu.

By linked I mean each item in the base menu has a corresponding set of items in the linked menu.

Eg: If the available selections on the base menu are A and B, and A is the current selection, then the linked menu
will display (say) A1, A2 and A3. Then, when the user changes the current selection on the base menu from A to B,
the javascript provided will automatically change the available selections on the linked menu to (say) B1 and B2.

Details of the SQL are explained below.

You use the methods, as above, to retrieve the JavaScript and HTML, and include them in your CGI form.

The JavaScript is in 2 parts:

=over 4

=item The data and some general functions

lib/DBIx/HTML/LinkedMenus.pm  view on Meta::CPAN

=over 4

=item First column

The first column will be used as the value returned by a CGI object, for example,
when you call its param(<linked_menu_name>) method.

=item Second column

The second column will be used as the visible selection offered to the user on the
linked menu.

=back

Of course, the first 2 columns selected could be the same:

	linked_sql => 'select unit_code, unit_code from unit where ' .
				'unit_campus_id = ? order by unit_code',

But normally you would do this:

	linked_sql => 'select unit_id, unit_code from unit where ' .
				'unit_campus_id = ? order by unit_code',

Again: This means that the second column is used to construct visible menu items, and
when an item is selected by the user, the first column is what is returned to your
CGI script.

Now, notice the where clause. Each value of column three (3) returned by the base_sql
is used to select a set of items for the linked menu. The ? in the linked_sql's where
clause is where the value from the third column of the base_sql is plugged into the
linked_sql.

If a particular value of the base_sql's column three (3) does not return any items for
the linked menu, then that basic item does not appear on the base menu.

=back

=head1 Methods

=over 4

=item get($base_id, $link_id)

Returns the 2 visible menu items, (base, linked), corresponding to the 2 menu
selections.

Returns () if either $base_id or $link_id is not a key into the internal hash
holding the data.

You would normally do something like this:

	my($base_id) = $q -> param('dbix_base_menu')   || '';
	my($link_id) = $q -> param('dbix_linked_menu') || '';
	my($linker)  = ...
	my(@value)   = $linker -> get($base_id, $link_id);

=item html_for_base_menu()

Returns the HTML for a popup menu named after the base_menu_name parameter.

Output it somewhere suitable on your page.

Calling this method and outputting the HTML is mandatory.

=item html_for_linked_menu()

Returns the HTML for a popup menu named after the linked_menu_name parameter.

Output it somewhere suitable on your page.

Calling this method and outputting the HTML is mandatory.

=item javascript_for_db()

Returns JavaScript, including the <script>...</script> tags, which holds your data in a
JavaScript db, and includes some JavaScript functions.

Output it somewhere suitable on your page.

Calling this method and outputting the JavaScript is mandatory.

=item javascript_for_init_menu()

Returns JavaScript, including the <script>...</script> tags, which holds the function call
to a function which initializes the linked-menu system. The function itself is included in
the code returned by javascript_for_db().

Output it somewhere on your page after you have output the 2 pieces of HTML and after
you have output the string returned from javascript_for_db().

Calling this method is optional. If you do not call it, then calling the method
javascript_for_on_load() is mandatory.

=item javascript_for_on_load()

Returns a string to be used as a <body> tag's onLoad event handler. It calls the
function which initializes the linked-menu system. The function itself is included in
the code returned by javascript_for_db().

Output it as part of the <body> tag. See examples/test-linked-menus.cgi for an
example.

Calling this method is optional. If you do not call it, then calling the method
javascript_for_init_menu() is mandatory.

=item new(%arg)

The constructor.

See the previous section for details of the parameters.

=item size()

Returns the number of rows returned by your base SQL.

It will tell you whether or not your base menu is empty.

=back

=head1 Sample Code

See examples/test-linked-menus.cgi for a complete program.

The use of undef for the 4 parameters base_prompt, base_value, linked_prompt and linked_value
should not be confused with the use of undef in the test program.

The latter is used to indicate the first time the program is run, in which case there are no