Products API

Last edited: 10/13/2011

Display Mode: Auto

Depending on the URL, auto will either produce a list of families, a list of products, a list of skus or a single product/sku. See the product howto page for more information on this.

Display Mode: List

Depending on the parameters of the monklet or getContent, 'list' will produce either a list of families or a list of products. See the product howto page for more information on this.

Display Mode: Cloud

This will display a tag cloud consisting of all the tags used for products. 

Parameters

Pparameters apply to the list pages.  

family

For display:list or auto, will display a list of products for that family. "family:all" will display a list of all prodcuts in all families.

Example:

"family:family-title-slug",  

product 

For display:auto (coming to display:list). Will display product detail and a list of related skus (if applicable). Use family:all and product:all to show a list of all skus.

Example: 

"product:product-title-slug",

featured_families, featured_products, featured_skus

Will limit the lists to only display featured families, products and or skus.'Yes' will limit to only featured items. 'No' will limit list to items that are not featured.

Example:

"featured_families:yes",

"featured_products:no",

"feature_skus:yes",

howmany_family

Limits the number of families that will be returned.

Example:

"howmany_family:2",howmany_product

Limits the number of products that will be returned.

Example:

"howmany_product:2",

offset_family

Will skip the first X families.

Example:

"offset_family:1",offset_product

Will skip the first X product.

Example:

"offset_product:1",

find_category

Only show items assigned to that category. Limited to one category.

Example:

"find_category:category-slug",

find_tag

Finds all items with that tag or tags. Spaces in tags should be replaced with a dash (-).

Example:

"find_tag:tag-slug,tag-slug2",

find_group

Only show items assigned to that group. Can find multiple groups with a comma separated list. Uses group slugs.

Example:

"find_group:group-slug1,group-slug2,group-slug3",

hide_group

Do not display items assigned to that group. Can find multiple groups with a comma separated list. Uses group slugs.

Example:

"hide_group:group-slug1,group-slug2,group-slug3",

family_category_products

Will return a list of products in any family assigned to a given category. Uses show_productlist tags.

Example:"family_category_products:category-slug",

find_skutype

Will limit the results to products or skus of a certain type.

Example:

"find_skutype:sku-type",

 

find_similar

Will find products that share similar tags.  Use 'tagmin' to specify the number of the minimum number of tags the products will need to share. If 'howmany' is also used, it will only the return the most relevent X items.

If a 'related items' field has been configured for the skus, those will also be returned.

Example:

"family:all",
"find_similar:product-title-slug",
"tagmin:2",
"howmany:4",

order

Sets sort order of items in list. This is ordered by product code alphabetically by default.

itemdescription
recent by date, starting with most recently added product
title
by entry title, alphabetically
random For product lists only. Order is change periodically at least once per day.
groupby

Sets a criteria to group the family list by.

Available grouping criteria:

  • category

Example:

"groupby:category",
"group_show:__title__",

groupby_product

Sets the criteria to group the product list by. 

Available grouping criteria:

  • tag

Example: 

"groupby:tag",
"group_show_productlist:<h4>__title__</h4>", 

tagmin

Only for display:cloud. Will only display tags that have been used X amount of times.

Example:

"tagmin:3",

minprice

Only show families that have a price greater than X. Does not apply to products/skus at this time, only families.

Example:

"minprice:25", 

search

Will search for a given term in the title and description of prodcuts.

Example:

"family:family-title-slug",
"search:XXXXX",

sales

Only show products thate are on sale or only show non-sale items. Use Y for sale items, N for non-sale items.

Example:

"sales:Y", 

URL Parameters

All URL based parameters require display:auto 

http://www.site.com/family-slug/product-slug/

This will display a detail page for an entry. "show_detail","before_show_skulist","show_product","show_skulist","after_show_skulist" tags will be used. 

http://www.site.com/family-slug/

This will display a list of products for the family. "before_show_productlist","show_productlist", and "after_show_productlist" tags will be used.

http://www.site.com/anything-other-than-a-family-slug/

On any other page a list of families will be shown. "show_familylist" tags will be used.

API

Families List 

If no family is specified in the URL or through "family:XXXX", show_familylist tags are used.

show_familylist
TagDescription
__familytitle__
Title of the Family
__familydescription__ Description of the Family
__familytitlelink__ Produces /family-slug/
__familyimage__ The image for the family in an img tag
__familyimageURL__ Just the URL of the family's image
__preview__
A shortened version of the text. HTML is stripped. Defaults to be no more than 250 characters. Can be specified with __preview limit='120'__
__familyprice__ The price for the family
__familycategory__
The category for the family 
__familycategoryslug__ The slug of the category for the family
__familycategorydescription__ The description of the category for the family
__familycategoryimage__ The image of the category for the family
__familynumber__
The number of products in the family 
__familyallcategories__
A comma separated list of all categories for all families, links to /category/category-slug/
__buy label='Add To Cart'__
A link to add family to cart. Label can also be an image.
Any Custom Fields setup for Families will output their API tags
group_show
TagDescription
__title__
title of the group
__slug__
slug of the group
__description__
__groupimage__

 

Family Detail / Product List

If the URL or 'family' specifies a family, the following tags are available.

before_show_productlist, after_show_productlist

The same tags are availabel for before_show_productlist after_show_productlist

TagDescription
__familytitle__
Title of the Family
__familydescription__ Description of the Family
__familytitlelink__ Produces /family-slug/
__familyimage__ The image for the family in an img tag
__familyimageURL__ Just the URL of the family's image
__preview__
A shortened version of the text. HTML is stripped. Defaults to be no more than 250 characters. Can be specified with __preview limit='120'__
__familyprice__ The price for the family
__familycategory__
The category for the family 
__familycategoryslug__ The slug of the category for the family
__familynumber__
The number of products in the family 
__familyallcategories__
A comma separated list of all categories for all families, links to /category/category-slug/
__familycommentList__
A formatted list of comments with a field to add new comments
__familyallcategorysiblings__  Displays an unordered list <ul> of other families in the same category as the current one
__buy__  A link to add family to cart 
__searchterm__
If product list is filtered by a search term, displays the query
__pagination__ Divides the records into smaller groups and provides links to navigate through them
Any Custom Fields setup for Families will output their API tags
group_show_productlist
TagDescription
__title__ The title of the current group.
__slug__ The slug of the title of the current group.

show_productlist

TagDescription
__producttitle__ The title of the product
__productdescription__ The description of the product
__productnumber__ Incrementing number of the products
__producttitlelink__ Produces /family-slug/product-slug/
__productslug__ Just the product-slug
__productimage__ First image in an img tag
__productimage2__ Second image in an img tag
__productimage3__ Third image in an img tag
__productimageURL__ URL of the first image
__productimageURL2__ URL of the second image
__productimageURL3__ URL of the third image
__productimageURLtmb__ Thumbnail URL of the first image
__productimageURLtmb2__ Thumbnail URL of the second image
__productimageURLtmb3__ Thumbnail URL of the third image
__buy label='Add To Cart'__ A link which adds the product to the cart. Label can also be an image.
__preview__
A shortened version of the text. HTML is stripped. Defaults to be no more than 250 characters. Can be specified with __preview limit='120'__
__productprice__ The price of the product, will display the sale price if available. 
__productOriginalprice__ If a sale price is entered, displays the original price
 __productmatches__ Comma separated list of tags for the post
Any Custom Fields setup for Products will output their API tags
no_show

If no products are returned, no_show will be used. Uses the same tags as before_show_productlist.

Example:

"no_show:Sorry, no results were found for the search __searchterm__", 

Product Detail / Sku List / Sku Detail

If the URL specifies a family and a product the following tags are available.  Use before_show_skulist if skus are separate and show_product otherwise.

before_show_skulist / show_product / after_show_skulist
TagDescription
__familytitle__
Title of the Family
__familyimage__ The image for the family in an img tag
__familyimageURL__ Just the URL of the family's image
__familyprice__ The price for the family
__familycategory__
The category for the family 
__familycategoryslug__ The slug of the category for the family
__familyallcategories__
A comma separated list of all categories for all families, links to /category/category-slug/
__familycommentList__
A formatted list of comments with a field to add new comments
__producttitle__ The title of the product
__productdescription__ The description of the product
__producttitlelink__ Produces /family-slug/product-slug/
__productcode__ The code of the product 
__productimage__ First image in an img tag
__productimage2__ Second image in an img tag
__productimage3__ Third image in an img tag
__productimageURL__ URL of the first image
__productimageURL2__ URL of the second image
__productimageURL3__ URL of the third image
__productimageURLtmb__ Thumbnail URL of the first image
__productimageURLtmb2__ Thumbnail URL of the second image
__productimageURLtmb3__ Thumbnail URL of the third image
__producttags__
A comma separated list of tags 
__producttagslinks__
List list of linked tags. Links look like /products-about-tag-slug 
__buy label='Add To Cart'__ A link which adds the product to the cart. Label can also be an image.
__productprice__ The price of the product, will display the sale price if available. 
__productOriginalprice__ If a sale price is entered, displays the original price
__productpricedifference__ If a sale price is entered, displays the difference between the sale price and the original price
__productcommentList__ A formatted list of comments with a field to add new comments
Any Custom Fields setup for Products will output their API tags
show_skulist / show_sku

If skus are included with the products, the following tags will be available for show_product.

TagDescription
__producttitle__ The title of the product
__productdescription__ The description of the product
__producttitlelink__ Produces /family-slug/product-slug/
__productimage__ First image in an img tag
__productimage2__ Second image in an img tag
__productimage3__ Third image in an img tag
__productimageURL__ URL of the first image
__productimageURL2__ URL of the second image
__productimageURL3__ URL of the third image
__productimageURLtmb__ Thumbnail URL of the first image
__productimageURLtmb2__ Thumbnail URL of the second image
__productimageURLtmb3__ Thumbnail URL of the third image
__productprice__ The price of the product, will display the sale price if available. 
__skutitle__ The title of the sku
__skutitlelink__ Produces /family-slug/product-slug/sku-slug/
 __skucode__ The code for the sku
 __skuslug__ The slug of the sku
__skuimage__ Image in an img tag
__skuimageURL__ URL of the image
__buysku label='Add To Cart'__ A link which adds the sku to the cart. Label can also be an image
__skuprice__ The price of the sku