GreatWebScripts.com Well Designed Scripts for the Busy WebMaster

PhotoCap Users Guide



Requirements

 

PhotoCap© Installation Manual

 

Table of Contents

 

Introduction. 2

Requirements. 3

Installation. 5

Upgrade. 9

Setup Options. 10

Automatic Photo Advancement 12

Manual Photo Advancement 15

Caption Preview.. 16

Photo Reuse. 18

Customizations. 19

Custom Directory. 19

Div Tags. 20

Recommended User Environment 21

AJAX Interface. 21

Your First Test Drive. 22

Upload. 24

List 25

Captioning. 27

Text Hilights. 27

Image References. 28

Preview Caption. 28

Sequencing. 30

Voting. 30

Contest Results and Scores. 33

Wrapup. 35

Third-Party UMS Operations. 36

Installation. 36

aMember 36

PhpBB (v2 or v3) 37

Builtin UMS Operations. 38

Tips on using the Builtin UMS. 44

Troubleshooting. 45

Installation Failures. 45

 

 

 

Introduction

 

Thank you for trying the PhotoCap® PhotoCaption Contest Game.  We believe you will find it a major visitor attraction to your website that all members will enjoy playing. 

 

Installation of PhotoCap® is designed to be a 15-minute operation.  The installation script is designed to prompt you for needed information and guide you through the process.  After installation, you will see a setup screen to customize your installation to conform to your existing website look and feel.  There is actually very little information that PhotoCap® needs to run as most of its parameters have default values so you can get up and running very quickly.

 

If you’ve never used PhotoCap® before, we suggest you read the quick overview section entitled Your First Test Drive which will walk you through the various features.  We recommend this to all first-time users.

 

And if you have used PhotoCap® before, or have an older pre-2.0 version installed, you’ll definitely want to upgrade.  Version 2 of PhotoCap provides a quantum leap in Web interactivity by enhancing the user experience with the introduction of AJAX Technologies.  AJAX (Asynchronous JavaScript and XML) is the same technology that powers Google Maps and GMail.  It achieves increased user responsiveness and interactivity by exchanging small amounts of data with the server "behind the scenes" so that entire web pages are not reloaded each time there is a need to get data from the server. This increases the web page's interactivity, speed, functionality, and usability.

 

 

 

Requirements

 

Installation of PhotoCap® requires the following:

  1. A web server or web hosting account running (almost) any major Operating System (Linux, Windows, Unix)
  2. A SQL database system, one of:
    1. MySQL (3.22 or higher)
    2. PostgreSQL  (7.1.x or 7.2.x)
    3. MS SQL Server (7 or 2000)
    4. Microsoft db2
  3. PHP (4.3.1 or higher recommended for security, but above 4.0.3 will suffice).
  4. A UMS (User-Management System) that allows the system to uniquely identify a user.  Supported UMSs are:
    1. Builtin: a fully functional embedded User Management System
    2. aMember Pro® (CGI-Central) [http://www.amember.com]
    3. phpBB® Bulletin Board [http://www.phpbb.com] (Version 2 oe 3)
    4. (Additional UMS integrations are available at a modest fee)

 

If your hosting account does not meet the requirements above, PhotoCap cannot be installed on your account. 

           

You will also need access on your local machine to an archival utility such as WinZIP or WinRAR to extract the product files, and an FTP Client such as FileZilla or FTP Commander to place the files on your web hosting directories.

 

There are two PhotoCap embedded UMS available: the default UMS that has a single, administrative user that is intended for initial testing only so webmasters can get a working demo up quickly.  The default UMS (not builtin) is neither intended nor sufficient to use as a production system! 

 

By contrast, the builtin UMS is a fully functional embedded User Management System supplied with PhotoCap.  You should either use a plugin that is compatible with your existing site UMS or use the builtin UMS.  If you are intending to use the builtin UMS with PhotoCap, please review the Section Builtin UMS Operations at the end of these instructions.

 

Before continuing with the installation, you need the following information in hand:

 

  1. The database type (MySQL, Postgres, etc) your web host provides;
  2. The name of a previously-created database that Photocap can access;
  3. A username to that database, with create/drop/insert/delete privileges;
  4. The password to the username account;
  5. The Host where the database server resides.  This value is typically localhost, but check with your web hosting company if unsure.

Installation

 

This section details how to perform a fresh install of PhotoCap – i.e., if you have never installed a copy on your site before.  See here for upgrade instructions if PhotoCap is already installed and you are trying to upgrade to a later version.

 

  1. Unzip the PhotoCap® delivery package to your local drive.
  2. FTP all files to your host into a UMS-protected directory /PhotoCap. (Note: Your UMS may require the files to be placed below a specific directory in order to be protected from unauthorized access; if so place the files in that directory but within a /photocap subdirectory)
    1. All .php, .sql, .css, .txt and .htm files should be uploaded in ASCII mode, while all graphics should be uploaded in BINARY mode. If you are unfamiliar with what this means please refer to your FTP client documentation. In most cases this is all handled transparently by your FTP Client but if you have problems later you should be sure the files where uploaded correctly as described here.
  3. Sign into your Database Manager and create the database you want to use; while it is not required to have a database dedicated to Photocap it is recommended.
  4. Sign into your UMS (if you have one), as an Administrator and ensure your UMS reports you as an Administrator.  If you do not have a UMS, refer to the section Built in UMS Operations.
  5. Run the installer by pointing your web browser to http://www.yourhost.com/photocap/install/install.php

 

You should see the PhotoCap Installation Script Display (Figure 1: Installation Script Initial Display) below appear.

Figure 1: Installation Script Initial Display

Step 1 is to select the database type (also referred to as DBMS, Database Management System) your web hosting provides.  If you do not know the database type, contact your hosting company for details.

 

Step 2 is to provide the details of how to connect into the database; this includes the server where the database is installed, the username and password, and the name of the database to use.

 

Step 3 is to identify the UMS (User Management System) you intend to use.  You must be signed in with an account that the UMS reports as an Administrator.

 

When completed press the Submit Button.  The installation script will create and populate the necessary tables and create the configuration file.  The installation status is displayed in the top window, along with any suggested changes.  If any errors are detected, correct the problem and press the Submit Button again.  When the installation parameters are correctly configured, you will see the following status window (Figure Figure 2: Successful Installation Display):

 

Figure 2: Successful Installation Display

 

 

This indicates the installation was successful, and you can now select the Setup Options you wish to set.  Select the link under “Please go to this page and complete the setup”, and you will see the Configuration page display.

Upgrade

 

This section details how to upgrade to a later version of PhotoCap from an earlier one.  It assumes PhotoCap is already installed and working at your site.  See here for information on how to install PhotoCap if you do not have an earlier version installed.

 

Before starting, backup your data, including the php files, and especially the data from the database.  Reference your web hosting provider documentation for steps on how to backup your database.

 

  1. Backup your data!
  2. Unzip the archive to your hard drive
  3. FTP the files up to the PhotoCap directory on your web host.
  4. Point your browser to http://<sitename>/photocap/install/install.php.
  5. Under the database section, if there is a ‘LoadDB’ button select it to update your database.
  6. Select the link under “Please go to this page and complete the setup”, and review the Parameters to ensure they are customized to your desires (reference next section).

 

Setup Options

 

The Setup Options Display (Figure 3: Setup Options - General Tab) allows you to select various parameters that affect how PhotoCap® works.  Unlike the Installation Script from the previous step which is intended to be run only once, the Setup Options can be run anytime you want to update your selections.

 

But first things first: You should notice a yellow message box indicating that the installation scripts are still present on the site.  If you intend to go through the demonstration steps under Section Your First Test Drive, you should leave the installation scripts in place; if you have already run the demonstration or do not care to run it, you can delete the scripts.  In all cases, before you allow public access to PhotoCap®, ensure you delete the installation scripts.  Leaving the scripts in place with a production system is a very serious security issue that could cause loss of your entire photo database.  (If you decided you need the installation scripts after deletion, simply upload that install/ directory via your FTP Client).

 

The Setup options are split into separate tabs:

  1. General: customize overall system parameters.  It is recommended you review and set these according to your site needs.
  2. Display: enables and defines the Version 2.0 AJAX interface.
  3. Scoring: sets the points awarded for different activities in the contest.  Since changing these could affect past contests, you should review and modify these when first installing the contest.
  4. Folders: defines where the contest photo files are stored.  If you change these folders after installation, you must move the existing files manually to the new directory.
  5. Security: allows you to set parameters that could impact the operation of the site.  Be careful when changing these values.
  6. Unsafe: Contains parameters that control internal processing of PhotoCap.  Do not change these unless directed by GreatWebScripts Technical Support.
  7. License: provides information regarding your current license.  Information here is for review only (no updates).

 

If you change any data in any of the tabs, press the Save Button to commit the changes or the Revert button to cancel the updates.  Note that specific details concerning the meaning of each parameter are along the left hand panel.

 

 

 

Figure 3: Setup Options - General Tab

Automatic Photo Advancement

 

The automatic advancement of your photo contest requires cron access.  The cron job is a scheduled task on your host server, and is a built-in operation of the *nix Operating System.  It simply indicates a script to run automatically, and how often to run it.  In this section you will enter the script to advance the photos, which will automate the process of moving the photos through the stages.

 

If your hosting company does not provide a cron utility, or you wish to advance the photos manually, reference the next section of Manual Photo Advancement.

 

Instructions provided are for a CPanel interface; if your host is not CPanel based contact them for instructions on how to set it up.

 

Before starting, there are several values you will need to know:

 

Document Root: This is the path your web host uses to access your site; it is provided to you by viewing the {Setup Folders} Document Root.

 

PhotoCap Installation Directory: This is the directory on your site where you installed PhotoCap; it is provided to you by viewing {Setup Folders} PhotoCap Installation Directory.

 

The PhotoCap Pathname you need to provide in the steps below is the concatenation of the above two values; a typically example is:

Document Root:  /home/user/public_html

PhotoCap Installation Directory:  /photocap/

                        (Then the PhotoCap Pathname is:  /home/user/public_html/photocap/)

 

PhotoCap Password: If you have set the password (via the {Setup Security: Auto-Advance Password Field}) use that password after the script name, preceded by a question mark.

 

 

To setup the cron job, perform the following steps. These steps set the system to advance the photos once per week, on Sunday Morning at 1:01 AM (Server Timezone).

 

  1. Log into your web host account; the screen in Figure 4: CPanel Main Display should be visible.
  2. Select the Cron jobs icon
  3. If the next display requests your experience, select Standard.
  4. You should now see the Cron Job definition display as below in Figure 5: Cron Job Entry

 

 

Figure 4: CPanel Main Display

 

 

 

 

Figure 5: Cron Job Entry

 

  1. Enter the following in the Command to run:

php -q {PhotoCap Pathname}/photocap/photocap_move.php? password={AdvancePassword} >> photocap.cron.log

Note: Enter as one line, with no blank or linebreak after the question mark;

Replace {PhotoCap Pathname} with what you calculated above.

 

Note: the ?password={AdvancePassword} is needed only if you have set the auto-advance password in the {Setup Security : Auto-Advance Password Field}

 

6.      Set the Options Boxes to the following values:

a.       Minute(s):         1

b.      Hour(s):            1

c.       Month(s):         Every Month

d.      Day(s):             Every Day

e.       Weekday(s):     Sunday

(If you want to advance it more than once per week, select the appropriate Weekday entries by holding down the CTRL keys when making additional selections).

 

7.      When you have completed the entries, press the Save Crontab button.

 

Troubleshooting: If auto-advance does not work via the cron job, you can attempt the following:

 

1.      Try defining your Domainname when invoking the script:

php -q {PhotoCap Pathname}/photocap/photocap_move.php? password={AdvancePassword} –server={Domainname} >> photocap.cron.log

Note: Enter as one line, with no blank or linebreak after the question mark;

Replace {PhotoCap Pathname} with what you calculated above.

Replace {Domainname) with your sitename (i.e., www.sitename.com)

 

 

 

Manual Photo Advancement

 

If you cannot or do not want to use Automatic Photo Advancement, you can advance the photos automatically at a time of your own choosing.  There are three methods to do the advancement depending on what granularity of control you need.

 

  1. External Semi-automatic: This method works by having you manually run the script that would be called by the cron job in the Automatic Photo Advancement Step.  Whenever you want to advance the photos, simply invoke the script at:

 

{PhotoCap Pathname}/photocap/photocap_move.php?password={AdvancePassword}

 

Note: the ?password={AdvancePassword} is needed only if you have set the auto-advance password in the {Setup Security : Auto-Advance Password Field}

 

  1. Internal Semi-automatic: In this method, you use the Administrator List Display
    (reached by pressing the List Button at the bottom of the display) and selecting the Advance button on that display.  (The effect of this is the same as in the External Semi-automatic case).

 

  1. Manual: In this method, you use the Administrator List Display
    (reached by pressing the List Button at the bottom of the display) and selecting the Complete / Caption / Ballot buttons on that display to move the specific photos into the slots you decide.

 

 


Caption Preview

 

Caption Preview is a new feature designed to add excitement to your game by increasing interaction between your players.  This feature, defaulted to OFF, is enabled through the Setup Button ® Security Tab Display.  The feature is disabled by default, and placed on the Security Tab, because it permits captions submitted by players that have not been approved by the Administrator to be displayed.  This may lead to SPAM or inappropriate captions displayed – ensure your players are mature enough to handle the Caption Preview feature!

 

If the feature is enabled, as each caption is entered it is displayed on a board above the Main Caption display, so users can view other’s input before entering their own.  In this way, users can ‘play off one another’ and submit better captions.  Reference Figure 6: Caption Preview Display as an example of the display.

 

Note the white panel below the “Current Captions” Heading.  This is the Caption Preview area.  As users enter captions via the Caption display, they are added here so new users who arrive to add captions can see all those entered previously for ideas.

 

 

Figure 6: Caption Preview Display

Photo Reuse

 

PhotoCap allows you to reuse the database of photos you build up over time so that your members will never be without a contest.  There are two ways you can reuse the photos from the database:

  1. Automatic:  To enable automatic photo reuse, first ensure the Administrator Option is enabled: Sign in as Administrator, and go to the Setup Button, General Tab, then find the Reuse Photos entry and ensure it is set to Enabled.  Next press the List Button and select the All Filter.  Associated with each file you will see a Reuse Checkbox.  If that box is checked, the photo is eligible to be recycled when necessary; photos are reused only when no Pending entries are found.

 

Photos are reused in a quasi-random order according to last time used.  This ensures the photos are not reused in exactly the same order each time, but also attempts to select a photo that has not been displayed recently.  If the Reuse Checkbox appears dimmed, it means the photo has been reused recently and will not be selected again until the cycle of photos is reused.

 

Photos that are themselves copies are not able to be recycled so that the same photo is not reused repeatedly.

 

  1. Manual:  If you want to control the photo reuse more closely, you can always disable the Automatic mode and copy the photos manually.  Press the List Button and selected the Completed Filter.  You may make a copy of any Completed photo by pressing the Copy button.  This creates a copy of the photo file, and places it into the Pending state.  From here, the file is treated as any uploaded file in the Pending state and can be renamed, deleted, or moved into play.

 

 


Customizations

 

PhotoCap is set up to allow you to customize various features concerning the look and feel of the game to your site, and ensure you do not lose those customizations during a subsequent software update of the product.  This is done through the use of a /custom directory.

 

Custom Directory

 

The /custom directory allows you to make the PhotoCap game fit with the overall appearance of your site in a way that ensures you do not lose those files with subsequent software updates. 

 

In the /custom directory of Photocap you will find two files named photocap_header_panel-dist.php and photocap_footer_panel-dist.php. Use them as a template to create a header and footer for each page of the game (perhaps to use as an advertisement or special notice).

 

To create the header or footer panels, copy photocap_header_panel-dist.php to photocap_header_panel.php and/or photocap_footer_panel-dist.php to photocap_footer_panel.php, and then make any updates in the copied files.  You may use standard php or html in the files.

 

In the ranks subdirectory are icon files named rank_1.jpg through rank_6.jpg, corresponding to the icons used for the rank indicators from the Scorecard.  Photocap comes shipped with The Simpsons icons; you may substitute indicators of your choosing which fit in with the theme of your site by copying the new icon files to a

/custom /ranks directory (Note that you will need to create the /ranks subdirectory below custom if not already present).

 

You can also customize the prize icons.  The files are located in the images subdirectory, named prize1.gif, prize3.gif, prize3.gif.  These are the icons displayed for the First Place, Second Place, and Third Place winners of your contests.  If you increase the number of prizes, you can add additional gifs with appropriate names for display.  If you increase the number of prizes, you can also update the CSS file entry archiverow-n to specify the background color of the new prize row on the Winner’s Page.  To provide your own prize images, copy the icons files to prize1.gif … prizeN.gif in the /custom/images directory.

 

Lastly the photocap.css file contains the CSS commands used to format the display. You will find many updates to Photocap to better harmonize with your site.  First, copy file photocap.css from into the custom directory before making your changes; this prevents a future software update of Photocap from overwriting your changes.  If file photocap.css is found in the custom directory, it is loaded when the script runs (and overrides the values specified in the distribution file).

 

 

Div Tags

 

Div Tags are a great feature for you to create unique site customizations for your captions.  They allow you to create new tags that players use to hilite the text in their captions.  The screen to create these tags is under Setup → Security Tab.  The procedure to create a new tag is:

  1. Add a new tag under the Div Tag entry in Setup → Security Tab.  This is the name your players will use.  (Example: you want to use ‘blue’, so enter <blue> in the Div Tag entry.);
  2. In custom/photocap.css, create an entry for .blue; specify any css parameters you design, such as color: blue;
  3. Players can now enter the tag <blue> and </blue> to specify that highlighting. (Example: <blue>This text is in blue</blue>).

 

 

Recommended User Environment

 

The AJAX Technologies introduced in PhotoCap 2.0 require users to have updated browsers in order to take full advantage of its capabilities.  PhotoCap dynamically checks the user’s browser as it executes and if it finds the environment lacking it automatically falls back to an earlier, reduced capability.  Nonetheless, GreatWebScripts recommends the following minimum version of user’s browsers for full enhanced support::

o  Internet Explorer 5.0+,

o  Safari 1.2,

o  Mozilla 1.0 / Firefox,

o  Opera 8+,

o  Netscape 7.

 

o  With Javascript and Cookies enabled for full support

 

Note: as a WebMaster, you have no control over a user’s environment when he visits your site.  The previous paragraph is not meant to imply you must validate every visitor’s machine that comes to you site; it is provided so that if a player contacts you that he is not experiencing the enhanced version of your site, you can determine the reason.

 

 

AJAX Interface

 

The AJAX Interface is enabled by default.  It indicates PhotoCap should validate the settings of the user’s browser and if enabled, use JavaScript to enhance the game experience.  The Administrator may manually disable AJAX via the switch setting in the Administrator Control Panel, Display Tab, Enable AJAX Interface setting.

 

Each user will see the Ajax Meter near the top of the display as shown below.  The Meter indicates whether the Ajax interface is enabled for that user – if the user’s browser does not support Javascript or Cookies, Ajax cannot be enabled.  The user can request PhotoCap to recheck the Ajax, or manually enable/disable it.

 

Figure 7: Ajax Meter

Your First Test Drive

 

OK, you installed PhotoCap, configured it, setup the photo advancement – now what can it do?  Here’s your first introduction to the product.

 

First off, remember that the photos go through four stages during the game:

  1. Pending:         When first uploaded and before being used in the contest.
  2. Captioning:    Uses are able to enter captions for the photo.
  3. Balloting:       Users are able to vote for their favorite captions for the photo.
  4. Complete:        Captioning and Balloting are finished, and score has been tallied.

Note that several photos can be at Pending or Complete, but only one photo at a time is at Captioning, and another photo at Balloting. (i.e., photos are captioned and voted one-at-a-time).

 

 

 

Diagram 1: Photo Cycle

 

 

Let’s get started.  First, sign on as an Administrator, and go to the Setup Options Page (http://www.yoursite.com/photocap).  You’ll see the Main Page as in Figure 8: Main Display below.

 

 

 

Figure 8: Main Display

 

 

This is the main display your users will see when the login to the game (except of course a photo will be displayed).  Most users will NOT see the buttons in the display at the bottom highlighted in yellow; as those are Administrator-only functions.  We’ll discuss the other parts of the screen once we get a photo installed.

 

Upload

 

To upload your first photo, press the Upload button.   You’ll see the Upload Display as in Figure 9: Upload Display.  This is where you (and your users if you let them), will upload their photos to be used in the contest.

 

 

 

Figure 9: Upload Display

 

Press the Browse button.  You’ll see a popup that allows you to find a file on your local machine.  Find a picture file (.jpg. .gif. .png) you want to upload, select it, and press the Open button.  [It doesn’t matter what the picture is, because we are going to delete it when done].  The filename will be in the file selection field next to the Upload button.  Now add the title “First Photo” to the photo so you’ll remember what it is, and press the Upload button.  The file will be uploaded to your website, ready for use in the PhotoCap contest.  We need at least three photos to demonstrate all the features, so find two more photo files and upload them as well, using the titles “Second Photo” and “Third Photo”.

 

List

 

Once we have the three files uploaded we can work with those photos.  Press the List button at the bottom of the display in the yellow highlighted area.  You should see a display similar to the one below in Figure 10: List Display.

 

Figure 10: List Display

 

 

 

(Your display will have the three photos you uploaded) Note the three photos we uploaded.  Their statuses are all Pending, because they are ready to be used in the game.  There is a button Delete to erase the photo, Rename if you want to change its title, and a ReSeq button we’ll get to shortly.  Also notice the Column of Sequence along the far right.  That tells you which photo will be used next if the Automatic Photo Advancement is used (through either the cron job discussed earlier, or the Advance button you see on this display).  Automatic Photo Advancement always picks the lowest-sequenced photo to use next or a random selection if no photos are sequenced.  Right now they are all set to Random because we didn’t specify an order.

 

If you want to explicitly pick a photo for advancement, you can select the Caption and Ballot buttons.  Select the Caption button next to the First photo.  Note that at the bottom of the display you now have a Caption Button. 

 

Captioning

 

Press the Caption button, and you will see the display as in Figure 11: Caption Display.

 

The Caption Display is typically the first display your users see when the open the contest.  It displays the photo you uploaded, plus <three> fields for user input.  (The <three> indicates the field is configurable, so you can set it to however many entries you want a user to be able to enter).  For the captions, enter “Photo Caption 1” for the first photo, “Photo Caption 2” for the second and “Photo Caption 3” for the third. Press the Save button.  You have just entered your first three captions in the contest!

 

Note that the captions are randomly reordered – this is so users cannot influence the voting.

 

Since you are the Administrator, you will see a Caption* button at the bottom of the display.  That’s called the Caption Spy – it’s used so you can review the current contest captions to ensure they fit your site’s Terms of Service (TOS).  Press it, and you will see your three captions listed.

 

Text Hilights

 

As Admin, navigate to the Setup → Security Tab, and ensure Enable Text Hilighting in Captions is selected and then press the Caption button to return to the Captioning Display.  You will now see the Text Hilight buttons on the Captioning Display.  The  is used to bold the text; the  is used to italicize the text; and the  is used to underline the text. Note that when you press the buttons a bracketed symbol is used;  text between the bracketed systems has the highlighting applied to it.  If text is already typed, you can select the text and then press the button; the selected text is bracketed with the symbols.

 


Image References

 

As Admin, navigate to the Setup → Unsafe Tab, and ensure Allow Images in Captions is selected and then press the Caption button to return to the Captioning Display.  You will now see the Image Button in the Captioning Display – press the  to reference an image into your captioning.  You must type the complete http://header into the text for the image to be accessed.  Note: after trying this feature, you may wish to go back to your Admin Display and disable it, as it allows users to reference any other photo with no approval from you.

 

Preview Caption

 

Uses can view their captions, with text highlighting and image references complete, by pressing the  Preview button.  A second window is displayed with the caption text exactly as it will appear on the final display.

 

Figure 11: Caption Display

Sequencing

 

Now press the List button to get back to the Photo List Display.  Note that the First photo is marked as Current, and Second and Third are Pending.  Now we’re going to advance the photos along to the next stage.

 

But let’s specify an order for the photos.  If we were to simply either request an advance at this point, photo Second or Third would be selected at random.  We will have the system select the Third photo. 

 

Type a ‘2’ for the photo titled Second, and a ‘1’ for the photo titled Third.  (That’s not a misprint, you want to enter ‘2’ for the Second and ‘1’ for the Third.  We’re going to fix it in a minute).  Press the Apply button at the bottom.  There will be no real changes to the display.

 

The way it stands now, the Second photo has a sequence of 2 and the Third Photo has a sequence of 1, so Automatic Photo Advancement would pick the Third Photo (because it has the lowest sequence number).  Suppose we want to use the Second Photo next.  Go into the Sequence column next to the photo titled Second, type a ‘0.5’, and press Save.  The display will be re-ordered to show the new sequencing of photos – now the Second Photo will be used next, and then the Third. 

 

The Second Photo has a sequence to ‘0.5’.  To make it easier to understand, let’s resequence the photos to integer numbers by press the ReSeq button.  Now the photos are renumbered in the sequence you specified, started from 1.  Just confirm the Second Photo has a sequence of 1, and the Third has a sequence of 2.

 

Press the Advance Button.  The Advance function is a semi-automatic way of advancing your photos – the photo that was Balloting is moved to Completed, the photo that was Captioning is moved to Balloting, and the system selects the next sequenced Pending photo and makes it Captioning.  In this case, the photo titled First is moved to Balloting, and the photo titled Second is moved to Captioning.

 

Voting

 

A Vote button is now available at the bottom of the display because a photo is in the Balloting phase.  Press the Vote button, and you will see the display as in Figure 12: Voting Display, except you will not see the captions you entered.

 

The Balloting Display is the second most often display for your users when the play the contest.  It displays a photo plus the captions entered by users during the Captioning phase.  Note that from this display you can’t tell which user contributed the caption; this is to avoid bias in the voting. 

 

Figure 12: Voting Display

 

You also cannot vote for the captions you entered, again to avoid bias in the voting. Actually this is a configuration setting that is normally off, and this is the reason why there are no captions available for you to vote.

 

We need to enable voting of our own captions.  Press the Setup button at the bottom of the display, then the Security Tab.  Set the entry for “Vote Own Captions” and set it to Enabled.  Press the Vote button, and you will see the display as in Figure 11: Caption Display.  There are the captions you entered previously, sorted in random order to avoid bias.

 

For the “Photo Caption 2” from the pulldown menu select “1”.  This means you vote that caption to First Place.  Notice that the display is updated to show that caption in the proper place, and remove it from the voting area (you cannot vote for the same caption more than once).  For the “Photo Caption 3” from the pulldown menu select “2”.  Now you have voted two captions, for “Photo Caption 2” in First Place and “Photo Caption 3” in Second Place.

 

Now we’re going to insert the third caption into First Place.  For the “Photo Caption 1” from the pulldown menu select “1”.   This moves the other captions down a place, and inserts that caption as First Place.  Select “Photo Caption 2” from Second Place and choose “Remove”.  This deletes your vote for the caption, and allows you to select another.  In this example this is no other caption to select, but you could leave it empty and vote for only First and Third place.

 

Since you are the Administrator, you will see a Vote* button at the bottom of the display.  That’s called the Vote Spy – it’s used so you can review the current contest voting to get advance notice of the winner.

 

You can experiment with the Voting display as desired, but before you proceed to the next step ensure the “Photo Caption 1” is in First Place, “Photo Caption 2” in Second Place, and “Photo Caption 3” is in Third.

 

Contest Results and Scores

 

You are in the normal state of the game at this point- one photo (First) is at Balloting, allowing users to vote captions that were entered previously, and another photo (Second) is at Captioning, allowing users to enter captions.

 

Next we advance the First Photo to its final phase, Completed.  Press the List button to get back to the Photo List Display.  Note that the First photo is marked as Balloting, Second is marked as Captioning and Third as Pending.  Press the Advance button. 

 

Now the First photo is marked as Completed, Second as Balloting, and Third as Captioning. Press the Caption Button to get back to the Captioning display. You will also see a Winner button at the bottom.  Select the Winner button.

 

This shows the Results Display, where the winners of the previous contest are shown.  The First, Second, and Third place entries are displayed.  Selecting the entries will display a popup of the Vote Record, all votes collected for that photo so users can validate the results.

 

You will also see a Scores button at the bottom.  Selecting the Scores button will popup a window that provides the Contest Scorecard, indicating all contestants, completed photos, and the current score for each user.  Selecting a user will display the User Scorecard for that user, which details his total points and score.

 

 

Figure 13: Contest Scorecard

 

Figure 14: User Scorecard

 

 

 

Wrapup

 

Before exiting the demonstration, visit the Configuration display and restore the setting we changed.  Press the Setup button at the bottom of the display, then the Security Tab.  Set the entry for “Vote Own Captions” and set it to Disabled. 

Third-Party UMS Operations

 

This section details how to work with a third party UMS and PhotoCap.  PhotoCap works by querying the UMS as to the current user’s name and userid.  The UMS should provide a unique userID for each user; the userID is stored when the user interacts with the game.  Then the game queries the UMS to determine the username for each userID it encounters to make it more presentable to the human player.

 

PhotoCap ensures that the UMS unique userID is set before allowing a player to interact; if not set he is prompted to log into the UMS first.

 

Installation

 

This section describes how to select and install a UMS during the installation process.   The installation follows a standard model:

  1. If the UMS has a method to indicate whether an account is a privileged user, that method is employed to indicate the user is a PhotoCap admin; otherwise the UMS is extended to provide such a notice.
  2. Using the method identified or created in Step 1, add/modify an account to have PhotoCap Admin privileges.
  3. Sign in to the PhotoCap Admin account.
  4. Run the installation script, and select the desired UMS.
  5. Enter/change any parameters needed for the UMS.

For virtually all UMSs, the PhotoCap Admin is distinct from the Site/UMS Admin, so you can add as many PhotoCap Admins as desired, without giving them other site Admin powers.

 

aMember

 

To install the aMember UMS, follow these steps:

 

  1. From the aMember Control Panel, create two new fields for aMember:
    1. admin: Checkbox field; is set if user is admin.  This field is NOT available for the standard aMember User to set / review; it should only be set via the aMember Control Panel. Set it if the user is a PhotoCap administrator in your system.

Field Name: admin

Field Title: Administrator (whatever)

Field Type: Common field

SQL Field Type: Blob

Display Type: Checkboxes

Field Value: administrator|Administrator

Visibility: Display in signup / profile: Don't Display

 

    1. Timezone:  Pulldown field for user to set his local timezone so datetimes are displayed in local zone.

Field Name: timezone

Field Title:  Timezone (whatever)

Note: If you do not create the timezone field, all times will be set to your server's time zone.

 

  1. From the aMember Control Panel, check the 'admin' box for one of the aMember users you want to be a PhotoCap Administrator
  2. Sign in to aMember using the account you set in Step #2.
  3. Run the PhotoCap installation script: at www.yoursite.com/install/install.php
  4. Under the UMS Parameter Section, select 'aMember' and press the Submit button.
  5. Verify the fields under the UMS Parameters Section:
    1. AMEMBER_DIR: aMember Root, typically /amember/.  The aMember configuration file config.inc.php should reside there
    2. AMEMBER_ADMIN_FIELD: The name of the Admin checkbox you created in Step a.
    3. AMEMBER_TIMEZONE_FIELD: The name of the Timezone field you created in Step a.
  6. When the fields are correct press the Submit button.

 

 

Troubleshooting:

  1. If you get an error that you are not signed in as an Administrator,

ensure the aMember account name you are signed in as has the "admin” box that you created checked.  (Note: You can only set this via the aMember Control Panel).  

 

 

 

PhpBB (v2 or v3)

 

To install the phpBB UMS, follow these steps:

  1. phpBB contains a setting indicating if the user is an Admin; that same setting is used by PhotoCap.  If the account is an Admin for phpBB, he is also an Admin for PhotoCap.
  2. Sign using the account you set in Step #1.
  3. Run the PhotoCap installation script: at www.yoursite.com/install/install.php
  4. Under the UMS Parameter Section, select ‘phpBB’ and press the Submit button.
  5. Verify the fields under the UMS Parameters Section (In general, the defaults should be correct):
    1. PHPBB_COOKIENAME: Cookie used to store login information.
    2. PHPBB_SIDGETNAME: Parameter used to pass phpBB SID via URL
    3. PHPBB_TABLEPREFIX: phpBB Tablename prefix
    4. PHPBB_DBNAME: The database that phpBB uses, if different from the one used by PhotoCap.
    5. PHPBB_LOGIN: The URL to redirect the user if he attempts to enter the Photocap game without having signed in (typically this is the phpBB sign in page).  This allows the user to log in, and then return to the PhotoCap game.
  1. When the fields are correct press the Submit button.

 

 

Builtin UMS Operations

 

The builtin UMS is a complete UMS that you can use if your site does not have an existing User Management System.  It allows for three levels of users, which determine the amount of changes an individual can perform.  User authentication is provided by a password of selectable length.

 

The builtin UMS is a fully functional and automated UMS. It has the ability to require a valid email address by sending the initial password; to allow a user to retrieve a forgotten password via email address; and to allow users to register a new account.

 

There are three types of Users:

  1. Root Admin: The superuser in charge of all other users.  He can add, modify, delete, or promote any other account.  Only the Root Admin can promote (or demote) any User account to Admin status. There is only one Root Admin account, created at Installation.
  2. Admin: Admins are in control of the game functions.  They can adjust the parameters of the game, move the photos, edit the user inputs, and all the other functions of “Administrator” in the game writeup above.  You can have as many Admin accounts as you want. (The Root Admin is also an Admin).
  3. User: Users are the standard players.  They can enter captions, vote, and all other non-Administrator functions. (The Root Admin and all Admins are also Users).

 

When you install PhotoCap, you will be asked for your UMS.  If you select builtin and press Submit, the following fields will be available for you to fill in:

 

 

Figure 15: UMS Parameters

 

 

The fields you need to supply are Administrator Username, Administrator Password (twice), and Timezone.  The Administrator Username is the Root Admin account.  The Timezone field is used to adjust the Activity Log times to local time. 

 

Once you complete the fields and Submit, you can access the Setup Options Page.  You will notice that you first need to login to the UMS.

 

Figure 16: Login Prompt Display

 

 

Enter the Root Admin Username and Password as you supplied on the installation script.  You will be logged into the UMS, and placed at the Setup Options Page.

 

The page is identical to that described previously, with the addition of a band of options for the UMS.

 

Figure 17: UMS Band

 

The band of commands at the top allows you to control the User Management System.  The functions are:

  1. Logoff: Sign off the UMS.  You will have to re-enter your username and password to get back into the system.
  2. Change Password: Allows a user to change his password (and the Root Admin to change his login).
  3. My Account: Allow a user to change his account information (email, timezone).
  4. Manage Users [Admin]: Allows the Admins to add, modify, and delete other users.  The Root Admin can promote other users from this display.
  5. Activity [Admin]: Allows the Admins to monitor the activities of the UMS.
  6. UMS Setup [Root Admin]: Allows the Root Admin to setup the parameters of the display.

 

We’ll more closely examine the major displays of Manage Users and Activity Display.  An example of the Manage Users, reached by selecting the Manage Users from the menu band is below:

 

 

Figure 18: Manage Users List

 

Figure 18: Manage Users List shows the users defined in the System.  The current user is highlighted in yellow.  The Username, UserID (assigned automatically by the UMS), IP of signup, Email are all displayed, along with an Admin defined comment and date of account creation.  There are four operations permitted for each user:

  1. The status of the user is indicated by a redlight/greenlight icon; a  indicates the user is Active and may log into his account; a  indicates the user is Inactive and may not signin. The  indicates the user is Pending, meaning you have required Email Validation at registration and the user has not yet signed in.  As soon as the user does sign in, his status will switch to Active.
  2. The rank of the user is displayed via icon; a  indicates the user is an Admin, while a indicates the User is at the User level.
  3. The red ‘X’  is selected to delete the user;
  4. The green ‘E’  will allow an Admin to edit the user account to modify his account data and/or the account password.
  5. Pressing the New Button allows the Admins to create new users.

 

There is a restriction that one Admin account cannot modify any other Admin account – only the Root Admin can modify other Admin accounts.

 

Finally, Figure 19: Setup Display is the UMS Setup Parameters display, accessible only to the Root Admin.

 

 

Figure 19: Setup Display

 

 

 

 

 

Most of the entries are self-explanatory.  Several to pay special attention to are:

 

  1. Enable Game: Setting this to Disabled signs-off any players, and does not permit anyone except the Root Admin to sign on.  This is used if you need to perform maintenance on the site and do not want your users to log in. 

Normal State: Enabled.

 

  1. Allow User Registration: Setting this to Disabled precludes users from creating new accounts, in which case an Admin user must create all accounts.  If new user registration is enabled, a Register link is displayed link at the Login Prompt (Figure 16: Login Prompt Display).

Normal State: Enabled.

 

  1. User Address Information: Set this to Required to force new users to enter some text for address information (which of course is not verified), or Optional to allow the user to enter address information, or None to not display the address fields.

Normal State: None.

 

  1. Allow Reset Password: When Enabled the user can request his password be reset and emailed to him at his registered address.  This displays a “Forgot your Password?” link at the Login Prompt (Figure 16: Login Prompt Display).

Normal State: Enabled.

 

  1. New User Initial State: Setting this to Inactive means that when users create a new account, they cannot sign in until an Admin approves the registration.  If set to Active, users can sign in and play as soon as they register. When set to Require Validation the user’s initial password is randomly generated and emailed to him at the address he registered. 

Normal State: Inactive.

 

Tips on using the Builtin UMS

 

  1. If you have not had any spammers or troublemakers visit your site (you’re lucky!) you can set the New User Initial State to Active to allow new users to register quickly.  If you get too many troublemakers, you will have to adjust it back to Inactive.
  2. In general, once a user has been playing the game DO NOT delete his account, even if he is no longer playing.  If you delete the account, the photos he uploaded, his captions and his votes all become ‘orphaned’ such that the system cannot determine the player’s name. Instead of deleting the account, just set it to Inactive.

 

Troubleshooting

 

Installation Failures

 

This section deals with problems that preclude the installation from completing.  They are indicated by Red Errors at the top of the PhotoCap Installation Screen.

 

Message

Explanation

Remedy

Could not connect to database: verify username, password, and host.

 -OR-

No Connection: Double check the “Database Parameters” in the table below

PhotoCap could not connect to your database.

Double check the values you supplied for username, hostname, and password are correct and try again. (Before submitting, try the Verify Database Parameters Test).

ERROR Creating Table: tttt - Verify User uuuu has full privileges in Database dddd

PhotoCap cannot create tables in the database

Verify the specified user has the Create privilege in the specified database.

ERROR Inserting Into Table: tttt - Verify User uuuu has full privileges in Database dddd

PhotoCap cannot insert into tables in the database

Verify the specified user has the Insert privilege in the specified database.

ERROR Updating Table: tttt - Verify User uuuu has full privileges in Database dddd

PhotoCap cannot update tables in the database

Verify the specified user has the Update privilege in the specified database.

ERROR Selecting From Table: tttt - Verify User uuuu has full privileges in Database dddd

PhotoCap cannot select from tables in the database

Verify the specified user has the Select privilege in the specified database.

ERROR Deleting From Table: tttt - Verify User uuuu has full privileges in Database dddd

PhotoCap cannot delete from tables in the database

Verify the specified user has the Delete privilege in the specified database.

ERROR Dropping Table: tttt - Verify User uuuu has full privileges in Database dddd

PhotoCap cannot drop tables in the database

Verify the specified user has the Drop Table privilege in the specified database.

No write access to current directory

PhotoCap must write to the current directory it is installed in to create the configuration file

chmod the /photocap directory to 0755

 

Error Creating the Configuration File

PhotoCap must write to the current directory it is installed in to create the configuration file

chmod the /photocap directory to 0755

Error writing the Configuration File

PhotoCap must write to the current directory it is installed in to create the configuration file

chmod the /photocap directory to 0755

HTTP Error 500 – Internal Server Error

The PhotoCap scripts are present on your site but are not executable.

chmod the /photocap directory to 0755