Field Type Entity / Content-Item (enhanced in 08.03) [todo]

Warning ⚠️: New Docs Available

These are old docs and we haven't found the time to completely move them. You will find comprehensive new docs on docs.2sxc.org.

The entity field type is to establish relationships between content-items, both 1:1 and 1:n. This can be

1. a lookup-relationship like 'Author'
2. a parent-information like 'ManagedBy'
3. a list of shared children like 'Tags'
4. a list of un-shared children like 'recipe-steps'

Whatever you need, you can link it with this. 

Basic Configuration

The following settings can be made

1. Allow Multi Value: this tells the system that more than 1 item are permitted. Set this to true for things like tags, categories, checklist-steps, journal etc. Set it to false for things that are only allowed once, like author, country-of-origin, etc.
2. Entity Type: this is the type name (content-type) of the the items allowed to appear here. Usually it is only one type, like Tag, Download, NewsItem etc. If you leave this blank, any kind of type is allowed, and you won't be able to creat new items from this UI, because the system won't know what type to recommend. 
3. Enable Edit Items new in 8.3: This adds a pencil icon on every item, so that you could edit it directly from the list of items. In many cases it's ideal to leave it on, but there are cases where the content-editor should only select things, but not change them (like tags, categories). There are also cases where editing is essential (like JournalEntries). 
4. Enable Create New Item new in 8.3: This adds a + button so that the editor may add new items, like new tags, new authors etc. There are cases where you don't want this - for example when the user should only assign existing categories. 
5. Enable Add Existing Items new in 8.3: This allows the content-editor to search for existing items (like existing categories) and add them. This makes sense for categories, tags, author and more. You want to disable this for scenarios with Private-Children. For example, if you want to keep a list of Recipe-Steps or Journal-Entries, than these should always be created here and removed here - but you don't want the user to add existing steps from a different recipe. 
6. Enable Remove Item new in 8.3: This allows the user to press - and remove items from the list. Removing does not delete the item, it only removes it from the list. 
7. Enable Delete Item not-implemented: This is not implemented yet . It will allow you to add an x button to delete items - so remove and really delete. 

Remember to Plan Ahead in Large Scenarios

If you're just setting up a simple list and want to add related information like tags, team-members or whatever, this is easy and you can't really go wrong when you follow your intuition. In complex scenarios we recommend that you plan a bit more though. Here are some questions we recommend that you consider in those cases:

Relationship Parent to Child or Child to Parent

The question is: Should the relationship be managed in the parent, or in the child? In other words, does the parent have a field for the children, or does the child have a field for the parent?

1. 1:N Mapping: If it's managed in the parent and pointing to x-childred, you can map each child to many parents. It also means that the content-editing flow usually will go through the parent (to create the child or map an existing child-item to it). This is a good idea in cases where adding children usually is part of creating/editing the parent. It also offers the benefit of controlled sorting of the children: the sequence of items in an entity-field is preserved and also passed in the same way to the templating engine. 
2. N:1 Mapping: If it is managed by the child and pointing to the parent, then it is often more of a author or category-assignment
3. N:N Mapping: There are cases where you have multi-assignments on both sides of the relationships, like tags used in multiple products. 

Note that Templates can Work With Both Relationship-Links

Just to be precise: the question of which item points to the related one is mainly a question of managing / editing the content. So choose a solution that makes sense for managing the work; the templates can query the relationships both ways (from parent to child as well as from child to parent). 

Exclusive Mappings

In many cases the user can assign a target item (like the author) to multiple other items (like multiple products). But there are cases where this doesn't make sense - for example, when the sub-items are actually "parts" of the parent-item. Scenarios could be:

1. Steps in a recipe
2. Journal or history entries of a larger record
3. Parts-list
4. Customer Quotes about a specific product

All these cases need sub-items, but they shouldn't be available to assign to another product. 2sxc 8.3 adds this feature. Basically you just have to set:

1. Enable Create to true
2. Enable Add Existing to false
3. You probably also want enable-edit to be true and enable-remove to be true