Skip to content

CrossModel User Interface

Watch it first

The CrossModel user interface walks through the welcome page, the workbench, the editors and the panels around them in a minute and a half.

Understanding the main components of the CrossModel User Interface

When you open a CrossModel workspace you are greeted by the welcome page, described in full below:

The CrossModel welcome page open in the editor, with the Model Explorer beside it

Close it, or open a model from the Model Explorer, and you are looking at the workbench itself:

The CrossModel workbench with a system diagram in the editor and the Properties panel showing the selected node

The workbench has five regions:

  • The toolbar - under the menu bar, the actions you reach for all day: save, undo, the assistant, and the name/id switch. See below.
  • The left bar - switches the left panel between the Explorer, Search and Source Control.
  • The left panel - navigate your workspace. This is where the Model Explorer lives.
  • The editor - the centre area, showing the selected model item: a form, a diagram, or the code view.
  • The right bar and panel - the Properties view, CrossGenerate, the AI Chat and the Outline.

The welcome page

The welcome page is more than a splash screen - it is the fastest way into a working workspace. It is the screenshot at the top of this page, and each of its sections offers something different:

Section What it offers
Start / Recent Open a workspace, or return to one you used recently
Tutorials & Examples Clone a ready-made workspace straight from the CrossModel examples repository
Clone Repository Clone any Git repository by URL - see Git Provider Authentication
Help Links to this knowledge base and the CrossModel website
Settings Open the settings editor or the keyboard shortcuts editor

Tutorials & Examples is worth knowing about before you start the tutorials. Pick a topic from the cascading dropdowns and press Clone, and CrossModel fetches a prepared workspace for you:

  • BrightGreen is the base data model on its own, and is the starting point for the tutorials that build from scratch.
  • tutorials gives you the starting point for a tutorial that continues from an earlier one - it contains the previous tutorial's result, without the answers to this one.
  • examples gives you the finished result, useful as a reference or to see what is possible without doing the work first.

What happens after you press Clone

CrossModel asks you two questions before the models appear. Both matter:

  1. Choose a folder to clone into. The picker opens one level above your workspace, so the folder it offers by default is next to your workspace rather than inside it. Select your workspace folder, then press Select as Repository Destination. Cloning anywhere else leaves the files outside the workspace, where the Model Explorer will not find them.
  2. "Would you like to open the cloned repository, or add it to the current workspace?" Press Close. Because you cloned into your workspace folder, the repository is already part of the workspace and there is nothing to open or add. The other options move you to a different workspace root, which is not what the tutorials assume.

The models then appear in the Model Explorer under crossmodel-examples.

Each dropdown is one level deeper: the choices come from the branch names in the public crossmodel-examples repository, where every / in a branch name starts a new dropdown. Choosing tutorials → mapping → with-multiple-sources clones the branch tutorials/mapping/with-multiple-sources.

All of these branches build on BrightGreen, the shared base data model used throughout the tutorials, so every workspace you clone drops you into the same familiar landscape with only the material for that topic added. The tutorials index lists which workspace belongs to which tutorial.

You can reopen the welcome page at any time from Help → Welcome, and turn off the startup behaviour with the Show welcome page on startup checkbox at the bottom.

Reopening a session is not the same as restarting the workspace (as of v1.12.0)

Reload the browser tab of a session that is still running and the workbench comes back exactly as you left it: the same editors open, and the same one in front. Stop the workspace and Start it again and it does not. You get the welcome page and nothing else. The open editors belong to the running session rather than to the workspace, so a screenshot of a workbench with several tabs open is someone mid-session, not what a freshly started workspace looks like.

The toolbar

Since v1.22.0 a toolbar runs under the menu bar, with the actions you would otherwise reach through a menu or a shortcut:

The toolbar under the menu bar

Group Actions
Left Save, Save All, Undo, Redo
Centre CrossModel Assistant, Properties, Toggle Name/Id Display
Right Close All Tabs in Main Area, Split Editor Right, Reset Workbench Layout

Undo and Redo work on the editor you are working in, a form included, so a change made in a form can be taken back from here as well as with Ctrl+Z. Split Editor Right opens a second copy of the editor beside the first, each with its own tab, which is how you look at an entity's form and its code, or two parts of one diagram, at the same time. Reset Workbench Layout puts every panel back where a new workspace has it; reach for it when a panel has gone missing.

Above the toolbar, in the title bar, a search box opens the command palette, the same as Ctrl+Shift+P, and the name of the workspace you are in sits on the right.

The left bar

View Shortcut What it does
Explorer Ctrl+Shift+E Navigate your workspace - contains the Model Explorer and the File Explorer
Search Ctrl+Shift+F Search for files by name or content across the whole workspace
Source Control Ctrl+Shift+G Record and share your changes through Git - see Version Control with Git

At the bottom of the left bar, the gear icon opens the Manage menu, which is the route to settings, keyboard shortcuts and themes.

The Explorer contains two trees

The Explorer is not a single tree. It holds several collapsible sections:

  • Open Editors - everything you currently have open.
  • Model Explorer - your workspace as model objects, labelled by name, with entities expanding into their attributes and identifiers. This is the view you will use most.
  • File Explorer - every file and folder in the workspace, including the ones that are not models: code generation templates, generated scripts, README.md, .gitignore. The Model Explorer never shows these.
  • Timeline - the history of the selected file: every commit that changed it.

Because the two trees answer different questions, it is worth reading The Model Explorer to see when to reach for each.

The right bar

View Shortcut What it does
Properties Alt+Shift+P Shows and edits details of whatever is selected - an entity in a diagram, an attribute mapping, a source object
CrossGenerate - The code generation panel: pick a model object, write a template, preview and generate
AI Chat Ctrl+Alt+I The AI modeling assistant
Outline Ctrl+Shift+I The structure of the editor in front: a diagram's elements, a form's sections and rows, a file's blocks - see below

Other views

Not every view is pinned to a bar. Open any of them from the View menu:

View Shortcut
Problems - warnings and errors when a model is in an invalid state Ctrl+Shift+M
Extensions - install and manage extensions from Open VSX Ctrl+Shift+X
Output Ctrl+Shift+U
Model Explorer, AI Configuration, AI Agent History -

The View menu

Finding your way around a large diagram

A diagram with forty entities on it is quicker to search than to scan. Since v1.16.0 there are two ways to do that, and they answer different questions: the search palette when you know what you are looking for, the Outline when you want to see what is there.

Search: jump straight to one element

Press Ctrl+F with a diagram in front of you, or use the magnifier in the diagram toolbox. A box opens over the canvas listing every node and edge on the diagram. Type part of a name to narrow it, and pick an entry: CrossModel selects that element and centres the canvas on it, so you do not have to find it by eye first.

Searching a diagram for Customer

Entries read name (id) - Customer (CustomerNode) - because the name is what you recognise and the id is what the diagram file records. Relationships and inheritance links are listed too, not only entities. On a mapping diagram the attribute mappings are listed as CustomerSource.CustomerID style endpoints, qualified with the source object they belong to, so two attributes with the same name on different sources do not read as the same thing.

Outline: see the whole diagram as a list

The Outline view (Ctrl+Shift+I, or the Outline icon in the right bar, where it is docked since v1.25.0) lists everything on the diagram, grouped the way the model itself is structured. Clicking an entry selects it on the canvas.

The Outline view of a system diagram

The groups follow the diagram type:

Diagram Groups
Logical diagram Entity Nodes, Relationship Edges, Inheritance Edges, Notes
Conceptual diagram Entity Nodes, Relationship Edges, Notes
Mapping diagram Sources, Target, Attribute Mappings

A group only appears when the diagram has something in it, so a diagram without notes or inheritance links simply has fewer groups.

The Outline view of a mapping

A mapping's outline is the quickest way to read what the mapping actually does: the Attribute Mappings group lists every source-to-target pair in one column.

Outline in the code editor

The same view works on the Code Editor tab. There it shows the structure of the file itself rather than the drawing: each collection under the keyword that introduces it in the file (nodes, entityNodes, attributes, mappings), and each entry under it by its id. Clicking an entry jumps to that block in the code, which is the quickest way around a long entity or mapping file. This arrived in v1.18.1; before that the code tab had no outline worth using.

The Outline view next to a diagram's code

The headings use the keyword exactly as the file spells it. A diagram last saved before v1.18.0 says diagram: and entityNodes; CrossModel still reads those, and the outline shows them as written. The first time you save such a diagram, CrossModel rewrites the keywords to the current logicalDiagram: and logicalEntityNodes, so expect those lines in your next Git diff. The file keeps its .diagram.cm name.

Outline in the form editor

Since v1.25.0 the Form Editor tab has an outline too. It follows the form: one entry per section, the fields inside it, and every row of a grid, so an entity's outline lists its attributes and identifiers by name, and a diagram's form lists its nodes and edges. Click a section in the outline and the form opens it if it is closed and scrolls straight to it.

The Outline view beside an entity form: General, Attributes with every attribute, Identifiers, Style

On a long entity this is the quickest way to an attribute halfway down the grid, and it shows at a glance which sections hold anything at all.

Fold the toolbox away when it is in the way

The diagram toolbox sits over the top right of the canvas and stays open until you close it. Its leftmost control minimises it to a single icon, which is worth doing whenever you are reading a diagram rather than drawing on it - and before you take a screenshot of one.

VS Code compatibility and extensions

The CrossModel workbench is VS Code compatible. The keyboard shortcuts, the command palette (Ctrl+Shift+P), the editor behaviour and the settings model are the ones you already know, so if you work in VS Code you will find your way around immediately.

That compatibility is not only skin deep: CrossModel can run VS Code extensions, installed from the Open VSX registry. Open the Extensions view with Ctrl+Shift+X or from View → Extensions, search for what you need and press Install. The extension applies to the session you are working in.

This is worth knowing because the editors you use around your models are ordinary editors. A PDF viewer, for example, turns documentation that a colleague dropped in the workspace from raw text into a readable document - useful when you are handing that documentation to the AI modeling assistant. The same goes for syntax highlighting of the template languages you write for code generation.

Settings

Open settings from Welcome → Open Settings, from the gear in the left bar, or with the command palette (Ctrl+Shift+P). Settings have two scopes, shown as tabs:

  • User - applies to you, across every workspace.
  • Workspace - applies to this workspace only, and is stored in a .crossmodel folder inside it. Because that folder lives in the workspace, workspace settings are versioned in Git alongside your models and are shared with your team.

Search for cross-model to find the CrossModel-specific settings:

The CrossModel settings

Setting Default What it controls
Display: Labels name Whether model elements are labelled by their human-readable name or their technical id
Editor: Update Delay Ms 500 How long after you stop typing before validation, diagrams and completions refresh
Log: Server: Level info How much the CrossModel language server writes to the output channel
Trace: Server off Traces communication with the language server - for diagnosing problems

Choosing between names and ids

Every model object has two labels: a name you choose for people to read, and an id that is unique and stable for machines. Postal Code and PostalCode are the same attribute - the first is its name, the second its id.

By default CrossModel shows names everywhere: in the Model Explorer, in form fields, in grid cells, and on diagram nodes. Toggle Name/Id Display in the toolbar switches between the two in one click, which is the quick way; the setting below is the same switch. Switch to ids when you want to see the technical identifiers instead - useful when you are writing code generation templates or expressions, which refer to objects by id rather than by name.

The setting changes only what is displayed. It never changes the model itself, so it is safe to flip back and forth while you work.

The editor delay is worth tuning on large workspaces

Editor: Update Delay Ms trades responsiveness against effort. Lower it towards 0 for immediate feedback on a small model; raise it on a large workspace where constant revalidation feels heavy.