Entity Fields & Attributes

Entity Fields and Attributes

# Entity Fields & Attributes

> OVERVIEW: When entity fields are created pointing to an external Topic, the fields belonging to that topic can be used without needing to copy data back and forth. For documentation purposes, I'll refer to these secondary fields as "entity attributes."

Supported Features (9/3/2014):

* SRP, Map, Slideshow, Versus, and Detail Soft Joins
* SRP, Gallery View, and Map View templates
* Narratives

*Disclaimer:  Only a these features support entity attributes for now, but we'll add more in the future as we create new features, iron out any bugs with the current setup, and learn where/when entity fields will be most helpful to the Product.*

## Setup

To set up entity attributes, the fields you're going to be accessing need to be marked as "Shared". This should generally be done by the owner of the Topic that the entity field points *to*, as it will be their responsibility to make sure that retros or changes to the Topic don't break entity field use.

As an example, let's say I'm in Colleges and I'd like to use the population of the college's State in a narrative. I'd create an entity field pointing to State Facts, and then:

1. In State Facts, open the *Field Sidebar*.
2. Select the "Population" field, and open the *Advanced* section.
3. Change the field's status from "Private" to "Shared".
4. Save the changes.

![setup](https://dl.dropboxusercontent.com/u/42869844/ftb/2014/Entity_Docs-01.png)

> TIP: The *Field Usage* button on the *Field Sidebar* has been updated to search other Topics that might be accessing the field through an entity attribute.

## Use

At this point, "State Facts: Population" will be available to any Topics with a State Facts entity field. Find these fields in the SoftJoin editor, the *Field Sidebar*, or by adding `{{entity.attribute}}` in a narrative. For now, only *Dropdown* entity fields are supported. *Multiple Selection Lists* are a bit more complicated but may be added in the future. 

To find entity attributes in the *Field Sidebar*, select the entity field first. Attributes will be shown in a section below:

![use](https://dl.dropboxusercontent.com/u/42869844/ftb/2014/Entity%20Use.png)

Here's an example with a narrative:

```
{{#if state_entity.population > 30000000}}
  {{college}} is in a large state, with a population of {{state_entity.population}}.
{{/if}}
```

Want to customize the anchor text when you link to an entity field? Sure thing.

```
Read the [full details about {{gizmo_entity.title}}]({{gizmo_entity._url}}).
```

## Shared vs Private Fields

So why do we separate shared and private fields? As far as the platform is concerned there's no difference, but if you're in charge of a Topic that other PMs may use with entities, you'll probably want to have some say in which fields they get access to. By marking fields as "Shared", you're giving others permission to use the field in own Topics.

By default, the title field, main image field, and any fields that are already used by SoftJoins will be shared.

*Note: In the future, we'll probably also prevent SoftJoins and Widgets from using fields that are not shared. This should simplify retros, as you will only need to worry about other Topics using those specific fields.*

## Questions?

Let Don McCurdy or Dylan Wenzlau know if you have questions about using this feature, thanks.