CMS Pro CS Course Developer Guide

Copyright © 2002 Vision Infosystems, LLC


Table of Contents

CMS Pro Extension Library (Widgets)
CMS Pro Logging Support
CMS API Functions Overview
   CMS_ApplicationName
   CMS_AskToContinue
   CMS_BookmarkFilename
   CMS_BookName
   CMS_CourseDir
   CMS_CourseID
   CMS_CourseName
   CMS_DataDir
   CMS_EmpID
   CMS_GetRecordedScore
   CMS_GoToModule
   CMS_IniFile
   CMS_IsCourseCompleted
   CMS_IsCourseModuleCompleted
   CMS_LogDir
   CMS_LogFileName
   CMS_Login
   CMS_LogInfo
   CMS_LogType
   CMS_MarkAsCompleted
   CMS_ModuleFileName
   CMS_ModuleID
   CMS_ModuleOrdinal
   CMS_ModuleOrdinalsForCourse
   CMS_PostLogToDB
   CMS_RecordScore
   CMS_ResponseDetail
   CMS_ReturnToCMS
   CMS_SetBookmarkFilename
   CMS_SetNextModule
   CMS_StampActivityDate
   CMS_UserID
   CMS_UserIsGuest
   CMS_UserName

Updated 10/15/2002

CMS Pro Extension Catalog

The CMS Pro system provides an extension catalog containing objects (widgets) that can be dragged onto your course books when using ToolBook II Instructor or Assistant. These objects contain API function capabilities necessary for your course books to work with the CMS Pro system, such as course completion and return to CMS.

To install the extension catalog so that you can access it from ToolBook Author mode, you first must copy the extension catalog files from the CMS Pro folder where they are installed (CMSProCSnn\Catalog) into the Catalog folder of the ToolBook installation. Next, with your course book open in author mode, you must load the CMS Catalog by selecting the View|Catalog menu item. This opens the ToolBook II Instructor Catalog viewer. Select the Open Catalog menu item on the viewer and select the "CMS Pro - Catalog" item from the list. The CMS Pro widgets become available for use.

The CMS Pro Catalog contain four different widget sets.

You access the different sets by clicking the desired set in the left pane and the widgets in the set will appear in the right pane. You can now drag the desired object from the right pane to your course book for your use. The widget object contains the necessary OpenScript code to accomplish its task. Developers are welcome to modify the OpenScript code to customize the object operation to meet your needs.

The Mark As Completed (Conditional)

The Mark As Completed (Conditional) widget object uses extended properties to assist the developer to properly set the conditions for achieving completion after the object has been placed in the course book. To access these extended conditions in author mode, highlight the object and select the Object|Extended Properties menu item from the ToolBook menu bar. This should bring up the Mark as Completed properties viewer. Select the Actions tab to set these properties.

The Mark As Completed (Conditional) Actions tab allows the developer to select the appropriate properties to achieve tha desired effects from the object. There is help information provided from this screen to explain the different options.

Table of Contents


CMS Pro Logging Support

The ToolBook II courseware development system provides the ability to log student actions and selections on each question object used in your course books. This logging capability can work very effectively with the CMS Pro system. The native method for recording the question logging is to use text files on the student computer, or to a directed file location. CMS Pro provides the ability to capture that log information from the text files and place them into the CMS database as text blocks associated with the summary results for the course module. The CMS Pro CS system further parses the session summary to question item results data and stores them as data items in the Reponses table for detailed reporting and analysis. This section will describe the logging options and how to setup logging to work with CMS Pro.

To enable logging for your course book in author mode, select the Object|Lesson Properties menu item from the Instructor menu. This will bring up the Properties for Lesson viewer. You will make all necessary setting on the Native ToolBook tab of the viewer.

The following description of how to set these properties for CMS Pro starts at the bottom of the viewer with the File options section. This section is left blank to work properly with CMS Pro. The text-based logging files will be temporarily placed in the Windows temp file. CMS Pro will take the data from the text file and put it into the CMS database and the text version becomes unneeded.

The Destination setting should be set to "Course Management System" by selecting the drop-down arrow and picking it off of the list. If that option is not on your list, the Log to CMS=TRUE setting must be added to the Options section of the TBnn.ini file on your computer. See the CMS Pro Installation Guide for more details on this setting.

The Included data section offers you four options of logging content to add to your log entry. NOTE: The Session summary option is the only required option for CMS Pro operation. The four options are:

The final section to address is the type of log, Transcript format, Tab Separated format or no logging. To turn logging on for the book, the type of log setting must be changed from no logging to either Transcript or Tab Separated. The Transcript format is designed to present the log in a format easily readable in a text reader, such as Notepad. The Tab Separated format is designed to easily convert into data columns to be imported into a database or spreadsheet program such as Excel. For purposes of CMS Pro, either option is satisfactory. CMS Pro provides you the ability to review the logging data in the format that you selected.

After all of the necessary logging properties have been set on the lesson properties viewer, you may close the viewer and save the book to retain your settings. The next time the book is loaded, the logging functions selected will be operational. If you load this book separately from CMS Pro, you may be asked to enter your name to be placed into the log file. To review the log in CMS Pro, see the Review Activity function in the Admin module. Review the help information available there for more details.

Table of Contents


API Functions Overview

The CMS Pro system exposes several application programming interface (API) functions that you can use to enhance the functionality of your ToolBook applications. These functions can help gather details about the current user, such as the user's name, and various details about the course, such as the course name, book file name, and the course completion status.

In addition to providing information to your application at runtime, many of the CMS API functions also enable you to navigate between the modules (books) that make up a course, return to the Student.exe program at any time, and mark a course book module as completed at an appropriate location in a book.

Using OpenScript, you can make a call to CMS API functions in the same way used to call any other function. For example, you might provide a button in a course module that takes the user to the next module, as in the example shown below:

to handle buttonClick
     go to page "Main Menu" of book CMS_ModuleFilename("Next")
end

Each of the CMS Pro catalog objects make use of one or more of the CMS API functions described in this document. Thus, you can call these API functions directly, or combine them to make new catalog objects for use in other ToolBook applications.

Several of the functions accept one or more parameters. To determine whether a function accepts parameters, look to the Syntax section of the function. If the function name is followed by left and right parenthesis "()" then the function does not accept or require parameters. If, however, there are one or more values within angled brackets "<...>" then the function accepts at least one parameter. Optional parameters are those contained within squared and angled brackets. For example, the "course ID" value in the following function is optional: CMS_GetRecordedScore([<course ID>]).

Note: For compatibility with versions of the CMS dating back to the original product from Asymetrix, CMS Pro recognizes the original CMS API function names, which began with the characters "ASYM_". This is true for most, but not all, of the API functions listed in this document. Examine the Syntax section of the function before using it in your books to determine whether the older "ASYM_" syntax is available.

Table of Contents


CMS_ApplicationName()

Syntax

CMS_ApplicationName()

ASYM_CMS_CMSApplicationName()

Parameters

None

Description

Gets the path and file name of the CMS application that ran the current instance of ToolBook II. The return value is also used by the CMS_ReturnToCMS() function.

Returns

In the CMS, returns a string that contains a full path and file name. If the current book instance is not run from the CMS, this function returns null.

Example

-- Gets the path to the student.exe module and
-- reads from an .ini file in the directory.

get CMS_ApplicationName()
cmsPath = ASYM_PathOfFile(It)
glossaryBook = GetIniVar("Books", "Glossary", (cmsPath & "courses.ini"))
go book glossaryBook

Table of Contents


CMS_AskToContinue()

Syntax

CMS_AskToContinue()

ASYM_CMS_AskToContinue()

Parameters

None

Description

Checks if a course uses default navigation. If so, the function then checks if the current module is marked as completed; if so, then checks if the course is actually incomplete. If the course is incomplete, the user should be prompted to continue with the next course. This function is called by the exit message handler.

Returns

True or False. True indicates that the course uses default navigation and the current module is marked as completed, but the course itself is actually incomplete, so the user should be asked to continue with the next module. False indicates that the course does not use default navigation or the course is completed, so the user should not be prompted to continue with the next course.

Example

-- Asks the user to continue
-- or go back to the CMS
if CMS_AskToContinue()
  request "You have not finished the course. Do you " &\
    "want to continue?" with "Yes" or "No"
  if It = "Yes"
    -- Goes to the next module
    ...
  else
    -- Otherwise, return to CMS

    get CMS_ReturnToCMS()
  end if
end if

Table of Contents



CMS_BookmarkFilename()

Syntax

CMS_BookmarkFilename()

ASYM_CMS_BookmarkfileName()

Parameters

None

Description

Gets the name of the file that contains the bookmark information for the current module of the course for the current user.

Returns

If successful, the function returns a string that contains a file name, or null. If an error occurs, a value is set for CMS_dbError() and calling CMS_dbOK() returns false.

Example

bookMarkFile = CMS_BookmarkFileName()

Table of Contents


CMS_BookName()

Syntax

CMS_BookName()

ASYM_CMS_BookName()

Parameters

None

Description

Gets the name of the book that the CMS defines as the current module.

Returns

A string that contains a file name (not including the path).

Example

bookName = CMS_BookName()

Table of Contents


CMS_CourseDir()

Syntax

CMS_CourseDir()

Parameters

None

Description

Returns the directory path string for the location of the course books as specified for the CMSAModules setting of either the CMS.ini or TBnnR.ini files. This function can be used in place of the full path during the assignment of course modules to a course. CMS will then use the return value for locating the course books on the local computer or network. Therefore, when necessary to move the location of the course books, changing the setting in the ini file will allow CMS to find the new location without having to update each course module file location in the database.

The setting in the ini file looks like the following:

   [Paths]

   CMSAModules=D:\CMSPRO\COURSES

If this setting exists in the TBnnR.ini file, it will be used in place of the setting in the CMS.ini file. See the CMS Pro installation documentation (Install.pdf) for more details about these settings.

Returns

A string that represents the directory path for the courses as specified in the CMS.ini or TBnnr.ini file. If no course directory path is specified in either ini files, the function returns null.

Example:

When assigning a course book as a module of a course, the course file name and its path are entered into the CMS Pro Admin module. The following shows an example of how to use this function instead of the hard path.

  File: %cms_coursedir()%Book1.tbk

Table of Contents


CMS_CourseID()

Syntax

CMS_CourseID([<module ID>])

ASYM_CMS_CourseID([<module ID>])

Parameters

<module ID> The CMS-assigned ID number for a course module. If null, the module ID of the current module is used by default.

Description

Gets the course ID for the current course run by the user of the CMS or for the specified module ID. The course ID number is assigned to the course by the CMS. Each course has a unique ID.

Returns

A number that represents the ID of the current course. If no course is running, or if the specified module ID is invalid, the function returns null.

Table of Contents


CMS_CourseName()

Syntax

CMS_CourseName()

ASYM_CMS_CourseName()

Parameters

None

Description

Gets the title of the current course run by the user of the Student Access application (STUDENT.EXE). This value is automatically set by the Student Access application when the user selects a course.

Returns

When called from a course module, the function returns the name of the course as defined in the CMS Pro Administration application.

Example

courseName = CMS_CourseName()
text of field "Course Title" of background "Main" of this book = courseName

Table of Contents


CMS_DataDir()

Syntax

CMS_DataDir()

Parameters

None

Description

Gets the directory that contains the CMS Pro database tables. This function reads the "CMSDataDir" item in the [Paths] section of the TB60R.INI file (or TB70R.INI for ToolBook II version 7, etc.).

Returns

A string that contains the path (including the trailing backslash "\") of the directory.

Example

-- Write notes from a student to a unique file
-- into the CMS Pro database directory.
ask "Please enter your question or comment:"
if it = null
  break
else
  userText = It
end if
dataDir = CMS_DataDir()
userID = CMS_UserID()
userFile = dataDir & userID & ".txt"
if ASYM_IsFile(userFile)
  openFile userFile
else
  createFile userFile
end if
writeFile userText to userFile
closeFile userFile

Table of Contents


CMS_EmpID()

Syntax

CMS_EmpID()

Parameters

None

Description

Returns the value in the EMPID column of the User database file for the current logged-in user.

Returns

A string that contains the current logged-in user's employee ID.

Example

get CMS_EmpID()

Table of Contents


CMS_GetRecordedScore()

Syntax

CMS_GetRecordedScore([<course ID>])

ASYM_CMS_GetRecordedScore([<course ID>])

Parameters

<course ID>  The CMS database ID of the course. If null, the score for the current course is returned by default.

Description

Gets the recorded score and maximum score for the course specified by <course ID>.

Returns

If successful, the function returns a comma-separated list of two numbers. The first number is the recorded score; the second number is the maximum score possible. If an error occurs, the function returns null and sets the CMS error state, which you can check using CMS_dbOK() or CMS_dbError().

Example

scoreData = CMS_GetRecordedScore(CMS_CourseID())
if item 1 of scoreData < minScoreToContinue of this book
  go page "lesson1"
end if

Table of Contents


CMS_GoToModule()

Syntax

CMS_GoToModule(<module> [,<course ID>])

CMS_GoToModule("first-incomplete")

ASYM_CMS_GoToModule(<module> [,<course ID>])

Parameters

<module>  A value of first, next, previous, last, or the ordinal number that specifies the module.

<course ID>  The ID of the course that owns the specified module. You cannot define course IDs; they are generated by the CMS. If null, the course ID of the current course is used by default.

<"first-incomplete">  Specifies navigation to the first incomplete module of the course for courses that use default navigation. If the course does not use default navigation, using the <"first-incomplete"> parameter acts like the first value for <module>.

Description

Navigates to the specified module. STUDENT.EXE calls this function in its CMS_GoToModule("first-incomplete") form when a course is chosen; the exit handler calls this function in the same form when the user exits a completed module of an incomplete course and chooses Yes at the prompt.

Returns

If successful, the function returns true; otherwise, it returns null.

Example

if CMS_GoToModule("next") = null
  beep 1
  request "Congratulations, you've reached the end of the course."
  get CMS_ReturnToCMS()
end if

Table of Contents


CMS_IniFile()

Syntax

CMS_IniFile()

Parameters

None

Description

Gets the name of the .INI file in which the CMS system preferences and configuration are stored. This file is located in the same directory as the CMS database files.

Returns

A file name.

Example

-- Get a custom setting from the CMS.INI file.
get CMS_IniFile()
mediaDir = getIniVar("Custom", "MediaDir", it)

Table of Contents


CMS_IsCourseCompleted()

Syntax

CMS_IsCourseCompleted([<course ID>])

ASYM_CMS_IsCourseCompleted([<course ID>])

Parameters

<course ID>  The course ID to check.

Description

Specifies if a course has been completed. This function checks the activity record of the course for the current user to determine the status.

Returns

If the course is marked as completed, the function returns true; otherwise it returns false. If an error occurs, the function returns null.

Example

-- If the course is completed, goes back to the CMS;
-- otherwise goes back to the first module which contains the
-- course navigation map
if CMS_IsCourseCompleted()
  get CMS_ReturnToCMS()
else
  get CMS_GoToModule("First")
end if

Table of Contents


CMS_IsCourseModuleCompleted()

Syntax

CMS_IsCourseModuleCompleted([<module ordinal>][,<course ID>])

Parameters

<module ordinal> The ordinal position in which the module is listed in the module list for the course. If null, the current module is used by default.
<course ID> The course ID to check. If null, the current course ID is used by default.

Description

This function checks the activity record of the course and module for the current user to determine whether the module is marked as completed.

Returns

If the course module is marked as completed, the function returns true; otherwise it returns false. If an error occurs, the function returns null.

Example

-- If the course module is completed, go to the next module.
-- Otherwise go back to the first module which contains the
-- course navigation map.
if CMS_IsCourseModuleCompleted()
  get CMS_GoToModule("Next")
else
  get CMS_GoToModule("First")
end if

Table of Contents


CMS_LogDir()

Syntax

CMS_LogDir()

ASYM_CMS_LogDir()

Parameters

None

Description

Gets the default directory for log files defined as the "DefaultLogPath" item in the [Paths] section of the CMS.INI file.

Returns

A string that contains the directory (if one has been set) or null if no setting exists.

Example

-- Gets the default log directory and writes information
-- to that directory
thePath = CMS_LogDir()
fileName = thePath & fileName
createFile fileName
writeFile MyStuff to fileName
closeFile fileName

Table of Contents


CMS_LogFileName()

Syntax

CMS_LogFileName()

ASYM_CMS_LogFileName()

Parameters

None

Description

Gets the name of the log file for the current CMS session (logged-in user, current module, current course). This function checks the LogFileNam field of the activity record to get the log file name.

Returns

A string that contains the CMS log file name.

Example

get CMS_LogFileName()

Table of Contents


CMS_Login()

Syntax

CMS_Login()

Parameters

None

Description

Gets the login name for the current user of the Administration or Student program.

Returns

A string indicating the current user's login name, as defined in the User database table.

Example

get CMS_Login()
request "Your CMS Pro login name is:" && It

Table of Contents


CMS_LogInfo()

Syntax

CMS_LogInfo()

ASYM_CMS_LogInfo()

Parameters

None

Description

Combines the CMS_LogFileName() and CMS_LogType() functions to get both the log file name and the log file type of the current CMS session (logged-in user, current module, current course). This function checks both the LOGFILENAME and LOGTYPE fields of the activity record to get the file name and type.

Returns

A two item value that indicates the log file name (item 1) and the type of log (item 2). The log types are: <none>, transcript, or responseData.

Example

get CMS_LogInfo()

Table of Contents


CMS_LogType()

Syntax

CMS_LogType()

ASYM_CMS_LogType()

Parameters

None

Description

Gets the log file type of the current CMS session (logged-in user, current module, current course). This function checks the LogType field of the activity record to get the type.

Returns

A value that indicates the type of log file: <none>, transcript, or responseData.

Example

get CMS_LogType()

Table of Contents


CMS_MarkAsCompleted()

Syntax

CMS_MarkAsCompleted(<status>)

ASYM_CMS_MarkAsCompleted(<status>)

Parameters

<status>  A value of true (completed) or false (incomplete). The status is then written to the Status field of the activity record as 0 (false) or 1 (true).

Description

Sets the completion status for the current CMS module. After the module is marked, the completion status for the entire course is recalculated. If all of the modules of the course are completed, the course is marked as completed.

Returns

If successful, the function returns true; otherwise, it returns false.

Example

-- Saves the score and marks course as completed
-- when the student finishes
get CMS_RecordScore(theScore, maxScore)
get CMS_MarkAsCompleted(true)

Table of Contents


CMS_ModuleFileName()

Syntax

CMS_ModuleFileName(<module>[,<course ID>])

CMS_ModuleFileName("first-incomplete")

ASYM_CMS_ModuleFileName(<module>[,<course ID>])

ASYM_CMS_ModuleFileName("first-incomplete")

Parameters

<module>  A value of first, next, previous, last, or the ordinal number that specifies the module.

<course ID>  The ID of the course that owns the specified module. You cannot define course IDs; they are generated by the CMS. If null, the course ID of the current course is used by default.

<"first incomplete">  Specifies navigation to the first incomplete module of the course for courses that use default navigation. If the course does not use default navigation, using the <"first-incomplete"> parameter acts like the first value for <module>.

Description

Gets the file name of the specified module. You can use this function to get the file name of a book to which you want to navigate using a transition effect. When you use this function to get the file name of a book for navigation, you must call CMS_SetNextModule() with the same parameters. This is not a problem with CMS_GoToModule(), which automatically sets up the pending information and navigates to the book.

Returns

If successful, the function returns a file name (if one is found). If the course is an open enrollment course and the <module> parameter does not specify a number, this function returns the first incomplete module of the course.

If an error occurs, the function returns null.

Example

-- Gets the name of the previous module so user can go back
bkName = CMS_ModuleFileName("Previous")
if CMS_SetNextModule("Previous")
  transition "slide left" to first page of book bkName
end if

Table of Contents


CMS_ModuleID()

Syntax

CMS_ModuleID([<module ordinal>][,<course ID>])

ASYM_CMS_ModuleID([<module ordinal>][,<course ID>])

Parameters

<module ordinal> The ordinal position in which the module is listed in the module list for the course. If null, the current module is used by default.
<course ID> The course ID to check. If null, the current course ID is used by default.

Description

Gets the ID number of the current module for the current CMS session.

Returns

The ID number of the current module, or null if no course is in use.

Example

-- Get the module ID to use in custom code
modID = CMS_ModuleID()
get setIniVar("CustomLog", "ModuleID", "g:\log.ini", modID)

Table of Contents


CMS_ModuleOrdinal()

Syntax

CMS_ModuleOrdinal([<module ID>])

ASYM_CMS_ModuleOrdinal([<module ID>])

Parameters

<module ID> The CMS-assigned ID number for a course module.

Description

Gets the ordinal number of the specified module ID. If no module ID is specified, the current module for the current session is returned. Module ordinals are specified from 1 to the number of modules in the course, and indicate the order of the modules for a course that uses default navigation.

Returns

An ordinal number, or null if no course is in use or the specified module ID is not valid.

Example

-- Show the "Previous Module" button only if there is a module to go back to.
to handle enterPage
  modOrdi = CMS_ModuleOrdinal()

  visible of button "Previous Module" = (isType("REAL", modOrdi) AND (modOrdi > 1))
  forward
end if

Table of Contents


CMS_ModuleOrdinalsForCourse()

Syntax

CMS_ModuleOrdinalsForCourse([<status>][,<course ID>])

Parameters

<status> If specified, set to TRUE or FALSE. The result of each value is described below:
    If TRUE, the function returns ordinals for completed modules only.
    If FALSE, the function returns ordinals for uncompleted modules only.
    If null or any other entry, the function returns ordinals for all modules.

<course ID> The CMS-generated ID number of a course. If null, the current course is used by default.

Description

Retrieves the ordinal numbers of the specified course ID. If <status> is specified, the ordinal numbers are limited to those that meet the conditions of the <status> parameter. Module ordinals are specified from 1 to the number of modules in the course, and indicate the order of the modules for a course that uses default navigation.

Returns

A list (OpenScript "stack" datatype) of ordinal numbers, or null if no course is in use or the specified course ID is invalid.

Example

-- Prompt the student with a list of uncompleted modules.
-- Navigate to the specified module if valid.

to handle buttonClick
  vModOrdiStack = CMS_ModuleOrdinalsForCourse(FALSE)
  ask "Please enter the next course section to take from the following list:" && vModOrdiStack
  if ASYM_ItemInList(It, vModOrdiStack)
    get CMS_GoToModule(It)
  else
    request "Invalid course section number. Please try again."
    break
  end if
end if

Table of Contents


CMS_PostLogToDB()

Syntax

CMS_PostLogToDB()

Parameters

None

Description

For course books with logging enabled, this function writes the current contents of the log file to the CMS Pro database. It is not necessary to use this function since CMS Pro automatically writes the log file's contents to the database when the course book is closed. However, you may wish to call this function to update the CMS Pro database so that you may monitor student activity from the within the CMS Pro Administration application.

Returns

True if the function succeeds, or False if it fails.

Example

-- Update the log in the CMS Pro database after leaving a page
-- that has a question.

to handle leavePage
  forward
  objList = ASYM_CollectWidgets(this page)
  step i from 1 to itemCount(objList)
    pop objList into obj
    if ASYM_WID_QType of obj <> null
      get CMS_PostLogToDB()
      break step i
    end if
end

Table of Contents


CMS_RecordScore()

Syntax

CMS_RecordScore(<score>, <maxScore>)

ASYM_CMS_RecordScore(<score>, <maxScore>)

Parameters

<score>  The number of points the student earned on the module.
<maxScore>  The total number of points possible for the module.

Description

Collects a total composite score of all the test items in the current book and saves it in the activity record for the logged-in user.

Returns

If successful, the function returns true; otherwise, it returns false.

Example

-- Saves score and marks course as completed
get CMS_RecordScore(theScore, maxScore)
get CMS_MarkAsCompleted(TRUE)

Table of Contents


CMS_ResponseDetail()

Syntax

CMS_ResponseDetail()

Parameters

None

Description

Provides the ResponseDetail setting of the Default section in the CMS.ini file for whether the Logging data will be stored in the RESPONSES table in the database.

Returns

True if the setting is set to TRUE, or False if it set to FALSE.

Example

get CMS_ResponseDetail()

Table of Contents


CMS_ReturnToCMS()

Syntax

CMS_ReturnToCMS([<AutoNavNext>])

ASYM_CMS_ReturnToCMS([<AutoNavNext>])

Parameters

<AutoNavNext> A logical entry (TRUE or FALSE) that may be used to defeat the auto navigation setting for the current course. If FALSE is used, the CMS will not auto navigate if the course is set to do so, and the student will return to the CMS Student application's main menu. If TRUE (or any other entry including null) and auto navigate is enabled for the course, then CMS will send the student to the next course module for this course.

Description

Use this function to enable the user to return to the CMS Pro Student program to review his or her records, take another course, or exit from the CMS.

Returns

If successful, the function returns true; otherwise, it returns false.

Example

-- If the course is completed, goes back to the CMS.
-- Otherwise goes back to the first module, which is the course navigation map.
if CMS_IsCourseCompleted()
  get CMS_ReturnToCMS()
else
  get CMS_GoToModule("First")
end

Table of Contents


CMS_SetBookmarkFilename()

Syntax

CMS_SetBookmarkFilename(<file name>)

ASYM_CMS_SetBookmarkFilename(<file name>)

Parameters

<file name>  The name of the bookmark file, include its path.

Description

Sets the name of the bookmark file for the student's session. This function sets the ResumeFile field of the activity record to the specified <file name> value.

Returns

If successful, the function returns true; otherwise, it returns false.

Example

-- Derive a custom directory and filename for the bookmark file.
-- Otherwise, ToolBook will store the bookmark file in the user's temporary directory.
-- It's typically fine to accept the ToolBook default, but there may be cases where
-- providing a different location and file name is needed.
userDir = "g:\cmsusers\" & CMS_Login() & "\"
bookMarkFile = userDir & CMS_CourseID() & "_" & CMS_ModuleID() & ".bkm"
get CMS_SetBookmarkFilename(bookMarkFile)

Table of Contents


CMS_SetNextModule()

Syntax

CMS_SetNextModule(<module> [,<courseID>])
CMS_SetNextModule("first-incomplete")

ASYM_CMS_SetNextModule(<module> [,<courseID>])
ASYM_CMS_SetNextModule("first-incomplete")

Parameters

<module>  A value of first, next, previous, last, or the ordinal number that specifies the module.

<course ID>  The ID of the course that owns the specified module. You cannot define course IDs; they are generated by the CMS. If null, the course ID of the current course is used by default.

<"first-incomplete">  Specifies navigation to the first incomplete module of the course for courses that use default navigation. If the course does not use default navigation, using the <"first-incomplete"> parameter acts like the first value for <module>.

Description

Sets the pending status of the CMS to the specified module. The CMS uses the pending status to keep track of where it should go the next time it enters a book. The CMS_EnterApplication() function compares the current module (book) to the pending module to determine if it has entered the expected application. Use this function in conjunction with CMS_ModuleFileName() to navigate between modules of a course.

Returns

If successful, the function returns true; otherwise, it returns false.

Example

-- Gets the name of the previous module and navigates back using a transition effect
bkName = CMS_ModuleFileName("Previous")
if CMS_SetNextModule("Previous")
  transition "slide left" to first page of book bkName
end

Table of Contents


CMS_StampActivityDate()

Syntax

CMS_StampActivityDate()

Parameters

None

Description

Forces the update of both the ACTIVITYSTAMP AND UPDATESTAMP fields in the ACTIVITY table with the system date from the database server for the current course module. The ACTIVITYSTAMP is used in the system to show the last date/time that the student was active with this course module. If the course module is completed, this becomes the completion date.

Returns

The function returns TRUE if the update was successful or FALSE is it was not.

Example

get CMS_StampActivityDate()

Table of Contents


CMS_UserID()

Syntax

CMS_UserID()

ASYM_CMS_UserID()

Parameters

None

Description

Gets the user ID of the user that is currently logged in for the CMS Pro session. This value is automatically assigned to each user by the Administration application (ADMIN.EXE) when the account is created and is unique for each user.

Returns

The function returns the ID number of current user, or null if no user is logged in.

Example

to handle enterBook
  text of field "userid" of page "intro" of this book = CMS_UserID()
  forward
end

Table of Contents


CMS_UserIsGuest()

Syntax

CMS_UserIsGuest()

Parameters

None

Description

Determines if the current student is logged in as a guest or as a regular student.

Returns

The function returns TRUE if the current student is logged in as a guest, or FALSE if logged in as a regular student.

Example

get CMS_UserIsGuest()

Table of Contents


CMS_UserName()

Syntax

CMS_UserName()

ASYM_CMS_UserName()

Parameters

None

Description

Gets the name (last, first, and middle initial) of the user logged in for the current CMS session.

Returns

A comma-separated list of three items that make up the name of the current user. The first item is the user's last name, the second item is the user's first name, and the third item is the user's middle initial. If no user is logged in, the function returns null.

Example

-- Welcome the user by their first name
to handle enterPage
  fname = item 2 of CMS_UserName()
  request "Welcome" && fname & "! Please take a moment to review the" && \
    "instructions on this screen before proceeding through the course."

end

Table of Contents


CMS Pro CS Course Developer Guide
Copyright © 2013 Vision Infosystems