Entity and relationship patterns

These patterns can be used for data that may traditionally be managed as fields in a relational database. The advantages that PageSeeder offer for this kind of application are similar to a subset of broad area of database technology known as NoSQL . When used with this pattern, conceptualize PageSeeder as a document-oriented database . Some examples of  data that may be managed as fields are:

  • A pharmaceutical drug has multiple forms (tablets, capsules, soluble powders) and dosage strengths available under several brand names from a number of manufacturers each with a name, address and contact details.
  • A book has a title, ISBN, and is listed under more than category, in addition to being listed by the author and publisher, which is also listed with an address.

When working with data like these, an Entity-relationship  diagram can help to express the model. To do this, make each type of content an entity and label certain fields and each relationship with the cardinality:

  • 1 to 1
  • 0..1 to 0..1
  • 1 to N
  • 0..1 to N
  • N to M
  • 0..N to 0..M

In PageSeeder, the data can then be expressed as follows:

  • A document type for each entity.
  • A <property> for each field. To aid productivity and data quality, a custom editor PSMLPropertiesConfig can be set up for each data set.
  • Create a property of type xref from one end of each relationship: 1 to 1, 0..1 to 0..1
  • Create a property of type xref from the N end of each relationship: 1 to N, 0..1 to N.
    • It is also possible to use an xref list fragment from the 1 end of the relationship but this can make editing difficult if N is a large number (xref list fragments can be created using the xref list editor).
  • Create an xref fragment for each relationship N to M, 0..N to 0..M. To reduce the number of xrefs being edited this is usually done from the end for which N or M is largest.
  • The xref only needs to be at one end of the relationship because the reverse XRefs are created automatically.

The following configuration options are also recommended:

  • If there is more than one instance of an entity and there is no reason to name them differently, set the files to be auto-numbered in the document-config.xml. For example, the following would create documents like /books/00/001-book.psml in a books/ folder:
    <creation>
      <title>Book</title>
      <folder context="/books" path="{0P1000} />
      <filename value="{NNN}-book" editable="false"/>
      <document title="Book {N} {$ui.title}" docid="B{0000N}" />
    </creation>
    
  • If multiple collections of the same entity are required, a * wildcard in the context can be used. For example context=/libraries/* would ensure books are created under /libraries/mytown/books/00/001-book.xml or /libraries/yourtown/books/00/001-book.xml.
  • If generating updates to documents outside PageSeeder, use a different naming convention for the generated documents so they do not clash with those created in PageSeeder (e.g. /books/x00/001-book.xml with docid BX00001).
  • Create an xref list config for each xref list fragment to default the xref type to None and set the autosuggest to the correct target document type in the editor-config.json. For example:
    "
    PSMLXRefsConfig": {
      "xref": {
        "type": "None"
      },
      "autosuggest" {
        "with": {
          "psdocumenttype" : "author"
        }
      }
    }
    
  • If the target document type is in multiple collections, autosuggest can be restricted to the current collection by adding “psancestor” under "with" (e.g. "psancestor" : "libraries/*"). The * will automatically be replaced with the context of the current document (e.g. libraries/mytown).

image008.gif

The example Entity-relationship diagram above could be implemented using three document types: book, author and publisher.

  • As per the recommendations above, the N to 1 relationship will be an “author” property at the N end (i.e. in the book document)
  • In the N to M relationship, since an author has probably written more books than a book has authors, the N will be the larger number. So as per the recommendations this will be implemented as an xref list fragment at the N end (i.e. in the book document)

Below is an example of the book, author and publisher PS XML including these relationships and the other fields.

<document level="portable" type="book">
   <section id="metadata">
      <properties-fragment id="1">
         <property name="title" title="Title" value="My story"/>
         <property name="isbn" title="ISBN" value="0864412345"/>
         <property name="category" title="Category" value="Fiction"/>    
         <property name="publisher" datatype="xref" title="Publisher">
            <xref type="none" frag="default" href="../../publishers/00/001-publisher.psml">XYZ Books</xref>
         </property>
     </properties-fragment>
  </section>
   <section id="authors">
      <title>Authors</title>
      <xref-fragment id="2">
         <blockxref type="none" frag="default" href="../../authors/00/001-author.psml">John Jones</blockxref>
         <blockxref type="none" frag="default" href="../../authors/00/002-author.psml">Jane Black</blockxref>
      </xref-fragment>
  </section>
</document>
<document level="portable" type="author">
   <section id="metadata">
      <properties-fragment id="1">
         <property name="name" title="Name" value="John Jones"/>
     </properties-fragment>
  </section>
</document>
<document level="portable" type="publisher">
   <section id="metadata">
      <properties-fragment id="1">
         <property name="name" title="Name" value="XYZ Books"/>
         <property name="address" title="Address" value="P.O. Box 123, My City"/>
     </properties-fragment>
  </section>
</document>

Created on , last edited on