Running content modeling workshops
This page is for project managers who facilitate content modeling, and for the editors and developers who take part. It answers: how to prepare and run the workshops, which questions to ask, how each answer maps to a concept of Exponential (class, attribute, datatype, node, section, state, language, role, layout), and what the workshops must produce so that developers can build and editors can recognize their content. The product terms come from The content model and editing content.
Contents
- Why content modeling matters in Exponential
- The concepts in one table
- Who takes part
- Preparation
- Workshop 1: content inventory and types
- Workshop 2: attributes and datatypes
- Workshop 3: the tree, relations and taxonomy
- Workshop 4: permissions, stages and languages
- Workshop 5: pages and layouts
- The class sheet to copy
- After the workshops
- Common pitfalls
Why content modeling matters in Exponential
"As a CMS its most notable feature is its fully customizable and extendable content model" (README, quoted on Who is the Exponential Foundation?). In Exponential you define your own types of content instead of fitting your content into fixed pages and posts. That freedom is the reason to model carefully: every class you agree on becomes forms that editors fill in every day, templates that developers write, and permissions that administrators assign.
The concepts in one table
| Concept | What it is | Decided in | Read |
|---|---|---|---|
| Content class | A type of content: a name, an identifier and a list of attributes (for example Article: Title, Intro, Body, Image) | Workshop 1 | Content model, section 1 |
| Class group | A folder of classes in the class editor (Content, Users, Media, Setup) | Workshop 1 | Class groups |
| Attribute and datatype | One field of a class and its kind: one line, several lines, rich text, image, relation ... | Workshop 2 | Content model, section 1 |
| Content object | One piece of content, an instance of a class, with versions and languages | same | |
| Node, location | A place of an object in the content tree; one object can have several | Workshop 3 | same |
| Section | A group of objects for permissions, navigation and designs; not a place in the tree | Workshop 4 | Sections |
| Object state | How far along content is (review, legal clearance, embargo, featured) | Workshop 4 | Object states |
| Workflow | Steps such as approval that run before or after an operation | Workshop 4 | Workflows |
| Content language | A language content is written in; shown per siteaccess | Workshop 4 | Content languages |
| Role and policy | Who may do what, limited by section, class, subtree, language, state | Workshop 4 | Roles and policies |
| Layout, zone, block, rule | How a page is arranged, and which pages get which layout | Workshop 5 | The layouts editor |
Who takes part
| Person | Why | Workshops |
|---|---|---|
| Project manager | Facilitates, keeps the decision log, guards the scope | all |
| Lead editor | Knows the content and the daily work | all |
| One or two editors | Will fill in the forms; spot what is missing | 1, 2, 5 |
| Lead developer | Knows what each decision costs to build; maps answers to classes | all |
| Designer | Knows which fields the design needs | 2, 5 |
| Administrator | Roles, sections, languages, siteaccesses | 4 |
| Translator or language owner | For multilingual sites | 4 |
Keep the group small enough to decide. Invite the others to a review of the results instead.
Preparation
- To do: A demonstration installation everyone can open, with a site package that has demo content (
sevenx_multisiteis the default ofexp:install; 4.3 Site packages). Showing real classes in Setup > Classes makes every concept concrete. - To do: A content inventory: a list of the content that exists today (pages, documents, products, people, events), with rough counts and an owner per area.
- To do: Ten real examples of content, printed or on screen, of different kinds.
- To do: The requirement list from discovery (Planning an Exponential project).
- To do: Copies of the class sheet.
- To do: A decision log (Project templates).
Workshop 1: content inventory and types
Goal. A list of content classes with a one-sentence purpose each.
Agenda:
- Show the product (15 minutes). The developer opens a class in Setup > Classes and creates an object of it, following Content model, sections 2 and 3. Everyone sees that a class is a form and an object is a filled-in form.
- Sort the examples (30 minutes). Lay out the ten examples. Group those that have the same fields. Each group is a candidate class.
- Name the classes (20 minutes). A name people read and an identifier code uses (
article,event). Note the object name pattern: which field names an object in lists (for example<title>). - Check against the inventory (20 minutes). Does every item of the inventory fit one class? Items that fit none are a new class or a sign that two classes should be one.
- Reuse (15 minutes). Which classes already exist in the site package? Reusing a shipped class saves template and translation work.
Output: the class list, each class with name, identifier, purpose, owner, estimated number of objects.
Tip
Ask "what would an editor search for?" rather than "what does the page look like?". A class describes content, not a page layout; the layout is decided in workshop 5.
Workshop 2: attributes and datatypes
Goal. For each class, its attributes with their datatype, whether required, and whether translated.
The datatypes available for new attributes are the AvailableDataTypes[] list of settings/content.ini, 35 entries
in the shipped list (Content model, section 1); extensions add more.
Map the editors' words to them:
| Editors say | Datatype identifier (settings/content.ini) |
|---|---|
| a title, a name, one line of text | ezstring |
| several lines of plain text | eztext |
| formatted text with headings, links, images | ezxmltext (rich text, edited in the online editor) |
| a date; a date and time; a time | ezdate, ezdatetime, eztime |
| yes or no | ezboolean |
| a number | ezinteger, ezfloat |
| one choice from a list | ezselection |
| a link to another item; several | ezobjectrelation, ezobjectrelationlist |
| a picture | ezimage |
| a file to download; audio or video | ezbinaryfile, ezmedia |
| a web address; an e-mail address | ezurl, ezemail |
| keywords | ezkeyword |
| a table of values | ezmatrix |
| a price | ezprice, ezmultiprice |
| a country | ezcountry |
| a user account | ezuser |
Extensions add others, for example tags (eztags), map locations (ezgmaplocation), star ratings
(ezstarrating) and spam protection for forms (recaptcha, hcaptcha)
(Extensions, themes and packages).
For each attribute decide:
- To do: Name and identifier.
- To do: Datatype.
- To do: Required? Image fields can require alternative text (Content model, section 9); decide it here, it is an accessibility requirement.
- To do: Translated? For a multilingual site: is the value the same in every language (a date, a price) or written per language?
- To do: Searchable? Will people search for it?
- To do: Shown where? Full view, list view, both, nowhere (internal).
- To do: Example value from the real examples.
Output: one completed class sheet per class.
Workshop 3: the tree, relations and taxonomy
Goal. Where content lives, how items point to each other, and how content is classified.
Questions:
- The tree. Draw the top two or three levels of the content tree. Which class may be created below which? Content that belongs in several places gets several locations (one object, several nodes), not copies.
- Relations. Which items refer to which (an article to its author, an event to its venue)? Each is an object relation attribute. Decide what happens when the target is removed; the content checks list "broken relations" afterwards (Content checks).
- Taxonomy. Is classification free (keywords) or controlled (tags managed by someone)? Controlled tags are
eztags(eztags); check the database first, becauseeztagsis not usable on MongoDB (MongoDB limits). - Media. Where do images and files live: in the media library, below the content that uses them, or both?
- Addresses. Which URL should an item have? URL aliases follow the tree; global aliases and wildcards exist for exceptions (URL aliases).
Output: a tree diagram (on paper is fine), a relation list, a taxonomy decision.
Workshop 4: permissions, stages and languages
Goal. Sections, states, workflows, languages and the role plan.
| Question | Product answer | Read |
|---|---|---|
| Are there groups of content only some people may read or edit (members area, intranet department)? | A section per group; roles limited by section | Sections |
| A new installation has five sections (Standard, Users, Media, Setup, Design); which do we add? | New sections; note that the Anonymous role reads only Standard by default | Sections, section 2 |
| Does content pass stages, with different people allowed in each stage? | A state group with states; policies limited by state | Object states |
| Must someone approve before publishing? | A workflow with an Approve event and a trigger; the workflow cronjob must run | Workflows |
| Which languages, and which is the main language of each item? | Content languages; SiteLanguageList per siteaccess; "always available" items | Content languages |
| Who may do what? | Roles assigned to user groups | Roles and policies |
Note
Sections, states and the tree are three independent ways to group content. "Sections say where content belongs ..., and the content tree says what it sits under. States say how far along content is" (Object states). Use the one that matches the question, not all three for everything.
Output: section list, state groups, workflow list, language list, role plan (role, groups, policies, limitations).
Workshop 5: pages and layouts
Goal. Which pages editors arrange themselves, and which are fixed templates.
With Exponential Layouts, "a layout is a saved arrangement of blocks in zones, and a rule decides which pages get it" (Who is the Exponential Foundation?). In the workshop:
- Open the Layouts tab of the demonstration installation and walk "In action: the layouts editor" of the admin tour.
- List the page types (home, landing pages, section front pages, article pages).
- For each: fixed template, or a layout editors change? Which zones? Which blocks?
- Which blocks are the same on many pages (header, footer, a prefooter)? They belong in a shared layout, linked from the others (The layouts editor).
- Who may change layouts? The Layouts tab is shown only to roles that may work with layouts.
Output: page type list with layout decision, zone and block list, shared layout list.
The class sheet to copy
Class: <Name> identifier: <identifier> group: <Content | Media | ...>
Purpose: <one sentence>
Owner (editor): <name> Expected number of objects: <n>
Created below: <parent classes> May contain: <child classes>
Object name pattern: <<attribute>> Section: <section> States: <state group or none>
Approval before publishing: <yes/no, by whom>
| # | Attribute name | Identifier | Datatype | Required | Translated | Searchable | Shown in | Example value |
|---|----------------|------------|----------------|----------|------------|------------|-----------------|---------------|
| 1 | Title | title | ezstring | yes | yes | yes | full, list | <example> |
| 2 | Intro | intro | ezxmltext | no | yes | yes | full, list | <example> |
| 3 | Image | image | ezimage | no | no | no | full | <file> |
| 4 | <name> | <id> | <datatype> | <y/n> | <y/n> | <y/n> | <where> | <example> |
Open questions: <list>
Decided on: <date> by: <names>After the workshops
- Write it up in one document: class sheets, tree, relations, taxonomy, sections, states, workflows, languages, roles, page types. Version it in the project repository next to the code.
- Review with editors who were not in the room. Ask each to place five real items in the model.
- Prototype: a developer creates two or three classes on the test installation (a class is created in minutes, Content model, section 2). Editors enter real content into them.
- Adjust and freeze the model for the build. Later changes go through the change process of Estimating and scoping.
- Plan migration and entry from the class sheets (Planning, phase 4).
Common pitfalls
| Pitfall | Why it hurts | Remedy |
|---|---|---|
| One class per page design | Many classes with the same fields; templates multiply | Model content; arrange pages with layouts or view templates |
| One "generic page" class for everything | Nothing can be listed, filtered or reused | Split by what editors search for |
| Copies instead of locations | Two objects drift apart | One object with several locations |
| Sections used as folders | Sections are not places in the tree | Use the tree for structure, sections for permissions |
| Languages decided late | Translation flags, siteaccesses and roles change | Decide languages in workshop 4 |
| Too many languages added "just in case" | Each language is a bit of a limited mask (at most 62) and removing one is only possible when nothing uses it | Add a language when it is needed (Content languages) |
| Alternative text left optional | Accessibility gaps found in QA | Make it required in workshop 2 |
Related pages
- The content model and editing content
- Sections, Object states, Workflows
- The layouts editor
- Planning an Exponential project
- Planning multisite and multilingual projects
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.