This electronic book, the WACS Programming Guide, is designed to act both as an introduction to programming with the WACS API in either perl or PHP, and as a reference volume for both the API itself and the database schema. This book assumes you already have a basic knowledge of programming in your choosen language (PHP5 or perl5) and have some understanding of databases and in particular SQL (Structure Query Language). Some familiarity with WACS at a user level would also be a distinct advantage, and I'd strongly recommend working through the companion user guide first - who knows it might give you some ideas about neat extra features you can add to your own site. All documentation for WACS is available both within the distribution and from the WACS Web Site at Sourceforge.net.

It is important to stress that ALL of the collection management tools are implemented in Perl and the PHP interface is an optional addition to, not an alternative to, the core Wacs system which is perl based. Given the relative youth of the WACS system, php5 has been selected for the implementation to save future porting efforts as it is expected that php5 or later will be the minimum common standard by the time Wacs reaches 1.0. There is no intention to support older dialects of php at this point.

As the WACS software package is Open Source, we're always looking for contributions; if you create a site design (or prototype for one) which you don't end up using, maybe you would consider donating it to the repository of sample WACS Skins. We can always substitute our own artwork into already written web application code.

For copyright/licensing reasons, the example images feature sets from photoshoots by the main developer of WACS (Beaky) and a friend of his. These sets will be available on our demonstration site when that goes live. Please understand that due to the bandwidth and storage costs in running such a server on the internet, and the need to verify (as best we can) that the applicant is an adult, there is a small charge for access to the site.

The very first step is to import the WACS API modules into your program file along with those standard modules needed to access the database. These files should be in the right location already and should just be found without any additional specification of where they are.

require_once "wacs.php";
require_once "DB.php";

$wacs = new Wacs;

The same code segment implemented in perl looks like:

use Wacs;
use DBI;

	Note
	The PHP interface requires an Object Handle to use when accessing the WACS module which we're simply calling $wacs. Perl doesn't need such a construct - there is simply the one instance.

The second step is to read the standard WACS configuration file to find out where everything is, and then check that this user is allowed to access the WACS system. This is a two step process, and the reading of the configuration file must be done first; otherwise WACS doesn't know where to look for the security files it needs to determine whether this user should be given access or not.

// read the Wacs configuration files
$wacs->read_conf();

// check the auth(entication and authorisation) of this user
$wacs->check_auth( $_SERVER['REMOTE_ADDR'], 1 );

and here is the same thing again in the perl dialect:

# read the Wacs configuration files
read_conf;

# check the auth(entication and authorisation) of this user
check_auth( $ENV{"REMOTE_ADDR"}, 1 );

The third step is to initialise the database connection. Since some databases require an environment variable to determine where their configuration files have been stored, this needs to be set first. Wacs provides for this and this code will create that environment variable, if needed, and then proceed to establish the database connection itself.

// database initialisation
// - establish environment variable
$dbienv = $wacs->conf_get_attr("database","dbienvvar");
if( ! empty( $dbienv ))
{
        putenv($dbienv."=".$wacs->conf_get_attr("database","dbienvvalue"));
}
// - connect to the database
$dbhandle= DB::connect( $wacs->conf_get_attr("database","phpdbconnect") );
if( DB::iserror($dbhandle))
{
        die("Can't connect to database\nReason:".$dbhandle->getMessage."\n");
}
$dbhandle->setFetchMode(DB_FETCHMODE_ORDERED);

and here's how we do it in perl:

# database initialisation
# - establish environment variable
$dbienv = conf_get_attr( "database","dbienvvar" );
if( $dbienv ne "" )
{
        $ENV{$dbienv}= conf_get_attr( "database","dbienvvalue" );
}
# - connect to the database
$dbhandle=DBI->connect( conf_get_attr("database","dbiconnect"),
                        conf_get_attr("database","dbuser"),
                        conf_get_attr("database","dbpass") ) ||
die("Can't connect to database\nReason given was $DBI::errstr\n");

OK, let's just study this code for a moment. It first calls the WACS API function conf_get_attr with the section parameter of database as it wants database related configuration information, and an argument of dbienvvar. The WACS API function conf_get_attr is short for configuration get attribute and returns the value of the configuration file parameter of that name or it's default value. The dbienvvar means database interface environment variable. A typical value for this might be something like ORACLE_HOME which is the environment variable that Oracle 10g and 11i requires to be set in order to find it's current configuration.

The next line of the code checks to see if we got back an actual variable name (eg ORACLE_HOME) or an empty string (ie nothing). If we were given a valid variable name, then we're going to need to set it the value it should be, which again we can get from the configuration file, this time called dbienvvalue which is short for database interface environment value (as distinct from the variable name we just looked up). A likely value for this might be /usr/local/oracle. Obviously if we're given no variable name to set, there's no point looking for a value for it! Conversely we are assuming that having bothered to name the variable in the configuration file, also put in a valid value for it - this code could break if the variable name is specified but not it's value.

The second section of these code segments is to do with the establishment of a connection to the database and is a little different between the two versions. Both systems use a handle for the database connection, which we call $dbhandle - imaginative name huh? In both cases, the respective database APIs provide a connect function which takes an argument of how to connect to the database. The Php version takes a single argument, which is stored in our configuration files as phpdbconnect and includes the whole username, password and database specification in a single lump. The Perl version asks for three: the database specification, the username and finally the password. The configuration file knows these as dbiconnect, dbuser and dbpass respectively.

The final bit copes with putting out some kind of error message, at least showing the point of failure, if we are unable to establish a connection to the database. The methods are very slightly different, but the effect is very much the same between the two versions. We then just tell the PHP DB interface how we wish it to organise the returned data; the perl DBI default is pre-determined and is what we want.

	Tip
	Note that you might wish to have completed the output of the HTML header section and started the body by this point so that should the database connection fail, the error message will be visible.

The next step in the process is to use the database connection we've established to actually make a request of the database. For now don't worry about what that request is or how we've written it - we'll come back to that topic in detail later in this chapter. Look at the mechanics of how we're issuing the request and getting back the results. What we're going to ask the database for is a list of those girls who are marked as Favourite Solo models. We chose this because both the models in our current samples directory are marked as this and so even if you only have our sample records loaded, you should find some matches.

// do db select
//                0      1        2          3
$query = "select mname, modelno, mbigimage, mimage from ".
         $wacs->conf_get_attr("tables","models").
         " where mflag = 'S' order by mname";
$cursor = $dbhandle->query( $query );

The method is a little different in perl in that it is seperated into two steps; as a result it looks like this...

# do db select
#                 0      1        2          3
$query = "select mname, modelno, mbigimage, mimage from ".
          conf_get_attr("tables","models").
          " where mflag = 'S' order by mname";
$cursor = $dbhandle->prepare( $query );
$cursor->execute;

	Note
	The query structure is very similar between Php and perl apart for the two step process of validating and then seperately executing the query in perl. This is mostly down to different traditions that exist for database accesses in each language. The net result is similar in technical terms and identical in output terms

In both cases we're putting together an SQL query that reads:

select mname, modelno, mbigimage, mimage
from models
where mflag = 'S'
order by mname

This query asks the database to fetch the four named items: mname, modelno, mbigimage, and mimage from the database table called models where the field mflag has a value of the capital letter S and to sort the results it returns to us by the value in the field called mname. It may not surprise you to learn that mname is the model's name, modelno is our reference number for her, mbigimage is the (location of the) large size headshot of her and mimage is the (location of the) smaller size headshot of her.

You may have noticed that the only part of this that wasn't copied verbatim from the code is the from models bit and that there we've used the WACS API call conf_get_attr to get the actual name of the database table concerned from the main WACS configuration file. This is actually important and it's strongly recommended that you do use this form when creating SQL queries. If you really insist on knowing why, take a look at the section on the tables part of the wacs.cfg configuration file in the WACS configuration guide.

Once we've created the SQL query, we feed it to the database routines. The first step is to pass in the SQL query and have the database perform that search on the database. Once the query has been executed, we want to pull back the matching records (or rows in database parlence) for each model. In both Php and Perl we're calling a routine that returns to us a single row from the database (a single model's record in this case) each time it's called. When we run out of records, a null return is given and our while loop ends. In Php, the function to do this is called using fetchRow which returns the next row as an array of values, which we assign into the variable $results each time. In Perl, the function we're using is called fetchrow_array because perl offers us a choice in the type of data we are returned and in this case we want a numerically indexed array.

	Note
	There are other approaches to getting back the data, including having it returned in one big lump (such as with the Php call getAll()) - this has been avoided as some WACS installations might have tens of thousands of matching records for some queries.

The final step is to actually generate some output from the data we've fetched from the database. We're going to do this as an unordered list in HTML, so we're going to be adding a little formating to the output as we retrieve each record.

print "<ul>\n";
while( $results = $cursor->fetchRow() )
{
        print "<li>";
        print "<a href=\"".$wacs->conf_get_attr("server","cgiurl");
        print "wacsmpthumbs/".$results[1]."\">";
        print $results[0]."</a></li>\n";
}
print "</ul>\n";

and here's the perl version...

print "<ul>\n";
while( @results = $cursor->fetchrow_array )
{
        print "<li>";
        print "<a href=\"".conf_get_attr("server","cgiurl");
        print "wacsmpthumbs/".$results[1]."\">";
        print $results[0]."</a></li>\n";
}
print "<ul>\n";

We start off by printing out the HTML instruction to start an unordered list (<ul>) in a line on it's own. We then start a while loop which goes through each entry until it's done them all. Both versions use the database cursor object ($cursor) to fetch the next record (aka row) from the database using the fetchRow or fetchrow_array method and assigning it into the array $results (or in perl @results). The act of the assignment fails when there are no more records to fetch and the while loop will terminate. The construct here is based upon the fact that both languages have seperate operators for assignment (=) and comparison (== and eq) and so the code is unambiguous (at least to the php and perl interpreters it is!).

Once inside the body of the while loop we print out the start of list entry tag (<li>) and start in on making use of the data. In the quest to make this example a little bit more satisfying, we've tried to make sure this application does something vaguely useful. A simple list of names is all well and good, but we wanted it to actually do something! So what we've done here is to create a link around each models name that points to her model page as displayed by the standard WACS tools. The raw HTML to achieve this would look like:

<a href="http://www.mywacsserver.com/cgi-bin/wacsmpthumbs/123">
Sarah</a>

So we're left with a slight problem here in that we don't know in advance (trust me on this) what the WACS server is called, we don't know what the models are called and we don't know what their numbers are. We have no idea if we have a model number 123 or not and whether she's called Sarah; but the WACS system should be able to fill in all the blanks for us.

The first part of the code merely prints out the start of the HTML <a href="> and then we ask the WACS configuration system what it's externally visible URL for cgi-bin programs is. We do this using the conf_get_attr call again, telling it we want an answer in the section server of the URL for cgi scripts aka cgiurl. On the next line of the example we put the name of the WACS application we want to link to, in this case wacsmpthumbs. Since the way we tell wacsmpthumbs what we want it to look up is to add a slash and then the model number to the URL, we add a slash (/) on the end and then the number.

	Tip
	You may have noticed that we added a comment on the line above the SQL select statement with 0,1,2,3 with each number above the field name in the query. This was a shorthand to ourselves to remind us what the index number in the array is for each of those database fields.

Since the order of the fields we asked for was mname, modelno, mbigimage and then mimage, the results in the array will be the same - element 0 will be the mname, element 1 will be the model number, and so on. In both cases we're dealing with a single-dimensional array. The first field we want to go into the URL for wacsmodelthumbs is the model number, so that will be element 1 (not zero) therefore we write $results[1]. We then finish off the URL reference by closing the quotes (") and the > tag.

We then want to print the model's name which will be element 0 in our arrays, put out the closing anchor tag (</a>) and then finish off the unordered line entry with the end line tag (</li>). We then print out a new line so the generated page is easier to read. The moving on to the next record will be done as a by-product of the test for the next iteration around the while loop. Once we exit the loop, we finish off the HTML unordered list.

To just finally finish it off, we need to add a few more pieces just to make it work. For the Php version, we need to declare it as being a php program with <?php at the very start of the file, with a matching ?> at the very end. For perl, we need to declare it as a perl script with the very first line being just #!/usr/bin/perl. Additionally for perl, we need to output the mime content type declaration so that the web browser knows what kind of object it's being passed - this is done simply with:

print "Content-Type: text/html\n";
print "\n";

Next we need a couple of lines of HTML preamble near the beginning (as mentioned before, just before the database connection code so we could see any error message that appears):

<html>
<head>
<title>MySimple: Index Of Favourites</title>
</head>
<body>

Similarly at the end, we just need to finish the page off with the html tail piece:

</body>
</html>

Our first WACS application is now complete, so copy the file into the either the web server document tree (for Php) or the web server cgi-bin directory (for perl). When you call up the URL, you should see something like this....

Granted it's fairly plain, but the names are in alphabetical order and there are links on each name to that girl's model page. If you didn't see any output, or got an error, you need to check the error log for the server you're using. With Apache on linux, the usual location of this is /var/log/httpd/www.mywacserver.com-errorlog or something similar to that.

This has been a fairly long and intense chapter, but we obviously had a lot of ground to cover and we really wanted to achieve a usable program before the end of it. This hopefully we've done. We've seen how to include the WACS module and the Database interface module. We've seen how to use read_conf and check_auth to read the configuration files and check the user's credentials. We've then made multiple uses of conf_get_attr to get all of the information together we need to make a connection to the database.

After all that setup procedure, which will become a very familiar template as you program with the WACS API, we looked at creating and sending a query to the database, retrieving the results and formating those results as a simple web page. In the next chapter, we'll look at how to make use of other information stored within the database.

The next step is to modify the display loop to include the extra details and in this case it probably makes sense to switch to using an HTML table cell to contain and manage the entry. We'll start off by simply re-writing the existing display loop to build the results into an HTML table instead - once we have that working, we'll restyle the table to include the extra fields we just added to the query. There is no actual requirement to make use of all the fields we've requested.

Lets have a look at the structure of the HTML document we're outputing here: First we need to open the new table, then each model will have her own row as we go through with the headshot image on the left and her name on the right, and finally we'll finish off the table. The HTML (minus the links) to do this will look something like:

<table>
 <tr>
  <td><img src="icons/Roxanne-1.jpg" alt="[Roxanne]"></td>
  <th>Roxanne</th>
 </tr>
 <tr>
  <td><img src="icons/Sabrina-1.jpg" alt="[Sabrina]"></td>
  <th>Sabrina</th>
 </tr>
</table>

Of course the next step is to re-write the code to actually recreate the necessary HTML; the start and end of the table simply replace the unordered list (<ul> and </ul> ) tags outside the loop that iterates through the list of models returned by the database. The list element (<li> and </li>) tags get replaced by the row start and end tags (<tr> and </tr>. Since we're puting the headshot icon and the name in separate elements and want a link to the appropriate model page on both of them, we need to double up the code that creates the hypertext link to wacsmpthumbs. We then include the icon (with alignment attributes) in a standard table tag ( <td> and the name in a heading (<th>) table tag so it comes out in bold and is centred.

The mysimple example thus re-writen will look like:

// output the results
print "<table>\n";
while( $results = $cursor->fetchRow() )
{
        // start the HTML table row
        print "<tr><td valign=top align=center>\n";
        // link around the headshot image
        print "<a href=\"".$wacs->conf_get_attr("server","cgiurl");
        print "wacsmpthumbs/".$results[1]."\">";
        // head shot image
        print "<img src=\"".$wacs->conf_get_attr("server","siteurl");
        print "icons/".$results[3]."\"[".$results[0]."]\"></a>\n";
        // end this cell and start the next
        print "</td><th>\n";
        // link around name
        print "<a href=\"".$wacs->conf_get_attr("server","cgiurl");
        print "wacsmpthumbs/".$results[1]."\">";
        // the name
        print $results[0]."</a>\n";
        // end the HTML table row
        print "</th></tr>\n";
}
print "</table>\n";
// finish off

# output the results
print "<table>\n";
while( @results = $cursor->fetchrow_array )
{
        # start the HTML table row
        print "<tr><td valign=top align=center>\n";
        # link around the headshot image
        print "<a href=\"".conf_get_attr("server","cgiurl");
        print "wacsmpthumbs/".$results[1]."\">";
        # head shot image
        print "<img src=\"".conf_get_attr("server","siteurl");
        print "icons/".$results[3]."\"[".$results[0]."]\"></a>\n";
        # end this cell and start the next
        print "</td><th>\n";
        # link around name
        print "<a href=\"".conf_get_attr("server","cgiurl");
        print "wacsmpthumbs/".$results[1]."\">";
        # the name
        print $results[0]."</a>\n";
        # end the HTML table row
        print "</th></tr>\n";
}
print "</table>\n";
# finish off

When run, this modified version of the script should produce the following:

As you can see, this has improved the layout somewhat over the previous version using just unordered list elements. Now to add those extra fields....

To display some more details about the model, we're going to span the headshot on the left hand side over several rows, and add the model details themselves as additional table rows on the right hand side. Our first change therefore is to add rowspan=4 to the options on the image container <td> tag. The resulting php code is:

        // start the HTML table row
        print "<tr><td rowspan=4 valign=top align=center>\n";
        // link around the headshot image

and in perl reads:

        # start the HTML table row
        print "<tr><td rowspan=4 valign=top align=center>\n";
        # link around the headshot image

Next we add the second row which will include her hair colour and length, then a third row which will describe her breast size and the fourth row that gives the number of image sets and the number of videos we have for her.

        // end the HTML table row
        print "</th></tr>\n";
        // do the second row (her hair)
        print "<tr><td>hair: ";
        print $results[5]." ".$results[4];
        print "</td></tr>\n";
        // do the third row (her breasts)
        print "<tr><td>breasts: ";
        print $results[6]."\n";
        print "</td></tr>\n";
        // do the fourth row (her sets)
        print "<tr><td>sets: ";
        print $results[7];
        if( $results[8] > 0 )
        {
                print " videos: ".$results[8];
        }
        print "</td></tr>\n";

and the same implemented in perl would look like:

        # end the HTML table row
        print "</th></tr>\n";
        # do the second row (her hair)
        print "<tr><td>hair: ";
        print $results[5]." ".$results[4];
        print "</td></tr>\n";
        # do the third row (her breasts)
        print "<tr><td>breasts: ";
        print $results[6]."\n";
        print "</td></tr>\n";
        # do the fourth row (her sets)
        print "<tr><td>sets: ";
        print $results[7];
        if( $results[8] > 0 )
        {
                print " videos: ".$results[8];
        }
        print "</td></tr>\n";
}

With these changes made, if you now run this version of the program, which is called mysimple4 in the samples/programming directory, you should see something like this:

There's obviously a lot more room for using many more of the fields within the model schema for further improvement of our model index, and we'll return to this subject in a later chapter (Chapter 5, The User Interface Toolkit). Before we leave the topic of models and move on to sets, we will cover just one more topic, that of adding rating icons.

Since we're starting a new application, we'll start from scratch with the basic bones which we'll call setdisp. Much of the basic structure of this program should be getting quite familiar by now. The same five basic steps are to be found here - bring in the modules, initialise them, set up the database connection, submit the query and loop through the results outputting them.

What we're setting out to do in this script is to display a list of the latest additions of image sets marked as being of category flag type T which means they're solo sets involving toy usage. This we achieve by requesting only sets of type I which means image sets and of category flag type T.

	Tip
	The full lists of recommended values for the type and category flag can be found in the schema reference section at the back of this book in Chapter 10, Schema Reference: Sets.

The basic format is that we once again create an HTML table with a row for each record. There's a link on the name of the set that leads to the standard WACS page display program wacsindex. This takes a number of URL arguments but the one we're using here is to prefix the set number with page which puts it into paged display mode and appended with a .html so that it saves correctly and in some cases will get cached. We're shrinking the font in which it's displayed as it can be quite a long line of text in it's stored form (but more on that topic later).

	Note
	The SQL query itself looks after the ordering of the output; the order by sadded desc retrieves the entries in the reverse order in which they were added - the database field sadded being the date the set was added to the database, and the desc (meaning descending) puts the biggest value first. In this case that is the most recent date...

<?php
// setdisp - set display program
require_once "wacs.php";
require_once "DB.php";
$wacs = new Wacs;
$wacs->read_conf();
$wacs->check_auth( $_SERVER['REMOTE_ADDR'],1 );
// start the document
print "<html>\n";
print "<head>\n";
print "<title>SetDisp - List of Sets</title>\n";
print "</head>\n";
print "<body>\n";
// connect to the database
$dbienv = $wacs->conf_get_attr("database","dbienvvar");
if( ! empty( $dbienv ) )
{
        putenv($dbienv."=".$wacs->conf_get_attr("database","dbienvvalue"));
}
$dbhandle = DB::connect( $wacs->conf_get_attr("database","phpdbconnect"));
if( DB::iserror($dbhandle) )
{
        die("Can't connect to database\nReason:".$dbhandle->getMessage()."\n");
}
$dbhandle->setFetchMode(DB_FETCHMODE_ORDERED);
//                0      1       2      3         4        5
$query = "select setno, stitle, stype, scatflag, simages, scodec ".
         "from ".$wacs->conf_get_attr("tables","sets")." ".
         "where stype = 'I' and scatflag = 'T' ".
         "order by sadded desc ";
$cursor = $dbhandle->query( $query );
print "<table>\n";
$setcount=0;
while( (($results = $cursor->fetchRow()) &&
        ($setcount < 25 )) )
{
        // start the row
        print "<tr><td align=center>\n";
        // create the link
        print "<a href=\"".$wacs->conf_get_attr("server","cgiurl");
        print "wacsindex/page".$results[0].".html\">";
        // print out the set name
        print "<font size=-2 face=\"arial,helv,helvetica,sans\">";
        print $results[1]."</font></a>\n";
        // end the row
        print "</td></tr>\n";
        $setcount++;
}
print "</table>\n";
print "</body>\n";
print "</html>\n";
?>

and implementing the same code in perl gives us:

#!/usr/bin/perl 
# setdisp - set display program
use Wacs; 
use DBI;
read_conf();
check_auth( $ENV{'REMOTE_ADDR'},1 );
# output the HTML headers
print "Content-Type: text/html\n";
print "\n";
print "<html>\n";
print "<head>\n";
print "<title>SetDisp - List of Sets</title>\n";
print "</head>\n";
print "<body>\n";
# connect to the database
$dbienv = conf_get_attr("database","dbienvvar");
if( $dbienv ne "" )
{
        $ENV{$dbienv}= conf_get_attr( "database","dbienvvalue" );
}
$dbhandle=DBI->connect( conf_get_attr("database","dbiconnect"),
                        conf_get_attr("database","dbuser"),
                        conf_get_attr("database","dbpass") ) ||
die("Can't connect to database\nReason given was $DBI::errstr\n");
#                 0      1       2      3         4        5
$query = "select setno, stitle, stype, scatflag, simages, scodec ".
         "from ".conf_get_attr("tables","sets")." ".
         "where stype = 'I' and scatflag = 'T' ".
         "order by sadded desc ";
$cursor = $dbhandle->prepare( $query );
$cursor->execute;
print "<table>\n";
$setcount=0;
while( (($results = $cursor->fetchrow_array ) &&
        ($setcount < 25 )) )
{
        # start the row
        print "<tr><td align=center>\n";
        # create the link
        print "<a href=\"".conf_get_attr("server","cgiurl");
        print "wacsindex/page".$results[0].".html\">";
        # print out the set name
        print "<font size=-2 face=\"arial,helv,helvetica,sans\">";
        print $results[1]."</font></a>\n";
        # end the row
        print "</td></tr>\n";
        $setcount++;
}
print "</table>\n";
print "</body>\n";
print "</html>\n";

When we run this set against our demonstration web server, we get the following output which is a list of the sets containing dildo use in most-recent first order.

While it works and is usable, it's not exactly the greatest web page ever, so let's try and brighten it up a little. It'd be quite nice to be able to include an icon, and of course wacs has the infrastructure to do this for us. In fact, it offers us three different options of what size of icons we'd like: set, std and mini. In this case since we're trying to get a fair number of entries shown, we'll opt for the mini version. We get this by calling the wacsimg command and specifying that we'd like the mini version.

To make this happen we need to add another cell to the table with the HTML img tag pointing at wacsimg. As before we'll specify both align and valign properties for this table cell. So if we modify the code, much as we did before for the model icons, we get the following in php:

        // start the row
        print "<tr><td valign=top align=center>\n";
        // create the link for the icon
        print "<a href=\"".$wacs->conf_get_attr("server","cgiurl");
        print "wacsindex/page".$results[0].".html\">";
        // add the icon itself
        print "<img src=\"".$wacs->conf_get_attr("server","cgiurl");
        print "wacsimg/mini".$results[0].".jpg\" alt=\"[icon for ";
        print $results[0]."]\">";
        // end cell, next cell
        print "</td><td align=center>\n";
        // create the link

and of course the same example in perl looks like:

        # start the row
        print "<tr><td valign=top align=center>\n";
        # create the link for the icon
        print "<a href=\"".conf_get_attr("server","cgiurl");
        print "wacsindex/page".$results[0].".html\">";
        # add the icon itself
        print "<img src=\"".conf_get_attr("server","cgiurl");
        print "wacsimg/mini".$results[0].".jpg\" alt=\"[icon for ";
        print $results[0]."]\">";
        # end cell, next cell
        print "</td><td align=center>\n";
        # create the link

and if we run the resulting program, we get something like this:

One of the design decisions taken when designing WACS was to encourage directory names to be the same as the set names, and to make those more usable outside of the WACS system, to make them not include spaces. Instead the so-called Camel Technique, so named because of all the humps in it, where an upper case letter signifies the start of each new word. This is used along with a technique where underscores (_) act as the transitions between the three sections of the set name: these are:

However the underscore aspect is only used in the directory name and not in the set title (field stitle) as stored in the database which has spaces instead. Amongst our tasks, we will need to replace the spaces with the appropriate HTML table tags.

Fortunately we can use a regular expression to convert the Camel-Style text back into something a little bit more readable. This next group of changes to the code are to do exactly that. We're going to take a slightly different approach from before as we're not going to make the split off parts into seperate HTML table cells. This is because that makes both the font setting and HTML link creation much more complex - we're merely going to insert a forced line break <br> tag into the places where we want a new line to start. Then we're going to break up the Camel-Style text into seperate words. We do this with:

Our first substitution is going to be to replace the spaces (the section dividers in the stitle field) with the appropriate HTML directives. The second and third ones actually break up the words at the points the case changes:

        // print out the set name
        print "<font size=-2 face=\"arial,helv,helvetica,sans\">";
        $prettytext = $results[1];
        $prettytext = preg_replace('/\s/','<br>', $prettytext );
        $prettytext = preg_replace('/(\w)([A-Z][a-z])/','$1 $2', $prettytext );
        $prettytext = preg_replace('/([a-z])([A-Z])','$1 $2', $prettytext );
        print $prettytext."</font></a>\n";
        // end the row

To implement the same functionality in perl actually uses exactly the same regular expressions (aka regexp) but looks very different as it's all done in assignment operations without any explicit function call. There's no preg_replace used here. Anyway here is exactly the same functionality in perl:

        # print out the set name
        print "<font size=-2 face=\"arial,helv,helvetica,sans\">";
        $prettytext = $results[1];
        $prettytext =~ s/\s/<br>/g;
        $prettytext =~ s,(\w)([A-Z][a-z]),$1 $2,g;
        $prettytext =~ s,([a-z])([A-Z]),$1 $2,g;
        print $prettytext."</font></a>\n";
        # end the row

With these changes in place, we can once again copy over the code and we have a much more presentable output from the program; here's an example:

Hopefully with this we've got the output presentation of the sets list looking a whole lot better than it was in the first example. There are of course many more fields within the set database that we could also make use of in our pages. We will return to them when we look at the WACS User Interface Toolkit in Chapter 5, The User Interface Toolkit. For now, before we finish our look at sets, we're just going to look at how we find the model or models featured in a given set.

One of the things that often confuses people about true relational databases is that they are unable to do a one-to-many or many-to-many relationship directly. While many so called easy-to-use databases do offer field types that purport to offer such linking, they are problematic and do not fit into any sensible logical model for how things should be structured. Worse, each vendor's implementation (those who do implement it at all) is different and incompatible. However with a sensible schema design, this limitation really isn't a problem at all.

One such instance of this need to link one-to-many is the concept of linking a set with a model within WACS. In the easy case, you'd have thought that you'd simply put the model number into one of the fields in the set schema and the job would be done. But what do you then do when you have two models featuring in a set; easy you might say - one is the main model, the other is a secondary model, so just add a second field for the additional model and put the second number there. Of course that then makes the SQL query more complex each time as you've got to check both fields before you know if a model is in a set or not. It still might work, but it's already getting cumbersome. You might discover a set first by virtue of the additional model and only afterwards identify the official primary model.

Just about every adult site we've encountered does feature at least a few sets with three models, so suddenly we're looking at a second additional model field and having to check that as well. And believe me, there are a few sites of which Sapphic Erotica comes to mind in particular where sets with three, four, five or even six models in a single set are relatively common. Simply put, adding models to the sets table just doesn't scale. So we take the proper relational database approach and add an additional schema called assoc for associations which gives us these relationships. It's a very simple schema, basically containing a primary key, a model number and a set number.

The process of finding out who is in a set becomes very simple and straight forward - you simply search the assoc table for the set number you're looking at. If we're looking for who is in set no 123, we simply use the following SQL query:

select amodelno from assoc
where asetno = 123

We then merely loop through the results of the above query and each record we find is another model involved in this set. If we don't get any results returned, then there aren't any models associated with this particular set. Of course we probably want more than just the model number(s), but that too is relatively simple. Consider the following query:

select modelno, mname, mimage, mbigimage
from models, assoc
where modelno = amodelno
  and asetno = 123

This query simply retrieves the model details for each model who is involved with this particular set, one record at a time. Due to the way relational databases are engineered, this is actually a very quick and efficent process. The first line of the where clause does what is known as a relational join and establishes the necessary connection between the assoc and models tables necessary for what we're trying to do. Additionally it's a very logical and elegant solution that will cope with none, one, two, three, four or as many models as you like within a single simple action.

	Note
	Although we make use of the assoc table, we don't actually use any results from it - we don't need to - it has silently taken care of handling the connection we needed to make.

If we go back to our example program displaying sets, we can modify it to include this activity as a sub-routine. What we're going to do is to divide the right hand side of the output into the two cells, one with the title, and the other with the model(s) featuring in the set. The icon will remain on the left. First step is to add the rowspan attribute to the left hand side cell so the icon spans it.

        // start the row
        print "<tr><td rowspan=2 valign=top align=center>\n";
        // create the link for the icon

and in perl, it'll look very similar:

        # start the row
        print "<tr><td rowspan=2 valign=top align=center>\n";
        # create the link for the icon

The next step is to create a new function to handle the query to look up the entries in the assoc table. We're going to call this function simply getmodel and it'll take just one argument, the set number for which we want the model(s) details. It will return to us a potentially quite long string variable containing all the model names that matched surrounded by a link to each model's WACS model page.

	Note
	So long as we use a different cursor variable to the database routines we can quite happily run another query and loop through it's results while inside an outer loop looking at the results of a completely different query. This is where the whole concept of a cursor becomes really useful.

function getmodel ( $setno ) {
        global $dbhandle;
        global $wacs;
        $gmresult='';
        //                   0        1      2       3
        $modelquery="select modelno, mname, mimage, mbigimage ".
                    "from ".$wacs->conf_get_attr("tables","models").
                    ", ".$wacs->conf_get_attr("tables","assoc")." ".
                    "where modelno = amodelno ".
                    "  and asetno = ".$setno." ".
                    "order by mname ";
        $modelcursor=$dbhandle->query( $modelquery );
        // loop through the results
        while( $modelresults = $modelcursor->fetchRow() )
        {
                // do we need a divider?
                if( ! empty( $gmresult ))
                {
                        $gmresult.="<br>";
                }
                // add the model link
                $gmresult.="<a href=\"".$wacs->conf_get_attr(
                                "server","cgiurl")."wacsmpthumbs/".
                                $modelresults[0]."\">";
                // add her name and close link
                $gmresult.=$modelresults[1]."</a>";
        }
        // return the complete string
        return( $gmresult );
}

and the same code implemented in perl looks like this:

sub getmodel( $ )
{
        my( $setno )=@_;
        my( $gmresult, $modelquery, $modelcursor, @modelresults );
        $gmresult='';
        #
        $modelquery="select modelno, mname, mimage, mbigimage ".
                    "from ".conf_get_attr("tables","models").
                    ", ".conf_get_attr("tables","assoc")." ".
                    "where modelno = amodelno ".
                    "  and asetno = ".$setno." ".
                    "order by mname ";
        $modelcursor=$dbhandle->prepare( $modelquery );
        $modelcursor->execute;
        # loop through the results
        while( @modelresults = $modelcursor->fetchrow_array )
        {
                # do we need a divider
                if( $gmresult ne "" )
                {
                        $gmresult.="<br>";
                }
                # add the model link
                $gmresult.="<a href=\"".conf_get_attr("server","cgiurl").
                        "wacsmpthumbs/".$modelresults[0]."\">";
                # add her name and close link
                $gmresult.=$modelresults[1]."</a>";
        }
        # return the complete string
        return( $gmresult );
}

The final step of this process is to add into our main loop going through the retrieved set records a call to the getmodel function. This looks like:

        // next right hand cell
        print "<tr><td align=center><font size=-1>\n";
        print getmodel( $results[0] );
        print "</font></td></tr>\n";
        // increment set count 

and in perl this looks like

        # next right hand cell
        print "<tr><td align=center><font size=-1>\n";
        print getmodel( $results[0] );
        print "</font></td></tr>\n";
        # increment set count 

With these changes incorporated into the code, we now have the finished version of the setdisp program (setdisp4.php or setdisp4 in the samples directory. If we now copy this script up to the web server and run it, we should see something like this:

Once again we've gradually developed a program up to the point where it is now offering quite reasonable functionality and layout making use of the WACS programmers toolkit API. Hopefully this has given you an insight into what WACS is capable of and the basics of how to make use of it's API. In due course, we hope to have a respository of WACS skins, or mini-site scripts, which you can download and tailor to your own needs. If in the course of learning the WACS API you write some programs you'd be happy to share with others, please send them to us and we'll include them in the respository.

To include support for the WACS User Interface (WacsUI) toolkit within your application, you need to add the following extra lines to your code, ideally just after the Wacs core module.

require_once "wacsui.php";

$wacsui = new WacsUI;

and here's the perl dialect of the same activity...

use WacsUI;

print $wacsui->describeher( 
       array( 'hair'=>$results[4],
         'length'=>>results[5],
         'titsize'=>>results[6],
         'pussy'=>>results[7],
         'race'=>>results[8],
         'build'=>>results[9],
         'height'=>>results[10],
         'weight'=>>results[11],
         'occupation'=>>results[12]))."\n";

	Note
	We have to package up our parameter list as an array in order to pass it in Php; perl is somewhat simpler with a simple sequence of named parameters.

print describeher(
        hair=>$results[4],
        length=>$results[5],
        titsize=>$results[6],
        pussy=>$results[7],
        race=>$results[8],
        build=>$results[9],
        height=>$results[10],
        weight=>$results[11],
        occupation=>$results[12] )."\n";

The above example is based upon modifying the MySimple example program from in the second chapter to add the following extra fields into the query: mhair, mlength, mtitsize, mpussy, mrace, mbuild, mheight, mweight, moccupation after the mimage (with a comma of course) and before the from clause.

Both the models and sets schemas feature fields that contain a space seperated list of keywords that mark certain attributes found within that set. These can be quickly turned into a small HTML table of icons using the routine addkeyicons. The fields suitable for use with this are scatinfo from the sets table and mattributes from the models table. These are passed as the first attribute; the second being the displayed size of the icons which for the default icons would be a maximum of 48 x 48 pixels. The function is called simply with:

	addkeyicons( $results[16], 24 );

Another example of using the wacsui module can be found in the newsets.php application in the samples directory. This is a more "real world" worked example showing a new releases index page; it makes use of both the iconlink and addkeyicons functions.

Detailed documentation on each call available and how it works can be found in the API reference section Chapter 7, WACS API: User Interface Module.