How to Use the Mura ORM Assembler

Warning! This feature is in ALPHA status as of Mura v7.1, and functionality may change without notice.

As previously mentioned, the Mura ORM Assembler enables for the creation and management of Mura ORM entity definitions and relationships. Once you've enabled the Mura ORM Assembler & Scaffolder, you may follow the steps outlined below to create Mura ORM entity definitions and relationships. Only Super Admin Users are able to use the Mura ORM Assembler.

  1. From the back-end administration area of Mura, select Content on the main navigation, then select the Custom tab.
  2. To create a new Mura ORM entity, click the Add button.
  3. You should be taken to the Custom Mura ORM Entity screen.
  4. Complete the information on the Definition tab. The primary fields are described below.
    • Entity Name
      • A variable-safe name (no spaces, begins with a letter, letters, numbers and underscores only). For instance, if you were creating a "Book" entity, you might call this entity simply "book".
    • Display Name
      • This is the human-readable version of the Entity Name, such as "Department Heads" or "Types of Pets".
    • Table Name
      • This is the table name the entity's data will be stored in. It is usually advisable to match it to the entity name, and is often prefixed with some special name to distinguish it in the database and avoid naming collisions with Mura's own table names. For instance, a "book" entity might have a table name like "custom_books" or "mycompany_books".
    • Order By (optional)
      • This is the default property (column) by which to sort/order your entity data by. It must match one of the Property Names of the entity (see below).
    • Scaffold
      • If enabled, this gives the entity permission to be managed in the Mura ORM Scaffolder for data entry/management.
    • Bundleable
      • If enabled, the entity and any stored data will be included in any site bundles.
    • Publicly Accessible
      • If enabled, the entity may be displayed and/or managed via the front-end of your Mura site. However, you will also be responsible for building the user interface for display and/or management on the front-end itself.
  5. Also on the Definition tab, is where you manage the Entity Properties and relationships. An entity's "properties" are the fields where data will be stored, and will essentially be turned into columns within the defined Table Name. Every entity has a mandatory "id" property, which you may rename, but not delete. In addition, new entities also begin with an optional "siteid" property, which is important for tying the data to a specific Mura site. An entity's "relationships" are the keys that bind your entity to other Mura ORM entities.
    • How to Add /Edit Properties
      • Click the Add Property button, or select a property to edit.
      • You should now see the Property Details screen. The fields are described below.
        • Property Name
          • The variable-safe name for the property. For example, "booktitle" or "bookauthor".
        • Display Name
          • The human readable version of the property name. For example "Book Title" or "Book Author".
        • Data Type
          • The SQL data type the property should be saved as.
          • Valid options are:
            • VarChar
            • Text
            • Int
            • Boolean
            • DateTime
            • Any
        • Field Type
          • Valid options are:
            • None
              • This is the default value, and if selected, no database index will be created.
            • Index
              • If selected, a database index will be created on the property.
        • Default
          • The value entered here will be used as the default value in the Mura ORM Scaffolder. This is useful when the property's Form Field type is set to Dropdown or Radio to pre-select one of the the option list values.
        • Form Field
          • The value selected here will determine how the form field will appear in the Mura ORM Scaffolder when administrators are entering data.
          • Valid options are:
            • Text Field
            • Text Area
            • HTML Editor
            • Dropdown
            • Checkbox
            • Radio
            • Hidden
            • Do not render
        • Length
          • The maximum length of the data field.
        • Required
          • If checked, the property will be required in the Mura ORM Scaffolder.
        • List
          • If checked, the property will be displayed in the list view of the Mura ORM Scaffolder.
        • Filter
          • If checked, end users may use the "Filter By" functionality on this property in the list view of the Mura ORM Scaffolder.
        • Nullable
          • If checked, the property will be set to "NULL" in the database if no value is entered in the Mura ORM Scaffolder.
        • Option List
          • This field will appear if the Form Field type is set to Dropdown or Radio. Enter a carat (^) delimited list of values to be used as the labels for the form field. For example, "Matt^Grant^Steve".
        • Option Value List
          • This field will appear if the Form Field type is set to Dropdown or Radio. Enter a carat (^) delimited list of values to be used as the value which will be stored in the database. For example, "001^002^003". 
      • When finished, click the Add Property button.
      • To reorder Entity Properties, click+drag and drop the properties.
      • Click Save when finished.
      • A message will appear at the top of your screen to indicate when the entity definition has been saved.
      • In addition, a ".CFC" file will be auto-generated and saved under {context}/modules/dynamic_entities/model/beans/{EntityName}.cfc. If you wish, you could copy this file and save it under your own ../model/beans/ directory, and then delete the auto-generated file itself.
      • If you wish to delete the entity, simply click the Delete button, and select OK on the Alert dialog window. Also, when deleting entities, only the entity definition itself will be deleted from Mura, and the auto-generated ".CFC" file. However, all data will still be stored in the associated tables.
    • How to Add/Edit Relationships
      • Click the Add Relationship button, or select a relationship to edit.
      • You should now see the Relationship Details screen. The fields are described below.
        • Property Name
          • The variable-safe name that references the related entity. For example, a "book" entity might have related "authors". So, you could enter "author" or "authorid".
        • Display Name
          • The label, or human readable version of the relationship. For example, "Author" or "Author ID".
        • Relationship Type
          • When working with relationships, read the relationship from left to right. In other words, the left word refers to the current entity, and the word on the right refers to the related entity.
          • Valid Options:
            • one-to-many
              • This common type of relationship indicates the current entity may be related to multiple related entities. For example, one "order" entity could be related to multiple "product" entities.
            • one-to-one
              • This very simple relationship indicates there will only be one related entity to the current entity. For example, each "product" entity can be related to only one "manufacturer" entity.
            • many-to-one
              • Similar to the one-to-many relationship, this common relationship type indicates there may be multiple current entities related to a single entity. For example multiple "product" entities can be related to only one "order" entity.
          • If you wish to create a "many-to-many" relationship, the recommended approach is to simply create a one-to-many/many-to-one association between three participating entities. In other words, you would create a special entity to bind the related entities together. For example, you could have an "author" entity, a "book" entity, and a "authorsbooks" entity which stores the primary key values of both "authors" and "books" as a "many-to-one" relationship. For more information on this approach, view our blog post titled Mura ORM and Many-to-Many Relationships.
        • Relates To
          • Select the actual entity that this entity is related to. Only defined entities will appear in the list, in addition to Mura's own entities (such as "content" and "user"). If the desired entity has not been defined yet, you will need to define the entity, and come back to create the relationship.
        • Foreign Key Column
          • In most cases, this should be the related entity's "Primary Key" field. However, there may be an occasion where another field should be used to bind the entities together.
        • Render Field
          • The select menu will be populated with the properties of the selected entity from the "Relates To" field. Select the desired property to display when viewing the entity list in the Mura ORM Scaffolder table. For example, if the related entity is "author", you may wish to select the "Last Name" property instead of some obscure "authorid" property.
        • Load Key
          • This field relates to the Foreign Key Column. If the current entity is related by something other than the Primary Key, you should enter it here.
        • Cascade Delete?
          • Valid Options:
            • none
              • Do nothing if any related entities are deleted.
            • delete
              • If selected, this entity will be deleted when the related entity is deleted.
      • When finished, click the Add Relationship button.
    • The relationship will now display under the Entity Properties area. Simply click the gears icon to edit the relationship again, if desired.
  6. The JSON tab displays the string to be saved in the database as the definition of the entity, and captures all of the properties and relationships created using the Mura ORM Assembler. This is especially useful information when using Mura.js to work with Mura ORM entities.
  7. When finished, click the Save button to save your entity definition.