/*********************************************************************************
 * Copyright (c) 2009, Darrell F Dieringer
 * www.electricdarrell.com
 * 
 * This file is part of dfdZazzleStore.
 * 
 * dfdZazzleStore is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * dfdZazzleStore is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with dfdZazzleStore.  If not, see <http://www.gnu.org/licenses/>.
 * 
 * dfdZazzleStore is based on code released in
 * Zazzle Store Builder 1.0.2 - a Zazzle.com product publishing tool
 */

README.txt

For a working production example (as a Wordpress plugin), see...
   http://www.artofdancemadison.com/shop/

See also "README_WORDPRESS.txt" and "README_STANDALONE.txt" for other
important information about installation, configuration, and usage.




WHERE "dfdZazzleStore" COMES FROM...
   "dfdZazzleStore is based on Zazzle Store Builder v1.0.2 (from zazzle.com).
   However, I have adapted some parts of it, completely overhauled other
   parts of it, as well as written my own code so that:
    (1) it will work as a WordPress plugin
    (2) multiple store grids work well (including pagination and sorting)
    (3) it does not use uninitialized variables - zazzle's original code
        caused a lot of warning messages to be logged to the apache error log
    (4) the querystring is no longer used for passing configuration settings.
        supports only the querystring arguments necessary for handling the
        following: pagination, sorting, and maintenance.
   
   Zazzle's unmodified code and documentation can be found here...
     http://www.zazzle.com/sell/tools/storebuilder
 



WHAT "dfdZazzleStore" DOES...
   Displays merchandise available on Zazzle.com (either your own products or
   products from the Zazzle Marketplace) on your website.
   



HOW "dfdZazzleStore" WORKS...
   "dfdZazzleStore" works using ONE of TWO possible methods of operation:
    (1) as a Wordpress Blog plugin
        - you must be running a Wordpress blog and have the ability to install
          plugins.
        - if using caching, you must have the ability to change write
          permissions on a directory - see "CACHING" (below)
         
    (2) as a completely stand-alone set of PHP scripts
   
   See separate README_WORDPRESS.txt and README_STANDALONE.txt for
   specific information.




DESIGN GOALS...
   To provide a relatively-simple system for creating one or multiple Zazzle
   Store Grids on a user's website or Wordpress blog.

   To make it possible for users with little technical/programming skills
   to create attractive Zazzle Store Grids.
   
   To conceal from the user the "mechanical" parts of how the scripts
   communicate with zazzle.com, allowing the user to spend more time
   on layout or store content.
   
   To provide the wide base of Wordpress users with an easy system for
   incorporating Zazzle Store Grids into existing site content and layout.

   To use css to control presentation of Zazzle Store Grids.




REQUIREMENTS...
   A web server to which you can upload files (the files in "dfdZazzleStore").
   
   A web server that runs PHP.  My development system uses PHP5, but I
   do not think there is anything in "dfdZazzleStore" that would prevent
   its use on PHP4 environments. (unconfirmed)
   
   To use "dfdZazzleStore" as a Wordpress plugin, you must have an installed
   and working Wordpress blog and the ability to create or edit pages/posts
   on your site.
   
   You must edit several important configuration variables in
   "<our_install_dir>/include/_defaultconfig.php" or remember to define
   appropriate overrides in every ZSTORE_GRID section (as described under
   "INLINE METHOD" in "<our_install_dir>/README_WORDPRESS.txt")
   



LIMITATIONS...
   See "STYLE SHEET" (below).
   
   If using "dfdZazzleStore" as a Wordpress plugin, please consider
   all of the following: 
    - Installation/configuration/alteration advice regarding your Wordpress
      blog or the theme(s) you use is beyond the scope of this plugin. You
      must have your own working knowledge regarding maintenance of your blog.
     
    - Depending on how you intend to use this plugin, you may need to edit
      Wordpress template files for your theme. "README_WORDPRESS.txt" and
      "README_STANDALONE.txt" may offer SUGGESTIONS or tell you to read code
      comments in specific files for SUGGESTIONS regarding which template
      files you may need to edit.
     
    - I do not know how every single Wordpress theme is designed, so I
      cannot promise that the suggestions will be correct. I do, however,
      want to point you in the right direction if I can.
      
    - If you disable this plugin through your Wordpress admin control panel,
      ZSTORE_GRID sections appearing in any page/post WILL DISPLAY AS
      TEXT.
      
      To avoid this behavior, I could have designed the ZSTORE_GRID section
      to appear inside an html comment section. However that confused Wordpress.
      Specifically, if markup tags (<b> <i>, etc) appeared in GRID_DESCRIPTION
      while the entire ZSTORE_GRID section was inside an html comment, Wordpress
      deleted some of the tags. I believe this is a Wordpress bug related to how
      Wordpress attempts to insert a matching closing tag if you unintentionally
      leave a tag open. I didn't track it down, and instead designed around it.
      
      If you disable this plugin, you will need to either
       (1) delete existing ZSTORE_GRID sections in any page/post
       (2) wrap existing ZSTORE_GRID sections inside html comments. REMEMBER,
           a single "-->" closes every open "<!--" before it.




STYLE SHEET...
   The default style sheet "<our_install_dir>/css/z_zazzlestore.css" MAY NOT
   BE SUFFICIENT OR MAY BE INCREDIBLY UGLY WHEN USED ON YOUR SITE.  Other
   existing style sheets on your site may define styles for any of the
   elements used in Zazzle Store Grids (images, borders, alignment, fonts,
   font sizes, etc).
   
   I cannot possibly know how "z_zazzlestore.css" will interact with your
   existing style sheets. IT IS UP TO YOU TO MAKE YOUR Zazzle Store Grids
   LOOK THE WAY YOU WANT THEM TO LOOK.
   
   In Wordpress, stylesheets are included by calling "add_action('wp_head', ...)".
   Wordpress inserts style sheets in the order that it finds each such
   call to "add_action()", which can be used anywhere in any of the Wordpress
   code base, third-party plugins, and themes.
   
   This means it is intended default behavior for Wordpress to add style
   sheets defined by plugins (like this one) BEFORE style sheets defined by
   your Wordpress theme. (Wordpress loads plugins before it loads your theme,
   I believe.)
   
   This means style sheets added after this one (even by other plugins)
   may define styles that collide with, extend, or override the styles
   defined in "z_zazzlestore.css".
   
   The default width (800px) for Zazzle Store Grids may not fit inside your
   site design, ESPECIALLY IF YOU ARE USING THE WORDPRESS INLINE METHOD
   (see README_WORDPRESS.txt).
   
   Even if your browser (for instance, Firefox) displays the resulting Zazzle
   Store Grid acceptably, it may not render properly in other browsers (for
   instance, Internet Expolrer) if the Zazzle Store Grid width exceeds the
   width defined by your Wordpress template for the page/post display area.
   
   You will ALMOST CERTAINLY need to edit "z_zazzlestore.css" to define
   additional styles or to override problematic existing style definitions.




CACHING...
   "dfdZazzleStore" has the ability to cache images/rss feed results on your
   web server.
   
   If you are not using caching (see "<our_install_dir>/include/_defaultconfig.php"),
   YOU DO NOT NEED TO WORRY ABOUT ANY OF THE FOLLOWING INFORMATION.
   
   The default cache dir is "/images/zazzlecache", relative to your web server's
   document root. This can be changed in "<our_install_dir>/include/_defaultconfig.php"

   The cache directory must be writable to the user account corresponding to the
   "apache" web server (or whatever web server program your production system
   uses). This may involve changing group ownership as well as changing user and/or
   group permissions on the cache directory to include "w" (write) permissions,
   though this will depend a great deal on how your web hosting provider handles
   file ownership and whether apache runs as <your-login-account> or as "apache"
   (or as some different user entirely).
   
     WARNING: Your web hosting provider MAY have security measures in place
       that will prevent access to locations (directories or scripts) that are
       too permissive with write access permission. If you receive "404" errors
       in your browser and you are certain you have uploaded the scripts, then
       the error you are experiencing MAY be a result of too-permissive write
       permissions. You may TRY the following... 

   Set only "user"-writable permissions ( chmod 0755 ) on the cache directory.
   Set "user" and "group"-writable permissions ( chmod 0775 ) on the cache directory.
   Set "user" and "other"-writable permissions ( chmod 0757 ) on the cache directory.
   At last resort, set world-writable ( chmod 0777 ) permissions on the cache directory.
   NOTE: these all apply "read" and "enter/execute" permissions for the "user",
         "group", and "other".

   
   THE CACHE IS AUTOMATICALLY UPDATED AND CLEANED PERIODICALLY. To clean the
   cache MANUALLY, visit the page on which your Zazzle Store appears and 
   append "?zstore_cleanCache=1" (w/o quotes) to the URL (or "&zstore_cleanCache=1"
   if there are already querystring parameters).
      http://your.server.com/path/to/your/installation.php?zstore_cleanCache=1

      ...or...
      http://your.server.com/path/to/your/installation.php?some_arg=10&zstore_cleanCache=1

      ...or (being mindful of already-existing "#" in querystring)...
      http://your.server.com/path/to/your/installation.php?some_arg=10&zstore_cleanCache=1#1




GRID_CONIGURATION_VARS...
   See "<our_install_dir>/include/_defaultconfig.php"
   See also "LAYOUT", below.

   FOR WORDPRESS PLUGIN INSTALLATIONS:
     Any and all of the variables you find in "_defaultconfig.php" may be
     overridden in a ZSTORE_GRID section (as described under "INLINE METHOD"
     in "<our_install_dir>/README_WORDPRESS.txt").
 
   FOR STANDALONE INSTALLATIONS
     Any and all of the variables you find in "_defaultconfig.php" may be
     overridden in a manner similar to that seen in the example
     "<our_install_dir>/sample_index.php"
   
   GENERAL NOTES:
         For boolean (true/false) values, it is wise to use either the word
         'true' or the word 'false' (w/o quotes).  However, the underlying code
         interprets any values like "1" "True" and "Yes" (not case sensitive)
         as meaning true.
         ALL OTHER VALUES FOR BOOLEAN VARIABLES ARE TREATED AS FALSE. This
         includes things that you think of as false, like "0" "False" and "no"
         AS WELL AS ABSOLUTELY ANYTHING ELSE, like "handstand" "42" "tardis"
         "whatever".
         
         STANDALONE installations:
         WORDPRESS PSEUDO STANDALONE METHOD installations:
           It is necessary to surround strings with quotation marks.
           You are writing code afterall.
         
         WORDPRESS INLINE METHOD installations:
         WORDPRESS TEMPLATE FUNCTION METHOD installations:
           It is NOT NECESSARY to surround the values for your GRID_CONFIGURATION_VARIABLES
           with quotes. You can, but it is not necessary.
         
             szContributorHandle = myhandle      //these are equivalent
             szContributorHandle = "myhandle"    //these are equivalent
         
           If you need to specify an empty value, it MUST be done like this...
         
             szContributorHandle = ""


   WARNING: When using the Wordpress plugin INLINE METHOD or TEMPLATE FILE METHOD
            (each requires defining ZSTORE_GRID sections), each variable
            name/value pair MUST appear on a separate line. Only the first
            space-separated value after the "=" sign is used as the value of
            that variable. Everything else is ignored.
            
            ZSTORE_GRID sections do not presently support any GRID_CONFIGURATION_VAR
            value that requires a space-separated list, even if that list appears
            in quotes. (This may limit your use of szKeywords.)
            
            If this is important to you, you will need to implement the
            "PSEUDO STAND ALONE METHOD" for Wordpress (see README_WORDPRESS.txt)
            since you can code the variable values you desire.
            
            The reason for the limitiation is that variable values have to be parsed
            from the ZSTORE_GRID by a Wordpress filter function (which is part
            of the "dfdZazzleStore" plugin). I did not write a sophisticated parser.



LAYOUT...
   There is no single setting that determines the number of images that appear
   in each row when a Zazzle Store Grid is displayed. Instead, the number per
   row will depend on FIVE separate things. Four are directly under your control,
   and the fifth is at least influenced by you... 

    (1) whether "fEnableGridWidthStyles" is true or false.
        - If true, values from the appropriate GRID_CONFIGURATION_VARS are important (see "GRID_CONFIGURATION_VARS" above)
        - If false, values from the style sheet are important (see "STYLE SHEET" above)

    (2) the value of "nGridWidth" CONFIGURATION_VAR
         -or- the "width:" parameter of ".centerGrids" class

    (3) the value of "nGridCellSpacing" CONFIGURATION_VAR
         -or- the "margin-*:" parameters of ".gridCell" class

    (4) the value of "nGridLeftPadding" CONFIGUARTION_VAR
         -or- the "padding-left:" parameter of ".allGrids" class

    (5) the actual size of the image returned by Zazzle, which MAY BE
        DIFFERENT than the _requested_ size you specified in "nGridCellSize"
        CONFIGURATION_VAR.  The actual size of the image returned by Zazzle
        is ALWAYS USED, regardless of the size you requested and regardless
        of the value of "fEnableGridWidthStyles"




CONTACT THE AUTHOR
   http://www.electricdarrell.com/