Textpattern Resources at textpattern.org

As written in the textpattern forum I want to publish yab_shop . Yab_shop is a simple shopping cart plugin with paypal support for textpattern.

• Small feature list
• Download and installation
• Update
• Setup
• Tags for output
• Important notes on setup and maintaining
• Notes
• Something like a roadmap
• Changelog

Small feature list

• L10n for output
• encrypted paypal checkout
• google checkout
• automatic output the currency symbols and number formatting, depending on your config (supported paypal iso 4217 currency codes, see paypal supported currencies and additional EEK, RSD, BRL, PHP, RON and ZAR (ask for more))
• tax rate support
• tax rate exclusive or inclusive
• support for promotional discounts by promo-key
• selectable shipping costs and free shipping limit
• multiple product properties up to three variants (e.g. size, color or whatever you want)
• special prices for a property (Huh? What?: See live in demoshop!)
• affirmation mail to customer or not (ok, this could be a bug too)
• should work with all url types
• output is xhtml 1.0 strict
• it’s a plugin (can easily be installed in addition to an already existing txp installation)
• all the advantages of txp for the products (customizable, categories, all(?) plugins etc.)

Download and installation

Grab the current plugins here. Due the size of the whole plugin I have to split in three single plugins. You have to install all three plugins. If you have problems with upload and install, try to install the compressed version (is included in the download file).

Content of download files:

• Three plugin files
• Three compressed plugin files
• Three source code files
• Optional language files
• One little readme

Content of download files:

• Three plugin files
• Three source code files
• Optional language files
• One little readme

Gzipped Tarball – yab_shop_0.8.5.tar.gz

If you want see the code, please use the source, ‘cause it’s commented. I’am always open for suggestions, especially concerning the resolving of security issues.

Installation

1. Install and activate these plugins.
2. Go »Extensions->Yab_Shop Preferences« and install the needed database tables.
3. (optional): Install a prepared and prefilled language/localisation plugin (yab_shop_add_language_xx-xx_vx.x.txt)
4. Set your preferences and language/localisation

Update

Mostly you can seemlessly update the plugin. With version 0.8.0 config and language strings will saved in additional database tables.

Updating from a version before v0.8.0

1. Make a copy of your settings and language/localisation strings.
2. Remove or disable the yab_shop_config plugin
3. Install the ones (yab_shop_core, yab_shop_admin, yab_shop_3rd_party)
4. Go »Extensions->Yab_Shop Preferences« and install the needed database tables.
5. (optional): Install a prepared and prefilled language/localisation plugin (yab_shop_add_language_xx-xx)
6. Set your preferences and language/localisation

Updating from a version before v0.7.0

For an easy usage to newcomers and by the reasons of new features some tags has been removed or renamed.

• <txp:yab_shop_cart output="message" />
  Attribute value output="message" doesn’t exists any more. See below the for changes.
  And now you have to place it in checkout section to (f.i. with <txp:yab_shop_cart output="none" />)!
• <txp:yab_shop_add_message message="your message here" output="message" />
  Removed.
  Now use <txp:yab_shop_cart_message /> instead.
• <txp:yab_shop_custom_field name="price custom field" />
  Renamed to <txp:yab_shop_price /> without an usage of attributes.
• <txp:yab_shop_property_prices />
  Removed. Now load the jquery.js manually please!

Setup

Note: I’ve set up an additional page with a tiny howto and a FAQ about yab_shop.

You have to create one additional section. This section is used for the checkout (table and form).

Further you have to create at least one additional custom field in where you can store the price for the products. So create one and name it.
Place the used name for the price in the config plugin. Now you can create up to three addtional custom fields if you want multiple product properties.

Next you have to configure your shop. So go »Yab_Shop Preferences« which contains the configuration and go »Yab_Shop L10n« which contains the phrases where you can change on your own. See the yab_shop_admin plugin help for further information.

For encrypted paypal button and google checkout setup see plugin help for yab_shop_config!

Tags for output

<txp:yab_shop_add />

This tag outputs the add-to-cart form for the specific product. You have to place it into the individual product/article form (maybe "default"). Since yab_shop_v0.7.0 you can place it in article listings too.

<txp:yab_shop_cart />

This tag is used for adding, editing and deleting products and it’s outputs the little cart. It must be placed somewhere in the shop sections and in the your checkout section. Since yab_shop_v0.7.0 it can be used as a container tag. You can change the output by the following attribute:

• output="cart" – default, outputs the little cart
• output="none" – no output, so you can use it checkout section without any output

Usage as container tag

<txp:yab_shop_cart>
  <txp:yab_shop_cart_items />
  <txp:yab_shop_cart_quantity />
  <txp:yab_shop_cart_subtotal />
  <txp:yab_shop_cart_link />
  <txp:yab_shop_cart_message />
</txp:yab_shop_cart>

<txp:yab_shop_cart_items />

Outputs the items in the cart al a list. Can only be used inside the container tag <txp:yab_shop_cart>. No attributes.

<txp:yab_shop_cart_quantity />

Shows the quantity of the items in the cart. Can be used standalone or inside the container tag <txp:yab_shop_cart>. The following attributes are available:

• output=“single”
  Choose your itemcount. ‘single’ for different products. ‘all’ for all product items (default ‘single’).
• showalways=“1”
  Displaying it even if cart is empty (default ‘1’).
• break=“br”
  Break after output (default ‘br’).
• label=“Quantity”
  Label or name before itemcount output (default ‘Quantity’).
• wraptag=“span”
  Wraptag around the output (default blank).
• class=“someclass”
  Class for wraptag (default blank).

<txp:yab_shop_cart_subtotal />

Shows the cart subtotal. Can be used standalone or inside the container tag <txp:yab_shop_cart>. The following attributes are available:

• showalways=“1”
  Displaying it even if cart is empty (default ‘1’).
• break=“br”
  Break after output (default ‘br’).
• label=“Subtotal”
  Label or name before itemcount output (default ‘Subtotal’).
• wraptag=“span”
  Wraptag around the output (default blank).
• class=“someclass”
  Class for wraptag (default blank).

<txp:yab_shop_cart_link />

Shows a link to your checkout page. Can be used standalone or inside the container tag <txp:yab_shop_cart>. The following attributes are available:

• showalways=“1”
  Displaying it even if cart is empty (default ‘1’).
• break=“br”
  Break after output (default ‘br’).
• label=“proceed to checkout”
  Label or name before itemcount output (default ‘to_checkout’ from yab_shop_config).
• wraptag=“span”
  Wraptag around the output (default blank).
• class=“someclass”
  Class for wraptag or link, if no wraptag is set (default blank).

<txp:yab_shop_cart_message />

Shows a message depending on a done action. Can be used standalone or inside the container tag <txp:yab_shop_cart>. The following attributes are available:

• add=“Product has been added”
  Shows a message when a products has been added to cart (default ‘Product has been added’).
• edit=“Cart has been updated”
  Shows a message when a product count has been changed in checkout page (default ‘Cart has been updated’).
• del=“Product has been deleted”
  Shows a message when a product has been deleted from cart in checkout page (default ‘Product has been deleted’).
• break=“br”
  Break after output (default ‘br’).
• wraptag=“span”
  Wraptag around the output (default blank).
• class=“someclass”
  Class for wraptag (default blank).

<txp:yab_shop_price />

It outputs the price. It can be placed in all article/product forms (individual and listings).
The following attributes are available:

• wraptag=“span”
  Wraptag surrounded the Price (default ‘span’).
• class=“yab-shop-price”
  Class for the wraptag (default ‘yab-shop-price’).

<txp:yab_shop_checkout />

This tag outputs the checkout table, where you can edit product quantities. And it outputs the checkout form, where you can finally submit your order.
The following attributes are available:

• summary=“your summary here”
  Summary attribute of the HTML table element.

<txp:yab_shop_show_config />

Outputs a value of the current yab_shop_config, so it can be used for weird things (<txp:if ... />, <txp:variable ... /> etc. pp.).
The following attributes are available:

• name=“config value here”
  The value of the config.

Important notes on setup and maintaining

All numbers for prices in custom field or shipping costs in config can be written with comma or dot as decimal delimter. But beware: Do not use any thousand delimiter!
The output format in HTML or mail depends on the selected currency in the config.

How do I input product properties?

If you use one, two or all three custom fields for different product properties you have to fill the input fields with values separated by a semicolon, followed by a whitespace (you can leave the whitespace out, it will work both ways).
E.g. for custom field »Size«: 0.2mm; 3m; 5km; 100pc

And how do I input prices for a property?

Note: You can only assign one property with a price.
First go in »Yab_Shop Preferences« and change the Use property prices to Yes.
Then, if not yet done, load the jquery.js in your shop sections. Add the following line in your form or site template between the <head> and </head>:

<script type="text/javascript" src="<txp:site_url />textpattern/jquery.js"></script>

Input the Prices:

If you want use a property price you must give a price in your price field (custom field) even so. You can use it as an base price.
Now you can give prices to the properties in one property field (custom field). Use double minus as delimter between property and price. E.g for the property field color:

red; white--2,50; black--12,00; green--0,55

The properties with no price declaration will use the base price of the price field (custom field). The first property price should be the same as the base price. That’s all!

How do I use promo-codes, coupons etc.?

Go in »Yab_Shop Preferences« and set the Promocode key with a key, which a customer have to insert on the checkout page to get the promotional discount (E.g. 'XFHTE' or another value). With Given promo discount (%) you can set the promotional discount in percent (E.g. '5'). Absolute discounts like 5€ on all products are not supported due the lack of support by paypal and google checkout.

Notes

Since products are stored like normal articles, you are able to use (all?) relevant plugins. (Not tested!)
You can see a live demo on demoshop.yablo.de.
See forum thread for support.

Something like a roadmap

• encrypted paypal button it’s done
• a small admin interface to manage orders

Changelog

• 08-02-25 – v0.1.0:
  • internal release
• 08-02-27 – v0.1.1:
  • some variables and functions renamed, demoshop published
• 08-03-01 – v0.1.2 :
  • error messages for required fields and cache handling (see forum) – public release
• 08-03-04 – v0.1.3:
  • extended iso 4217 currencies (prepared for paypal support)
  • mime encoded headers for mail (thx ruud, see forum)
  • minor changes for ouput
• 08-03-07 – v0.1.4:
  • fixed CAD ouput
  • fixed tax rate calculating, when tax rate is float with a comma as decimal delimiter
  • removed  
  • new attribute output added for <txp:yab_shop_cart />, so cart output is optional
  • minor changes in plugin help
• 08-03-11 – v0.2.0:
  • non-encrypted paypal checkout
• 08-03-15 – v0.2.1:
  • support for EEK (Estonian kroon)
  • changed payment method output (if only one payment method available)
• 08-03-27 – v0.3.0:
  • fixed too paranoid sanitization
  • dynamic encrypted paypal button implemented
• 08-04-09 – v0.3.1:
  • new tag <txp:yab_shop_add_message /> added
• 08-04-16 – v0.3.2:
  • support for RSD (Serbian dinar)
• 08-06-04 – v0.3.3:
  • Bugfix: All three product properties now submitted to paypal (property 2 and property 3 are merged in paypal submit form)
• 08-06-18 – v0.4.1:
  • google checkout support
  • removed specific shop section (products can be organized in all sections now)
  • minor typo fix
• 08-06-19 – v0.4.2
  • bugfix misformed google checkout xml if no item description is given
• 08-08-12 – v0.4.3
  • paypal encryption now uses temp directory from txp advanced preferences
  • html class and id names are now css compliant (ascii)
• 08-08-15 – v0.4.4
  • support for BRL (Brazilian real)
• 08-09-27 – v0.5.0
  • new feature: special (additional) prices for a property. You have no clue what I mean? Look at the »Variant« of this product in the demshop!
  • license notice added
• 08-10-28 – v0.5.1
  • added support for ZAR (South African rand)
• 08-12-19 – v0.5.5
  • new feature: support for promotional discounts (see plugin help)
  • new feature: remember checkbox for submitted data
• 09-01-14 – v0.5.6
  • fixed bug when property prices are used and 'custom_field_price_name' other than 'price'
  • bugfix: using “:” in properties in chekout table
  • bugfix: using “: “ as delimter instead of misleading “ – “ in property select element
• 09-01-27 – v0.5.7
  • new feature: products in cart an checkout table are now linked back to their product site
  • new feature: support for article image thumbnails in checkout table
• 09-02-20 – v0.6.0
  • bugfix: property prices now works with non-ascii chars in custom field name
  • bugfix: fixed a bug related with property prices and custom fields (if not used)
  • bugfix: removed invalid html (p>p)
  • new feature: added a redirect for a thanks site (for site tracking/conversion)
  • new feature: optional state form in checkout
  • new feature: special shipping cost for single products
• 09-03-17 – v0.6.1
  • new feature: enhanced <txp:yab_shop_add_message /> (see plugin help)
  • new feature: support for PHP (Philippine Peso)
  • bugfix: changed html code in checkout form
  • bugfix: added anchor for error messages
• 09-03-18 – v0.6.2
  • bugfix: fixed some bugs, when <txp:yab_shop_add_message /> is used in checkout page
  • bugfix: minor typo in plugin help
• 09-05-03 – v0.7.0
  • bugfix: forms are now valid (X)HTML
  • bugfix: product properties are correctly escaped now
  • bugfix: order of postcode/city in mail does now match the html order
  • bugfix: minor typos (but maybe some others are added:/)
  • bugfix: name of property custom field can include whitespace and are html-escaped now (class names has been changed)
  • new feature: support for RON (Romanian lei)
  • new feature: terms of use checkbox is now optional (via config)
  • new feature: <txp:yab_shop_cart /> can be used as container tag now
  • new feature: new tag: <txp:yab_shop_cart_items />
  • new feature: new tag: <txp:yab_shop_cart_quantity />
  • new feature: new tag: <txp:yab_shop_cart_subtotal />
  • new feature: new tag: <txp:yab_shop_cart_link />
  • new feature: new tag: <txp:yab_shop_cart_message />
  • new feature: <txp:yab_shop_cart /> works in checkout section too
  • new feature: <txp:yab_shop_add /> has full article listing support now
• 09-06-05 – v0.7.1
  • bugfix: forms and select elements in article listings now have an unique id for XHTML-validity and form has an anchor
  • bugfix: replaced array_flip() with another method in yab_shop_field_names() to prevend some warnings and errors
  • bugfix: removed hardcoded withespace and doublepoint from label in <txp:yab_shop_cart_subtotal /> and <txp:yab_shop_cart_quantity /> for a flexible output
  • new feature: <txp:yab_shop_checkout /> now have the optional attribute ‘summary’ for html table summary (accessability)
  • new feature: added the attributes ‘wraptag’ and ‘class’ for <txp:yab_shop_price />
  • new feature: added new tag <txp:yab_shop_show_config /> for returning config values
• 09-07-29 – v0.8.0
  • new feature: configuration and language/localisation now stored in database
  • new feature: admin UI for configuration/preferences and language/localisation
  • new feature: support for selectable languages and localisations (depending on Textpattern language)
• 12-08-31 – v0.8.1
  • bugfix: fix a bug with PHP 5.3 and a deprecated warning (referencing new instances)
  • bugfix: fixed a bug in the install/update procedure
  • bugfix: refurnished admin UI for TXP 4.5.0
  • bugfix: partial using of plugin flags (prefs and delete)
• 2017-02-09 – v0.8.2
  • bugfix: TXP v4.6-ready
  • bugifx: PHP v7.1-ready
  • bugfix: incorrectly formatted item amount when using paypal and promo code
  • bugfix: serbian dinar (RSD) know corrcetly shown as »din«
• 2018-10-18 – v0.8.3
  • bugfix: annoying sizeof error
  • bugfix: disable sending last modified header
• 2018-12-12 – v0.8.4
  • bugfix: TXP v4.7.1-ready (removed obsolet is_windows() function)
• 2019-02-27 – v0.8.5
  • bugfix: 4.7-ready save button
  • bugfix: MySQL yab_shop_prefs name and val varchar size changed to 191 to prevent hitting the limit. It’s now safe for InnoDB and utf8mb4 (767 bytes)