Location: PHPKode > projects > Browseable Online Backup System > bobs-0.6.4/doc/assign.php
<?PHP
// =======================================================================
// Author: Joe Zacky  August 2002
//
// Note: The file "class_assign.php" must either be in the same directory as
// this file, or you must change the "include" directive below to specify 
// the path to class_assign.php.
// =======================================================================

if (!include("class_assign.php")){                       // the assign class definition
    $thisfile = getenv("DOCUMENT_ROOT") . "$PHP_SELF";
    exit("<hr>The file <b>class_assign.php</b> was not found.<br>
    It is needed for this document to work properly.<br>
    It should be in the same directory as this file: $thisfile<br>");
}

// Uncomment the following line to turn on debug.
$debug = TRUE;

$CR = "\n";                                    // carriage return

// Start the session
if(!session_is_registered("assign")) {
    session_register("assign");                       // Store $mysession variable in session
}
?>

<html>
<head>
<title>assign class</title>
</head>

<body>
<a name="intro"></a>
<center><h1>assign class</h1></center>
<h2>Introduction</h2>
<p>
    The <em>assign</em> class is used for displaying two lists of items and being able to 
    move the items between the two lists, thereby assigning them to one or the other.
    This was originally designed for maintaing users and groups. Select a group
    and shuffle the users between being assigned to the group or not.
</p>
<p>
    There are "Add" and "Remove" buttons to move the items between the list boxes.
    There is a "Done" button to indicate the assignments are complete.
    The Add and Remove processing are performed by the <em>assign</em> class.
    When "Done" is pressed, your program can retrieve the assign lists.
</p>
<p>
    the html is retrieved with the <em>gethtml</em> function. Then your program can
    echo it where you want it to be displayed.
</p>
<!--------------------------------------------------------------------------->
<hr>
<a name="contents"></a>
<h2>Table of contents</h2>
<a href="#intro">Introduction</a><br>
<a href="#contents">Table of contents</a><br>
<a href="#section1">Section 1. Creating the <em>assign</em> object</a><br>
<a href="#section2">Section 2. Adding items to the <em>assign</em> object</a><br>
<a href="#section3">Section 3. Displaying the form</a><br>
<a href="#section4">Section 4. Processing the form</a><br>
<a href="#section5">Section 5. Function reference</a><br>
<!--------------------------------------------------------------------------->
<hr>
<a name="section1"></a>
<h2>Section 1. Creating the <em>assign</em> object</h2>
<p>
    Include the source of the <em>assign</em> class in your php source file.
</p>
<pre>
    include("class_assign.php");
</pre>
<p>
    Create a session to store the variables between displays of web pages.
</p>
<pre>
    // Start the session
    if(!session_is_registered("assign")) {
        session_register("assign");         // Store $assign variable in session
    }
</pre>
<p>
    Create the <em>assign</em> object and store it in a variable 
    that will be saved along with the session variable <em>assign</em>.
</p>
<pre>
    $assign = new assign("section1");
</pre>
<p>
    This is what the <em>assign</em> object looks like now.
</p>
<?
    $assign[1] = new assign("section1");
    echo "<pre>\n"; print_r($assign[1]); echo "</pre>\n";
?>
<!--------------------------------------------------------------------------->
<hr>
<a name="section2"></a>
<h2>Section 2. Adding items to the <em>assign</em> object.</h2>
<p>
    Let's add "freds" and put him in the "assigned" list.
</p>
<pre>
    $assign->additem("freds", TRUE);
</pre>
<p>
    Now add "susanw" to the unnassigned list and pass her name as the third
    parameter, that will make her name visible, but the program can still
    refer to the value "susanw".
</p>
<pre>
    $assign->additem("susanw", FALSE, "Susan Weisengard");
</pre>
<p>
    Now add some more people.
    Notice the "assigned" items have an <em>assign</em> value of 1.
</p>
</p>
<pre>
    $assign->additem("susanw", FALSE, "Susan Weisengard");
    $assign->additem("frankz", FALSE, "Frank Zappa");
    $assign->additem("barneyr", TRUE, "Barney Rubble");
    $assign->additem("fredf", FALSE, "Fred Flinstone");
</pre>
<?
    $assign[1]->additem("freds", TRUE);
    $assign[1]->additem("susanw", FALSE, "Susan Weisengard");
    $assign[1]->additem("frankz", FALSE, "Frank Zappa");
    $assign[1]->additem("barneyr", TRUE, "Barney Rubble");
    $assign[1]->additem("fredf", FALSE, "Fred Flinstone");
    echo "<pre>\n"; print_r($assign[1]); echo "</pre>\n";
?>
<!--------------------------------------------------------------------------->
<hr>
<a name="section3"></a>
<h2>Section 3. Displaying the form</h2>
<p>
    The <em>gethtml()</em> function returns a variable containing html code.
    The html code includes the selection list boxes, "Add", "Remove", and
    "Done" buttons, and the list box headings in a table within a form.
    Just echo the output of <em>gethtml()</em>.
</p>
<p>
    First let's clear the list.
</p>
<pre>
        $assign->clearitems();
</pre>
<p>
    Then add some items.
</p>
<pre>
    $assign->additem("krupscom",  FALSE, "Krups Coffee O-Matic");
    $assign->additem("elwok",     FALSE, "Electric Wok");
    $assign->additem("blender",   TRUE,  "Super Max Malt Blender");
    $assign->additem("51227369",  FALSE, "Waffle Iron");
    $assign->additem("Corkscrew", TRUE);
    $assign->additem("33714258",  TRUE,  "Lettuce strainer");
    $assign->additem("55147206",  FALSE, "2-Slice Toaster");
    $assign->additem("50177546",  TRUE,  "4-Slice Toaster");
    $assign->additem("bd7078",    FALSE, "Sushi Tray");
    $html = $assign->gethtml($PHP_SELF);
    echo $html;
</pre>
<?
    $assign[1]->clearitems();
    $assign[1]->additem("krupscom", FALSE, "Krups Coffee O-Matic");
    $assign[1]->additem("elwok", FALSE, "Electric Wok");
    $assign[1]->additem("blender", TRUE,  "Super Max Malt Blender");
    $assign[1]->additem("51227369", FALSE, "Waffle Iron");
    $assign[1]->additem("Corkscrew", TRUE);
    $assign[1]->additem("33714258", TRUE,  "Lettuce strainer");
    $assign[1]->additem("55147206", FALSE, "2-Slice Toaster");
    $assign[1]->additem("50177546", TRUE,  "4-Slice Toaster");
    $assign[1]->additem("bd7078",   FALSE, "Sushi Tray");
?>
<p>
    Here's what the form looks like.
</p>
<?
    $html = $assign[1]->gethtml($PHP_SELF);
    echo $html;
?>
<p>
    And here's the html output from <em>gethtml()</em>.
</p>
<?
    $htmlcode = htmlspecialchars($html);
    echo "<pre> $htmlcode </pre>\n";
    echo "<pre>\n"; print_r($assign[1]); echo "</pre>\n";
?>
<!--------------------------------------------------------------------------->
<hr>
<a name="section4"></a>
<h2>Section 4. Processing the form</h2>
<p>
    Functions are provided to process the information from the form.
    Briefly, they are:
        <pre>
        $assignlist['name']  Hidden form field containg the list name.
        getname              Get the name of the list.
        getaction            Get the value of the button pressed.
        doaction             Perform the add/remove actions.
        getassigned          Get the values of the assigned list items.
        getunassigned        Get the values of the unassigned list items.
        getall               Get the values of all the list items - both assigned and unassigned.
        </pre>
</p>
<p>
    First setup the <em>assign</em> object.
</p>
    <pre>
    if (!isset($assign)){                                
        $assign = new assign("section4");                // Create the object
        $assign->set_assigned_hdg("Shopping Cart");      // customize the headings
        $assign->set_unassigned_hdg("In Stock");
        $assign->set_add_button("<- Add to Cart");       // Customize the buttons
        $assign->set_remove_button("Remove from Cart ->");
        $assign->set_done_button("Checkout");
        $assign->clearitems();                           // Clear any items in the list
        $assign->additem("krupscom",    FALSE, "Krups Coffee O-Matic");    // Add the items
        $assign->additem("elwok",       FALSE, "Electric Wok");
        $assign->additem("blender",     TRUE,  "Super Max Malt Blender");
        $assign->additem("wafflemaker", FALSE, "Waffle Iron");
        $assign->additem("Corkscrew",   TRUE);
        $assign->additem("lstrainer",   TRUE,  "Lettuce strainer");
        $assign->additem("toast-2",     FALSE, "2-Slice Toaster");
        $assign->additem("toast-4",     TRUE,  "4-Slice Toaster");
        $assign->additem("sushit",      FALSE, "Sushi Tray");
        $assign->additem("magnet",      FALSE, "Refrigerator Magnets");
    }
    </pre>
<p>
	All the form information is contained in an array named
	<em>assignlist[].</em> The <em>assignlist[]</em> array is defined in the html 
	form fields.
</p>
<p>	
	Pass the <em>assignlist[]</em> array to the <em>assign->doaction()</em> 
	class function and the add/remove buttons will update the list boxes.
</p>
<pre>
    if ($assignlist['name'] == "section4" &                // If this form is active
        $assign->getaction($assignlist) != "Checkout"){    // and "Checkout" button not pressed,
        $assign->doaction($assignlist);                    // then process the add/remove buttons.
    }
</pre>
<p>
    Once the "Done" button is pressed (or before if you want to),
    you can retrieve the list values:
</p>
<pre>
    if ($assign->getaction($assignlist) == "Checkout"){
        $assigned = $assign->getassigned();
        $unassigned = $assign->getunassigned();
        $all = $assign->getall();
    }    
</pre>
<?
    // Create and initialize the assign object
    if (!isset($assign[2])){                                
        $assign[2] = new assign("section4");
        $assign[2]->set_assigned_hdg("Shopping Cart");
        $assign[2]->set_unassigned_hdg("In Stock");
        $assign[2]->set_add_button("<- Add to Cart");
        $assign[2]->set_remove_button("Remove from Cart ->");
        $assign[2]->set_done_button("Checkout");
        $assign[2]->clearitems();
        $assign[2]->additem("krupscom",    FALSE, "Krups Coffee O-Matic");
        $assign[2]->additem("elwok",       FALSE, "Electric Wok");
        $assign[2]->additem("blender",     TRUE,  "Super Max Malt Blender");
        $assign[2]->additem("wafflemaker", FALSE, "Waffle Iron");
        $assign[2]->additem("Corkscrew",   TRUE);
        $assign[2]->additem("lstrainer",   TRUE,  "Lettuce strainer");
        $assign[2]->additem("toast-2",     FALSE, "2-Slice Toaster");
        $assign[2]->additem("toast-4",     TRUE,  "4-Slice Toaster");
        $assign[2]->additem("sushit",      FALSE, "Sushi Tray");
        $assign[2]->additem("magnet",      FALSE, "Refrigerator Magnets");
    }

    // Perform action if "add" or "remove" button pressed.
    
    if ($assignlist['name'] == "section4" &
        $assign[2]->getaction($assignlist) != "Checkout"){
        $assign[2]->doaction($assignlist);
    }
	    
    // Make a table containing the assign form and the get...() function outputs.
    
    echo 
        '<a name="section4form"></a>' . $CR .
        '<table border="1" cellpadding="3">' . $CR .
        '<tr>' . $CR .
	    '<td>' . $CR;

    $page=$PHP_SELF . "#section4form";
    $html = $assign[2]->gethtml($page);
    echo $html;
    
    echo 
        '</td>' . $CR .
	    '<td>' . $CR .
	    '<pre>' . $CR;
	    
	echo 'getname(): ' . $assign[2]->getname() . $CR;
	echo 'getaction(): ' . $assign[2]->getaction($assignlist) . $CR;
	echo 'getassigned(): ' . $CR;
	print_r($assign[2]->getassigned());
	echo 'getunassigned(): '  . $CR;
	print_r($assign[2]->getunassigned());
	echo 'getall(): ' . $CR;
	print_r($assign[2]->getall());
	
	echo '
	    </pre>
	    </td>
	    </table>
	    ';
?>
<p>
    This is what the <em>assignlist</em> array (from the html form elements) currently looks like:
</p>
<?
    echo "<pre>\n"; print_r($assignlist); echo "</pre>\n";
?>
<p>
    And this is the <em>assign</em> class object:
</p>
<?
    echo "<pre>\n"; print_r($assign[2]); echo "</pre>\n";
?>
<!--------------------------------------------------------------------------->
<a name="section5"></a>
<hr>
<h2>Section 5. <em>assign</em> class functions</h2>

<hr>
<pre>
void <b>assign</b> ( string $name )

    <b>Description</b>
    
        Class constructor
    
    <b>Parameters</b>
    
        $name    The form identifier.
	
                 The <em>getname()</em> function will return this value so your program
                 can know which form it's working with.

    <b>Returns</b>
    
        Nothing
</pre>

<hr>
<pre>
void <b>setsize</b> ( int $size )

    <b>Description</b>
    
        Set the length (number of displayed items) in the list boxes.
    
    <b>Parameters</b>
    
        $size    Number of displayed items in the list boxes.
	
    <b>Returns</b>
    
        Nothing
</pre>

<hr>
<pre>
void <b>set_assigned_hdg</b> ( string $text )

    <b>Description</b>
    
        Set the "assigned" list box heading. The default is "Assigned".
    
    <b>Parameters</b>
    
        $text    The heading you want to appear above the left list box.
	
    <b>Returns</b>
    
        Nothing
</pre>

<hr>
<pre>
void <b>set_unassigned_hdg</b> ( string $text )

    <b>Description</b>
    
        Set the "unassigned" list box heading. The default is "Unassigned".
    
    <b>Parameters</b>
    
        $text    The heading you want to appear above the right list box.
	
    <b>Returns</b>
    
        Nothing
</pre>

<hr>
<pre>
void <b>set_add_button</b> ( string $text )

    <b>Description</b>
    
        Sets the text displayed on the "Add" button. Defaults to "<- Add".
    
    <b>Parameters</b>
    
        $text    The text you want to appear on the "Add" button.
	
    <b>Returns</b>
    
        Nothing
</pre>

<hr>
<pre>
void <b>set_remove_button</b> ( string $text )

    <b>Description</b>
    
        Sets the text displayed on the "Remove" button. Defaults to "Remove ->".
    
    <b>Parameters</b>
    
        $text    The text you want to appear on the "Remove" button.
	
    <b>Returns</b>
    
        Nothing
</pre>

<hr>
<pre>
void <b>set_done_button</b> ( string $text )

    <b>Description</b>
    
        Sets the text displayed on the "Done" button. Defaults to "Done".
    
    <b>Parameters</b>
    
        $text    The text you want to appear on the "Done" button.
	
    <b>Returns</b>
    
        Nothing
</pre>

<hr>
<em>Joe Zacky, September 2002</em>

</body>
</html>

Return current item: Browseable Online Backup System