Design Document Client Side Overview

From BOARD18 Project WIKI
Jump to: navigation, search
This page has been updated to comply with Release 2.5.x of BOARD18.
Design Document edit

The client side application is divided into sections by page. In other words, the server can send a number of different pages to the client browser. Each such page will have its own associated JavaScript file(s) and its own associated CSS file. Pages that include PHP code will have the extension 'php'. Other pages will have the extension 'html'.

Currently I have implemented sixteen pages, but more may be be added as needed.


The Index Page

The index.html page is one of the two pages which is not password protected. It is the introductory page to BOARD18 and contains a welcome message. It is used for logging in to Board18 and for registering new players. It also contains player ID and password recovery functions. The index.html and access-denied.html page make use of a number of cookies to control the sign-in and security experience of BOARD18. These cookies are described on this page.

The Access-denied Page

The access-denied.html page is the other of the two pages which is not password protected. It is the page that handles unauthorized access to password protected pages. It has an access denied message but is otherwise identical to the index.html page.

The Main Page

The board18Main.php page displays a list of the logged in player's active games. The player can select any of the listed games to start a game session in that game or to link to the board18Misc page where miscellaneous service actions can be performed for that game. He can also select a link to the board18New page if he wishes to start a new game.

The View Page

The board18View.php page displays a list of all active games. The player can select any of the listed games to view the game session for that game.

The Admin Page

The board18Admin.php page contains a form that can be used to change the player's first name, last name, email address or password. It also has a special form to handle forced password changes. The left side of the board18Admin.php page is normally blank but for an admin level player it contains links to 3 other pages which can only be accessed by admin level players. And one other page that can only be accessed by admin or author level players.

The Players Page

The board18Players.php page is used to administer players. It can only be accessed by admin level players.

The Games Page

The board18Games.php page is used to administer game sessions. It can only be accessed by admin level players.

The Boxes Page

The board18Boxes.php page is used to administer game boxes. It can only be accessed by admin level players.

The BoxLoad Page

The board18BoxLoad.php page is used to load new game boxes from a browser to BOARD18. It can only be accessed by author or admin level players.

The Misc Page

The board18Misc.php page can be used to perform miscellaneous service actions on an in progress game session.

The New Game Page

The board18New.php page contains a form that can be used to create a new BOARD18 game session. It displays a list of the available game boxes and a list of the available players as aids to filling out the form.

The Map Page

The map page consists of the page header, the game board map (on the right) and the left sidebar containing the tile and token trays.
The following is an overview of its main features.

JavaScript Objects

The Map page uses a number of JavaScript objects to manage the data structures necessary for the game.
These objects are documented in detail here.

Main Menu

The main menu drops down from the header division. Actually this is true for most BOARD18 pages.
The WIKI page Board18Map6 has some details about the implementation of the main menu.

Selecting Trays

The left sidebar contains the active tray beneath a tray selection drop down menu.
The WIKI page Board18Map6 has some details about the implementation of the tray selection drop down menu.
Clicking on the name of a tray in this menu makes that tray the active tray.

Selecting Tiles or Tokens from Tray

The tiles or tokens in the active tray are displayed with a count of available items in the upper left corner. If the count is zero then the tile is greyed out and cannot be selected. Clicking on a tile or token in the active tray will select that tile or token and it will be highlighted with a red background.

Dropping Tiles or Tokens on Map

When a tile on the active tray is highlighted (selected), it can be dropped on a map hex by clicking on the hex. The tile will be automatically centered in the hex. The dropped tile has NOT yet been permanently placed and can be further adjusted (rotated) before it is.

When a token on the active tray is highlighted (selected), it can be dropped on a map hex by clicking anywhere on the hex. The token will be placed at the point that is clicked. The dropped token has NOT yet been permanently placed and can be further adjusted (flipped or moved) before it is.

Rotating Tiles

Clicking on a dropped tile before the move has been submitted will cause the tile to be rotated clockwise. There are also menu items and keyboard shortcuts that can be used to rotate a tile in this situation.

Moving (or Flipping) Tokens

Clicking on a dropped token before the move has been submitted will cause the token to be repositioned to the point of the click. There are also menu items and keyboard shortcuts that can be used to flip a token in this situation.

Submitting Moves

A move in progress will be submitted to the server database when the Accept Move menu item is clicked. A move in progress will be discarded when the Cancel Move menu item is clicked. These options are also provided on the right click context menu and with keyboard shortcuts .

Right Click Context Sensitive Menus

Both the BOARD18 map page and the BOARD18 market page use context sensitive menus and token selection canvases to enable players to specify their moves. Positioning for these is implemented using the following design principles.

  1. All positioning is based on the document. Thus the menu division and the token selection canvas are defined with the body as their immediate parent.
  2. A common docPos(event) function is provided which returns the position in the document of a mouse event. This function should work with any current browser.
  3. The positioning if a token selection canvas should be based on the position of the mouse event which displays the context menu not the mouse event which selects an item from this menu.
  4. Logic is provided to adjust positioning for menu and canvas instances that would otherwise overlap the right or bottom edges of the document.

A right or left click event on the game board in the Map page can cause a context menu to be displayed. Whether this menu is displayed at all and the selection of items in this menu are both dependent on the context of the event. All of the "context sensitive menu logic" that performs this function is contained in the board18Map5.js file. Special logic to handle hexes that contain multiple items is contained in the board18Map4.js file.

Keyboard Shortcuts

The Map page supports a number of keyboard shortcuts. A list of these shortcuts can be found here.
The logic to handle keyboard shortcuts is contained in the board18Map7.js file.

The Stock Market Page

The stock market page consists of the page header, the stock market chart (on the right) and the left sidebar containing the token trays.
The following is an overview of its main features.

JavaScript Objects

The Market page uses a number of JavaScript objects to manage the data structures necessary for the game.
These objects are documented in detail here.

Main Menu

The main menu drops down from the header division. Actually this is true for most BOARD18 pages.
The WIKI page Board18Market6 has some details about the implementation of the main menu.

Selecting Trays

The left sidebar contains the active tray beneath a tray selection drop down menu.
The WIKI page Board18Market6 has some details about the implementation of the tray selection drop down menu.
Clicking on the name of a tray in this menu makes that tray the active tray.

Selecting Tokens from Tray

The tokens in the active tray are displayed on the left. Clicking on a token in the active tray will select that token and it will be highlighted with a red background.

Dropping Tokens on the Stock Market

When a token on the active tray is highlighted (selected), it can be dropped on a market price box by clicking anywhere on the box. The token will be placed at the point that is clicked. The dropped token has NOT yet been permanently placed and can be further adjusted (flipped or moved) before it is.

Moving (or Flipping) Tokens

Clicking on the box containing a dropped token before the move has been submitted will cause the token to be repositioned to the point of the click. There are also menu items and keyboard shortcuts that can be used to move or flip a token in this situation.

Submitting Moves

A move in progress will be submitted to the server database when the Accept Move menu item is clicked. A move in progress will be discarded when the Cancel Move menu item is clicked. These options are also provided on the right click context menu and with keyboard shortcuts.

Right Click Context Sensitive Menus

A right or left click event on the stock chart in the Market page can cause a context menu to be displayed. Whether this menu is displayed at all and the selection of items in this menu are both dependent on the context of the event. All of the "context menu logic" that performs this function is contained in the board18Market5.js file. Special logic to handle boxes that contain multiple tokens is contained in the board18Market4.js file. See the Right Click Context Sensitive Menus section in the Map Page section of this document for more information on positioning these menus.

Keyboard Shortcuts

The Market page supports a number of keyboard shortcuts. A list of these shortcuts can be found here.
The logic to handle keyboard shortcuts is contained in the board18Market7.js file.

The Snapshot List Page

The board18SnapList.php page will display a list of all of the snapshots that have been taken for the game so far. This list will be ordered with the most recent snapshots appearing first. And it will become paginated when the number of snapshots becomes large enough. Clicking on the "Snapshot Name" for a given snapshot will bring up the board18SnapMap page for that snapshot.

The Snapshot Map Page

Like the map page, the snapshot map page (board18SnapMap) consists of the page header, the map board (on the right) and the left sidebar containing the tile and token trays. This page cannot be used to modify the game. And it does not support keyboard shortcuts or right click context menus. This page is mostly a subset of the map page which is described above.

The Snapshot Stock Market Page

Like the stock market page, the snapshot stock market page (board18SnapMrk) consists of the page header, the stock market chart (on the right) and the left sidebar containing the token trays. This page cannot be used to modify the game. And it does not support keyboard shortcuts or right click context menus. This page is mostly a subset of the stock market page which is described above.