User Manual For Website Editors and Administrators
References in Contentstack
In Contentstack, as a Headless CMS, you work with a relational data management (see “Understanding Contentstack”). A relation between two datasets is called Reference.
A reference is a relation from one entry (dataset) to another. Even if two entries are referenced, both remain independent in regards to editing, versioning etc.
Example: A simple webpage needs at least an entry of the type “Web Page” and one of the type “Content Block”. So both are “referenced” to each other.
If you reference an entry in another entry, the referenced entry itself stays independent. This means, all options can and must be used independently.
In a reference field, Contentstack allows you to either (a) “Choose an existing entry” or (b) “Create a new entry”. In other words, if you see (a) or (b) you know that this is a reference field and thus you need to observe certain rules.
(a) “Choose an existing entry”
If you click this option, Contentstack provides you with a selection of possible Content Types and Entries to select.
(b) “Create a new entry”
If you click this option, Contentstack forwards you to the related Content Type’s form to create and store your desired piece of content. Once you store the new entry, it will be automatically related (= referenced) to the entry where you are coming from.
If you create a new entry and you want to create a referenced entry in the same step, you will mostly miss the “Create a new entry” option. → Save your just created entry and try again.
This is necessary because Contentstack needs the unique ID of the entry to be able to store the reference. This unique ID will be created by saving the entry for the first time.
If you want to re-use a referenced entry, but change some parts of it, please do not do it here, but take take care to copy it before you make any changes! → Copy with a new name and proceed as “usual”.
If you want to publish an entry with references, Contentstack will probably ask you, if you want to publish the entry with or without references. → Normally, you want to publish with references.
As already said, the referenced entries stay independent in regards to their edit and publish status. Technically, if you publish with references, Contentstack publishes multiple entries in one process.
Please refer to “Organize Content in Contentstack” to learn more about the handling of referenced entries.
How and where do I edit content?
When you click the edit icon next to a referenced entry, Contentstack will forward you to the edit form of this entry. If there are unsaved changes in the entry you are leaving, Contentstack will ask you if you want to save the changes.
If you are not sure where you are, have a look on the top left of the form. There you can see the name of the currently displayed entry (either the title or the internal name, depending on the content type) and the name of the content type itself
If you want to switch back to the step where you are coming from, use the left arrow.
Reference a new entry in a new entry
Even if it’s possible to create a new nested Entry into an Entry, we strongly recommend to always create an Entry first and reference the created Entry in another.
For every Entry reference in an Entry, Contentstack needs the unique, technical Entry ID. This means that technically multiple steps must be processed and in consequence some unexpected redirects might happen. So, it’s much easier to create first e.g. an Entry of the Content Type “Image” and then create a new Content Block in which you reference this Image.
If you are just about to create a new entry, e.g. a Web Page, and want to reference a content block for the main content area, you might miss the option to create a new content block:
The reason is that Contentstack must know the unique identifier of the entry in which you want to nest a new entry.
If you miss the option to create a new entry from another entry, please provide the mandatory field values and Save the entry. Now, you find the option “Create new entry”.
Change or edit a referenced entry
If there is an entry referenced, you can either edit this entry or remove the reference to add a new one.
To edit the entry, click the left icon.
2) To change the entry reference, click the right icon to remove the reference to the entry. Once this is done, you can add a new reference.