sutram docs
All pages

Drupal

drupal/sutram ships the Sutram library and opens the console for users with the Use Sutram permission. It registers no Drupal commands of its own; other modules do that, and its demo submodules show how.

composer require drupal/sutram
drush en sutram

Give the Use Sutram permission to the roles that should have it. Then, on any page, press ` (the key left of 1), or Ctrl+` inside a text field, and type help. The library is shipped in the module (lib/sutram); nothing is loaded from a CDN.

Demo submodules

They are demos, not a stable API: try them, or copy them as a starting point.

  • sutram_demo_nav: nav status, nav menu, nav search and nav go over the menus you choose. Each user sees only the links they may open. The commands come from the nav kit (the library sutram/nav); the submodule is only its adapter.
  • sutram_demo_page: page status, the page's title, route and entity, from the page kit (sutram/page).
  • sutram_demo_user: user status, user login and user logout, from the user kit (sutram/user). user login opens Drupal's login page; the person types the password. The submodule also emits user.changed when the page comes back as someone else.
  • sutram_demo_messages: Drupal's status messages, after a page load or an AJAX request, as messages status and message.shown events, from the messages kit (sutram/messages).
  • sutram_demo_lists: Views listings on the page, such as the content overview, as listing status, listing rows and listing go, from the lists kit (sutram/lists): rows, pages, table sorts and exposed filters.
  • sutram_demo_form: fill in and submit content forms, an adapter for the forms kit (sutram/forms). See below.
  • sutram_demo_canvas: build pages in the Drupal Canvas editor. See below.

Forms

The form commands follow the forms guide. They are registered once and look the form up when they run, so a form that arrives by AJAX (in a dialog, say) works too, and a form that has gone answers "not on this page". Fields are dotted paths such as title or body.value. set writes into the real inputs (and CKEditor), so the form on screen and the commands agree. submit clicks the real Save button: Drupal validates, checks access and runs its hooks as usual, and errors come back in form status <form>, by field.

form fields node-article-form
form set node-article-form title "Pour-over, step by step"
form set node-article-form field_tags "coffee, v60"
form set node-article-form status false
form submit node-article-form

Canvas

In the Canvas editor, the canvas commands add, change, move and remove components, and set the page's title, URL alias and description. They go through Canvas itself, so every change shows in the preview, can be undone and saves as a draft.

canvas components
canvas page set title "Our coffee"
canvas add heading --as=top
canvas set top text "Fresh every week"
canvas add card --after=top --as=intro
canvas set intro title "Single origin"

Pasted together, these lines run as one batch: if one fails, Canvas's undo takes back the others. --as names a new component so later lines can refer to it. canvas tree shows the page, canvas undo takes back the last change.

canvas publish is off by default. A site builder turns it on at Configuration › Development › Sutram Demo Canvas, and it is offered only to users who may publish in Canvas. It asks every time.

Add commands from your module

Define a library that depends on sutram/sutram, attach it where the commands make sense, and register them:

# mymodule.libraries.yml
commands:
  js:
    js/mymodule.sutram.js: { attributes: { type: module }, preprocess: false }
  dependencies:
    - sutram/sutram
// js/mymodule.sutram.js
globalThis.Sutram.register({
  name: "cache clear",
  provider: "cache",
  description: "Clear all caches",
  input: { type: "object", properties: {} },
  annotations: { consequential: true },
  run: async () => { /* call one of your module's own routes */ },
});

Pass what the commands need from PHP in drupalSettings, as the demo form module does. Commands run in the browser with the user's session, so they can do only what the user can already do. Check access on the server, in the routes your commands call, as you would for a button.

Try it

The demo site installs Drupal with the module, its submodules and Canvas in DDEV, with an empty Canvas page to build from the console.

This page as MarkdownEdit on GitHub

PreviousInstall