Class MacaoPersistence

This class is used to get the game score from the StorageManager and to open the save dialog in order to save the game score as a bookmark. It is also used to get the game score from the URL of the page, put it to the StorageManager and to restart the game.

Use the register methods to define the values, which are to be included in the saved game score. Use the methods setSaveDialogUrl() and openSaveDialog() to open the save dialog with the game score. Use the method closeWindowByOpener() to close the save dialog.

Use the methods getSaveDialogTitle(), getSaveDialogMessage() and getSaveDialogCloseButtonTitle() in the save dialog. This methods are providing internationalized texts, which where set by calling openSaveDialog().

Call the method openStartPage() to forward form the save dialog to the page with the StorageManager, if the save dialog is opened by a bookmark containing the game score. Call the method startGame() in the page with the StorageManager to start the game with or without a game score.

This constructor is used to create a MacaoPersistence object.

Use this utility method to calculate the number of bits, which is used to store an integer of a specified value.

Parameters

positiveInteger: Provide a positive integer, which size is to be measured.


Returns

Returns the number of bits, which is used to store this integer.

Call this method in the save dialog to close the save dialog.

In the browser, if a window was opened by another window, it is not allowed to close itself. But it must be closed from the window, which opened it. Call this method in the save dialog. It will find the owner window and will cause it to close the dialog.

Use method in the Save Dialog to get the Persistence object of the index frame, which opened the dialog.

Returns

Returns the persistence object, if it was found in the hierarchy of the opener windows and frames. Returns null, if the current window was not opened by another window using the method open.

Call this method in the save dialog to get the text for the close button title.

The title was provided calling openSaveDialog(). This way is choosen to provide the save dialog with internationalization support, because itself has no such support.

Returns

Returns the text for the close button title.

Call this method in the save dialog to get the text for the dialog message.

The message was provided calling openSaveDialog(). This way is choosen to provide the save dialog with internationalization support, because itself has no such support.

Returns

The method returns the message text.

Call this method in the save dialog to get the text for the dialog title.

The title was provided calling openSaveDialog(). This way is choosen to provide the save dialog with internationalization support, because itself has no such support.

Returns

The method returns the dialog title.

This method is called while loading a game score to open the current page of the score.

The method loads the page frameset URL to the start frame. The opener page name is added as URL parameter openerPage.

You can override this method to do something after the score is loaded but before the game is restartet.

Parameters

pageFramesetUrl: The URL of the frameset of the current page is provided.
openerPageName: The name of the opener page is provided. If the current page was not opened by another page, null is provided.
startFrame: The frame where the page is to be loaded.

Call this method to open the save dialog.

This method opens the save dialog. It provides the actual score of the game in the URL parameter score. So when the save dialog is bookmarked, the score is included in the bookmark.

Make sure to call the method setSaveDialogUrl() before to set the URL of the save dialog. This functionality has been separated, so the standard controllers page implementation can call this method without knowing the location of the save dialog of your game. If you have included the standard controllers page, you don't need to call this method, because it is called by the save menu item of the page.

The save dialog is opened as a new window. If the method fails to open the new window, it is probably hindered by a popup blocker. If the method detects that there is no new window, it displays a prompt dialog showing a popup blocker warning. The warning tells the user to deactivate the popup blocker in order to save the game. Currently there is NO problem with the standard popup blocker settings of the browsers. Normally a popup blocker detects unwanted windows, if there was no user interaction like a mous click before, which might have caused the opening of the window. But in our case the user has clicked in order to open the save dialog.

You can use the title and messge parameters to provide internationalized text.

If you call this method from another page than that one, which contains the persistence package, you need to provide a call back function, which opens a window. Copy the following source code to the calling page and provide the reference to the function with the last parameter. This is necessary to have a common behavior for different browser types.

function openWindow(url, name, parameters) {
	
	// open the window with the base path of the current page
	return window.open(getBasePath() + url, name, parameters)
}

Here is an example how you can call this method providing the just defined function:

// get storage manager frame
storageWindow = getStorageWindow()
			
// open save dialog providing the callback func.
storageWindow.persistence.openSaveDialog(
	600, 250, null, null, null, null, openWindow
)

Parameters

width: Provide the width of the save dialog in pixels.
height: Provide the height of the save dialog in pixels.
title: Provide the title of the save dialog. Provide null, if you want to use the standard title of the save dialog page.
message: Provide the message, which is to be displayed in the save dialog. Provide null, if you want to use the standard message of the save dialog page.
closeButtonTitle: Provide the title for the close button in the save dialog. Provide null, if you want to use the standard button title of the save dialog.
popupBlockerWarning: Provide the warning, which is to be shown, if the save dialog cannot be opened. Provide null, if you want to use the standard warning message, which is in English.
openWindowFunction: If you call this method from another page, provide a call back function to as specified above. If you call this method form this page, provide null.

Call this method in the save dialog, to forward to the page with the StorageManager, while a saved game is reloaded.

The method detects, if the save dialog is opened by a bookmark to reload a saved game or if it is opened by a running game to save the game score. If the save dialog is opened by a running game, the method does nothing. If it is not opened by a bookmark, it opens the page with the StorageManager and passes the game score as the URL paramter openScore. In the page with the StorageManager the method startGame() is to be called, in order to restart the game with the score.

Parameters

startPageUrl: Provide the URL to the page with the StorageManager. The URL has to be relative to the current page (Not relative to the basePath).

Call this method to register a storage value of type boolean.

Call this method, if you want a boolean value to be included in the game score, which you set to the StorageManager calling setStorageValue().

Parameters

valueName: Provide the name of the storage value.

Call this method to register a number storage value, which will be put to the game score with three decimal places.

Call this method, if you want a number value to be included in the game score, which you set to the StorageManager calling setStorageValue().

Parameters

valueName: Provide the name of the storage value.
signed: Provide true, if you want to include a signed number into the score. Provid false, if you want to include a positive integer.
maxLengthInBits: Provide the number of bits, which are to be reserved for the positive integer part of the value in the score. The sign bit is not included. You can use the method calculateLengthInBits() to calculate the number of bits for a maximum value. If the actual value exceeds the maximum or minimum value, it is cut to this value.

Call this method to register a game event to be stored in the game score.

Provide the name of the game event. Don't register game events, which are ever cleared, before a page is left. E.g. you have a game event SitsOnChair. The character has to leave the chair in order to leave the room.

See also setGameEvent() and setGameEvents().

Parameters

gameEvent: Provide the name of the game event.

Call this method to register a storage value of type integer.

Call this method, if you want an integer value to be included in the game score, which you set to the StorageManager calling setStorageValue().

Parameters

valueName: Provide the name of the storage value.
signed: Provide true, if you want to include a signed number into the score. Provid false, if you want to include a positive integer.
maxLengthInBits: Provide the number of bits, which are to be reserved for this value in the score. The sign bit is not included. You can use the method calculateLengthInBits() to calculate the number of bits for a maximum value. If the actual value exceeds the maximum or minimum value, it is cut to this value.

Call this method to register an inventory item, which is to be stored in the game score.

Call this method once for every item in every inventory. A game can have more than one inventory. But the standard page optional/controllers/inventory.html does only define one inventory with the name Inventory.

Parameters

inventoryObjectName: Provide the name of the inventory object, which may contain the item. Provide the name "Inventory", if you are using the standard inventory page.
itemName: Provide the internal case sensitive name of the inventory item. This must be the same name, which you use to create the inventory item during the game.
itemTitle: Provide the title of the inventory item.
imageUrl: Provide the image URL of the inventory item. The URL must be relative to the basePath.
subTitle: Provide the sub title of the inventory item. Provide null, if there is no sub title to be displayed.
maxQuantity: Provide the maximum quantity of the inventory item. Provide 0, if the inventory item has no quantity. The quantity is ever stored as signed value.
isDecimalQuantity: Provide true, to include three decimal places with the quanitity. Provide false, if the quanitity is to be stored as integer value.

Call this method to register a language for inclusion in the game score.

Call this method once for every language, which your game supports. Don't call this method, if your game is not internationalized.

Parameters

languageCode: Provide the code of a language like "en", "de", "fr", "es" etc.

Call this method to register a content page for inclusion in the game score.

Call this method once for each content page of your game. Don't call this method for frameset pages, controller pages or the top frameset page with the StorageManager.

Parameters

pageName: Provide the name of the content page. This is the case sensitive filename of the content page without extension.
pageFramesetUrl: Provide the URL of the frameset page belonging to the content page. The URL needs to be relative to the basePath. If you want to use the persistence package, each page needs its own frameset page. When the game score is reloaded, not the page is opened, but its frameset page. Include the package frameset.js in the frameset page.

Call this method to register a storage value of type String.

Call this method, if you want a String value to be included in the game score, which you set to the StorageManager calling setStorageValue().

Parameters

valueName: Provide the name of the storage value.
maxLengthInBytes: Provide the maximum number of characters, which can be stored in the game score. Keep in mind, that this space is ever reserved in the game score, even if the actual content is smaller or empty.

Call this method to set the version of the save configuration.

The version number is saved with the game score and checked when the game score is loaded. If the version number has changed, the loading of the game score is prevented and the user gets an error message. Increase this number each time, when you change the registration.

Its recommended to start with a version number of 8. This will reserve four bits for the version number. Its no problem to exceed this number of bits by a later version number. The default value is 0, which will include no version number in the game score.

Parameters

versionNumber: Provide the version number of the current registration calls. Provide 0, if you don't want a version number to be included in the game score.

Call this method to set the location of the save dilaog page.

Call this method before calling openSaveDialog().

Because a Macao installation can have more than one game, the position of the save dialog is the information, which game is saved in the bookmark. So the save dialog has no standard location in the directory structure. You are required to copy the master save dialog from the directory optional/controllers to your application directory. Then you need to adjust the links from start dialog to StorageManager page and vice versa. Do this by calling setSaveDialogUrl() in the StorageManager page and openStartPage() in the save dialog.

Parameters

saveDialogUrl: Provide the URL of the save dilaog page relative to the basePath.

Call this method in the page with the StorageManager to start a new game or restart a game with a provided game score.

The method checks the URL of the current page for the parameter openScore, which contains a game score. If it detects the parameter, it asks the user to restart the game using the score. If the user confirms, the game is restarted using the score. If the user doesn't confirm or if there is no score to be loaded, the method starts the game from the beginning using the firstPageUrl.

Parameters

firstPageUrl: Provide the URL of the frameset of the first page of your game. The URL needs to be relative to the basePath.
startFrame: Provide the frame, where the page is to be loaded.
showConfirmDialog: Provide true, if you want a confirmation dialog to be displayed, before a saved game is restarted. So the user can choose to use the saved score or start a new game, when the bookmark with a score is opened. Provide false, if you want the saved game to be started immediately, when the bookmark is loaded.