PLUGIN README
websiteFavorites - Website favorites functions for allowing users to marking
records as favorites (or "saving" records) in their profile.
-------------------------------------------------------------------------------


GETTING STARTED
-------------------------------------------------------------------------------
Please be aware that this is a fairly advanced plugin.  It will take care of
the basics and save you a lot of time implementing "saved" or "favorite"
records, but adding functionality beyond the basics may require more advanced
PHP, MySQL, Javascript, HTML or CSS knowledge.

This plugin works with the "Website Membership" plugin and requires that users
be logged in to mark a record as saved or favorite.

1) Install and activate the "Website Membership" plugin in the CMS under: Admin > Plugins.

2) Install and activate the "Website Favorites" plugin in the CMS under: Admin > Plugins.

3) Update the following variables at the top of the plugin file:

   $GLOBALS['WSF_LOGIN_REQ_MESSAGE'] = "You must login to use this feature!";
   // This is displayed if the user tries to add a favorite and isn't logged in to the website


CREATING ADD/REMOVE FAVORITE LINKS
-------------------------------------------------------------------------------
Follow these steps:

1) Make sure that /lib/viewer_functions.php is loaded at the top of the page.
The filepath will be different for each server but the PHP tag will look
similar to this:

  <?php require_once "cmsAdmin/lib/viewer_functions.php"; ?>


2) Add the following code to the <head></head> of your html page:

  <!-- favorites -->
  <script type="text/javascript" src="/cmsAdmin/plugins/websiteFavorites/websiteFavorites.js"></script>
  <script type="text/javascript" src="/cmsAdmin/3rdParty/jquery/jquery1.4.1.js"></script>
  <script type="text/javascript">jQuery.noConflict();</script>
  <?php $GLOBALS['WSF_SCRIPTS_LOADED'] = true; ?>
  <!-- /favorites -->

  Notes:
  - If needed, change the path /cmsAdmin/ to reflect the url of your CMS
  - Add this code before any other <script> tags, it's designed not to interfere if loaded first
  - (OPTIONAL) You can copy the javascript files to another directory if you prefer


3) Add this code where you want the add/remove favorite links:

  <?php
    $tableOrTag = 'article';       // Update with your section's table name
    $recordNum  = $record['num'];  // Update this with current record number
  ?>

  <div class="<?php wsf_cssClassFor($tableOrTag, $recordNum, 'add'); ?>"
       style="<?php wsf_displayStyleFor($tableOrTag, $recordNum, 'add'); ?>">
    <a href="#" onclick="<?php wsf_onClickFor($tableOrTag, $recordNum, 'add'); ?>">Add Favorite</a>
  </div>

  <div class="<?php wsf_cssClassFor($tableOrTag, $recordNum, 'remove'); ?>"
       style="<?php wsf_displayStyleFor($tableOrTag, $recordNum, 'remove'); ?>">
    <a href="#" onclick="<?php wsf_onClickFor($tableOrTag, $recordNum, 'remove'); ?>">Remove Favorite</a>
  </div>

4) Reload the page and click "Add Favorite".  The link should change to
"Remove Favorite".  Reload the page and confirm the link still displays as
"Remove Favorite" indicating that the current page is a saved favorite.


LISTING FAVORITE RECORDS
-------------------------------------------------------------------------------
Use the following viewer code to load only the users favorite records from a
section:

  <?php
    require_once "cmsAdmin/lib/viewer_functions.php";

    // get favorite record nums
    $tableOrTag        = mysql_escape('news');  // update this with your table or tag name
    $currentUserNum    = mysql_escape( @$CURRENT_USER['num'] );
    $favoriteNumsQuery = "SELECT recordNum FROM `{$TABLE_PREFIX}_website_favorites` WHERE tableOrTag = '$tableOrTag' AND createdByUserNum = '$currentUserNum'";

    // load matching records
    list($favoriteRecords, $favoriteMetaData) = getRecords(array(
      'tableName'     => 'news', // update this with your table or tag name
      'perPage'       => '10',
      'where'         => " num IN ($favoriteNumsQuery) ",
      'loadCreatedBy' => false,
      'allowSearch'   => false,
    ));
  ?>

Just update 'news' with your tablename.


MANAGING FAVORITE RECORDS
-------------------------------------------------------------------------------
To allow the user to manage and remove their favorite links, such as in a
"My Profile" section of a website, use the above code to load the favorite
records, and this code below to display a "Remove" link beside each one:

  <h2>Favorites</h2>
  <?php foreach ($favoriteRecords as $record): ?>
    <?php
      $tableOrTag = 'news';          // Update with your section's table name
      $recordNum  = $record['num'];  // Update this with current record number
    ?>

    <div class="<?php wsf_cssClassFor($tableOrTag, $recordNum, 'remove'); ?>"
         style="<?php wsf_displayStyleFor($tableOrTag, $recordNum, 'remove'); ?>">
      <a href="<?php echo $record['_link'] ?>"><?php echo $record['title'] ?></a> -
      <a href="#" onclick="<?php wsf_onClickFor($tableOrTag, $recordNum, 'removeAndReload'); ?>">Remove</a>
    </div>
  <?php endforeach; ?>

  <?php if (!$favoriteRecords): ?>
     You don't have any favorites yet.
  <?php endif; ?>

Just replace 'news' with your table name and $record['title'] with whatever fields
you want to display from the record.


ALTERNATE USES
-------------------------------------------------------------------------------
There are a number of things you can do besides just allowing users to save
"Favorite" pages or listings on a website.

- Block Users: A common social networking website feature.  To allow users
to block each other use 'accounts' as the tableOrTag and the user number as
'recordNum'.  The block status can easily be displayed and a list of blocked
user numbers can be queried from the database.

- Wink/Wave: A common dating site feature.  To allow users to wink/wave at
each other disable the "remove favorite" function (see below) and create a
wsf_addFavorite_callback() function to send a message.  Additionally you
could query the database to allow users to see a list of users who had
wink/waved at them.

- Who's Viewed Me: A common social networking website feature.  To automatically
track which users have viewed each other add this code to the "view" or
"profile" page and replace $member['num'] with the number of the current member:

  if (@$CURRENT_USER) { // Add to "Who's Viewed Me"
    wsf_addFavorite('whos-viewed-me', $member['num']);
  }

- Product Wishlist: A common shopping/e-commerce site feature. Add products to
your "wishlist" for later access. Wishlists could even be displayed publicly or
queried for aggregate data such as "Most Desired Products".  Just use the same
setup as you would for Favorites or to use both features on the same site add
"-wishlist" to the tableOrTag value for the wishlist to keep the data separate.


ADVANCED TOPICS
-------------------------------------------------------------------------------

- If you can't use divs or need to use something else you can put the class and
style from the <div> in another tag or in the <a> itself (such as when the links
are inside <li> tags and divs break the design).

- You can use any value for "titleOrTag" (up to 255 characters long).  As long
as "titleOrTag" and recordNum form a unique value you can use them to check if
something is "enabled" or "toggled" or not.

- If you only want to "add favorites" you can remove the class and style from
the add div.  Duplicates won't be created.  This is used for something like a
dating site where you want to Wink/Wave at other members (see above).

- If you create a PHP function called wsf_addFavorite_callback() it will be
automatically called every time a favorite is added and passed the following
arguments: wsf_addFavorite_callback($tableOrTag, $recordNum)

- You can have the page automatically reload after adding or removing a favorite.
This is useful if you want to refresh a list of records such as after after
removing a favorite from a list of "My Favorites".  To do this add 'AndReload'
to the the third argument of wsf_onClickFor() like this:
  <a href="#" onclick="<?php wsf_onClickFor($tableOrTag, $recordNum, 'addAndReload'); ?>">Add Favorite</a>
  <a href="#" onclick="<?php wsf_onClickFor($tableOrTag, $recordNum, 'removeAndReload'); ?>">Remove Favorite</a>

- If you need to check if a current users has a particular favorite (such as
showing an additional icon or layout on favorite pages) you can call the
wsf_isFavorite() functin directly like this:
  <?php if (wsf_isFavorite('tableOrTag', $record['num'])): ?>


ADDITIONAL TECHNICAL NOTES
-------------------------------------------------------------------------------

- Website Favorites data is stored in a table called '_website_favorites'.
It's hidden from the menu by default but you make it visible and view it's data
in the CMS by unchecking this setting:
Section Editors > Website Favorites > Advanced > Hide Menu

- You can query the favorites database table directly. It's named
{PREFIX}_wsf_createSchema (where {PREFIX} is your table prefix, usually cms_)
And the columns are as follows:
createdByUserNum - the record number of the user who created the favorite
tableOrTag       - the table or tag that identifies the favorite
recordNum        - the record number that identifies the favorite

-------------------------------------------------------------------------------
end of file.
