Write an App Guide
Goal
Give your app its own help. This help site explains the platform: how a view works and how a form saves. It cannot explain your app, for example how your club takes a booking. An app guide is a short markdown document you write in the solution. It is imported along with the app, it is listed in the app's Help menu, and a button on a screen can open it.
Prerequisites
- You are signed in as a maker, with a solution and an environment selected.
- The app the guide is for is in the environment. It can be a model-driven app or a Studio app.
Steps
- Open your solution and choose App guides.
- Select New. The designer opens with a short example in it.
- Type a Title, for example Taking a booking. The Name fills itself in as you type. Screens and commands open the guide by this name, so it cannot be changed after you save.
- In App, choose the app whose Help menu should list the guide. Leave it empty for a guide that is only opened by name.
- Order sets the guide's place in that menu. Lower numbers come first.
- Write the guide in the editor. The preview beside it is exactly what a reader will see.
- Select Save.
Writing in markdown
| You write | The reader sees |
|---|---|
## Section | A heading |
**bold**, *italic* | bold, italic |
1. Step | A numbered list |
- Item | A bullet list |
`code` | code |
[text](https://example.com) | A link that opens in a new tab |
[text](guide:psl_guide_bookings) | A link to another guide |
 | A picture from the web |
Tables, quotes and code blocks work too.
HTML is shown as text. A guide can never run script, and a link opens only if it starts with
http, https, mailto or guide:.
Other languages
English is required. Every other language the platform ships has a tab beside it, and each one is optional. A language with nothing written shows a dot after its name. Readers of that language get the English guide, with a note saying it has not been translated. You can give a translation its own title, or leave the title empty to use the English one.
Opening a guide from a screen or a command
-
A drawn Studio screen. Give a button this click handler:
openGuide("psl_guide_bookings");The guide opens in a panel beside the screen, so the reader can follow it and keep working.
-
A form or a view. Add a command. Under When pressed, choose Open a guide and pick the guide.
-
Another guide. Link to it:
[how to cancel](guide:psl_guide_cancel).
If a screen names a guide that is not there, nothing opens. The screen's problems list and the command's message both name the guide it looked for.
It travels with the solution
A guide is a solution component, the same as a table or a script. Exporting the solution exports the guide in every language. Importing it puts the guide in the target environment's Help menu, and uninstalling the solution removes it.
Expected outcome
In the Shell, opening the app turns Help in the top bar into a menu. The app's guides come first, followed by the platform's own help. Choosing a guide opens it beside the page.