Introduction | Settings | Creating Items | Updating Items | Deleting Items
Expiry | Functions | Containers
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.
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.
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
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.
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.
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:
|Active||The thing is active & visible on the website|
|Notified||The thing is active & visible on the website, but is due to expire and the user has been sent a notification email.|
|Expired||The thing is expired & not visible on the website|
|Inactive||The thing is not visible on the website|
|Pening||The thing is awaiting approval and is not visible on the website|
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
There are 2 item functions:
- show_item(item_name, container)
- 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', '.*'); ?>
- 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)
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
|Macro||Is Replaced By|
|ROWCOLOR||When displaying lists, this alternates between the colors defined in the Search Settings.|
|IT-EXPIRY||Item Expiry Date|
|IT-CREATOR||Item's creator (email addr)|
|IT-DESC||The Item Description|
|IT-CATEGORY||The Item's Category|
|IT-TYPE||The Item Type|
|IT-STATUS||The Item Status|
|IT-IMAGE||The Item Image|
|IT-URL||The Item URL. This is the URL at which the item is visible - usually the O3 catalog page.|
|IT-SCURL||The Item SCURL. The URL where the item's schedule is available.|
|An 'Add to Cart' button is always displayed, whereas the favorites is displayed only if the item's not already present in the cart. The parameter is an optional button image (i.e. IT-CARTimg/cart.gif#)|
|IT-RENEW#||A 'Renew Listing' button. The option is the (renewal) Product name (i.e. IT-RENEWUpgradeListing#).|
|IT-APPROVE#||An Approve Item button - if the current user has update permissions. Option is the approval form name.|
|IT-DELETE#||A Delete Item button - if the current user has update permissions. Option is the approval form name.|
|UPDATE-ITEM#||Display the item update form - if the current user has update permissions.|
|UPDATE-IMAGES#||Display the image update form - if the current user has update permissions.|
|O3VAR#||Any internal value from the item's data or type data (i.e. O3VARsize#)|
|O3USR#||Any value from the current user's data or type data (i.e. O3USRus_email#)|
|SHOW-FORMform#||Display the (mandatory) form|
|O3IFa|b|c|d#||A simple comparison operator. If a=b then c is output, else d. The contents can contain other macros as all others are parsed first.|