=== Official Topspin Wordpress Plugin ===
Contributors: theuprising
Donate link: http://theuprisingcreative.com/
Tags: Topspin,store,merchandise,shop,music
Tested up to: 3.1
Stable tag: 3.0.1
Requires at least: 3.0.2

Quickly and easily integrate your Topspin Offers into customized, sortable and dynamically generated Store Pages.


== Description ==

This plugin allows novice and pro Topspin users alike to quickly and easily create integrated, customized, sortable and dynamically generated stores from their Topspin Offers in a few minutes.  

The plugin allows for the creation of any number of individual Store Pages and configurations of Offers based on Offer Types and Tags. Store Pages can be restricted to specific Offer Type(s) and/or Tag(s).  They can then be sorted by Offer Type(s), Tag(s), or Manually using a new drag-and-drop admin interface. 

Although these pages are called Store Pages, they aren't restricted to just the Buy Button Offer Type.  You can create dynamic pages featuring Buy Buttons, Email For Media Widgets, Streaming Player Widgets, Single Track Player Widgets, and any combination of them. 

(For example, a Store Page can be created that lists all Buy Buttons.  A second Store Page can be created that lists Streaming Players, or some manually sorted combination of Email-For-Media Widgets, Streaming Players, and Buy Buttons.  A third Store Page can be created that lists only Buy Buttons with the Apparel tag, effectively creating an Apparel sub-category for the main store.  Since Tags are custom and manually created, you can group your products in an way that works for your individual needs, such as Featured Items, On-Sale Items, etc.)

In addition to automatically creating Store Pages, Shortcodes are also generated for each Store Page that allow it's contents to be embedded on any other Page or Post.  

The possibilities are endless. 

This new version of the Official Topspin Wordpress Plugin is a complete rebuild from the ground up, simplified and optimized to make launching an integrated Topspin Wordpress store in minutes.

This plugin is in active development and more features will be added regularly.  Please see the Roadmap for more information.

= PLEASE NOTE =
To install this plugin you must deactivate and delete any previous versions of the v1 or v2 Topspin plugins.  This plugin will not upgrade them as it's completely re-written and must be installed individually / new. 

= Features = 
* Automatic Store Page creation based on Offer Types and Tags
* Display of Offers in some or all Offer Types and/or Tag groups
* Sorting by Offer Type(s), Tag(s), or Manually via the drag-and-drop admin interface
* Ability to select the # of columns for each Store Page from 1-6
* Ability to select the # of Offers to display on each page for Pagination
* Ability to set a Featured Item for each Store Page
* Customizable store name and slug
* Shortcodes for both Store and individual Featured Item content
* Immediate output of fully functional Store Pages will little or no CSS or Template customization (novice)
* Fully customizable Template and CSS files (pro)

= Topspin Artist Account Required.  Please visit: http://topspinmedia.com to sign up. =


== Installation ==

This plugin requires a Topspin Artist account to function.  If you don't have an account, you can get one here: http://topspinmedia.com

= Initial Installation =
1. Upload the `topspin` folder to the `/wp-content/plugins/` directory
2. Activate the plugin through the *Plugins* menu in WordPress. This will install your database tables and create a new top-level menu called *Topspin*.
3. Make sure your template is calling *wp_head()* and *wp_footer()* to allow loading of the necessary Topspin javascript libraries, template files and CSS. 
4. Make sure your Permalinks are set to anything other than Default.  Pagination will not work without non-default permalink structure.
5. Go to the *Topspin -> Settings* menu and add in your Topspin Artist ID, API Key, and API Username (you can get these from your Account settings at http://app.topspin.net)
6. Make sure the Offers you want to use have the *Offer API* checkbox selected.  If they don't, they won't be output by Topspin's API and won't show up as available Offers in the plugin.

= Upgrading from an earlier version = 
This plugin is a complete re-write.  In order to upgrade from a previous version you will need to first remove any previous versions of the Topspin plugin and then follow the instructions above to install this version.  Once installed, the easiest way to upgrade to future versions is to use the automatic upgrade feature built into WordPress.  You will be automatically notified of any updates to the plugin and given the option to install them with a single click. 

= CSS Customization = 
All markup output by this plugin is XHTML-compliant and heavily classed to allow for easily styling with CSS. The plugin comes with basic CSS style sheets named `topspin.css` and `topspin-ie7.css` located in the `/css/` directory in the `/topspin/` plugin directory.  

If you wish to edit the CSS styling, simply follow these directions.  Following this process will ensure that your custom CSS is not overwritten when upgrading the plugin in the future: 

1. create a new `topspin.css` file in your active theme's directory. 
2. copy any rules you wish to modify from the `topspin.css` file in the plugin's `/css/` directory into your new `topspin.css` file in your active theme's directory.
3. if you need to create specific rules for IE7, create a new `topspin-ie7.css` in your active theme's directory and add in any necessary IE7-specific rules. 

These CSS style sheets in your active theme's directory are considered "override" style sheets and only need to contain rules for elements, ids and classes that you wish to modify.  The remaining rules from the default CSS style sheets will automatically be used if no overriding rules are included.

= Template Customization =
If you are a pro user and are comfortable with creating and editing WordPress themes, the plugins template can be easily customized to suit your needs.  Simply follow the steps below to copy the template files from the plugin's `/templates/` directory to your active theme's directory and begin your customization. Following this process will ensure that your custom template modifications are not overwritten when upgrading the plugin in the future: 

1. create a directory named `/topspin-templates/` in your active theme's directory. 
2. copy the template files from the plugin's `/templates/` directory to your newly created `/topspin-templates/` directory. 
3. have fun modifying! below is a list of important PHP variables used in these templates: 
	in featured-item.php:
	$featureditem (array) - the array that contains the Featured Item's info
	in item-listing.php:
	$storedata (array) - the array that contains the general Store Page data
	$storeitem (array) - the array that contains all of the items on the Store Page

== Upgrade Notice ==

= Upgrading from an earlier version = 
This plugin is a complete re-write.  In order to upgrade from a previous version you will need to first remove any previous versions of the Topspin plugin and then follow the instructions above to install this version.  Once installed, the easiest way to upgrade to future versions is to use the automatic upgrade feature built into WordPress.  You will be automatically notified of any updates to the plugin and given the option to install them with a single click. 

= Topspin Artist Account Required.  Please visit: http://topspinmedia.com to sign up. =


== Usage ==

= Adding Store Pages =
Once installed, use the *Topspin -> Add Store* menu to add a new Store Page.  Select from the available options, sort as desired, save the page, and your new Store Page will be automatically generated.  This new page's URL will be your site's home URL + `/slug/` (slug being the slug you gave it when creating it.  If no slug is entered, it is automatically generated using the Store's name).

From this Add Store menu you can set the following: 
* Store Name (output name / title of the store) 
* Store Slug (the slug used in the URL for the store.  defaults to the Store Name if not inputted)
* Items Per Page (used to create a paginated Store Page, display as many Offers as you want per page) 
* Number Of Columns (specify the # of columns in your store output, from 1-5) 
* Default Product Sorting (specify if Offers should be sorted Alphabetically or Chronologically) 
* Sort By (specify if Offers should be sorted by Offer Type, Tags, or Manually)
* Offer Types (select which Offer Types to include on the Store Page and drag-and-drop sort if sorting by Offer Type.  Can be combined with Tags to further limit the Offers to display on the page.) 
* Tags (select to only display Offers with the selected Tags and drag-and-drop sort if sorting by Tags. If none are selected, all Offers are shown.  Can be combined with Offer Types to further limit the Offers to display on the page.) 
* Featured Item (set the Offer to display as a Featured Item on the Store Page.  Optional) 
* Manual Item Selection (used to manually sort the Offers on the store and manually show/hide Offers when Manual sorting is enabled)

= Viewing / Editing Existing Store Pages =
You can edit and view existing Store Pages by using the *Topspin -> View Stores* menu. This page also lists the shortcodes for each store and each store's featured content.  

= Shortcodes =
Shortcodes can be used on any page or post to output a Store's content or a Store's Featured Item.  All shortcodes use a Store Page's ID and can be found - along with the ID - in the *Topspin -> View Stores* menu. 

`[topspin_buy_buttons id=23]` will display the output of the Store Page with an ID of 23.
`[topspin_featured_item id=9]` will display just the Featured Item from the Store Page with an ID of 9.

(no other shortcode attributes are available at this time)

= Additional Suggestions = 
= It is highly suggested that anyone wishing to use this plugin a) has a solid understanding of how to create Offers in Topspin and b) has adequately tested their Store Pages and the checkout flow prior to going live with any Store Pages created by this plugin. =

= All Topspin Offers must have the Free via API checkbox marked.  Offers without this marked will not show up in the plugin. = 

= It is highly suggested that all Offer images are setup to be the same size for any particular Store Page.  This is to ensure that the Buy Buttons for each product line up correctly. = In an effort to create the most versatile default template, we haven't forced the Offers into tables or forced image resizing with Javascript but feel free to do so yourself.  In future updates we will be including phpthumb and the ability to normalize the size of the Offer images on the fly. 

We also suggest the use of the following additional plugins to maximize performance and functionality of this plugin, and your site as a whole: 

* WP Super Cache - A very fast caching engine for WordPress that produces static html files. Can decrease load times on your site by up to 10x. 
* Ultimate Google Analytics - Quickly and easily add Google Analytics Tracking to all of your site's content


== Roadmap ==

This plugin is in open development.  Over the weeks and months we hope to roll out regular updates with new features and optimizations, starting with: 

* Code clean-up / debugging
* Automatic cropping and scaling of thumbnails using phpthumb
* Addition of Facebook Sharing 
* Addition of ReTweeting w/ custom ReTweet Message
* Addition of multiple and manually sortable Featured Items
* Sidebar widget
* Further customizable page layouts for more dynamic and varied offer page creation without editing Theme or template files
* Sorting by Offer Type and Tags together
* Addition of Redeem Code Offer Type 
* AJAX-based pagination
* Option to show the Topspin cart at all times, even when empty
* Option to display the Topspin cart on the left or right
* Allow the inclusion of multiple artist accounts
* Addition of "Most Popular" sorting option
* New Shortcodes - Most Popular Products, Custom Content Blocks
* Addition of optional Featured Items fading/sliding marquee 
* Admin Localization
* Optimized output for non-Buy Button Offers
* Plugin Site for further documentation, discussion, feature requests, etc


== Screenshots ==

1. Plugin Admin -> Settings Page
2. Plugin Admin -> View Store Pages List
3. Plugin Admin -> Edit/Create Store Page
4. Plugin Admin -> View of the Edit/Create Store Page's Drag-And-Drop Manual Sort Interface
5. Front-End -> View of an out-of-the-box Store Page with a 3 column display and a Featured Item
6. Front-End -> View of a Store Page's "More Details" Colorbox overlay
7. Front-End -> View of the Topspin Checkout Flow overlay


== Changelog ==

= 3.0.1 = 
* Added default CSS styling for the Topspin Cart
* Added screenshots
* Cleaned-up documentation

= 3.0 =
* Completely rewritten from the ground-up (based on the v3.0beta plugin originally started by New Black)

= 2.0 =
* Second version (by StageBloc)

= 1.0 = 
* First version