Documentation Hub

Appearance

Web Services: Studio ​

Dialogue Branch Studio is a Vue 3 / Vite / Tailwind CSS single-page application bundled in the monorepo, in the apps/studio folder. It serves both as a reference client implementation and as a practical authoring and testing tool for a Dialogue Branch Web Service deployment.

Unlike a 3rd party client application, Studio never authenticates with Keycloak itself and never holds an OAuth2 access token in the browser — it delegates authentication entirely to the BFF. See Studio Authentication (via the BFF) for the full flow.

Running Studio ​

bash
cd apps/studio
npm install
npm run dev      # dev server with hot-reload
npm run build    # production build
npm run preview  # preview production build locally

The dev server proxies /api, /oauth2, /login, /logout, /whoami, and /actuator to the BFF, so during local development the BFF (see BFF Service) needs to be running alongside it.

Local development setups ​

The repository's top-level infrastructure/docker/compose.yml supports three local setups, matching what a given change actually needs:

  1. Web service only — run docker compose up -d (supporting services only: MariaDB, phpMyAdmin, Keycloak) and run the Web Service separately, e.g. ./gradlew bootRun in apps/api.
  2. Studio development — run docker compose --profile api up -d (also builds and starts the Web Service and the BFF), then run Studio itself separately with npm run dev as shown above. Its dev-server proxy sends /api, /oauth2, /login, /logout, /whoami, and /actuator to the Dockerized BFF on http://localhost:8082, so the browser only ever talks to Vite's own origin — same-origin without needing a real reverse proxy.
  3. Everything in Docker — run docker compose --profile studio up -d. Studio and the BFF both run as containers here too, fronted by an nginx service on http://localhost:8080 that path-splits requests between them (studio.conf), mirroring how a real deployment's reverse proxy makes them same-origin. Vite's dev-server proxy isn't available in this setup (nothing is running npm run dev), so this nginx service is what takes its place. Useful for testing the full containerized topology before deploying, without needing a real deployment to do it. If you already had a local Keycloak volume from before this third profile was added, keycloak-sync adds this profile's http://localhost:8080/... redirect/post-logout URIs to the existing dlb-bff client automatically on the next docker compose up — no volume reset or manual admin-console edit needed.

Features ​

  • Dialogue rendering — Once logged in, Studio lets you select a Dialogue Branch Project and start executing one of its dialogues, rendered either as chat "balloons" or as plain text, switchable via a mode selector.
  • Visual dialogue editor — A node-graph editor (built on Vue Flow) for authoring dialogues: reply links between nodes become edges in the graph, and nodes can be dragged, edited (title, speaker, colour, body text), renamed, and connected. Edits operate on a project's draft content (see Authoring API) — nothing changes for end-users executing the published dialogue until it is explicitly published.
  • Script comment — In the graph editor, a dialogue's script comment (its preamble) is shown at the top left of the graph, where it can be hidden behind a comment icon and shown again. The pen button opens it as plain text, without the // of each line; Add script comment starts one for a dialogue that has none. Empty lines between paragraphs are kept.
  • Testing in Authoring Mode — In Authoring Mode, opening a dialogue test-runs its current draft. Tests run against test variables: a copy of your stored variables (or, while acting as another user, theirs), shared by all of your tabs in the project, so a test never changes the stored values. The Variable Browser shows and edits that copy in Authoring Mode, as Test values (marked with a flask), with a reset button in its toolbar to start over. Live Mode shows and changes the stored values. A test left alone for a while (30 minutes by default) expires; its tab then says so, with a button to start it again. When the project has translations, Test in [language] as [any user / a female user / a male user] sets the user's gender in the test values ($dlb.userGender), so you can check gender-specific translations; a running test follows from its next step.
  • Simulating a user — An admin can run dialogues for another user without changing any of their data: Set Delegate User in the user menu, pick the user, and choose Simulate as. Dialogues then run as test sessions against a copy of that user's variables: their published content in Live Mode, their draft content in Authoring Mode. The user's real ongoing dialogue isn't offered to resume. The mode bar under the header says so while simulating, with Stop simulating; the Variable Browser's Values shows and edits the copy, and History shows the user's real history. Act as instead acts on the user's behalf for real: Studio first warns what that changes, and turns the mode bar red while acting, with Stop acting as. Set Delegate User is shown to admins only. Opening a project, or switching between Live and Authoring Mode, stops simulating or acting as someone.
  • Translating a dialogue — In Authoring Mode, the translation mode of a dialogue's tab shows each of its translatable texts, grouped by speaker, with an editable column for one or two of the project's translation languages; each change is saved as you leave the field. A translation stored with a source text that differs only in whitespace (for example a line break in a file written elsewhere) shows in its row too, and a gender-specific translation (in a nested context group such as female_addressee, see Translation Files) shows as a sub-row under its text; both can be edited there. When a language's translation holds entries that match no text of the dialogue (by speaker and text), for example because the text changed after it was translated, a Stale entries button shows how many; it lists them per language, and lets you delete one, or all of a language's, after confirming. Stale entries are never used, and are kept until you delete them. Each speaker's group shows the speaker's gender from the project (♀ or ♂; hover over it to read it). For languages where a text changes with the user's gender, the ⚥ button next to a text adds a Female user and a Male user translation below it; the translation above them is used for any other user. The × on such a row removes it, in every language. A gender variant that can never be used, such as a female_speaker one under a male speaker, is marked with a ⚠ that says why.
  • Dialogue Browser actions — Each dialogue in the Dialogue Browser has a ▶ button to open it. In Authoring Mode its other actions (Open, Rename…, Export as .dlb, Discard changes…, Delete…) are in a menu, opened by right-clicking the dialogue or with the ⋯ button that appears when you point at it (on touch screens it is always shown); the menu works with the keyboard as well (arrow keys, Enter, Escape). A dialogue pending deletion shows only its Restore button.
  • Deleting a dialogue — Delete… in a dialogue's menu marks it for deletion, after confirming (the confirmation says how many replies in other dialogues link to it, since those links break). It can be restored until the project is published next, which removes it for good; until then its published version stays live. Its open tabs close.
  • Discarding changes — In Authoring Mode, a dialogue marked Changed in the Dialogue Browser has Discard changes… in its menu: after confirming, its draft becomes identical to its published version again (nodes and their layout, script comment, translations, and its published name if it was renamed), and open tabs of it reload. Links in other dialogues that were updated for a rename of the dialogue or its nodes no longer match afterwards; publishing reports them. Discard All Draft Changes… in the Project menu (for admins, once the project has been published) does this for the whole project: every dialogue goes back to its published version, new dialogues are removed, and the project's name, description and translation languages go back to the published ones; open tabs are closed.
  • Project speakers — In Authoring Mode, the Speakers tab of Configure Project lists the project's speakers: add one with a name and a gender (undefined, female or male), change a gender, rename or remove one, or make one the default (choosing the default again leaves the project without one). Like the rest of the project's configuration, the speakers are saved as a draft and published with the project (see Speakers). Renaming a speaker renames it in the project's nodes and translations too: the row shows the old name until you save, and Save Draft first says how many nodes, dialogues and translations change, and asks to confirm. When a project has speakers, the node editor chooses a node's speaker from them, and a new node gets the default speaker (or the first one); a node whose speaker isn't one of them keeps it, with a warning in the graph and in the node editor. Every node but End needs a speaker. Removing a speaker doesn't change the nodes that use it.
  • Publishing — Publish Project in the Project menu first checks every dialogue. Errors must be fixed before publishing; warnings, such as a node that no reply link points to, or a node whose speaker isn't one of the project's speakers, are listed but don't stop it.
  • Importing scripts — In Authoring Mode, Import Scripts in the Project menu imports one or more .dlb files into a folder of the project as draft dialogues, named after the folder and each file name. It shows which dialogues already exist (including ones pending deletion) and only replaces those when you choose to; the import is all or nothing, and scripts with syntax errors are imported but listed with their errors, to fix before publishing.
  • Importing translations — In Authoring Mode, Import Translations in the Project menu imports one or more translation files (.json) into one of the project's translation languages. Each file becomes the translation of the existing dialogue named after the chosen folder and the file name (welcome.json into folder intro translates intro/welcome); a file without such a dialogue can't be imported. It shows which dialogues already have a translation in that language and only replaces those when you choose to, as a whole (not merged). The import is all or nothing. Afterwards it lists, per file, how many entries match no current term of the dialogue (an entry matches on its speaker and text; those entries are kept, but not used) and how many terms are still untranslated. To import a language the project doesn't have yet, add it in Configure Project first.
  • Exporting a dialogue — In Authoring Mode, Export as .dlb in a dialogue's menu in the Dialogue Browser downloads its current draft as a .dlb file, named after the dialogue (without its folder). Import it into the same folder to get the same dialogue back. Its translations are not included, and the action isn't offered on a dialogue pending deletion.
  • Project selector — Lists the Dialogue Branch Projects available on the connected Web Service (for users with the editor or admin role), so you can switch between projects without redeploying the client. An admin can delete a project there: that removes its dialogues (draft and published), translations and version history, but keeps its users' data (their variables and dialogue logs) unless you also tick the options to delete that; the project's name is free for a new project right away. Deleted projects whose users' data was kept are listed for admins in a separate, collapsed Deleted projects section, with when they were deleted and how much users' data they still have; Delete permanently… there removes that data and the project for good, after typing the project's slug to confirm.
  • Users — For admins, the Users button on the project selector opens a page, outside any project, listing everyone the Web Service has seen in your realm: their username (or only their subject, for someone only ever seen as a delegate), and how many variables and dialogue logs it holds for them in all projects. Search by username or subject. Erase data… erases everything the Web Service stores about a user — their variables, variable history and dialogue logs in every project, and the user itself — after typing their username (or subject) to confirm; it can't be undone.

Note

If you found errors or have questions about this page, please consider reporting an issue at https://github.com/dialoguebranch/platform or sending an email to info@dialoguebranch.com.