Virtual Field Guide Editor
A virtual field guide is a set of linked pages that lives inside your VRGS project and is read beside the 3D scene — a field trip booklet whose "go and look at this" links actually take the reader there.
VRGS authors guides in a WYSIWYG editor: you build the guide's structure in a sidebar, write the pages the way you would in a word processor, and drop in the things a booklet cannot do — a link that flies the camera to an outcrop, a map of the trip, a comparison slider between photo and interpretation, a quiz.
The editor and the reader are both built on the Microsoft Edge WebView2 runtime. Without it, guide pages can still be opened as plain files but the editor will not start.
How a guide is laid out
Everything lives under the project's HTML folder, listed in the HTML branch of the Collections tree. A field guide is a direct subfolder of that HTML root — that is the whole rule. Anything loose at the root is just a page.
A guide folder holds:
| File / folder | What it is |
|---|---|
map.html | Home — the map hub the guide opens at. Both View Field Guide and the reader's Home button land here. |
index.html | Contents — a live table of contents rendered from the guide's navigation, so it follows the Guide sidebar and never needs editing by hand. |
dayN.html | A Day — a hub for its own stops. |
dayN-stopM.html | A Stop — the page about one place. |
info.html | Safety, logistics, references. |
menus/main-nav.json | The guide's structure: order, labels, nesting. |
images\, videos\, style\ | The guide's media and stylesheet. |
Each page also declares what it is in a vrgs-page-type tag. That is what
gives it its symbol in the Guide sidebar, in the reader's navigation bars and on
the map — nothing is inferred from the file name, so a page keeps its identity
through a rename.
Creating a guide
From the Collections tree:
- Right-click the HTML branch → New Folder, and name it after the trip.
- Right-click the new folder → Add Field Guide Template.
The template is a worked clastic / fluvial example laid out as a navigation hub rather than a linear booklet: a map home page, a live contents page, four Days with two Stops each, and an info page. It is meant to be edited into your own trip, not read as-is — but it shows every block the editor can produce, in place.
Add Field Guide Template on a guide that already has pages asks before overwriting them.
Alternatively, select loose pages at the HTML root, right-click and choose Group into Field Guide — they are moved into a new guide folder together.
Guide folder commands
Right-click a guide folder in the Collections tree:
| Command | Effect |
|---|---|
| View Field Guide | Opens the guide in the reader (the WEB panel), entering at its map. Also makes it the active guide, so Home and Navigate to resolve here. |
| Add Field Guide Template | Writes the worked example into this folder. |
| New Page | Adds a page to this guide. |
| Open in Editor | Opens the guide's contents page for editing. |
| Rename | Renames the guide folder. |
| Delete Field Guide | Moves the guide and all its pages to the project's RECYCLING folder, after closing any of its pages open in the editor. |
Individual pages and asset files under HTML have their own menu: Open in Editor, Copy HREF, Open File Location, and Delete File / Delete Folder (to the recycle bin).
The editor window
Opening a page gives you three areas:
- Guide sidebar (left, top) — the guide's pages as a nested list, with a symbol per page type. This is where the guide's structure is edited.
- This page (left, bottom) — the current page's headings. Click one to jump to it.
- The page itself — the WYSIWYG canvas, with the toolbar above it.
Opening any page of a guide makes that guide active, which scopes the Guide list, the shared menus, the media browser and the reader panel to it.
Building the guide structure
Right-click a row in the Guide sidebar:
| Command | Effect |
|---|---|
| Open in Editor | Edit that page. |
| Add Stop to Day | (Days only) Creates a Stop inside that Day — it appears under it in the sidebar, in the Day's own stop list and in the reader's navigation. It also takes the current 3D view as its viewpoint, which is what puts it on the map. |
| Add Page to X | Creates a page of extra detail inside whatever you clicked. Something the reader clicks through to and reads, not a place — it gets no viewpoint and never appears on the map. |
| New Page (top level) | A page alongside the Days rather than inside one. |
| Add Map Page | Adds a map page to the guide. |
| Duplicate | Copies the page, keeping its type. |
| Rename… | Sets the label shown in the guide. Clearing it falls back to the page's own first heading. |
| Move Up / Move Down | Reorder within the same level. |
| Restore Previous Version… | Recover an earlier saved version of the page. |
| Delete… | Remove the page from the guide. |
Rows can also be dragged: drop on the top third of a row to place before it, the bottom third to place after it, and the middle to nest inside it. A page cannot be dropped into its own subtree.
Where a new page goes is decided by what you right-clicked, so there is nothing to choose and no way to get it wrong. A page added under a Day inherits that Day's layout, so the reader can navigate back to it and across to its siblings.
Writing a page
The toolbar carries font and size, text and highlight colour, bold / italic / underline, paragraph and heading levels, quote, alignment, lists, and clear formatting. Ctrl+S saves; Ctrl+Z / Ctrl+Y undo and redo; </> toggles the HTML source.
Insert
| Item | What it adds |
|---|---|
| Table | A table. |
| Callout | A coloured note box. |
| Quiz | A multiple-choice question with your own right/wrong responses, marked in the reader. |
| Link | An ordinary hyperlink. |
| VRGS Link | A link that acts on the 3D scene — see below. |
| Object Link | A link to an object in the project; clicking it in the reader navigates to that object. |
| Anchor Target | A named target elsewhere on the page can link to. |
| Image | An image from the guide's images folder or a URL. |
| Image with Caption | The same, as a captioned figure. |
| Comparison Slider | Two images with a slider between them — the standard photo-versus-interpretation figure. |
| YouTube Video | An embedded video. |
| Local Video | A video from the guide's videos folder. |
| Menu Bar | One of the guide's shared navigation bars. |
| Map | A live map block — see below. |
| Table of Contents | Built from the page's own headings. |
| Page Navigation | Previous / next links across the guide. |
VRGS links — the point of a virtual guide
Insert → VRGS Link offers three kinds:
| Type | What it does |
|---|---|
Geo Location (geo://) | Flies the 3D camera to a position. Press 📷 Get Viewpoint to fill it in from the view you are looking at right now. |
VRGS Command (vrgs://) | Runs an application command. |
| Flight Path | Starts one of the project's flight paths in the 3D scene. The dropdown lists the paths in the project. |
Give it a display label, and tick Show as a full-width bar to make it a bar across the page rather than an inline pill — which is what you want for the one viewpoint a Stop is really about.
Frame the shot in the 3D view, then insert the link and press Get Viewpoint. The same capture is what Add Stop uses, which is why a stop added from the sidebar already knows where it is.
The map block
A map block is a live map of the trip, and it is the same map the reader shows.
- Basemap — a street map, or an image you supply with geographic bounds.
- Spots — the guide's own Days, Stops and Viewpoints, derived from the pages themselves. A page that has a viewpoint has a place on the map; one that does not, does not appear. There is no separate list to keep in step.
- Outcrop model (DOM) outlines — the project's models, drawn live as dashed footprints. They are not stored in the page: the project is the source, so the outlines follow the models. Right-click one to navigate the 3D view to it.
- Right-click the map (while editing) to 📍 Add Stop here, or to add a 3D Viewpoint at that point.
- A legend switches the layers, and the basemap / overlay choices you leave it on are remembered while the project is open.
Images and video
Images and videos live in the guide's own images and videos folders. You can
drag and drop a file straight onto the page — it is copied into the guide and
referenced from there — or press Browse… in any image or video field to pick
from what the guide already has.
A page that points at an image on your own desktop shows nothing for anyone else. Dropping the file onto the page (rather than pasting a path to it) is what puts a copy inside the guide, where backups and file sharing will carry it.
Shared menu bars
A guide's navigation bars are shared: defined once and inserted on as many pages as you like, so changing the bar changes it everywhere it appears rather than on the page you happened to be editing. Create and edit them from the menu editor, and place one with Insert → Menu Bar.
Saving
The editor pushes its content to VRGS whenever you pause typing, when the editor loses focus, and when you save — each push stamped with the page it came from. Saving is therefore a write of content already in hand: it never has to wait on the editor, which is what stops a save freezing the application.
Two consequences worth knowing:
- A previous version of each page is kept, which is what Restore Previous Version… in the Guide sidebar reads.
- If a save is refused because the editor holds a different page than the one being saved, VRGS says so and offers to reload from disk. That is the one refusal with a way out; the others are reported with the reason.
Reading a guide
View Field Guide on the guide folder opens it in the WEB panel — VRGS's reader — at the guide's map. From there:
- Navigation bars and the contents page are rebuilt live from the guide's structure, so they always match what the Guide sidebar shows.
geo://and flight-path links act on the 3D view, which is the whole point: the reader and the scene are side by side.- The reader has a search box across the guide's pages.
- Navigate to on an object in the project tree switches the reader to the active guide's map with the live location marked, rather than to the web map.
Reports use the same editor
The Report editor is this editor in a second mode. A report is
deliberately not a guide page — it lives in the project's Reports folder, has
its own stylesheet and print rules, and opening one never re-points the Guide list
or navigates the reader away from the guide you were reading. A report opened in a
guide window (or the reverse) still parses and round-trips; it simply does not
offer the other mode's buttons.
Tips and troubleshooting
- The guide folder has no menu commands. A field guide has to be a direct
subfolder of the HTML root. A folder nested deeper, or one named
images,videos,menusorstyle, gets the ordinary item menu instead. - "This field guide has no map.html or index.html yet." The folder is empty — use Add Field Guide Template or New Page first.
- A new page did not appear in the reader's navigation. The reader reads the guide's structure; save the page, and check it is where you expect it in the Guide sidebar.
- A page shows a broken image. The image was referenced from outside the guide folder. Drag the file onto the page to bring a copy in.
- A stop is missing from the map. Only pages with a viewpoint have a place. Add one with Insert → VRGS Link → Get Viewpoint, or create the stop with Add Stop to Day, which captures the current view for you.
- Deleting the wrong thing. Pages, asset folders and whole guides all go to
the project's
RECYCLINGfolder rather than being destroyed.
See also
- Sharing Field Guides — writing one guide with several authors, through GitHub.
- Analysis Reports — the same editor, in report mode.
- Multiuser Virtual Field Trips — running a live trip through a guide.
- Flight Paths — the guided fly-throughs a guide page can start.
- Building and Delivering a Virtual Field Trip — how a guide fits with flight paths, media and a live session.