Composr Supplementary: Catalogue field references

This tutorial shows some advanced usage of catalogue field references. It will show you how to create a reference from one catalogue to another, and then extract individual fields for display.

Forward references

The following steps show you how to setup two catalogues, with one referencing the other – and then to use custom catalogue templating to extract an unrelated field from the referenced catalogue entry.

1) We set up our catalogue being referenced. We're create a standard title field and a picture field (which is what we'll be extracting). This is what the catalogue is set up like:



2) We add an entry to this referenced catalogue. This is what it is set up as:



3) We set up our catalogue doing the referencing. This is what the catalogue is set up like:



Note that we are using an "A reference to a catalogue entry in …" field, not a "Multiple references to a catalogue entry in …" field. Handling multiple reference fields is a lot more complicated.

4) We add an entry to this referencing catalogue. This is what it is set up as:



5) We then override the entry screen template for the referencing catalogue by creating a CATALOGUE_catalogue-with-references_ENTRY_SCREEN.tpl template. I just overrode it with the basic Tempcode needed to achieve our objective:

Here we are using the CATALOGUE_ENTRY_FIELD_VALUE symbol to extract the fields from our referenced catalogue.
0 references the 1st field in the referenced catalogue, as in computing we often count from zero. It is the title in our referenced catalogue. 1 references the 2nd field, which is the image.

58 is the ID of the reference field on my test site. You can actually see that in the screenshot for '3' above.

The PAGE_LINK symbol is being used to create hyperlinks to the referenced catalogue entry.

And this is what it looks like when we view the test entry in our referencing catalogue:

(Click to enlarge)

As you can see it is rendering the image field as a thumbnail right out of the box.

If we wish we could get the URL to the image instead, by using the CATALOGUE_ENTRY_FIELD_VALUE_PLAIN symbol instead. We could then render out the image in any way we want.

Backward references

What if we want entries in our referenced catalogue to show which entries are referencing them?

We can do this too, although it is a little more complex.

To do it we need to use the CATALOGUE_ENTRY_BACKREFS symbol.

Here is an example of the entry screen template overrode for the referenced catalogue, CATALOGUE_catalogue-with-picture-field_ENTRY_SCREEN.tpl:

The 58 locks it down to only extract references within field ID #58 (this is the field we made in our referencing catalogue). We don't strictly need to lock it down like this, but if we don't we cannot assume what fields may exist in the catalogue entries doing the referencing (as they could be from all kinds of different catalogues).

We use a loop as there may be multiple entries with back-references. The CATALOGUE_ENTRY_BACKREFS symbol returns a comma-delimited list, which LOOP will iterate over.

We then use PAGE_LINK and CATALOGUE_ENTRY_FIELD_VALUE in a very similar way to how we did before, except now the catalogue entry ID is in {_loop_var} instead of {_FIELD_58_PLAIN}.

(Click to enlarge)

See also

• Custom fields
• Custom structured content (via catalogues)

Feedback

Have a suggestion? Report an issue on the tracker.