ocPortal Tutorial: Custom structured content (via catalogues)

Written by Chris Graham, ocProducts

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.

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'.

Table of contents

ocPortal Tutorial: Custom structured content (via catalogues)

Fields

A catalogue consists of a number of fields.

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. The first such field will support attachments.
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
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)

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

A non-tree catalogue uses an index

There are two options to set how a catalogue may display:

'Own pages' – this allows you to make it so that catalogue categories show only skeleton information on entries, encouraging users to view the entry screen for full details; typically this will be used when entries have many fields.
'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.

A catalogue with 'own pages' enabled

A catalogue without 'own pages' enabled

Viewing a catalogue entry

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\Newfoundlandand 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

You can edit a catalogue to change details, add, edit or remove fields. You cannot change field data types after you have created them, as this would affect the integrity of any data that may have already been entered into them.

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_ENTRY.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_ENTRY.tpl template:

Code


			<div class="wide_table_wrap"><table summary="{!MAP_TABLE}" class="wide_table solidborder spaced_table">
   <colgroup>
      <col width="150" />
      <col width="100%" />
   </colgroup>

   {FIELDS}
</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 solidborder spaced_table">
   <colgroup>
      <col width="150" />
      <col width="100%" />
   </colgroup>

   {FIELDS}
</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.

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.

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.

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).

Concepts

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

ocPortal Tutorial: Custom structured content (via catalogues)

Fields

Modes of display

Creating a tree catalogue, fast

Code

Adding a catalogue

Editing a catalogue

Permissions

Customising the look & feel of catalogues

Tempcode programming

Code

Code

Custom template sets

Seamless catalogues

Code

Classified ads

Searching catalogues

Concepts

See also

Is this tutorial insufficient?