• Home
• News
• FAQ
• Documentation
• Community
• About

Adam Kennedy - Display.Only-0.04

  // Some things to show
  <p id='first'>First section</p>
  <p id='second'>Second section</p>
  <p id='foo'>Also in Second section</p>
  <p id='third'>Third section</p>
  
  // Create the swap control
  <script language="JavaScript" type="text/JavaScript">
  var only = new Display.Only( {
        one:   "first",
        two:   [ "second", "foo" ],
        three: "third"
        } );
  only.show("one");
  </script>
  
  // Link to show the second set
  <p><a href='javascript:void only.show("two"));'>Show the second item</a></p>

// JSAN::Concat-compatible dependency header
JSAN.use("Display");
// __CODE__

/*

=head1 NAME

Display.Only - Display one of several named set of elements at a time

=head1 SYNOPSIS

  // Some things to show
  <p id='first'>First section</p>
  <p id='second'>Second section</p>
  <p id='foo'>Also in Second section</p>
  <p id='third'>Third section</p>
  
  // Create the swap control
  <script language="JavaScript" type="text/JavaScript">
  var only = new Display.Only( {
  	one:   "first",
  	two:   [ "second", "foo" ],
  	three: "third"
  	} );
  only.show("one");
  </script>
  
  // Link to show the second set
  <p><a href='javascript:void only.show("two"));'>Show the second item</a></p>

=head1 DESCRIPTION

C<Display.Only> is used to control groups of elements such as pages within
a tabbed display, where you will only ever want to see one of them at a
time.

It takes a named set of items, with will either be a single element
name or an C<Array> of names, and controls their visibility so that only
one is shown.

=head1 METHODS

*/

// FIXME - We're actually completely screwed if we don't have the
//         Display primitives, so doing this won't help one bit.
if ( typeof Display == "undefined" ) Display = {};

/*

=head2 new Display.Only( { one: "foo", two: [ "bar", ... ], ... } );

The C<Display.Only> constructor takes as argument a plain object, where the
keys should be the names of each set of elements, and the value is either
of a) A C<String> containing an element id, or b) An C<Array> containing
a list of C<String> element ids.

When the object is initially created, if has no way of knowing which of
these named sets of elements should be displayed, and so does not make
any change to the visibility of the elements.

If you did not generate the HTML elements with the correct visibility
in the first place, you should immediate call the L<\show> method to
ensure the correct set of elements is showing.

=cut

*/

Display.Only = function (param) {
	// Were we passed an object
	if ( typeof(param) != "object" || param.constructor != Object ) {
		throw new Error("Display.Only constructor was not passed an Object");
	}

	// Populate the set hash
	this.sets = {};
	for ( var key in param ) {
		var set = param[key];
		if ( typeof set == "string" ) set = [ set ];
		this.sets[key] = set;
	}

	// Don't select something to show by default
	this.showing = "";
}

Display.Only.VERSION = 0.04;

/*

=head2 void refresh

The C<refresh> method does the mechanics of showing and hiding the appropriate
elements. You can call this yourself if a problem has occured and you need to
force the visibility of the elements to their appropriate values.

=cut

*/

Display.Only.prototype.refresh = function () {
	for ( var s in this.sets ) {
		var set  = this.sets[s];
		var show = s == this.showing;
		for ( var i = 0; i < set.length; i++ ) {
			show ? Display.showElementById(set[i])
			     : Display.hideElementById(set[i]);
		}
	}
};

/*

=head2 void show name

The C<show> method will change the set currently showing. The named list
will be shown, and all others will be hidden.

If the provided name does not match a set, no action will be taken. If the
set specified if already showing, the method shortcuts and no action is
taken. To force a refresh, see the L<\refresh> method.

*/

Display.Only.prototype.show = function (set) {
	if ( set == this.showing )                  return;
	if ( typeof this.sets[set] == "undefined" ) return;
	this.showing = set;
	this.refresh();
};

/*

=head1 SUPPORT

Until the JSAN RT system supports distribution queues, bugs should
be reported via the jsan-authors mailing list.

For B<non-support> issues or questions, contact the author.

=head1 AUTHOR

Adam Kennedy <jsan@ali.as>, L<http://ali.as/>

=head1 COPYRIGHT

Copyright (c) 2005 Adam Kennedy. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the the terms of the Perl dual GPL/Artistic license.

The full text of the license can be found in the
LICENSE file included with this package

*/