HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to compo.sr for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.


ocPortal Tutorial: Custom structured content (via catalogues)

Written by Chris Graham, ocProducts
Thumbnail: Adding a catalogue

Adding a catalogue

The catalogue system is a bit like a visual database system such as Microsoft Access: you create your own ‘record definitions’ that define what data you want for your records, and then you can add these records, and browse through them. All you need to do is to specify what goes in the records: the rest is all handled for you.

You can have as many catalogues as you like, and some pre-made ones provided by default.
The pre-made catalogues are:
  • Links
  • FAQs
  • Modifications
  • Hosted-sites
  • Developer-projects
  • Contacts
All the pre-made catalogues may be removed in the Setup Wizard, so depending on what you chose in that wizard, they may or may not currently be on your site.

Thumbnail: Choosing a catalogue to add an entry to

Choosing a catalogue to add an entry to

Catalogues can be used to model most things required by large websites that would otherwise have to be implemented either as new modules, or hard-coded pages. Note that catalogues are designed to store records of which there are likely more than one, not as a container for all unstructured custom information (that is what Comcode pages are for).

Catalogues are initially defined by the fields in them. 'Categories' are then made in the catalogue. Then categories are filled with 'entries'.


A warning

In some way we give you enough rope to hang yourself with via catalogues. In most cases, if you're not creating a pretty simple set of records, you'll want a programmer to properly implement an efficient database structure with the appropriate user interface and data rules. For a more detailed discussion, see this blog post:
http://ocportal.com/site/news/view/chris_grahams_blog/delivering-innovation.htm

There are loads of features within the catalogue system, and there are more we could add to give yet further power that could be sponsored. Just proceed with caution.

Fields

A catalogue consists of a number of fields.

Thumbnail: Adding an entry to a catalogue

Adding an entry to a catalogue

Catalogues support the following field types:
  • short_text – A short piece of text (less than 255 characters)
  • long_text – A long piece of text
  • short_trans – A short piece of text (less than 255 characters), that supports Comcode
  • long_trans – A long piece of text, that supports Comcode
  • integer – An integer (whole number)
  • float – A floating point number (a number with a decimal part)
  • picture – An uploaded image
  • upload – An uploaded file
  • url – A URL
  • page_link – A page-link (i.e. in-site link)
  • email – An e-mail address
  • user – A member ID
  • list – A list with some predefined choices. You choose which values are in the list by encoding it into the default field value, each list value is separated by a '|' symbol
  • tick – A checkbox, or if the value is set as non-required, a list with 'Yes' and 'No' as selectable options
  • auto_increment – An auto-incremented number (i.e. each entry in the catalogue is assigned a sequential number) (this is set automatically, and not visible when adding an entry)
  • random – A random 10 character alphanumeric code (this is set automatically, and not visible when adding an entry)
  • and more
Thumbnail: There are a whole host of options available after catalogue activity

There are a whole host of options available after catalogue activity

Programmers may add new field types by writing new hook code files.
The 'upload' and 'picture' types actually allow entry submitters to upload files from their own computer.

Fields may be given default values. Sometimes these have special meanings:
  • list – The values in the list, separated by '|'
  • auto_increment – The sequence start number (if it was left blank by the submitter).
  • random – The length of the random string (if it was left blank by the submitter).

You may order the fields, make some invisible, make some optional, and choose which defines ordering. The first field in a catalogue is used as the title field for entries in that catalogue.

You may also specify which fields may be used to search the catalogue (searching is performed with the regular ocPortal search module).

Modes of display

Thumbnail: A non-tree catalogue uses an index

A non-tree catalogue uses an index

There are two options to set how a catalogue may display:
  • 'Display type' – you can display entries in categories as title lists, field-maps, tabular listings, or in a grid of images (full customisation is possible via templating).
  • 'Is tree' – a tree catalogue has a full hierarchical category tree, much like the download system does; a non-tree catalogue just shows the categories from a single catalogue index.

Note that if you set all fields of your catalogue to "Display in category-views" and disable comments and ratings and trackbacks, there will be no links to the entry view screen. This is due to there being little purpose in this screen because everything already displays on categories.

Thumbnail: A catalogue with title-lists

A catalogue with title-lists

Thumbnail: A catalogue with field-maps

A catalogue with field-maps

Thumbnail: Viewing a catalogue entry

Viewing a catalogue entry


Display type

Title lists

Title lists are very simple lists of links. Each link links through to the full entry screen.

Templates:
  • CATALOGUE_*_TITLELIST_ENTRY.tpl
  • CATALOGUE_*_TITLELIST_WRAP.tpl

Field-maps

Field-maps are the most flexible display type because they can easily and automatically expand to show as much field data within the category view as you want.

Templates:
  • CATALOGUE_*_FIELDMAP_ENTRY_WRAP.tpl
  • CATALOGUE_*_FIELDMAP_ENTRY_FIELD.tpl

Tabular listings

Tabular listings will show your entries in columns. This works well if the data within any particular category-displayed field is short, and if there aren't too many of them.

Templates:
  • CATALOGUE_*_TABULAR_ENTRY_WRAP.tpl
  • CATALOGUE_*_TABULAR_ENTRY_FIELD.tpl
  • CATALOGUE_*_TABULAR_HEADCELL.tpl
  • CATALOGUE_*_TABULAR_WRAP.tpl

Grid of images

This is probably the most attractive display, and works well if you only really need to show a title and a thumbnail on the category screen.

The default template (CATALOGUE_DEFAULT_GRID_ENTRY_WRAP.tpl) assumes the first field is the title and the second field is the picture.
You therefore need to either:
  1. Follow this convention
  2. Create CATALOGUE_yournewcatalogue_GRID_ENTRY_WRAP.tpl such that it references a different field sequence number (replace FIELD_1_THUMB, noting that we're counting field sequence numbers starting from zero)

However there is an important exception to the above. The products catalogue already is bundled with a custom template set which is already referencing a different picture field. You also are not supposed to rearrange the first few fields in the products catalogue because they have a hard-coded meaning.

Templates:
  • CATALOGUE_*_GRID_ENTRY_WRAP.tpl
  • CATALOGUE_*_GRID_ENTRY_FIELD.tpl

Creating a tree catalogue, fast

There is a special feature on the screen to add a catalogue with a category tree constructed automatically for it.
To define the tree you just need to type in the categories you want in a special format that is very quick to write.

This is best shown by example, so here is an example for a catalogue category tree with that has categories for each of the states/provinces in the USA and Canada:

Code

USA\Alabama|USA\Alaska|USA\Arizona|USA\Arkansas|USA\California|USA\Colorado|USA\Connecticut|USA\Delaware|USA\Florida|USA\Georgia|USA\Hawaii|USA\Idaho|USA\Illinois|USA\Indiana|USA\Iowa|USA\Kansas|USA\Kentucky|USA\Louisiana|USA\Maine|USA\Maryland|USA\Massachusetts|USA\Michigan|USA\Minnesota|USA\Mississippi|USA\Missouri|USA\Montana|USA\Nebraska|USA\Nevada|USA\New Hampshire|USA\New Jersey|USA\New Mexico|USA\New York|USA\North Carolina|USA\North Dakota|USA\Ohio|USA\Oklahoma|USA\Oregon|USA\Pennsylvania|USA\Rhode Island|USA\South Carolina|USA\South Dakota|USA\Tennessee|USA\Texas|USA\Utah|USA\Vermont|USA\Virginia|USA\Washington|USA\West Virginia|USA\Wisconsin|USA\Wyoming|Canada\Alberta|Canada\British Columbia|Canada\Manitoba|Canada\New Brunswick|Canada\Newfoundland and Labrador|Canada\Northwest Territories|USA\Nova Scotia|USA\Ontario|USA\Prince Edward Island|Canada\Quebec|Canada\Saskatchewan|Canada\Yukon Territory

Adding a catalogue

To add a catalogue (amongst other functions) go to the 'Catalogues' icon in the Content Management Zone.

Editing a catalogue

Thumbnail: Editing a catalogue

Editing a catalogue

You can edit a catalogue to change details, add, edit or remove fields.

You cannot change field data types after you have created them (except between field types that have the same "storage" type) as this would affect the integrity of any data that may have already been entered into them. A workaround is to export to CSV, delete the field, create a new field with the same name and the new type, and reimport the CSV.

Permissions

Like other ocPortal content types, catalogues support access permissions. However because catalogues essentially allow many different content types to be produced (each in their own catalogue), there is an extra layer of permissions available: you may set access permissions for both catalogues, and categories within them.

Customising the look & feel of catalogues

If you have multiple catalogues on your website and you wish for them to have customised appearances, this is possible for advanced users via one of two ways:

Tempcode programming

It is possibly to achieve template customisation wholely within the default set of templates, by using template programming. The catalogue name is passed into every catalogue template meaning you can use template IF directives to differentiate against that name, producing different output accordingly.

Whilst the main CATALOGUE_DEFAULT_FIELDMAP_ENTRY_WRAP.tpl template uses the FIELDS parameter by default (which consists of precomposited template field rows, built using the other templates), it is also given special parameters correlating to each individual field row and each individual field value. You may thus entirely customise the catalogue look using these low level values to make very customised arrangements that are more complex than the simple tabular arrangement used by default.


For example, take the CATALOGUE_DEFAULT_FIELDMAP_ENTRY_WRAP.tpl template:

Code

<div class="wide_table_wrap"><table summary="{!MAP_TABLE}" class="wide_table results_table spaced_table">
   <colgroup>
      <col class="field_name_column" />
      <col class="field_value_column" />
   </colgroup>

   <tbody>
      {FIELDS}
   </tbody>
</table></div>

If we wanted to jazz a 'classifieds' catalogue up a bit, we might change it to something like:

Code

<div class="wide_table_wrap"><table summary="{!MAP_TABLE}" class="wide_table results_table spaced_table">
   <colgroup>
      <col class="field_name_column" />
      <col class="field_value_column" />
   </colgroup>

   <tbody>
      {FIELDS}
   </tbody>
</table></div>

{+START,IF,{$EQ,{CATALOGUE},classifieds}}
<p>
   This advert was posted by
   <a href="{$PAGE_LINK,_SEARCH:members:view:{SUBMITTER}}">{$USERNAME*,{SUBMITTER}}</a>.<br />
   You might want to
   <a href="{$PAGE_LINK,_SEARCH:contactmember:misc:{SUBMITTER}}">email {$USERNAME*,{SUBMITTER}}</a>
   to query more about {FIELD_0*}.
</p>
{+END}

You can see how you can reference individual fields in the template like {FIELD_0}.
For a full table of fields you can use, put {+START,PARAM_INFO}{+END} temporarily into the template, and it will show you everything defined in a neat table.

Custom template sets

For power users only

With some file system manipulation, you may make use of the 'custom template sets' feature. You then need to go to the themes/default/templates directory in ocPortal and copy all the CATALOGUE_DEFAULT_*.tpl files to CATALOGUE_<your-catalogue-codename>_*.tpl.
You would then customise these templates.

When we talk about default catalogue template set, we are referring to the CATALOGUE_DEFAULT_*.tpl files rather than referring to the default theme or the default versions within that theme. It is possible for custom themes to have their own versions of the default catalogue template set, and also per-catalogue versions.
We're using the word default in different contexts, so to clarify:
  • themes/default/templates/CATALOGUE_DEFAULT_*.tpl – the default theme's default default template set
  • themes/default/templates_custom/CATALOGUE_DEFAULT_*.tpl – the default theme's overridden default template set (i.e. a site's owner has decided to override it but not on a per-theme basis)
  • themes/default/templates_custom/CATALOGUE_somecatalogue_*.tpl – the default theme's custom template set for the somecatalogue catalogue
  • themes/mytheme/templates_custom/CATALOGUE_DEFAULT_*.tpl – the mytheme theme's overridden default template set
  • themes/mytheme/templates_custom/CATALOGUE_somecatalogue_*.tpl – the mytheme theme's custom template set for the somecatalogue catalogue

We intentionally did not provide a highly user-friendly interface for enabling custom template sets because the process of working with multiple sets of templates is inherently difficult, and by setting it up manually you will get a better feeling for what ocPortal does.

Seamless catalogues

As well as customising the catalogue templates, you may also customise the language strings used by catalogues in a similar way to how custom template sets are customised.

To do this, you need to manually edit the catalogues.ini file to add new equivalents to the DEFAULT__* strings (where 'DEFAULT' is replaced with the codename of the catalogue that you are customising for).

You can see this has already been done for some of the default catalogues:

Code

links__CATALOGUE={1}
links__CATALOGUE_INDEX=Link category index: {1}
links__CATALOGUE_CATEGORY={1}
links__CATALOGUE_ENTRY=Link: {1}

If you have the language cache enabled then you will need to empty the language cache before these changes will show up.

You can also add descriptions to the add and edit screens for catalogues by creating new strings like:

Code

CATALOGUE_<catalogue-name>_ADD_TEXT=Shown on add screen.
CATALOGUE_<catalogue-name>_EDIT_TEXT=Shown on edit screen.

eCommerce catalogues

ocPortal can have special eCommerce catalogues, which integrate with the ocPortal shopping cart. These catalogues provide the following special functionality:
  • special templating for tidy product display
  • easy adding to the shopping cart
  • tax calculation
  • discounting
  • stock counting
  • view tracking

An eCommerce catalogue always assumes it has a number of special eCommerce fields as the first fields in the catalogue. The default 'product' catalogue is configured like this and thus can be used as a reference for creating more product catalogues, if desired (few users will, however, require more than one product catalogue).
If an eCommerce catalogue is not correctly configured errors will occur.
The special eCommerce fields are:
  • title
  • code
  • price_pre_tax
  • reduction_start
  • reduction_end
  • stock_level [allows blank, meaning 'not stock counted']
  • stock_level_warn_at [allows blank, meaning 'not stock counted']
  • stock_level_maintain
  • tax_type
  • weight
  • description

Classified ads

Catalogues are ideal for setting up a classified ads system. In fact, there is special support for this as you can program a catalogue to move entries to an archival category after a specified period of time passes. There is also a permission ('Have a longer expiry-time for catalogue entries') that allows you to grant usergroups a longer period of advert display.

This feature works by logging the date/time for each entry added. This is stored in the ce_last_moved field in the database, under each entry. Any entry in a category that has a move target assigned will be scanned to see if the ce_last_moved date/time is more than the configured number of move days. If it is, the entry is moved. When an entry is moved, the ce_last_moved date/time is reset to the current time. Therefore you could, if you wished, set up chains of movements. There is no way in the ocPortal UI to change ce_last_moved manually (it is not affected by manual moves, validation, or editing), although you could manually make changes to it in the database or you could manually move it back after it has moved and therefore the timer reset. As the movement happens in the scheduler, the scheduler must be enabled for it to work.

The unofficial classified ads addon overrides the functionality of ce_last_moved and uses it to track listing times. Unlike the default functionality, this de-validates entries rather than moving them (to allow listing extensions).

Searching catalogues

The ocPortal search module provides special support for searching catalogues by matching against field values. You can choose which fields are searchable when you add them to the catalogue (or when you go back to edit).

CSV import

You can import CSV files into catalogues. Be aware this adds entries only, it doesn't try and do any merging with what is already there.

A note about permissions

If you manually alter the templates so that upload/picture fields display the raw URL, rather than going through ocPortal's downloader script, then you will need to delete the uploads/catalogues/.htaccess file. By default permissions are denied to directly access these URLs, to prevent users without catalogue access from accessing individual files.




Concepts

Catalogue
A custom database stored within your database: define your own records, and manipulate and view them as a part of your website

See also