User Manual For Website Editors and Administrators

Skip to end of banner
Go to start of banner

References in Contentstack

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 11 Current »

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.

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

(warning) 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”.

(warning) 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”.

If it’s still not possible to create a new entry, you might not have the permissions to create entries of this content type.

If you click “Create new entry”, you can add all information and save the new entry. When you clicked Save, Contentstack will lead you back to the Entry in which you clicked “Create new entry”.

⚠ This means that the new created Entry is saved, but not published! To publish the new Entry either select “Publish with references when you publish the Entry where you are coming from or navigate to the new created Entry explicitly and click “Publish”.

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.

  1. To edit the entry, click the left icon.

If you edit an entry, it will be changed for all places where you have this entry referenced. If you are not sure about the existing references, click the edit icon to open the entry. Then click the left arrow icon on the top right side to see all references.

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.

If you change the reference to an entry, this does not impact the referenced entry. So, if you are not sure if you break something by changing the referenced entry, it might be better to create a new instead.

(warning) Best Practice: Instead of starting from scratch, you can also copy an entry and adapt the copy to your needs.
If you aim at copying an entry and to edit the copy, please follow these steps:

  1. Leave the entry that you are currently editing. Take care to save you current status!

  2. Click “Content” in the main menu

  3. Select the Content Type where you can find the Entry you want to copy. E.g. go to “Content Block” if you want to copy a web page.

  4. Search for the desired entry. Above the list you find a search field. This might help you especially if there is a very long list.

  5. To create the copy, you have two options:

    • Hover over the row in the list view. At the right side an icon appears with three dots. Click the icon to open a context menu. In the context menu click “copy”

    • Click the entry to open the detail view. At the bottom, you find a “more” button. Click the button to see the options and click “copy”.

  6. The detail view of the copy opens and you can do all changes you need.

  • No labels