User Guide

This document describes how to access the functionality in the MyContexts program.

Perspectives on contexts

The user interface of MyContexts visualises perspectives on contexts. A context is just a collection of roles. You play a role in each context you're able to see or change. Associated with that role is a perspective that determines whether you can just inspect values, change them, delete them or add to them. It also determines whether you can change the filler of a role.

By opening a context (from an already open context) you navigate from screen to screen. Usually, you can open a context both in place of the open context, and on another tab or in a new browser window.

Apart from opening contexts, you can also open a form to edit properties of a role.

Roles and Cards

The MyContexts interface rests on the concept of a card. A card represents a role instance. It can be selected, dragged and dropped. Once selected, keys or combinations of keys trigger specific behaviour on the role represented by the card.

Single (functional) roles

Sometimes, a context will accept just a single instance of a role. A taxi situation, for example, will usually be modelled with just a single Driver role.

Multi-Roles

On the other hand, there may be multiple Passengers in a taxi, hence this role would usually be modeled as a Multi-Role.

Visualising Multi-Roles is different than visualising functional roles. For the latter, a single card will do. A Multi-Role is visualised with a table.

This so-called RoleTable shows properties of the roles on the columns and an instance of the role on each row. The table will usually have a column that sports small cards, allowing you to manipulate the role as an entity (see below).

Behaviour associated with Roles

There are five things one can do with an existing role:

• open it. If the role represents a context, a screen is opened that gives your perspective on that context;
• fill it with another role;
• fill another role with it;
• remove its filler;
• remove it from its context, thereby destroying it (but not its filler).

It is up to the designer of the screens to associated zero or more of these behaviours with a given representation of that role (say, a card). For some behaviours, the user interface clearly indicates whether it is available on a particular role (e.g. by displaying a + button on the toolbar under a multi-role table). In some cases you'll have to find out by trying (e.g. whether you can remove a role, by selecting it and pressing delete).

Triggering behaviour

All behaviour can be triggered with both the keyboard and the mouse.

With the mouse

• Click a card to select it.
• Doubleclick a card to open it: for context- and external roles the context will be opened, for other roles a form to edit their properties.
• Doubleclick a card while holding the shift or alt key to open it in a new window or on a new tab (which of the two will happen depends on browser type and its settings).
• Drag a card and
  • drop it on another card to fill that role with it;
  • drop it on the Trash to remove it from its context and destroy it;
  • drop it on the Pencil tool to edit its properties. This is useful mainly for context- and external roles (for double clicking them will open the context rather than the properties);
  • drop it on the Unbind tool to remove its filling role;
  • drop it on the toolbar at the top of the screen to put it on the card clipboard. Cards can be dragged from one window to another.

With the keyboard

• Click tab and shift-tab to move the focus around the screen.
• Tab into a solitary card to select it.
• When a card is selected
  • press shift-space, to open it;
  • press alt-shift-space to open it in a new window or on a new tab (which of the two will happen depends on browser type and its settings).
  • press ctrl-c to copy the card to the card Clipboard (in the upper left corner of the screen).
  • press backspace to remove the role from its context and destroy it.
• Once on the clipboard, the card can be dropped just as with the mouse:
  • to drop it on another card, select that card and press ctrl-v;
  • to drop it on the Pencil tool, select the Pencil tool and press space or return. This is useful mainly for context- and external roles (for double clicking them will open the context rather than the properties)(NOTE that this currently does not function: see Issue 3);
  • to drop it on the Unbind tool, select the Unbind tool and press space or return.
  • to clear the clipboard, press escape.

In the RoleTable

RoleTables have extra ways to trigger behaviour:

• use left- and right arrow keys to navigate from column to column (the up and down arrow keys will move from row to row, as in a list);
• press enter to start editing a cell's value;
• press enter while editing to save the changes and return to the navigating mode;
• press escape while editing to discard the changes and return to the navigating mode;
• press shift-space to select the row. this shows up as a selected card in the card column;

Using the mouse:

• click any cell to select it;
• shift-click a row to select it (that is, the card in the card column).

Notice that a selected card in the table supports the same keyboard triggers as a selected solitary card or a selected card in a list.

The table will 'remember' the selected cell as long as it is on the screen (it loses that memory on navigating to another context or when opening a role form). This memory shows up when you tab into the table.

Table controls

A table displays a toolbar just below it. This toolbar

• has a small card item that represents the selected row;
• has a clipboard icon that, when not greyed out, allows one to paste the role on the clipboard into the current role as filler;
• may have a drop-down menu with a thunderbolt icon. This menu holds row-specific actions you can perform.

• may have a drop-down menu with a plus icon. This menu holds role or context types. By selecting an entry you add a new row to the table representing an instance of the type.

• will have an external link icon if the row represents a context that has a public perspective on it. By clicking the icon, you will open a new browser tab with MyContexts showing the public version of the context.

In the File component

Properties can have a range of type File. In a form, such properties are displayed as two fields and, depending on state, one or two buttons.

The component has four states:

• empty
• filled
• readonly
• editable

The empty state displays a name field and a MIME type field, both plain string types (but only values that match the regular expression mentioned above are accepted as MIME type). It also displays an upload icon button. When a name and MIME type are entered for the first time, the control creates and stores a new file. The state then becomes filled. In the empty state, the component also functions as a dropzone (one can drop a file on it).

• On tabbing into the control, by default, the cursor will be in the name field (other than in filled state, the control does not have to be unlocked for editing when empty)
• press right arrow to move to the MIME field. Changes to the name will be preserved temporarily. Pressing right arrow again will focus on the upload icon button; pressing right arrow again moves the cursor back to the name field; changes to the MIME field are preserved temporarily.
• Press space when the focus is on the upload button to open the file selector dialog.
• Press escape to discard all changes.
• Press enter while in any field to actually save changes and to move the control to filled state.

NOTE: The use of the left-arrow key is consistent with the way one can move through a table. However, as a consequence, one cannot move through the text that has been entered in the control with the left-arrow key.

The filled state shows the name and mime type (and neither is editable). In this state, the control is draggable if a url is available (the payload will be a standard HTML File object). It is also a dropzone for such objects.

NOTE: the draggable interface has not yet been implemented.

• The control state can be moved from filled to editable by selecting it and then pressing enter. The cursor will then be in the name field. The MIME value cannot be edited.
• The download button can be selected if a url is available.
• Press space on the download button to activate it.

readonly is like filled, but without the possibility to move to editable. If there is an url in the property value, the end user will be able to download the file.

When editable, the control displays two buttons: one to download the file, one to upload it. Both can be activated by selecting and pressing space. The name of the file may be changed; its MIME type cannot. Move from button to button or field by pressing left arrow.

• Uploading a file will move the control back to filled state (after preserving changes).
• Pressing enter will preserve a change to the file name and move the control back to filled state.
• Pressing escape will discard changes and move the control back to filled state.

NOTE: When the user has not yet changed the file name, pressing enter has no effect. Press escape to leave the control.

In all states, the download button is only enabled if the control has a value for the database for the file. This will be

• after creating a new file and
• after uploading a file
• when the property value coming through the PDR API contains the serialised structure that contains a database value.

Open a context from the navigation bar

The MyContexts application is opened on the url https://www.mycontexts.com. This will land you on the standard entry page that lets you choose an App from those listed in a bar on the left. However, it is also possible to jump right into a specific context by entering the name of that context right after the url. For example, enter https://www.mycontexts.com?MySystem to open just the MySystem context (showing you the Apps you've installed and those that are available in the Repository).

The name you enter after the question mark is matched to indexed context names defined in models. Examples of indexed context names are:

• MySystem
• MyChats
• MyManagedModels
• MyBrokerServices

Just entering 'System' would be enough to land you in MySystem. If you enter 'My', however, you'll be presented the four names above and you can choose by clicking one of them.

NOTE: this currently does not work. See Issue 4

Navigating using the browser's tools

MyContexts stores the history of contexts that you've visited, in the browser's history. Consequently, you can navigate back (and forwards) using the browser's tools such as the navigation buttons.

Logging in to MyContexts is not, in this sense, a navigation action. Only when you open the System context does navigation start. As a reminder: the top entry in the browser's history list is the context you currently have on screen.

When you explicitly close a context (using the button in the menu), a new item is added to history with the title "Closed {contextname}" (where {contextname} has been replaced with the title of the context). If you navigate back from such a situation, you in effect re-open that context. This is useful when you have closed MyContexts. After logging in, by navigating back you pick up exactly where you left.

When you try to navigate away from MyContexts (e.g. by closing the tab) while a context is open, a warning is issued. Best practice is to first close the context and then navigate away (if you don't, others will think you still have that context open (in some situations, they can see that status)).

Finally, when you have navigated back to the point that the next time you go back would make you leave MyContexts, you'll get a warning if you try. It will say something to the effect of "Leave site?" (the exact wording is determined by the browser's makers). If you really want to exit, press Leave. You'll have to log in again if you want to resume MyContexts. Otherwise, press Cancel.