Tutorials - Domma CMS

1. Your First Page

Goal: Create a published page that appears on your site.

Steps

Make sure your server is running:
```
npm run dev
```
In admin, navigate to Pages → New Page.
Set the title to "About Us".

In the editor, write some Markdown content:

## Welcome to our site

We are a team passionate about building great web experiences.

Our story started in 2020 when we decided to...

Set the frontmatter field: description: "Learn about our team and mission"
Change draft to false to publish the page.
Click Save.
Visit http://localhost:4096/about to see your page live.

What you learned

URL mapping, frontmatter fields, publishing workflow, and Markdown editing in the CMS editor.

2. Contact Form

Goal: Build a contact form that sends email notifications and stores submissions.

Steps

Create a collection for contacts (to store submissions):
- Admin → Collections → New Collection
- Name: "Contact Submissions", slug: contact-submissions
- Add fields: name (string, required), email (email, required), message (textarea, required), createdAt (datetime)
- Click Save
Build the form:
- Admin → Forms → New Form
- Name: "Contact", slug: contact
- Add fields: Name (text, required), Email (email, required), Message (textarea, required)
- Submit button text: "Send Message"
- Success message: "Thank you! We'll be in touch soon."
- Click Save
Add an email trigger:
- In the form editor → Triggers tab → Add Trigger → Email
- To: your@email.com
- Subject: New contact from {{name}}
- Body:
```
Name: {{name}}
Email: {{email}}
Message: {{message}}
```
- Click Save
Embed the form in a page:
- Admin → Pages → New Page: "Contact Us", slug contact
- Add this content:
```
## Get in Touch

We'd love to hear from you.

[form slug="contact"]
```
Visit http://localhost:4096/contact — fill and submit the form.
Check Admin → Forms → Contact → Submissions to see the stored entry.

What you learned

Creating collections to store data, using the form builder, configuring email triggers, and embedding forms via shortcodes.

3. Blog with Collections

Goal: Create a blog with a posts collection, listing page, and article pages.

Steps

Create Posts collection:
- Admin → Collections → New Collection
- Name: "Posts", slug: posts
- Add fields: title (string, required), slug (string, required), content (richtext), excerpt (text), publishedAt (date), author (string), tags (tags), image (media), published (boolean, default: false)
- Click Save
Create a few posts:
- Admin → Collections → Posts → New Entry
- Fill: title "Hello World", slug hello-world, content "My first post!", published: true
- Click Save. Repeat for 2 more posts.

Create a listing page:

Admin → Pages → New Page: "Blog", slug blog

Add this content:

# Blog

Latest articles from our team.

[collection slug="posts" filter="published:true" orderBy="publishedAt" order="desc" limit="10"]

Customise with a block template:

Admin → Blocks → New Block: "Post Card", slug post-card

Template:

<div class="card mb-4">
    {{#image}}<img src="{{image}}" alt="{{title}}" class="card-img-top">{{/image}}
    <div class="card-body">
        <h3><a href="/blog/{{slug}}">{{title}}</a></h3>
        <p class="text-muted text-sm">{{publishedAt}} · {{author}}</p>
        <p>{{excerpt}}</p>
    </div>
</div>

Visit http://localhost:4096/blog to see your post listing.

What you learned

Defining collections with multiple field types, using the [collection] shortcode with filtering and ordering, and creating block templates to control how entries are rendered.

4. User Roles

Goal: Create a "Moderator" role that can manage content but not system settings.

Steps

Create the role:
- Admin → Roles → New Role
- Name: "Moderator", slug: moderator
- Enable permissions: pages (create, read, update, delete), collections (read, update), forms (read), media (create, read, update, delete), blocks (read, update)
- Leave disabled: users, roles, settings, navigation, plugins
- Click Save
Create a test user:
- Admin → Users → New User
- Name: "Jane Doe", email: jane@example.com, password: (set one)
- Role: Moderator
- Click Save
Test the permissions:
- Log out (top-right → Sign Out)
- Log in as jane@example.com
- Verify: Pages, Media, Blocks are visible in the sidebar
- Verify: Users, Settings are not visible
Observe the sidebar adapts — only permitted sections appear based on the role's permission set.

What you learned

Creating custom roles with granular permission sets, assigning roles to users, and how the admin sidebar adapts dynamically to the authenticated user's permissions.

5. Going Pro

Goal: Enable Pro mode, connect MongoDB, create a View, and create an Action.

Pre-requisite

MongoDB running locally or a connection string to MongoDB Atlas.

Steps

Set MONGO_URI in your environment:

echo "MONGO_URI=mongodb://localhost:27017/domma-cms" >> .env

Enable Pro mode:
```
npm run pro
```
Then restart the server:
```
npm run dev
```
Create a View (Top Published Posts):
- Admin → Views → New View
- Name: "Top Posts", slug: top-posts
- Source: Posts collection
- Pipeline:
```
[
  { "$match": { "published": true } },
  { "$sort": { "publishedAt": -1 } },
  { "$limit": 5 }
]
```
- Display mode: table
- Click Save, then Preview to see results.

Embed the View in a page:

## Featured Posts

[view slug="top-posts"]

Create an Action (New User Welcome Email):
- Admin → Actions → New Action
- Name: "Welcome Email", slug: welcome-email
- Add step: Email
- To: {{input.email}}
- Subject: Welcome to {{site.title}}!
- Body:
```
Hi {{input.name}},

Welcome aboard! Visit our site at {{site.url}}

Cheers,
{{site.title}} Team
```
- Click Save
Test the Action:
- In Action Editor → Test tab
- Input:
```
{ "email": "test@example.com", "name": "Test User" }
```
- Click Run — check your inbox for the test email.

What you learned

Setting up Pro mode with a MongoDB connection, building Views using MongoDB aggregation pipelines, embedding views via the [view] shortcode, and creating Actions to automate multi-step workflows such as sending welcome emails.