Skip to content
This repository has been archived by the owner on Apr 22, 2018. It is now read-only.

Latest commit

 

History

History
222 lines (157 loc) · 8.89 KB

README.rdoc

File metadata and controls

222 lines (157 loc) · 8.89 KB
Raw

Simple Product Manager ↑

A RadiantCMS extension providing a mechanism to handle products and categories that can then be used across the rest of the RadiantCMS site.

Also provides Category and Product pages for each of the items listed, and these pages can be prepared using existing Layouts and Snippets.

It was once very simple, now it does a little bit more…

Purpose ↑

Although simple product/category systems can be created using child pages and built in Radant tags, this can become a hassle - especially when it comes to maintaining linked Ordering and Product List pages.

This extension was created to make this process simpler by storing it all in one location (the DB) so as that it is easy to reuse the information across the site.

It handles nested categories, although these are a tad difficult to work with in the layouts.

Installation ↑

TODO

Dependencies ↑

The Share Layouts Extension must be installed. See : github.com/radiant/radiant-share-layouts-extension

For full configuration, you will also require the Settings extension. See : github.com/Squeegy/radiant-settings

The product images code uses attachment_fu, so you will need to satify the dependencies for that library too. See : github.com/technoweenie/attachment_fu

If you receive errors or warnings about JSON, ensure that the json gem is installed.

Usage ↑

The extension adds a “Products” page which provides a simple mechanism to add categories and products.

Products and Categories can be arbitrarily ordered within their groupings.

Tags ↑

The categories and products are exposed to the site using the following tags:

Category Tags ↑

<r:category:find [where=""] [tag=""]> ... </r:category:find>
<r:categories:each [where=""] [tag=""] [order="sequence ASC"] [parent="id or title"]> ... </r:categories:each>
<r:category:if [id=""] [title=""] [where=""]> ... </r:category:if>
<r:category:unless [id=""] [title=""] [where=""]> ... </r:category:unless>
<r:category:if_self> ... </r:category:if_self>
<r:category:unless_self> ... </r:category:unless_self>
<r:category:if_ancestor_or_self> ... </r:category:if_ancestor_or_self>
<r:category:unless_ancestor_or_self> ... </r:category:unless_ancestor_or_self>
<r:category:id />
<r:category:title />
<r:category:description />
<r:category:field name="" />
<r:category:link [selected="current"]>...</r:category:link>

Product Tags ↑

Product tags can either be used stand-alone to search all products in the database, or within a <r:category:find> or <r:categories:each> tag to search only within that Category’s products.

In this case, only Products directly owned by the current Category are shown - they do not recurse down into sub-Categories.

<r:product:find [where=""]> ... </r:product:find>
<r:products:each [where=""] [order="sequence ASC"]> ... </r:products:each>
<r:product:if [id=""] [title=""] [where=""]> ... </r:product:if>
<r:product:unless [id=""] [title=""] [where=""]> ... </r:product:unless>
<r:product:if_self> ... </r:product:if_self>
<r:product:unless_self> ... </r:product:unless_self>
<r:product:id />
<r:product:title />
<r:product:description />
<r:product:price [precision="2"] [unit="$"] [separator="."] [delimiter=","] />
<r:product:field name="" />
<r:product:link [selected="current"]>...</r:product:link>
<r:product:images:each [tag=""] [limit=""] [order="sequence ASC"]>...</r:product:images:each>
  <r:product:image:description />
  <r:product:image:filename />
  <r:product:image:url [type="product"] />
  <r:product:image:tag [type="product"] [alt="description"] [width=""] [height=""] />

Subcategory Tags ↑

Subcategory tags are only valid within the <r:category:find> or <r:categories:each>. They will restrict their search to include only Categories which are direct descendants of the currently selected Category.

<r:subcategory:find [where=""] [tag=""]> ... </r:subcategory:find>
<r:subcategories:each [where=""] [tag=""] [order="sequence ASC"]> ... </r:subcategories:each>
<r:subcategory:id />
<r:subcategory:title />
<r:subcategory:description />
<r:subcategory:field name="" />
<r:subcategory:link>...</r:subcategory:link>

Layouts and Snippets ↑

If you want to use the category and product page functionality, you will need to have two Layouts, and two Snippets.

Category pages will be displayed in the “Category” layout by default, but this can be changed by the “simple_product_manager.category_layout” setting.

Layouts can also be defined on a per-Category basis, so as that separate Categories (and their decendants) can use their own Custom layout. These are defined in the Category form.

The “category” snippet will be rendered within the relevant layout - regardless of whether it is the default setting, or a custom layout. The snippet will be rendered in the context of the Category, loaded by <r:category:find>.

Product pages will be displayed in the “Product” layout by default, but this can be changed by the “simple_product_manager.product_layout” setting, or by setting the “Custom Layout for Product” setting on the Category page.

Similarly to Categories, the “product” snippet will be rendered within this layout. The snippet will be rendered in the context of the Product, loaded by <r:product:find>.

No Category List is implemented, as it’s fairly trivial to code your own using <r:category:each> and friends.

Product and Category Pages (and URLs) ↑

By default, the extension adds routes for each Category and Product like :

/products/10-Category-Name
/products/10-Category-Name/30-Product-Name

And these are provided by <r:category:link> and <r:product:link> respectively.

When on a Category URL, the link element produced by the relevant <r:category:link> will include the class specified by “selected”, or the default of “current” if it is not provided.

When on a Product URL, relevant link elements produced by both <r:category:link> and <r:product:link> will include the relevant class specified by “selected”, or “current” if not set.

It’s worth noting that the /products URL is NOT handled - this allows you to place a generic product listing by creating a standard Radiant Page with a slug of /products

Custom Fields ↑

Both Categories and Products can be extended to include custom fields.

These custom fields must be defined using the Settings tab, and are called “Product fields” and “Category fields”.

These values must be a list of field names (letters only), separated by commas. (eg. “leadtime,weight”), and once they are saved they will be visible on the relevant form.

The data can then be accessed within the pages using <r:product:field name=“”> and <r:category:field name=“”> tags.

For example:

<r:categories:each>
  <p><r:category:title />: Average lead time required is <r:category:field name="leadtime" /></p>
</r:categories:each>

Photo Thumbnails ↑

The size of the resized images can be changed by editing the simple_product_manager_extension,rb file, and changing the PRODUCT_ATTACHMENT_SIZES constant.

You will need to retain the :product setting, as that is the default size used when the “type” isn’t specified for <r:product:image:url /> or <r:product:image:tag />

The size formats are those expected by attachment_fu.

Examples ↑

Product Listing ↑

A simple example for listing Categories and their products.

NOTE: This example assumes no subcategories

<h2>Product Listing</h2>
<r:categories:each order="title ASC">
  <div class="category">
    <h3><r:category:title /></h3>
    <r:products:each order="price ASC">
      <div class="product">
        <h4><r:product:link /> (<r:product:price precision="0" />)</h4>
        <p><r:product:image /><r:product:description /></p>
      </div>
    </r:products:each>
  </div>
</r:categories:each>

Order Form (for mailer extension) ↑

<h2>Order Form</h2>
<table>
  <tr><th>Product</th><th>Cost</th><th>Quantity</th></tr>
<r:categories:each order="title ASC">
  <tr><th colspan="3"><r:category:title /></th></tr>
 <r:products:each order="price ASC">
  <tr>
    <td>
      <r:product:title />
      <input type="hidden" name="mailer[products][<r:product:id />][name]" value="<r:product:title />" />
    </td>
    <td><r:product:price /></td>
    <td><input type="text" name="mailer[products][<r:product:id />][qty]" value="0" /></td>
  </tr>
 </r:products:each>
</r:categories:each>
</table>

TODO ↑

  • Deperately need some integration tests

  • <r:product:url> and <r:category:url> tags

  • Tag definitions need some major cleanup work

History ↑

See CHANGES.rdoc

Thanks ↑

Thanks to John Reilly, Justin Grammens who did most of the work to get the original extension working under Radiant-0.7.1 and 0.8.0.

Huge thanks to Ingvi Gudmundsson (www.ingvithor.net/) for sponsoring and helping test v0.4 to v0.7.

Thanks to Yves-Eric Martin for contributing the if_self unless_self tags.

Licensing ↑

Copyright © 2008-2009 Aurora Software (www.aurorasoft.com.au), released under the MIT license