presets.html 2.5 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849
  1. <p>When you install CER, it won’t do anything at all until you create at least
  2. one <dfn>preset</dfn>. A preset is a relationship between two reference field
  3. instances, which are referred to as the left and right fields, respectively.
  4. When a change occurs in the left field, the right field will react &mdash; and
  5. vice-versa.</p>
  6. <p>An example: suppose you have a user reference field called Author, and it
  7. lives on Page nodes. You also have a node reference field called My Pages, and
  8. it lives on users. You can set up a preset that looks like this:</p>
  9. <p>Node: Page: Author &lt;--&gt; User: My Pages</p>
  10. <p>In this case, Author is the left field and My Pages is the right field. When
  11. the Author field is changed on a Page node, the referenced user(s) will be
  12. given a back-reference to that node.</p>
  13. <p>By default, presets are <dfn>bidirectional</dfn>. This means that a change
  14. on either side of the preset will affect the other side. The previous example
  15. is bidirectional: you can change Author or My Pages, and the other side
  16. will react accordingly.</p>
  17. <p>It's possible to make a preset <dfn>one-directional</dfn>, which means that
  18. the right side will react when the left side changes, but NOT the other way
  19. around. In a one-directional preset, changes to the right field will have no
  20. effect on the left field.</p>
  21. <p>A one-directional version of the above example would look like this:</p>
  22. <p>Node: Page: Author —&gt; User: My Pages</p>
  23. <p>So what this means is that, in a bidirectional preset, it really doesn't
  24. matter which field is the left one and which is the right one. They’ll affect
  25. each other equally. But in a one-directional preset, it <em>does</em> matter
  26. which side you're on. CER allows you to &quot;invert&quot; (flip) a
  27. one-directional preset.</p>
  28. <p>Internally, CER treats all reference-type fields the same way, which allows
  29. you to put a different kind of field on either side of a preset. You don't
  30. have to necessarily relate a node reference field to another node reference
  31. field. You could relate a node reference field to a user reference field. The
  32. only restriction is that each side of the preset must be able to reference the
  33. other side. So, to again use our example, Author needs to be able to reference
  34. users, and My Pages needs to be able to reference nodes (of the Page type).
  35. CER won't let you create relationships between fields that can’t actually
  36. relate.</p>
  37. <p>CER presets are entities built on top of Entity API, and they can be
  38. imported and exported just like any other exportable entity type, including
  39. support for Features.</p>