What a custom backoffice in Sulu CMS actually is

A custom backoffice in Sulu CMS is the admin panel you build to let your team manage website content, users, and settings without touching code. Sulu comes with a default backoffice, but you can reshape it to match exactly how your organization works — hiding features you don't need, adding fields for your specific content types, and controlling who sees what.

The backoffice is where your editors log in to create pages, upload images, manage menus, and handle user accounts. A custom one means you've configured Sulu's built-in tools to fit your workflow instead of forcing your workflow to fit Sulu's defaults. You're not building a backoffice from scratch; you're configuring the one Sulu provides.

Key Takeaways

  • Sulu's backoffice is configured through YAML files in your project, not through a visual builder — you write configuration, not code.
  • You define content types (called "document types") by creating YAML files that specify which fields editors see and what kind of data each field holds.
  • Permissions are set per user role, so you can let some editors publish content while others can only draft it.
  • The backoffice reads your configuration when you start the server, so changes take effect after you restart and clear the cache.
  • Custom fields and sections are added through Sulu's built-in field types — text, rich editor, image, dropdown, date — not by writing custom code.

Setting up your first document type

A document type is a template that defines what fields an editor sees when they create a new piece of content. If you're building a blog, you'd create a document type called "Blog Post" with fields for title, body text, featured image, and publish date. Sulu ships with a basic page type, but you'll add your own.

Document types live in config/templates/pages/ as YAML files. Create a new file called blog-post.xml (Sulu uses XML for document type definitions, despite the YAML configuration elsewhere). Inside, you define each field with a name, type, and label that editors will see. A minimal blog post type looks like this: a title field (type string), a body field (type text_editor), and a featured image field (type media_selection). Each field gets a unique key that Sulu uses internally.

After you create the file, restart your development server and clear Sulu's cache by running the cache clear command. The new document type appears in the backoffice under "Create" — editors can now make blog posts with exactly the fields you defined, nothing more.

Configuring fields and validation rules

Each field in your document type can have rules attached. A title field might be required and limited to 100 characters. A body field might require at least 50 words. An email field should validate that the input looks like an email. Sulu handles all this through field configuration — you don't write validation code.

In your document type XML, you add attributes to each field: required="true" makes a field mandatory, minLength and maxLength set character limits, and type determines what kind of data it holds. A dropdown field gets a list of options defined right in the configuration. A date field automatically shows a calendar picker in the backoffice.

When an editor tries to save content that breaks a rule — leaving a required field blank, or entering text that's too long — Sulu shows an error message and prevents the save. This happens in the backoffice itself, so editors catch mistakes before content goes live. You can also set default values, so a "status" field might default to "draft" instead of making editors choose every time.

Managing user roles and permissions

Permissions in Sulu's backoffice are role-based. You create roles like "Editor", "Reviewer", and "Publisher", then assign permissions to each role. An Editor might be able to create and edit pages but not publish them. A Publisher can publish. An Admin can do everything. Users get assigned to roles, and their backoffice access is determined by what their role allows.

Roles are configured in the backoffice itself under Settings > Roles. For each role, you toggle permissions for actions like "Create", "Edit", "Delete", and "Publish" across different content types. You can also restrict a role to specific sections of your site — a regional editor might only manage pages under /north-america/ while another editor manages /europe/.

When a user logs in, they see only the content types and actions their role permits. If an Editor isn't allowed to delete pages, the delete button doesn't appear. This keeps the backoffice clean and prevents accidental damage — people can't delete what they can't see the option to delete.

Adding custom sections and organizing the sidebar

The backoffice sidebar shows sections like "Pages", "Media", "Settings", and "Users". You can add custom sections to organize your content types logically. If you have blog posts, news articles, and testimonials, you might create a "Content" section that groups all three instead of listing them separately.

Sections are defined in your Sulu configuration file (usually config/packages/sulu_admin.yaml. You give each section a name, an icon, and list which content types belong to it. The backoffice reads this configuration and reorganizes the sidebar accordingly. You can also reorder sections so the most-used ones appear at the top.

Custom sections make the backoffice feel built for your team's workflow. A news organization might have sections for "Stories", "Multimedia", "Editorial", and "Scheduling" instead of a generic list. Editors find what they need faster because the backoffice is organized the way they think about their work.

Setting up workflows and publishing states

Sulu supports publishing workflows where content moves through states: draft, review, scheduled, published. You configure which states exist and who can move content between them. A basic workflow might be: Editor creates a draft, Reviewer approves it, Publisher makes it live. A more complex one might include a scheduled state where content waits to publish at a specific date and time.

Workflows are set in your configuration and tied to roles. An Editor role might only move content to "Review". A Reviewer role moves it to "Approved". A Publisher role moves it to "Published". When an editor opens a page in the backoffice, they see buttons only for the states their role allows them to move to.

You can also set up automatic publishing — a page scheduled for 9 AM on Monday publishes automatically at that time without anyone clicking a button. This is useful for news sites, promotional campaigns, or any content with a planned release date. Sulu handles the scheduling in the background.

Testing your backoffice configuration

After you've created document types, set permissions, and organized sections, restart your development server and log into the backoffice as a test user. Create a piece of content using your new document type. Check that all the fields appear, validation works as expected, and the content saves correctly.

Test as different user roles. Log out, log in as an Editor, and verify they can't see the Publish button. Log in as a Publisher and confirm they can. Try to create content in a section a role shouldn't access — it should be hidden. These tests catch configuration mistakes before your team starts using the backoffice.

If something isn't working, check your YAML and XML syntax first — a missing colon or misaligned indentation breaks configuration silently. Clear the cache again and restart the server. Sulu logs errors to the console when it starts, so watch for messages about missing files or invalid configuration.

Frequently Asked Questions

Can I add fields that aren't in Sulu's built-in types?

Sulu's built-in field types cover most needs: text, rich text, image, video, dropdown, checkbox, date, time, and more. If you need something truly custom — like a field that calculates a value or connects to an external API — you can write a custom field type in PHP. For most backoffices, the built-in types are enough.

What happens if I change a document type after content already exists?

Existing content keeps its old data. If you add a new required field, old pages won't have a value for it — you'll need to edit them and fill it in, or set a default value for new edits. If you remove a field, the data isn't deleted from the database, just hidden from the editor interface. Changes to field types (like changing a text field to a dropdown) can cause problems, so test on a copy of your site first.

How do I let editors preview content before publishing?

Sulu includes a preview feature built into the backoffice. When an editor is working on a page, they click "Preview" to see how it looks on the live site without publishing it. The preview uses your site's actual templates and styling, so what they see is what visitors will see. You don't need to configure anything — it's on by default.

Can I restrict editors to only certain document types?

Yes, through role permissions. When you set up a role, you choose which document types that role can create, edit, and delete. An Editor role might only access Blog Post and News Article types, while a Publisher role can access everything. This keeps editors focused on their content and prevents accidental changes to other types.

Do I need to write code to build a custom backoffice?

For most customization, no — you write YAML and XML configuration. If you need custom field types, validation logic, or backoffice features that Sulu doesn't provide, you'll write PHP code. But the core backoffice — document types, permissions, sections, and workflows — is all configuration, not coding.