ocPortal Tutorial: Custom structured content (via catalogues)

Written by Chris Graham, ocProducts

Adding a catalogue

{!DOC_CATALOGUES}
The pre-made catalogues are:

Links
FAQs
Modifications
Hosted-sites
Developer-projects
Contacts

Choosing a catalogue to add an entry to

Catalogues can be used to model aspects of most 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 originally 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
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
email - An e-mail address
user - A member ID
list - A list with some predefined choices
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)

The 'upload' and 'picture' types actually allow entry adders 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 - Optional. The sequence start number
random - Optional. The length of the random string.

There are a whole host of options available after catalogue activity

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 as templates for searching the catalogue.

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 page 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

Editing a catalogue

You can edit a catalogue to change details, add, edit or remove fields. You cannot change field data types, as this would affect data integrity.

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:

Custom template sets

With some file system and database manipulation, you may make use of the 'custom template sets' feature. To deploy these you need to manually edit the database row for the catalogue you wish to have a custom template set so that the 'c_own_template' field is set to '1'. 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.

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.

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).
If you have the language cache enabled then you will need to empty the language cache before these changes will show up.

Concepts

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