-
-
Notifications
You must be signed in to change notification settings - Fork 31
Design: URLs
Share uses URLs to identify application state, so users can share exactly where they are in the app.
We adopt a URL structure similar to Google Apps URL structure:
http://<host>/<app>/<view>/<model>
Here are some examples for the current host='bldrs.ai', with app='share', view='v' and model='p/index.ifc' or its GitHub equivalent:
http://bldrs.ai/share/v/p/index.ifc
When the user first visits:
http://bldrs.ai
they are automatically navigated to the project logo:
https://bldrs.ai/share/v/p/index.ifc#c:-111.37,14.94,90.63,-43.48,15.73,-4.34
If the path refers to an IFC file the IFC.js loader is used to load the file path and display it.
App is share:
http://host/share/…
The default URL has no subject, as we will detect login credentials.
If we grow to support multi-login like GDocs, we can do a backward-compatible insert of subject between app and view:
http://host/<app>/<subject>/<view>/...
To signal subject is present, use /u followed by a login ordinal:
http://host/share/u/0/<view>/...
Note, this could perhaps be a full email? Like: /[email protected]/
View (or verb) for now just CadView with /v:
http://host/share/v/...
Model can either be a model in the current repository or a remote reference.
A reference to a file within the project is indicated with /p and then a local file path:
http://host/share/v/p/index.ifc
Here, haus.ifc is in the root serving folder of the application on GitHub pages, i.e. /docs/haus.ifc.
For remote, for now just other GitHub files signaled with a /gh prefix:
http://host/share/v/gh/...
GitHub repos are referenced by organization and repository name, followed by branch and version information and “public” for something. To begin with we’ll just support public main branch.
http://host/share/v/gh/<org>/<repo>/<branch>/<filename>
E.g.:
http://host/share/v/gh/bldrs-ai/Share/main/public/index.ifc
The segment “bldrs-ai/Share/main/public/index.ifc” triggers an HTTP fetch to:
http://raw.githubusercontent.com/bldrs-ai/Share/main/public/index.ifc
Elements in IFC models are have unique IDs for each element in the building. Adding an ID to the model gives an Element Reference.
https://host/share/v/p/index.ifc/84
Appending a sequence of Element IDs to the model path gives an Element Path.
https://host/share/v/p/index.ifc/84/103/138/160
Note, the path is purely navigational, showing containment structure of each element with its parent and children. Meaning, the following two paths are equivalent Element References, but the first URL shows the a:
https://host/share/v/p/index.ifc/84/103/138/160
https://host/share/v/p/index.ifc/160
IFC ids are unique but may change over time if the exporting tool re-encodes the file.
So it may be more reliable to use UUIDs for the node, so instead of a path, the URL above might be:
https://host/share/v/p/index.ifc/00000-191239-AFEBC911-132E234A
Search params are anchored on a model or element path:
https://host/share/v/p/index.ifc?q=wall
https://host/share/v/p/index.ifc/84/103?q=wall
Raw GUIDs may be searched directly as query strings
# The front box in the Bldrs logo:
https://host/share/v/p/index.ifc?q=2IenVgx2bDVfGVjVGJn15E
This file:
https://github.com/OlegMoshkovich/Bldrs_Plaza/commits/main/IFC_STUDY.ifc
Has multiple versions, that can be referenced directly by git sha hash path:
v1 https://github.com/OlegMoshkovich/Bldrs_Plaza/blob/5f424a0869345649d78f819d365ea642c4789458/IFC_STUDY.ifc
v2 https://github.com/OlegMoshkovich/Bldrs_Plaza/blob/4566a63cc29a0c7673db8ba992d597b16a671b87/IFC_STUDY.ifc
...
Share maintains navigation state in the URL.
:: param separator
: label-value separator
, list of values separator
= named value assignment
e.g.
https://host/share/v/p/index.ifc#c:1,2,3::p:x=1.234,z=2.345
Each feature that controls navigation stores its state with a unique prefix. Current prefixes are:
"c": camera
"i": issues
"m": placemark
"p": cut-plane
The camera token encodes the camera position and the target look at position, e.g.:
https://bldrs.ai/share/v/p/index.ifc#c:-111.37,14.94,90.63,-43.48,15.73,-4.34
The issue token encodes the currently active Note, which should be displayed next to the scene, e.g.:
https://bldrs.ai/share/v/p/index.ifc#i:1234
In the current implementation, this issue is also backed by a GitHub issue with the same ID.
The placemark token encodes the x,y,z location of a place in the scene, marked by an in-scene icon:
https://bldrs.ai/share/v/p/index.ifc#m:1.1,2.2,3.3
There maybe be many placemarks in the scene, but only 1 currently active. The currently active placemark will have a visually emphasized icon. The default icon for the rest will be visually present, but deemphasized.
TODO(pablo)...
- Maybe multiple active tokens in a single URL?
- Maybe optional text label, e.g.
m:1,2,3,Hello%20World
The cut-plane token encodes the currently active cut planes, which reveal cross-sections of the model, e.g.:
https://bldrs.ai/share/v/p/index.ifc#p:y=-5.28,z=5.515
Each cut-plane may be active independent of the others, so a coordinate order is insufficient and the name of the plane must be present to disambiguate.
Embedded applications should use a State Token to refer to their state. State Tokens are required for Cross-session persistence.
Small amounts of state should be directly encoded as parameters, e.g. with camera, which includes the coordinates. This state is implicitly persistent across sessions.
Larger amounts of state should be stored in browser datastructures or services, such as IndexedDB, or in Application backends. The State Token can be used as the primary key for CRUD operations against backend stores, but that is the responsibility of the Application author.