The Basic Mod Set: Client View

Cartesian

The Cartesian mod provides the item to which it is attached with simple two-dimensional cartesian geometry. It also supports user manipulation of the containership relation between objects. This mod may not be attached to users or contexts.

Representation


    { type:"cart", left:INT, top:INT, width:INT,
      height:INT }

where:

left and top are the X and Y coordinates of the screen position (in pixels) of the assocated item, relative to the position of its container.
width and height are the X and Y screen dimensions (in pixels) of the associated item.

Messages

move


 → { to:ITEMREF_STR, into:?REF_STR, left:INT,
          top:INT }

This message requests the server to change the position and optionally the container of the item to which it is targeted.

into optionally designates a new container for the item. The designated container must be reachable by the user sending the message.
left and top are the new position coordinates for the item, relative to its (new) container. Note that if the container is a user or the context, this is the item's position in the browser window itself.

If the destination is acceptable to the server, it changes the position and container of the targeted item, then broadcasts the "move" message to all users in the context informing them of the change.

Census

The Census mod allows a client to survey the number of users in a context. It may be attached to any kind of object.

Representation

There is no client-side representation of the Census mod.

Messages

census


 → { to:REF_STR, op:"census" }

This message requests a census of the context. The server will reply to the sender with the message:


 ← { to:REF_STR, op:"census", occupancy:INT }

where the occupancy parameter is the number of users in the context as of the time the message was sent.

Note that this operation works, assuming the mod is present, even in contexts where the users are not visible to each other. That is sort of the point, actually.

Chat

The Chat mod enables multi-user text chat in a context. It is attached to a context, never to a user or item. On the server, it may be configured to individually allow or disallow the "say" or "push" messages, both to the context as a whole (public chat or push) and to individual users (private chat or push).

Representation

There is no client-side representation of the Chat mod.

Messages

say


 → { to:REF_STR, op:"say", text:STR }

This message utters chat text on behalf of its sender. If the message is targeted at the context and the context's Chat mod is configured to allow chat, the server will transmit a corresponding "say" message to all users in the context, targeted at the context, with the same text, and marked as being from the user associated with the client sending this message. See the discussion of the "say" message in the Generic Messages section of the C-U-I Model document. If the message is targeted at a user and that user is in the same context as the sender and the Chat mod is configured to allow private chat, the server will transmit two copies of a corresponding "say" message, one to the targeted user's client and one sent back to the original sender.

text is the message being spoken.

If the user sending the "say" message has a TalkPrefs mod attached, clients should use its style attributes to render that user's chat text.

push


 → { to:REF_STR, op:"push", url:STR, frame:?STR }

This message issues a push request on behalf of its sender. If the message is targeted at the context and the Chat mod is configured to allow push, the server will transmit a corresponding "push" message to all users in the context, targeted at the context, with the same URL and frame, and marked as being from the user associated with the client sending this message. See the discussion of the "push" message in the Generic Messages section of the C-U-I document. If the message is targeted at a user and that user is in the same context as the sender and the Chat mod is configured to allow private push, the server will transmit two copies of a corresponding "push" message, one to the targeted user's client and one sent back to the original sender.

url is the URL to load.
frame, if given, names the browser HTML frame into which the URL is to be loaded. If omitted, the URL is loaded as an entirely new page.

Dictionary

The Dictionary mod associates a server-moderated name/value lookup table with the object to which it is attached. It may be attached to a context, user or item.

Representation


    { type:"dictionary", names:[STR], values:[STR] }

where:

names is an array of strings, containing the dictionary's lookup keys.
values is an array of strings parallel to names, containing the values. For a given element of names, the element of values with the same array index contains that name's value.

Messages

delvar


 → { to:REF_STR, op:"delvar", names:[STR] }

This message requests the server to delete one or more name/value pairs from the dictionary.

names is an array of strings containing the names of the entries to delete. Elements of the names parameter array that do not correspond to entries in the dictionary will simply be ignored.

Once the indicated entries are deleted, the "delvar" message will be broadcast to all clients in the context, informing them of the change.

setvar


 → { to:REF_STR, op:"setvar", names:[STR], values:[STR] }

This message requests the server to change the value of one or more name/value pairs in the dictionary.

names is an array of strings containing the names of the entries to be set.
values is a parallel array of strings containing the corresponding values to set those entries to.

Elements of the names parameter array that do not correspond to entries in the dictionary may result, at the server's discretion, in the addition of new name/value entries to the dictionary.

Once the indicated entries are set, the "setvar" message will be broadcast to all clients in the context, informing them of the change.

Image

The Image mod associates an image with the object to which it is attached. It may be attached to any kind of object, but normally it will be attached to items. This mod is purely a data object; it has no behavior and no message protocol. It is up to the client application to make use of this data appropriately.

Representation


    { type:"image", img:STR, width:?INT, height:?INT }

where:

img is the URL of an image.
width and height, if given, represent the horizontal and vertical extent of this image, in pixels.

Note

The Note mod associates a block of editable text with the item to which it is attached. It must be attached to an item, not a context or user.

Representation


    { type:"note", text:STR, style:?STYLEDESC }

where:

text is the text of the note.
style is an optional style description for rendering the text. See below for details on the style descriptor object.

Messages

edit


 → { to:ITEMREF_STR, op:"edit", text:?STR, style:?STYLEDESC }

This message requests the server to alter the text and/or style information on the note.

text, if given, is new text for the note.
style, if given, is new style information for the note. Only those attributes of the style that are actually sent will be modified; the remainder will be left unchanged.

Once the indicated changes are made to the note on the server, the "edit" message will be broadcast to all clients in the context, informing them of the change.

NoteMaker

The NoteMaker mod provides a facility for creating new items with Notes attached. It is normally attached to the context, but this is not required.

Representation


    { type:"notemaker", styles:STYLEOPTIONSDESC }

where:

styles is a collection of style options that can constrain the styles associated with notes this mod creates. See below for details on the style options descriptor object.

Messages

makenote

This message requests the server to create a new item with associated Note and Cartesian mods.


 → {


        to:REF_STR,

        op:"makenote",

        into:?REF_STR,

        left:INT, top:INT,

        width:INT, height:INT,

        text:STR,

        style:?STYLEDESC

into designates the container for the new item. It must be reachable by the user sending the request. If omitted, the new item is placed into the context itself.
left and top are the X and Y coordinates of the screen position (in pixels) of the new note, relative to the position of its container.
width and height are the X and Y screen dimensions (in pixels) of the new note.
text is the text of the new note.
style, if given, indicates the style attributes of the new note. Any style attributes which are not given (possibly all of them) will be taken from the defaults configured into the NoteMaker). If any of the style attributes requested are not permitted by the configured style options, the "makenote" request will fail.

If the request succeeds, a new item will be created in the indicated container, with attached Note and Cartesian mods according to the parameters given. The new item will be broadcast to all users in the context via a "make" message targeted at the new item's container.

TalkOptions

The TalkOptions mod describes controls the style information associated with user utterances displayed as a result of "say" messages. This mod must be attached to a context, not to a user or item. It operates in conjunction with the Chat and TalkPrefs mods. This mod is purely a data object; it has no message protocol.

Representation


    { type:"talkoptions", styles:STYLEOPTIONSDESC }

where:

styles is a collection of style options that can constrain the styles associated with chat. See below for details on the style options descriptor object.

TalkPrefs

The TalkPrefs mod holds a user's current chat text display style settings. It operates in conjunction with the Chat and TalkOptions mods. It is always attached to a user.

Representation


    { type:"talkprefs", style:STYLEDESC }

where:

style is a style descriptor that indicates how the user's chat utterances (as conveyed by "say" messages) are to be displayed.

Messages

style

The "style" message enables a user to request that their talk preference settings be changed.


 → { to:USERREF_STR, op:"style",
      color:?STR,
      backgroundColor:?STR,
      icon:?STR,
      textStyle:?STR }

color, if given, names the new preferred text color.
backgroundColor, if given, names the new preferred text background color.
icon, if given, is the URL of the marker icon image used to distinguish the user in chat logs.
textStyle, if given, is a style string for the rendering of chat text.

All parameters are optional. Any parameters omitted will result in the corresponding talk preferences setting remaining unchanged. If there is a TalkOptions mod attached to the context, the settings specified must be consistent with what that TalkOptions mod allows. Also note that a user may only change their own TalkPrefs and not those of other users. If the changes indicated are acceptable, the server alters the user's talk preferences and broadcasts the "style" message to all users in the context.

Descriptor Objects

There are a couple of JSON objects that are used to carry standard bundles of information in the representations of certain mods and in some messages. These are not mods or messages themselves, but simply bundles of data.

Style Descriptor

The style descriptor contains information for the rendering of text.

Representation


        type:"style",

        color:?STR,

        backgroundColor:?STR,

        borderColor:?STR,

        textStyle:?STR,

        icon:?STR

where:

color, if given, is the name of the text color.
backgroundColor, if given, is the name of the text background color.
borderColor, if given, is the name of the text border color.
textStyle, if given, is an HTML CSS style string for a text element.
icon, if given, is the URL of a marker icon.

All elements are optional. Color names are standard HTML color names.

Style Options Descriptor

The style options descriptor contains a collection of text style information. It represents a range of permitted style values for use in preference setting and display.

Representation


        type:"styleoptions",

        colors:[STR],

        backgroundColors:[STR],

        borderColors:[STR],

        textStyles:[STR],

        icons:[STR],

        iconWidth:?INT,

        iconHeight:?INT

where:

colors, if given, is a series of permissible text color names.
backgroundColors, if given, is a series of permisslbe text background color names.
borderColors, if given, is a series of permissible text border color names.
textStyles, if given, is a series of permissible text style strings.
icons, if given, is a series of permissible marker icon URL strings.
iconWidth and iconHeight, if given, are the common width and height, pixels, of the icons specified by the icons attribute.

All elements are optional.

Elko: Client Mods

The Basic Mod Set: Client View

Cartesian

Representation

Messages

move

Census

Representation

Messages

census

Chat

Representation

Messages

say

push

Dictionary

Representation

Messages

delvar

setvar

Image

Representation

Note

Representation

Messages

edit

NoteMaker

Representation

Messages

makenote

TalkOptions

Representation

TalkPrefs

Representation

Messages

style

Descriptor Objects

Style Descriptor

Representation

Style Options Descriptor

Representation