Help Center Claude MCP server MCP tool reference References

System overview Using the editor The Exotool language HTML templates The diagram The element catalogue

Using the Exotool Editor

This is a practical guide to building apps in the Exotool visual editor: how the canvas is organized, how you add and connect the pieces of your app, and the habits that keep a growing design clear and correct.

It assumes the picture painted in the System Overview (exotool_docs("overview")) — that you design an app as diagrams and Exotool builds the running PWA for you. For the code you write inside activities, and for dynamic content, see the companion references:

  • System Overview (exotool_docs("overview")) — what Exotool is and how the pieces fit.
  • Exotool Language Reference (exotool_docs("language")) — the activity language.
  • HTML Templates Reference (exotool_docs("templates")) — dynamic content and appearance.

Contents

  1. The editor at a glance
  2. The canvas and sheets
  3. Adding and arranging elements
  4. Where elements can go
  5. Navigation: links and connectors
  6. Symlinks: jump points
  7. Popups and panels
  8. Reusing elements with placeholders
  9. Adding behavior
  10. The app icon, background, and media
  11. Building and previewing
  12. Best practices

1. The editor at a glance

The editor is a web page — there is nothing to install to start designing. You work on a large canvas where each screen of your app appears as a box, and you assemble your app by placing elements, setting their properties, and drawing connections between them.

Three things you will use constantly:

  • The canvas — where your screens and their contents are laid out.
  • A palette of elements — the building blocks you add to the canvas (pages, content, lists, links, forms, and so on).
  • A property panel — where you fill in the settings of whatever element is selected (its title, what data it shows, its appearance, and any behavior).

You design, build, and try the app, then adjust and build again. The design is the source of truth; the running app is generated from it.

Starting from an existing project or a sample

You don't have to start from a blank canvas. You can copy an existing project into a brand-new one and build from there — an easy way to reuse earlier work or begin from a ready-made example.

  • Copy one of your own projects to get an independent duplicate you can change freely; the original is left untouched.
  • Start from a sample. Exotool includes ready-made example apps (grouped under SYSTEM : Samples). A sample is shared and read-only — you can open and look at it, but not change it directly. To build on one, copy it into a project of your own and edit the copy. This is a great way to see how something is put together or to get a running head start.

A copy is a full, independent duplicate — its screens, content, uploaded images and files, and settings all come across, and later changes to the copy never affect the original.

2. The canvas and sheets

A small app fits comfortably on one canvas. As an app grows, a single canvas can become crowded and hard to read, so the editor lets you spread a design across several sheets.

  • A sheet is one page of the canvas. You see one sheet at a time and switch between them.
  • Moving a screen to another sheet is mainly an organizing convenience and does not change how it is reached. (Activities are the exception — see the note on scope below.)
  • Each sheet has its own space, so screens on different sheets never visually collide.

Use sheets to group related screens — for example, keep the main flow on the first sheet and move a cluster of settings or admin screens to a second. When a connection needs to cross from one sheet to another, you make it with a symlink (see §6), because a connection line can only be drawn within the sheet you are looking at.

Sheets and behavior scope. A sheet is not only a layout aid — it also bounds the scope of a call between activities. When one activity calls another, the called activity's sheet (together with any sub-views grouping it) defines that call's scope. So grouping related activities onto a sheet makes them a self-contained, callable unit. See Adding behavior.

3. Adding and arranging elements

To build a screen, you add elements to the canvas and arrange them:

  1. Add an element from the palette — for example a Page to create a new screen, then content such as a Content Block or a List inside it.
  2. Set its properties in the property panel — a title, the data it shows, its styling, and so on.
  3. Position it so the layout reads clearly (see Best practices for spacing).

Elements nest: a screen contains its bars and body content, a navigation bar contains links, a list contains its items. The visual nesting on the canvas is the structure of the screen.

The palette is rich. Beyond pages and content blocks you have, among others: forms (with text, e-mail, dropdown, toggle, slider and other inputs, plus ready-made login and credit-card forms); lists — both data-driven lists that repeat one item layout over your data and a collapsible accordion list; images and image sliders/carousels (a fixed set of images, or a data-driven one); and floating action buttons, speed dials and popovers. You configure each through its properties, and for data-driven elements you point them at the data to display.

4. Where elements can go

Not every element can go directly inside every other. The most important rule to remember:

A link is not placed directly on a page, panel, or popup. Links live inside a container that holds links — a navigation bar, a toolbar, or a link menu. To put a tappable link in the body of a screen, add a link menu and place the link inside it.

More generally, the direct contents of a screen are its body and bar containers (navigation bar, toolbar, content blocks, lists, forms, link menus), not loose individual controls. If a link or similar control does not appear to do anything in the running app, the usual cause is that it was placed directly on a screen instead of inside a container. The editor will not stop you from doing this, so it is worth checking.

Navigation is how the user moves between screens, and you express it in two parts:

  1. A link — the thing the user taps. It lives in a navigation bar, toolbar, or link menu (see §4).
  2. A connector — a line you draw from that link to the screen it should open.

The link is the source of the connector; the target screen (a page, popup, or panel) is the destination. A back link is a special link that returns the user to the previous screen, so it needs no connector of its own.

Draw connectors deliberately and route them so the lines do not cut across screen boxes — a tidy set of connections is much easier to follow later.

A symlink is a small labeled jump point you place on the canvas — it appears as a round badge with a label (for example, "A"). Symlinks always work in matched pairs that share the same label: a connection runs into one badge and out of its twin somewhere else, so the pair behaves as a single jump.

Symlinks solve two problems:

  • Long or messy connections. Instead of dragging one connector all the way across a busy canvas, drop a labeled badge near the source and another with the same label near the destination. The connection reads as "source → Ⓐ … Ⓐ → destination".
  • Connections that cross sheets. Because you can only draw a connection within the sheet you are viewing, a symlink pair is how you link a source on one sheet to a destination on another: place one badge on each sheet and give them the same label.

Both ends of the pair must be connected. One badge needs something pointing into it and its twin needs a connection leading out to the real destination. A lone badge — one with nothing arriving, or nothing leaving — represents no jump at all and silently does nothing.

7. Popups and panels

Besides ordinary pages, two kinds of screen appear over or beside the current one:

  • A popup is content that opens on top of the current screen — a dialog, a detail view, a confirmation. It typically has its own small navigation bar with a close link.
  • A panel is a drawer that slides in from the left or right edge — a common place for a menu or settings. You choose which side it comes from and how it appears over the screen.

You navigate to a popup or panel the same way as to a page: a link wired by a connector (or reached through a symlink).

8. Reusing elements with placeholders

Often the same thing should appear in more than one place — a navigation bar shared by several pages, or a block of content shown on two different screens. Rather than rebuild it each time, Exotool lets you define an element once and reuse it through placeholders.

A placeholder is a slot. You do not create placeholders yourself; the editor manages them for you:

  • Empty slots appear automatically. When you add a screen, its bar, body, and toolbar positions show up as empty placeholders — dotted-outline boxes waiting to be filled.
  • Fill a slot by dragging an element onto its placeholder; the element takes that position.
  • Make something reusable by dragging a sub-element out — for example, drag a navigation bar out of its page onto the open canvas. The element now stands on its own, and Exotool leaves a placeholder behind in the original spot, linked to it. Drop placeholders on other screens and link them to that same element, and it appears on every one of them — change it once, and every place updates.

The reused element can live wherever you like — out on the canvas on its own, or inside one of the screens that uses it. Either way, the link from a placeholder to the element is what makes the element show up there.

9. Adding behavior

Where your app needs to do something — react to a tap, open a screen, submit a form, save data — you attach an activity and describe what it does in the Exotool language.

You attach behavior either on an element (for example, "do this when the user taps it" or "do this when the screen opens") or as standalone activities connected in sequence. You never have to decide whether logic runs on the device or the server — Exotool works that out for you.

One activity can also call another and resume when it returns. Such a call runs within a scope — the sheet the called activity sits on, together with any sub-views that group it. Because the sheet defines that boundary, putting a set of related activities on their own sheet also makes them a self-contained, callable unit. (See also The canvas and sheets.)

The behavior itself is a separate subject: see the Exotool Language Reference (exotool_docs("language")) for what you can write, and the HTML Templates Reference (exotool_docs("templates")) for dynamic, data-driven content.

Publishing an API endpoint

Sometimes you want part of your app's logic to be callable from outside — by another app, a backend script, or a partner's system. You can publish an activity flow as a named API endpoint using an API call node, which appears on the canvas as a small >> marker.

To create one: drop an API call node, give it a name, connect its output to the activity that does the work, and list the values it should return. When you build, Exotool turns it into a real endpoint that runs on the server (so it is safe for logic and data you would not put on the device). It accepts the inputs your activity expects and returns the values you listed.

You do not have to figure out how to call it: for every endpoint, Exotool writes ready-to-use JavaScript and Python call examples — filled in with that endpoint's actual inputs and outputs — into your app's generated code, so you can copy one straight into a caller. A Python caller looks like this:

import requests, json

endpoint = "https://your-app.example/entrypoint"   # your app's address
args = {                                  # the inputs your activity expects
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
}
response = requests.post(endpoint, data={
    "protocol": "jsonp_dgapp_responder",
    "service": "API_create_beneficiary",  # "API_" + the name you gave the node
    "args": json.dumps(args),
})
result = response.json()                   # the values you listed as returned
print(result)                             # e.g. {"userInfoID": ..., "profileID": ...}

10. The app icon, background, and media

Beyond the screens you design, an app carries media — the icon people tap on their home screen, an optional background image, and the pictures used inside your screens. You add these by uploading images and files into the app, separately from drawing the diagram.

The app icon. This is the picture that represents your app: it appears on the phone home screen when someone adds your app there, on the tab of a desktop browser, and as the app's icon if you publish a native version. You set it from a single image — choose Set App Icon, then drop an image file onto the control. From that one picture, Exotool automatically produces every size the different devices need, so you don't prepare them yourself. Use a clear, roughly square image; a new upload replaces the previous icon. The icon may be a PNG, a JPEG or an SVG. A PNG keeps its transparent parts. An SVG is the best source when the icon is a drawing: it is small, it is sharp at every size, it keeps its transparency, and one that is not square is centred on a transparent square and not stretched.

The app background image. You can give the app a background picture in the same way — upload one image (PNG, JPEG or SVG) and Exotool prepares it for use as the background.

Pictures inside your screens. Images shown in the app — in an image element, a gallery, or a list — are uploaded as image assets and then referred to by an image element on a screen. As with the icon, you provide the picture (PNG, JPEG or SVG) and Exotool prepares the sizes it needs. These sizes are stored as JPEG, which has no transparency: transparent parts come out white. A picture that must stay transparent, and an SVG that must stay an SVG, is uploaded as a file instead, which is stored exactly as it arrives. You can also upload other files an app may rely on (documents, audio, video, and similar).

A few practical notes:

  • Use a high-resolution source when you upload in the editor. Exotool scales an image down to make the sizes it needs, so start from a generously sized original — especially for the icon, which is reused at large sizes on some devices. An SVG has no size of its own and is always sharp.
  • Through an AI assistant it is the other way round. An assistant connected to Exotool sends a file slowly, so it uploads only a small picture itself: a drawn icon or image as SVG text, or a bitmap of about 64 by 64. For a photograph, a video or any large file (up to 8 MB) the assistant gives you a link to Exotool's upload page: it says what the upload is for, you drop the file on it or choose it, and you tell the assistant when it is done. The link works once and must be opened within two minutes. Where a file has a download link of its own (an export from Canva, an image on Unsplash, a Dropbox link ending ?dl=1), the assistant can pass that link to Exotool, which downloads the file itself (up to 8 MB) and keeps its own copy; with an image or design service connected to the assistant, nothing is uploaded by hand. A share link that opens a web page (Google Drive, OneDrive) does not work that way. You can also upload in the editor, by the steps below.
  • An SVG must be self-contained: no DOCTYPE or ENTITY declaration, no script, no reference to another file, and under 1 MB.
  • Square images for the icon. Non-square icons may be cropped on some devices.
  • Re-uploading replaces. Uploading a new icon or background swaps out the old one; rebuild and preview to see the change.

Uploading in the editor, step by step

Every upload starts in the properties panel, the panel of settings that the editor shows for whatever is selected on the canvas, and ends in a small upload window. Drop the file onto that window, or click in it and choose the file; the window closes by itself when the upload has worked, and an error is shown if it has not.

Open the project first: log in to the editor, pick the project from your list of projects, and wait for its diagram to appear.

The app icon

  1. Click an empty part of the canvas, so that the diagram itself is selected and not one of its elements.
  2. In the properties panel, click Set App Icon. A window titled Upload Icon opens.
  3. Drop the image onto the window, or click in it and choose the file.
  4. When the window closes, click Save/Generate, then look at the preview: the icon shows on the browser tab, and on the home screen when the app is added there.

The app background

  1. Select the app, the large box that holds all the screens.
  2. In the properties panel, set Background Image to Other. An Upload File button appears below it.
  3. Click Upload File and drop or choose the image.
  4. When the window closes, a small copy of the picture shows in the panel. Click Save/Generate and look at the preview.

A picture used on a screen

  1. Select the element that shows the picture, for example an image element.
  2. In its properties panel, click the button for its image. An upload window opens.
  3. Drop or choose the image.
  4. When the window closes, click Save/Generate and look at the preview.

A file, and a library file

The same three steps, from the properties panel of the element that uses the file: a file element for a document, a sound or a video; a library element for a PHP or JavaScript library file.

If the picture or file is on a web page, save it to your own machine first, then upload it as above.

  • On a computer: right-click the picture and choose Save Image As… (for a file, right-click its link and choose Download Linked File or Save Link As…).
  • On a phone or tablet: press and hold the picture and choose Save to Photos or Download image (for a file, press and hold its link and choose Download).

11. Building and previewing

When your design is ready, you build it. In Exotool, building and saving are a single step: saving your diagram compiles it into the working app. If something in the design cannot be built, the editor reports the problem on the specific element so you can fix it and build again.

Your app gets its own live preview. Each build recompiles your app — together with all its uploaded images and files — and installs it to a private preview address for the project. Anything not meant for production is left out of this build, so the preview behaves like the real thing. The editor shows this preview right beside your design, so you watch the app take shape as you work; each rebuild refreshes it.

The preview has a shareable link. That preview address is a normal web link. The DETAILS link in the top navigation bar shows it for the current project. Open it on your own phone or send it to someone else, and they can try the live app in a phone or desktop browser — no editor or install required. Because every build refreshes what lives at that link, share it once and rebuild as you go; the same link always shows your latest saved version.

Work in small loops — add or adjust a little, build, try it in the running app, and repeat — rather than designing everything before the first build.

Connecting to external services (resources)

Most apps need to talk to outside services — a database to store data, an e-mail server to send mail, a payment provider for e-commerce, or a web host to publish files. In Exotool you set each of these up once as a resource and then point your project at it.

A resource is a saved connection to an external service — its address and credentials — for example a MySQL database, an SMTP e-mail account, a PayPal account, or an FTP web host. You create a resource once and reuse it across projects, so you don't re-enter connection details each time.

To use resources in a project, assign one to each role it needs — its database, its e-mail server, its e-commerce/payment provider, its web host. When you build, the app is wired to those services. Roles you leave unset use a safe default (for example, the e-mail, payment, and web-host roles are simply off until you set them).

The database role is special — it always has a store, and you choose which kind:

  • Single File (the default) — your app's data is kept in one built-in data file. Nothing to set up; good for getting started and for smaller apps.
  • Multiple Files (File-Per-Object) — data is stored as many small files (one per record, plus index files) in a folder. Also built in, no external service needed.
  • MySQL — your app uses a real MySQL database. This one requires a database resource: create (or pick) a MySQL resource and assign it here.

The first two need no resource; only MySQL points at one. As with the other roles, changing the database kind takes effect on the next build.

Two things worth knowing:

  • Credentials live with the resource, not in your diagram. They stay out of the app's design, and can be updated or shared in one place.
  • Changing a project's resources takes effect on the next build. After assigning or swapping a resource, rebuild so the app picks it up.

12. Best practices

A diagram is read by a person, so treat clarity as part of the design.

  • Do not let elements overlap. Give every screen box a clear gap from its neighbors. Overlapping boxes are hard to read and easy to misinterpret.
  • Lay screens out in reading order. Arrange the flow left to right (or top to bottom) in the order the user moves through it, so the diagram tells the story of the app.
  • Split a busy design across sheets. Keep a sheet to about one laptop screen, since not everyone has a large one. When a sheet grows past that, move a related cluster of screens, one band of the user's flow, to another sheet and bridge any connections with symlinks. Keep each sheet uncluttered in its own right.
  • Wire both ends of every symlink. A half-connected jump point does nothing — make sure something points into one badge and the twin leads out to the target.
  • Put links in containers. Keep links inside a navigation bar, toolbar, or link menu, never loose on a screen, so they actually work.
  • On form inputs, leave the icon set to "none". The form-field icons do not render correctly, so do not assign one — keep every input's icon as none.
  • Don't use a Buttons Row in a form. It does not behave as expected; place form buttons directly in the form instead.
  • Lay flows left to right. Connection arrows always point to the right, so place each screen or step to the right of whatever leads to it. A connection that has to double back to the left forces a long, looping line and clutters the diagram — arranging things in left-to-right order keeps the arrows short and straight.
  • Line up with the item, not the screen. A connection leaves the right edge of the link, list, form or button that triggers it, at that item's height, and several connections entering one side of a box arrive spread evenly along that side: one in the middle, two at a third and two thirds, three at a quarter, a half and three quarters, in the order of where they come from. Place an incoming jump point or activity level with its arrival slot, and the line draws straight.
  • Lay screens in rows, with shared decisions between them. Follow the user's flow left to right along a row (splash, load, list, detail, form), start a new row for a second flow (sign-in, account), and put an activity that both rows reach, such as a "Signed in?" decision, between the rows. Leave room between screens for connection lines and their condition diamonds.
  • Put an activity to the right of what triggers it, at the same height, never below it; a conditional branch continues to the right of its diamond.
  • Send a Home link to the first real screen after the splash, not to the splash itself, or the splash and its delay replay at every tap.
  • Keep a single jump point close to its source. When only one connection feeds a symlink badge, put the badge right next to the element that links to it, at the same height; the connection then draws as a short straight arrow instead of a long route. Save the longer "teleport" jumps for connections that genuinely cross sheets or span the canvas. The twin badge that leads out to a target goes just to the left of that target, level with its arrival slot, even when another connection already arrives there, so that both come in from the left.
  • Start each sheet's content near the top-left. Don't leave a wide empty margin above or to the left — otherwise the reader has to scroll around before seeing anything. Leave just enough border for the connection lines to route, no more, so some elements are visible the moment a sheet opens.
  • Don't leave empty sheets. Keep your sheets consecutive; an empty sheet between used ones is a place for the reader to get lost.
  • Mind what a sub-view encloses. A sub-view groups whatever its box completely surrounds — that enclosure is what defines the group, not just decoration. Size and place it deliberately, and make sure it doesn't accidentally swallow a neighboring element, which would quietly change that element's behavior.
  • Route connectors cleanly. Draw connection lines so they do not run through screen boxes, and use symlinks rather than dragging very long lines.
  • Name things meaningfully. Give screens and key elements clear titles; it makes both the diagram and the running app easier to understand.
  • Build often. Frequent builds catch problems while the change that caused them is still fresh.

Where to go next

  • System Overview (exotool_docs("overview")) — the big picture of how Exotool turns your design into a running app.
  • Exotool Language Reference (exotool_docs("language")) — everything you can write inside an activity.
  • HTML Templates Reference (exotool_docs("templates")) — building dynamic, data-driven content.