List Items

Introduction | Settings | Creating Items | Updating Items | Deleting Items
Expiry | Functions | Containers

Introduction

The list items module allows users to add their own things to a data-driven website. Examples would be Property, Cars, Artwork, Scripts...

This module allows you to setup any data fields for items (using the Types module - which is required), and allows users to add, update and delete items. Permissions can be set using O3's powerful permissions system - to determine who can add, update and delete which items.

The List Items module also allows items to be created automatically when a product is purchased (i.e. for Premium Listings).

Items can be fully administered in O3's Items management page.

Related Modules

The Types module is required for the List Items module.

To allow image uploads for items - you need the Uploads module

To allow users to add products which are actually sold through your site for a commission, you need the 'Affiliate Shop' module.

Items can have associated schedules - allowing users to book intervals or events associated with the item (like bookings for a holiday property or guitar lessons). To use this feature you need the Scheduler module.

Settings

There are quite a few options in the settings which affect the way list items are handled. You'll find them under the 'List Items' settings:

• Displaying Items: This section defines the text / headings and containers used to show items.
  
  
• Inserting/Updating Items: This section defines the default status for items, and the default forms used to create and update them.
• Item Expiry: Defines how long items are valid for, and the text of the warning emails sent prior to, and on expiry. Renewal product is a product which allows the customer to renew their listing before or after it runs out.
• Item Permissions: These define who can Add, Update, Delete and Approve items.
• Cart Text & Images: O3's cart can double up as a favorites list - allowing users to save and compare their favorite items - using a compare list

Creating Items

Items can be fully administered in O3's Items management page, and can be created from the front-end by displaying a form (defined in O3's Forms Manager) using the show_form('FormName') function. O3 comes with example forms you can use and modify.

In addition, you can create items automatically when a product is purchased (premium listings). It's an option you set for the product, in the Products Manager. The item details can be automatically included in the order confirmation to the customer - so they can go straight to their listing and edit it immediately.

Updating Items

Items are updated using an update form. To display an update form for an item - you put the UPDATE-ITEM macro into the Item List or Item Detail container where you want the form to go. The form used is taken from the item's Type first, if that's not set - it uses the form defined in the settings.

Deleting Items

Items are deleted using a delete form. To display an update form for an item - you use the SHOW-FORM# macro into the Item List or Item Detail container where you want the form to go. The form used is taken from the item's Type first, if that's not set - it uses the form defined in the settings.

To include an image upload form - you'd use something like this macro in the container: SHOW-FORMUploadImages#

Item Expiry & Status

Items, like other O3 objects, can have one of O3's standard statuses:

Expiring & Notifying Automatically

You can use O3's 'Expire Items' script (o3/list/expire-items.php) to automatically expire items and send out notifications for you. You can run the script manually (it's accessed from the links at the bottom of the O3 main page), or you can schedule it to run under cron with the required parameters. i.e.:

• To give a warning of 1 month:
  usr/bin/php /home/public_html/o3/list/expire-items.php?warning_period=1 MONTH 2>&1 >/dev/null
• To expire expired items:
  usr/bin/php /home/public_html/o3/list/expire-items.php?go=1 MONTH 2>&1 >/dev/null

Item Functions

There are 2 item functions:

1. show_item(item_name, container)
2. show_items(namelike, categorylike, ownerlike, type, statuslike, order, typedata, container, incols)
   
   • All parameters are optional
   • namelike - A case-insensitive regular expression matching the item name (i.e. 'exactname' or 'part' or 'item1|item2|item3' etc)
   • categorylike - A case-insensitive regular expression matching the item category.
   • ownerlike - A case-insensitive regular expression matching the item creator.
   • type - A single type, or a list of pipe-delimited types (i.e. 'type1|type2...').
   • statuslike - A case-insensitive regular expression matching the item status (i.e. 'A' or 'A|N').
   • order - a list of columns to order the results by. Can include columns for the item's Type! (i.e. 'it_type ASC, it_type DESC, size')
   • typedata - an SQL expression to be included in the WHERE clause specifying Type data. (i.e. 'AND size>100 AND color=`blue`')
   • container - the container the results should be displayed in.
   • incols - the number of columns to show the list in (overrides the default set for the container)

You can call these functions anywhere in your HTML - using the (PHP) syntax. i.e:
<? echo show_items(); ?>

Example: To create an Owners page - you need to use the function call like this:
<? echo show_items('', '', $us_email, 'premiumlisting', '.*'); ?>
Where:

• The ownerlike field is the current user
• The type of item to display is your premium or free listing type
• The status as '.*' which means all (because if you've set items to be created at status 'Pending' then the owner won't be able to see the listing until it's approved)

Item Containers

Items, like other O3 objects, have a List container for showing lists of items, and a Detail container for showing all an item's details. The default containers are defined in the Settings, and you can specify a different one in the show_item() function call, or as a parameter (con) to the catalog page.

You can display your items any way you like by changing the container, and you can have lots of different containers to show the items in different ways (if you want).

Here's a list of the Macros available in O3's Item Containers. Note the most common problem with setting up containers is fogetting the closing '#' on the macros which take parameters. Ensure that you always use it or you'll get strange results.:

Item Container Macros