POPSCO - Display size adapter for SCOs

Version 1.04
By Claude Ostyn
Copyright © 2006, 2007 Claude Ostyn – All rights reserved

Overview

Often, online learning content requires a minimum display size to provide a good learner experience. However, SCORM does not currently define any way to specify that size. Content developers have been using popup windows to try to get around this limitation, but this often results in a proliferation of popup windows. A cascade of popup windows makes for a confusing user experience. POPSCO is a small add-on that can be used with any SCO to help ensure that the SCO will be displayed at the desired size, regardless of how a LMS displays SCOs. At the same time it tries to avoid opening unnecessary popup windows. It requires no modification to existing SCOs and works with SCORM 1.2 and SCORM 2004. Free use is allowed with attribution under a Creative Commons 2.5 Attribution-ShareAlike 2.5 license.

^ Top of page

Description

This is a "wrapper" SCO used to launch a "real" SCO at a specific display size in SCORM 2004 or SCORM 1.2. By default, it uses an automatic best fit behavior: If the window provided by the SCORM runtime environment is large enough to accommodate the desired size, it displays the SCO centered within that window, otherwise it displays the SCO in a new popup window.

An option to turn off the automatic best fit behavior allows forcing the use of the popup window regardless of of whether the SCO would fit in the current window. This option might be useful if you need a window with as few distracting elements as possible. If a popup window is used, it is sized to fit the desired display area size, automatically taking into account window borders, title bar, toolbars, etc. The popup window size and visible window features are always constrained by the size of the screen and by browser security features; for example, you cannot turn off the title bar. If the SCO was launched by the LMS in a popup window rather than a frame, another option allows growing the current window to accommodate the required display size, but of course this option works only if the current window is a popup window, not if it is a frame. The default settings for the various features can be modified by changing settings in the script, or by specifying parameters in the launch URL.

The high performance API relay works automatically with either SCORM 2004 or SCORM 1.2. It does not perform any conversion and is totally transparent to the SCORM API.

The actual SCO launched through POPSCO does not need to be modified in any way. Uses JavaScript only. No Java, no ActiveX, no Flash, no server-side component to activate. No nagging and no expiration date. Works offline as well as online. Subject to the usual browser security and popup control constraints.

^ Top of page

Summary of features

Every one of these features is settable by editing the value of a variable in the script. Most feature options can also be set by URL parameters without editing the script. The default settings should be appropriate most of the time.

^ Top of page

Live demo

This demo uses the actual popsco.htm file available for download below.

The demo launches a dummy SCO or a web page of your choice in a frame with a predefined viewport size, similar to the frame that a LMS might use as a "stage" in which to play SCOs. It uses a couple of dummy SCOs to keep the demo simple because the main issue here is display size, not the SCORM API. To try the demo:

  1. Choose a predefined dummy SCO or type in the URL for some arbitrary page, such as http://www.adlnet.gov
  2. Click the button "Launch"
  3. Click the button "Launch through POPSCO" and notice the difference.
  4. Try to change the desired display size to different values, then launch the dummy SCO again. Observe the result. For example, try 800 x 600.
  5. Try to minimize the popup window to see how POPSCO prompts the user and restores the popup window on demand.

The demo uses the POPSCO default settings, except for the desired size. If the desired display size is larger than the viewport in the frame, the dummy SCO or your chosen web page is launched in a popup window. If you have a popup blocker, turn it on and observe how POPSCO puts up a warning if it cannot open the window.

Sample page to launch:
Small SCO Big SCO
URL:
(size will be the frame size)
Desired display width:  height: 

Full screen demo

POPSCO can also be used to launch the SCO using the full screen. For security reasons, current browsers no longer support a true kiosk mode unless it is invoked by the user. The danger of hacking exploits simulating an entire desktop well enough to fool many users made this restriction necessary. To see how POPSCO can launch a page with a best effort to use the full screen in your browser, try the button below. This will launch the page selected in the demo above.

^ Top of page

How it works

The LMS launches the popsco.htm file as a SCO, with the URL of the actual SCO as a parameter. The popsco.htm file checks its parameters for the required display size, prepares the window, sets up a relay API object and and launches the actual SCO in the window. Depending on the required display size and the options in effect, the actual SCO may be launched in the original window or in a popup window. The actual SCO finds the relay API object and happily communicates with the API without realizing that it is not talking directly to the LMS.

POPSCO automatically sets up the appropriate relay API object regardless of whether the runtime environment is SCORM 1.2 or SCORM 2004 conformant.

^ Top of page

How to use

Integrating POPSCO into the SCORM package

The popsco.htm file must be added to your SCORM package. Small modifications of the manifest are also needed. The <resource> element that specifies each SCO is configured to launch the actual SCO through the popsco.htm file. In other words, you launch this SCO instead of the target SCO, and specify the target SCO as a parameter in the launch URL in the resource element in the manifest.

The example below illustrates typical changes to the manifest.

(before)
<resource ... href="mysco.htm">
  <file href="mysco.htm"/>
  ...
(after)
<resource ... href="popsco.htm?sco=mysco.htm">
  <file href="popsco.htm"/>
  <file href="mysco.htm"/>
  ...

Customizing with parameters

See the Options Reference section below script for a detailed descriptions of the customizable values. The preferred method of customization is through URL parameters; that way you can use the same unmodified popsco.htm for any number of SCOs. Note that the parameter names are case insensitive, but the values are case sensitive.

For example, to set the desired display size for a particular SCO, you can use something like

href="popsco.htm?sdw=600&amp;sdh=500&amp;sco=mysco.htm"

(Note how the & character separating the parameter name=value pairs is encoded as &amp; in the XML manifest file to avoid violating XML syntax.)

If the SCO requires parameters

If the SCO requires parameters of its own, you must make the SCO parameter the very last in the series of URL parameters, and set the parameterized URL for the SCO as the value for that parameter.

Example of resource href with parameters:
href="mysco.htm?foo=1&amp;bar=3"
Correct:
href="popsco.htm?sdw=600&amp;sdh=500&amp;sco=mysco.htm?foo=1&amp;bar=3"
This will work as expected because the URL used to launch the SCO will be mysco.htm?foo=1&bar=3, and POPSCO will process the sdw and sdh parameters for its own use.
Incorrect:
href="popsco.htm?sco=mysco.htm?foo=1&amp;bar=3&amp;sdw=600&amp;sdh=500"
This won't work as expected because POPSCO will not interpret parameters sdw and sdh as being for its own use. Instead, these will treated as parameters in the URL to launch the actual SCO and the SCO will be launched with the URL mysco.htm?foo=1&bar=3&sdw=600&sdh=500

Closing the popup window

Whether to close a popup content window automatically when a SCO finishes is a complicated issue due to differences in LMS behaviors. It has been made even more complicated by recent browser security features that prevent scripts from closing a window. For a more complete discussion of this issue, see the white paper At the end of the SCO: To close or not to close. This white paper also recommends a simple SCO design feature to provide a satisfactory user experience regardless of whether the window can be closed.

^ Top of page

Options reference

The only option you must specify is the relative URL for the SCO to launch, as illustrated in the examples above. Everything else is optional.

The options are controlled by ECMAScript global variables in the script of the file popsco.htm. Many options can be overridden by providing a parameter in the URL used to launch the file. If no URL parameter is shown in the table, the option can only be set by modifying the script.

Basic options

Variable Type URL parameter Default value Description
gsSCOurl string SCO   gsSCOurl is the URL of the actual SCO to display. The default value is an empty string, but a value must be provided either by editing the script or by using the SCO parameter in the URL.
gnSCODisplayWidth integer SDW 700 Width of stage area required by the SCO. This is the actual display area width, not including the window borders.
gnSCODisplayHeight integer SDH 525 Height of stage area required by the SCO. This is the actual display area height, not including window border, title, status bar, etc.

Advanced options

Variable Type URL parameter Default value Description
gbAllowScrolling boolean SCRL true If true and a popup window is created, the window displays scrollbars as needed. Note that when this option is used some browsers may display scrollbars even when not needed. Set to false only if you know that your content does not need scrolling, e.g. if it is a Flash movie.
gbCenter boolean CENTER true If gbCenter is true and a popup window is created, will try to center the popup window on the screen.
gbAutoFit boolean AUTOFIT true If gbAutoFit is true, use a popup only if the size of the stage window in which this is launched is smaller than gnSCODisplayWidth and gnSCODisplayHeight. If the current stage window is large enough, just replace this with page the SCO. Set to true for general use. Set to false if you really want to force a popup window every time.
gsBgColor BG string D0D0D0 Three hex digits that represent the background color to be used for this page. It is also used for the surround if the SCO is displayed in a centered frame within this page. This value should be in upper case.
gsFgColor string FG 000000 Three hex digits that represent the text (foreground) color to be used for this page if it shows a prompt to the user. Must contrast with gsBgColor. This value should be in upper case.
gbTryAutoGrow boolean   false Used only if gbAutoFit is true. If gbTryToAutoGrowLaunchWindow is true and this launcher page is launced in a top level window, it will try to grow the size of the top level window to fit the desired size. If that works, the SCO is launched in the same window. If that fails, the SCO is launched in a popup.
gbFillTheScreen boolean FILLSCREEN false If gbFillTheScreen is true, ignore width and height settings and try to set the window as close to the size of the screen as the browser will allow. This value overrides gbAutoFit.
gbAllowResize boolean RESZ true If true and a popup window is created, the window is resizable by the user.
gbAutoCloseWithPopup boolean AUTOCLOSE false If gbAutoCloseWithPopup is true, then this window will monitor the popup window and, if allowed, will attempt to close itself if it detects that the popup window has been closed. Has no effect if this page is opened in a frameset. Note that, depending on how this SCO was launched, this feature may not work in FireFox, due to the security rule "Scripts cannot close windows that were not opened by script." In IE it may cause a dialog box to come up to ask the user whether it is OK to close the window. Test with different browsers if you use this feature. It is better to end your SCO with a "passive" page than to try to make a SCO try to close the window.
gbAddParamsFromThisUrl boolean   true If gbAddParamsFromThisUrl is true, parameters passed to this SCO will also be passed to the launched SCO. It is strongly recommended not to change this setting. See gbStripPopupParameters below for filtering option. Note that if this option is false and any other parameters need to be passed in the URL specified by the SCO parameter, the entire value of the SCO parameter must be URL encoded.
gbStripPopupParameters boolean   true If gbStripPopupParameters is true, any of the parameters specified in this script will be stripped but the remaining parameters will be passed to the SCO that is launched in the popup window. The stripped parameters are specified in the array variable gaParamsToBeStripped.
gbMonitorPopupWindow boolean   true If gbMonitorPopupWindow is true and a dependent popup window is opened, this window will show a prompt telling the user that the actual content is running in another window, with a button to reactivate that window in case it got deactivated or minimized. When this page detects that the popup window has been closed, it will change its prompt from telling the user that there is another window to telling the user that the content is no longer available. This works only if the browser allows a popup window to open as a popup; it does not work if the window is forced to open as a tab within the same browser window.
gnPopupMonitorInterval integer   1000 gnPopupMonitorInterval is the number of milliseconds between checks that the dependent popup window is still open. This monitoring function is also required to enable automatic closing when the dependent popup is closed. This check takes very few CPU cycles, but if there is a performance issue the interval can be increased. Do not set this value to less than 100. If there is a real problem due to some conflicting code in the SCO or the LMS, the check can be turned off by setting gnPopupMonitorInterval to 0.
gbRecenterAfterGrow boolean   true If gbRecenterAfterGrow is true and gbCenter is false and the popup window had to be made larger than its original size, it is recentered moved to the top left corner of the screen to ensure that it is entirely visible. Unless those conditions are met this flag has no effect. Actual results may vary depending on the browser.
gbDebug boolean DEBUG false If true show explanatory alerts in case of trouble. Can be overridden by the URL parameter DEBUG with value "true" or "false"

POPSCO can be localized or adapted to your editorial requirements easily by modifying global variables that contain the user interface strings.

Variable Default value Description
gsCannotOpenPopup Cannot open a required popup window. Please turn off any popup blocker for this site. Text of alert message shown when POPSCO cannot open a popup window.
gsSCOInOtherWindow The learning content is displayed in another window. Text shown in the LMS-provided "stage" window for the SCO when POPSCO uses a popup window to display the actual SCO. This text is removed automatically when the popup window closes.
gsResetFocusLabel Bring the content window to the front Caption of the button shown in the LMS-provided "stage" window for the SCO when POPSCO uses a popup window to display the actual SCO. This button is removed automatically when the popup window closes.
gsNoSCO Nothing to launch. No SCO parameter specified. Text shown in the LMS-provided "stage" window when no actual SCO to display is specified in the gsSCOurl variable and no SCO URL is provided as a parameter.
gsPopupClosed This content is no longer available. Text shown in the LMS-provided "stage" window after a popup window used to display the actual SCO has been closed.
gsLaunchWindowTitle SCO Launcher Default title for the POPSCO frame. Usually invisible. Provided to support accessibility requirements because a frame title is usually never displayed. If Popsco creates a popup window, the title of that window will be the title provided by the SCO.
^ Top of page

Known issues

With IE6, if a popup window is opened the window includes an unnecessary "dead" scrollbar on the right. This is a known IE bug for which there is no robust workaround. You can eliminate that scrollbar by setting the scrollbars option to false, but if you do then the popup window never displays scrollbars, even if they become necessary. Suppressing this scrollbar could become a problem if the window ends up being too small, for example if the screen is too small for the requested window size. This extraneous scrollbar problem does not occur in FireFox.

POPSCO was tested with IE 7.0, beta 2, and found to be working as expected. Hoever, there is intense feedback from the IE user community about windowing features of IE 7, and it is anyone's guess what the final windowing behaviors will be. POPSCO tries for a safe, conservative approach, but no one will know for sure until the final version of IE 7 is released whether changes will be required.

With Firefox, it is not possible to suppress the status bar at the bottom of a popup window invoked by a script.

^ Top of page

Download

Please read the no nonsense License and terms of use below before downloading or using this tool. By downloading or using this software you signify your agreement with the license and terms of use.

Right-click here to download popsco.htm.

The following alternative download link is provided because scripting is not available in your browser: popsco.htm.

^ Top of page

License and terms of use

Creative Commons License This work is licensed under a Creative Commons Attribution-ShareAlike2.5 License.
USE AT YOUR OWN RISK
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

^ Top of page

FAQ

Which browsers does this work with?
POPSCO has been tested and found to work as expected with generic configurations of IE6 SP2, IE7 beta 3 and FireFox 1.5.06. It should work with most other modern browsers. Popup blocking must of course be turned off for the LMS site (see below for details). It will not work properly with antique browsers that do not support getElementById and the try/catch constructs in JavaScript. The popup and popup resizing features do not work with the default Opera settings because Opera opens popup windows as tabbed child windows in the same browser window and blocks script popups. Opera also opens by default with a maximized window that cannot be resized. The author welcomes any feedback on experiences you may have with other browsers (please send feedback to tools@ostyn.com).
Will this work with any SCO?
It works with any SCORM 1.2 or SCORM 2004 conformant SCO as long as the SCO uses the standard method to locate the SCORM API object. SCOs that do not use the canonical method specified in SCORM 1.2 or in SCORM 2004 may fail to locate the API relay in POPSCO. In particular, if a SCO uses the incorrect method of searching for the API from the top down that is found in some old templates, it will find the wrong API object and the results may be unexpected. Similarly, POPSCO will probably not work with an LMS that fails to pass the current SCORM conformance test suite because it does not instantiate the API object correctly. Interoperatibility requires conformance.
What if our users' popup blockers keep this from working right?
Configure the popup blockers to specify that content from your SCORM LMS site should be allowed to open popups, or switch to a LMS that does not use popups and turn off the POPSCO popup options. The autofit behavior in this utility works well in a LMS that uses only frames and no popups. POPSCO has been tested with and without the Google Toolbar in IE, with the Firefox generic popup blocking settings, and with the very user-unfriendly Opera popup blocker.
Will my content still pass the SCORM test suite with POPSCO?
Yes. If your content passes the conformance test suite without POPSCO, it should pass with POPSCO. However, see the note below. I say "should" pass rather than "will" because there is a small chance that some SCOs may have some internal bug that would only appear in the context of a "pure" popup window. The test suite pops up a window to launch SCOs. However, the SCO is actually launched within a frame in a frameset in that window, rather than directly in the window.
Note: As of 15 September 2005, there is still a bug in the current test suite for SCORM 2004, in the file CP_SCOWrapper.htm dated 3 November 2005. This causes the test suite to construct an invalid URL when launching a SCO with parameters. As as a result POPSCO does not get its launch parameters. This has been filed as issue #10194. It is unclear whether this Test Suite bug will get fixed. The workaround for the bug requires modifying the test suite to correct the URL that it constructs, which I find problematic--a test suite cannot be trusted if you have to modify it to make it work. On the other hand, the workaround fix is very localized and can be pointed out in an audit report where credibility is an issue.
Is this section 508/accessibility standards conformant?
There is nothing in this utility that inhibits accessibility as long as the browser or screen reader used can work with windows and frames and does not prevent JavaScript from running normally. The dynamic prompt that tells the user about the content running in another window is nice but not critical for operation. It is important that your SCO pass accessibility validation. Your SCO must also have a web page title since that will be required to identify the window or frame that contains the SCO. Feeback from accessibility experts on how to improve POPSCO for accessibility is very welcome.
Can I use POPSCO in a LMS implementation?
POPSCO may be useful for a quick fix in an LMS implementation to handle some difficult cases. It designed so that you can launch a POPSCO instance inside another POPSCO instance safely and without creating unnecessary windows. However, a LMS should probably be coded to handle this in a more generic way. If you use any of the code from POPSCO in your LMS implementation, attribution is required as per the Creative Commons 2.5 license, unless you arrange for a different license.
Why is this free?
Because a rising sea lifts all boats. This is a tool that many of our consulting customers can use, but it helps everybody to create standards conforming content that has a consistent, user-considerate behavior. Reinventing the wheel is not a good use of the time and resources that should be devoted to making the content more effective and enjoyable. This is to be shared, not hoarded.
Can I use this in a commercial product?
Yes, as long as you abide by the terms of the Creative Commons license and Terms of Use above. Please read the license for details. If you cannot abide by those terms, another licensing arrangement can be made.
If I include this in another product, will you support it?
Please read the Terms of Use above first. It is up to you to do the due diligence to verify that this utility works as required with your product. This may involve a detailed code review and extensive testing in the context of your product's life cycle and deployment environment. Free support is not available for this utility, but you can of course contact tools@ostyn.com to enquire about a consulting engagement. If you cannot abide by those terms, another licensing arrangement can be made.
Can I redistribute this without paying fees or royalties?
Yes, as long as you abide by the terms of the Creative Commons license. Please read the license for details. If you cannot abide by those terms, another licensing arrangement can be made.
I found a bug. How can I get it fixed?
Please report bugs to tools@ostyn.com. Your bug report will be considered for fixing the next release.
I need another feature. How can I get it?
Please contact tools@ostyn.com to inquire about a customized version or a consulting engagement to assist your developers.
I need technical support. How can I get it?
Please read the Terms of Use above first. Bug reports are welcome but no free private technical support is available. If you don't mind seeing your question and the response shared with the public, please inquire in the public SCORM forums at www.adlnet.gov. If you need private technical support, contact tools@ostyn.com to inquire about a consulting engagement for support.
Do you accept endorsements?
Yes. If this utility turns out to be useful to you, quotable endorsements are highly appreciated.
What if this code stinks/looks bad/is not sufficiently documented/does not meet our standards?
Sorry. Please read the Terms of Use above. If you need code customized to your requirements, contact tools@ostyn.com to enquire about a consulting engagement or about different licensing terms.