No Competition SelectedNetwork Access Policies: Off
Superuser () R/W
Credits

Interactive Guide — How to write a course

← Back to administration

1. The idea

A course is a sequence of steps shown in a side panel, on top of any ianseo page. Each step explains one action, can point at it visually — a highlighted button, an arrow, a tooltip — and then waits until the action has really been performed before unlocking the next step.

Everything is built from the visual editor (New course or Edit): no code needed. The JSON is generated for you, and stays reachable for advanced users in the folded "JSON source" section.

2. The course

FieldPurpose
TitleThe name shown in the catalogue and at the top of the panel.
DescriptionOne short sentence, shown under the title in the catalogue.
VersionA free-form number such as 1.0. Raise it and the users who had finished the previous version are marked "previous version".
ThumbnailAn optional 16:9 image, shown in the catalogue so a course is recognisable at a glance.
IDA unique identifier, generated for you. Do not change it once the course has been published: it is the key progress is recorded against.

3. The step

Every step has:

Use + Before and + After to insert steps, and the ◀ ▶ arrows to move between them. The left-hand panel is a live preview: what you see is exactly what the user will see.

4. Writing the content

The toolbar above the preview formats the text:

Inside a tip box: press Shift + Enter to start a new line within the box. Press Enter on its own to leave the box and carry on with ordinary text below it.

5. Images

Images are embedded in the course itself, as base64. Avoid heavy files — a GIF of several megabytes makes the course, and its synchronisation, slow. The editor warns you past 2 MB.

6. Triggers

A trigger describes what the user has to do for the step to be complete. A step may hold several, and they fire in order — drag and drop to reorder them. There are two families.

⚡ Action — the user does something

FieldPurpose
PageThe page the action happens on. Empty means the step's own default page. * means any page, which is what menus need since they exist everywhere.
TypeThe event to wait for: click, double click, change, entry, focus, hover, submit… — none highlights the element and lets the user confirm by hand.
SelectorThe element, as a CSS selector — #btnSave, .menu-item. It is highlighted, with an arrow.
TooltipOptional short text shown beside the highlighted element.
RequiredWhen ticked, the step does not complete until the action is done.

✓ State — waiting for a condition to become true

Instead of an action, the step waits for a condition inside ianseo to be met — "a competition is open", for instance. While it is not, a message says so. The condition is checked again every time the user comes back to the step.

One built-in condition is always available: 📍 Current page. It checks that the user is on a given page, named in the field that appears. That page may differ from the step's own page. Until the user gets there the step stays locked and a "Go to the page →" link is shown.

The other built-in condition is 🔎 Presence or absence of an element. You give a CSS selector — prefix selectors such as [id^="…"] work here too — and say whether the element must be present or absent. Useful for waiting on a confirmation message, a window opening, a loading indicator disappearing. This condition is re-checked automatically, because such an element can appear or vanish without the page ever reloading.

The * page works both as the step's default page and on each trigger individually. A trigger set to * stays active whatever page is on screen.

Conditional branches (⎇ Active if…)

Every trigger, action or state, has an ⎇ activation condition. By default a trigger is always active. It can be made conditional:

A trigger whose condition is not satisfied is skipped, and the sequence moves to the next one. That is what lets a course take different paths depending on the state of ianseo and then rejoin a common sequence:

For example: "if NOT: a competition is open" on a trigger that walks the user through creating one; the triggers after it, with no condition, are common to both cases. For an "else", use two triggers — one if X, the other if NOT X.

7. Finding a CSS selector

To target an element — a button, a field, a link:

In the inspector, right-click the element's line and choose Copy → Copy selector.

Numbered ids, which change every time

Some ianseo ids carry a record number that changes with the participant or the competition, such as #d_q_QuSession_25360 or #d_QuD1Score_25360. An exact selector would work once and never again. Use a prefix selector:

The trigger then fires on any matching element — the Session box of any participant, say — and the arrow points at the first one found. The trigger recorder spots these numbered ids by itself and writes the prefix selector for you.

8. Recording triggers automatically

Rather than typing selectors by hand, 🔴 Record triggers, in the step options, captures them by clicking directly in ianseo:

Afterwards, read the triggers through — type, tooltip, required — adjust what needs it, then save the course. The generated selectors are robust but not infallible on very dynamic elements.

9. Step options

OptionEffect
OptionalShows a "Mark as done" button: the user can complete the step without performing the action.
Non-permissiveBlocks every click outside the expected element, so the user can only interact with the target. The panel flashes red when a click is blocked.

10. Quiz and challenge — bronze, silver and gold

A course can offer up to three activities: the step-by-step guide, a quiz and a challenge. At the end of the guide the user is invited on to the quiz, then the challenge, then the next course. Each activity passed raises the achievement:

AchievementEarned by
🎯 Bronze targetFinishing the guide
🎯 Silver targetThe guide plus one other activity
🎯 Gold targetEvery activity the course offers

The conditions shipped with the module cover the usual run of a competition:

11. Learning path, checklists, troubleshooting, contextual help

12. User accounts (shared server)

When the server runs an account module, each account has its own progress: courses under way, steps completed, quizzes, challenges and achievements are recorded per user, without affecting anybody else. The "Learn to use ianseo" banner appears for an account that can see no competition at all, which is the sign of a new organiser. The courses themselves stay common to the whole server. With no account module nothing changes: the progress is simply the installation's.

13. Translating a course

A course carries every language it has been written in, inside its own file: it stays one document with one version number, and the update mechanism has one thing to compare.

Only the text of a field is translated. The structure around it — steps, triggers, selectors, pages — is never duplicated, so the languages cannot drift apart. A course whose translated version pointed at a different button than the original would be worse than a course with no translation at all.

A reader gets the course in the language of their interface. Failing that, English; failing that, the language the course was written in — so a course translated into only one language is still served, never shown empty. A regional language counts as its parent along the way: a reader set to Canadian French gets the French text before English is considered.