Among the Concord Consortium's many projects are several that relate to understanding the submicroscopic world of atoms and molecules. Three major pieces of software have been developed to facilitate this understanding: The Molecular Workbench, The Molecular Viewer, and Pedagogica (which is a general activity creation tool). An online database which links to activities created using the previously mentioned software has also been made available.
This guide will give an overview of the available software and how to install it. All of our software is Java based, and some of it uses other core technologies that are freely available if not already installed on your system. To facilitate the launching of differing pieces of software for various activities, we use Java Webstart which provides for the ability to create a standard web page link which, when clicked, will launch the appropriate software from your hard drive (and even download it if necessary). These web page links are found in the molo database.
Outlined below is a detailed description of each piece of software, how to install it, and how to use it either with the database or as a stand alone application. There are also many instructions for how this is to be done in a multi-user environment, such as the typical school computer lab. For most people, the simple instructions outlined on the software downloads page will suffice. If you have trouble installing the software or want more detailed information on the variety of ways this software can be used, the information provided below should help. If you have further questions, please contact: firstname.lastname@example.org
Java with Java WebStart
Java is a platform independent programming language, which means that someone can write software on one type of machine and it should run everywhere regardless of the operating system. Because we want users of all platforms to have the ability to run our software, we chose to use this programming language.
In Java versions 1.4 and later, an additional technology called Java WebStart was included in the standard installation. This technology allows someone to write a small script, which is stored in a file with a .jnlp extension. Opening a .jnlp file with Java WebStart causes Java WebStart to download a java application (which is specified in the jnlp script) to the user's local WebStart cache folder, and then to run that application.
Some of our software is small enough that each user will end up with a copy of that application in their user's WebStart cache (i.e. The Molecular Workbench and the Molecular Viewer), but some software is too large (i.e. Pedagogica) to make this practical, so a separate installation must be done such that all users can share this common set of activities.
Quicktime with Quicktime for Java
Quicktime is a technology for playing many different media types. A quicktime player can play movies, gif animations, and even Macromedia Flash movies. Some of our activities have incorporated a Java version of the Quicktime player. For this Java player to work Quicktime needs to be installed on your system as well as some special Quicktime for Java classes that will allow us to interface our Java activities with the native Quicktime installation.
Not every one of our activities uses Quicktime, so some of them will run without installing Quicktime. However, it is highly recommended that this installation is done to avoid having some activities not function properly.
Java with Java WebStart
You will need to have Java version 1.4.1 or later installed on your system.
- For PC: Install the latest version of Java from Sun.This link will take you to a web page which checks to see if you have the latest installation and provide installation options.
- For Mac: Use the "Software Update" feature of OS X to update the Java version.
Quicktime with Quicktime for Java
- For PC: Install the latest version of Quicktime: http://www.apple.com/quicktime/download/win.html
- For Mac: Use the "Software Update" feature of OS X to update Quicktime.
Checking My Core Installations
Click this link to check that webstart is working and that you properly installed the necessary core technologies: Check Webstart and My Core Installations
If everything is working properly, you should see the following window appear. If the window does not appear, then Java WebStart is not working properly. See the troubleshooting sections below for possible reasons why WebStart is not working. The most common issues are either proxy or internet filtering related.
Note: (Windows only issue) If this window comes up but tells you that Quicktime is not installed properly, but you are sure you followed the installation instructions correctly, restart your machine and run the test software again. If this doesn't work, then it is likely that you have multiple versions of Java on your machine. To resolve this:
- Open the Add/Remove Programs control panel and remove all versions of Java.
- Move all java folders to the recycle bin. Typically there is only one Java folder in Program Files. You can also search for j2se and j2sdk to make sure all folders that contain these character sequences have been removed from your system.
- Repeat the installation process as outlined above: install Java, then Quicktime.
Once the core technologies described above have been installed, you can begin to use the molecular based applications, each of which is described below.
The Molecular Workbench
The Molecular Workbench is a piece of software , the primary function of which, is to run molecular dynamics models. Along with dynamic models, a Molecular Workbench page can display text, images, and questions. The editing environment for creating these pages has been modeled after a typical word processor, so no programming knowledge is necessary for the authoring of these pages. Teachers (and students) are encouraged to not only view premade activities, but to create their own.
What happens when I click on web page link for a Molecular Workbench activity?
- A file with a .jnlp extension is downloaded by your browser. On most machines this file is automatically opened and launched via Java WebStart.
- Java WebStart checks to see if the Molecular Workbench already exists in the user's WebStart cache. If not, the Molecular Workbench is downloaded to the cache. If the Molecular Workbench already exists in the cache, then WebStart will check if there is a newer version available on our server, and update the cached software if possible.
- Then, Java WebStart launches the Molecular Workbench and tells it to show the activity that was specified in the .jnlp file.
The Molecular Workbench can be launched as described above, but it can also be run independently of any specific activity. To launch the Molecular Workbench with a generic page of links to premade activities, or to use the Molecular Workbench to design your own activities, follow one of the two methods below:
- Via WebStart
- Download the MW.jnlp file by right-clicking (or ctrl-clicking) on this link: MW.jnlp
- From the menu that pops up, choose "Save Target as..." or the closest menu option to that which allows you to save that file to disk.
- Double-click on the downloaded file to launch the Molecular Workbench from your webstart cache.
- If this is to be used in a multi-user environment, make sure everyone has read and write permissions for this file.
- Without Webstart
- Download the following file: The Molecular Workbench
- If installing this in a multi-user environment, make sure the folder containing workbench.jar (and workbench.jar itself) has read and write permissions for all users so that the Molecular Workbench can update itself as necessary and cache some other files locally.
- Double-click on workbench.jar to launch the Molecular Workbench.
Pedagogica is a generic platform for authoring and delivering a variety of activities. It allows the author to customize in great detail the student/activity interaction. Programming knowledge is required to be able to author activities in this way, so, typically, Pedagogica is used only to launch pre-made activities designed here at the Concord Consortium. Because Pedagogica is a more generic tool, the software and all molecular related activities require about 35MB of disk space. Therefore, the bulk of this software is not kept in the individual user's Web Start cache folder.
What happens when I click on a web page link for a Pedagogica activity?
- A file with a .jnlp extension is downloaded by your browser. On most machines this file is automatically opened and launched by Java WebStart.
- Java WebStart checks to see if a small Pedagogica Launcher application exists in the user's Web Start cache. If not, the Pedagogica Launcher is downloaded to the cache. If the launcher already exists in the cache, then Web Start will check if there is a newer version available on our server, and update the cached software if possible.
- Then, Java WebStart starts the Pedagogica Launcher, passing the information about which activity to launch.
- The Pedagogica Launcher will search your drive in typical installation locations for the workspace.jar file inside of the PedagogicaActivities folder. If it finds this file, Pedagogica is launched and the activity specified in the original .jnlp file will be displayed. If it can't find the workspace.jar file, then a window will pop up asking you to either locate it yourself, or to download a new Pedagogica installation, after which the activity will be launched. (Note: If installing Pedagogica at this time, about 12 MB of files will be downloaded the first time you run an activity, causing a significant delay before the activity is displayed. You will only be asked once to either install or find workspace.jar. However, if it is not installed in one of the typical locations, then each user may be asked to locate the workspace.jar file the first time they launch a Pedagogica activity.)
Pedagogica can be launched as described above, but it can also be run independently of any specific activity. To launch Pedagogica so that a window allowing you to browse and launch Pedagogica activities appears, follow one of the two methods below:
- Via WebStart
- Follow the detailed instructions below for installing Pedagogica.
- One of the files that will be installed is called Pedagogica Activities.jnlp.
- Double-click on the installed Pedagogica Activities.jnlp file to launch Pedagogica.
- Without Webstart
- Follow the detailed instructions below for installing Pedagogica.
- Open the installed PedagogicaActivities folder and double-click on workspace.jar - the application for browsing installed Pedagogica activities.
Of the two pieces of Concord Consortium software mentioned above, only one is recommended for "pre-installation" - Pedagogica. The others will be installed in each user's Java Web Start cache folder the first time an activity using either the Molecular Workbench or the Molecular Viewer is launched via a web page link. The full Pedagogica installation is around 35 MB, so, it is recommended that this is installed prior to launching any Pedagogica activities. (Note: In a multi-user environment, if Pedagogica is not pre-installed, each user will end up with the entire 35MB installation, instead of sharing one installation located on the machine's hard drive.)
To install Pedagogica:
- Download and unzip the following file: Pedagogica Activities
- Inside the Pedagogica Files for Full Installation folder you will find three items:
- Read Me - for installation instructions
- Pedagogica Activities.jnlp - a Java Web Start script for launching Pedagogica so that a window allowing you to browse and launch Pedagogica activities appears. This can be used independently of web page links for running Pedagogica activities.
- PedagogicaActivities - a folder containing all the supporting software and files for running Pedagogica activities.
- Then just drag the PedagogicaActivities folder to one of our recommended installation locations. If you choose not to place the PedagogicaActivities folder in one of those locations, then a window will pop up the first time you try to launch a Pedagogica activity, asking you to either find the workspace.jar file (which is located inside the PedagogicaActivities folder) or to install Pedagogica. Once you have specified the location of workspace.jar you will not see this window again. (Note: In a multi-user environment, if the PedagogicaActivities folder is not installed in one of our recommended locations, each user will be asked to locate the workspace.jar file upon initial launching of the first Pedagogica activity.)
- Place the Pedagogica Activities.jnlp file in a convenient location if you would like to launch Pedagogica activities independently of using web page links.
- If you are installing Pedagogica in a multi-user environment, then you must set the permissions properly for both the PedagogicaActivities folder and the Pedagogica Activities.jnlp file. All users must have read and write access to these files.
As mentioned above, the Molecular Workbench can also be run as a separate application (i.e. not launched via web links). This can either be done via Java WebStart or by installing a separate version of this application outside of the Web Start cache.
To launch via Web Start without using a web page link:
- Download this .jnlp file by right-clicking (or ctrl-clicking) on the link and choosing "Save Target As..." from the popup menu: MW.jnlp (for the Molecular Workbench)
- Double-click on this downloaded file to launch the appropriate application.
- (Note: In a multi-user environment make sure to set the permissions properly for each of the .jnlp files. All users must have read and write access to these files.)
To launch without using Web Start and to install a version of the application separate from the user's Web Start cache (only recommended if Java WebStart is not functioning properly):
- Download this file: The Molecular Workbench
- Place the workbench.jar appilcation in a folder where you would like it to be installed.
- Double-click on workbench.jar to launch the application.
- (Note: In a multi-user environment workbench.jar and the folder where it is stored must have the permissions set so that all users have read and write access.)
Within the typical school environment where each machine is behind a firewall, http requests pass through a proxy server, internet filtering software is used for all data passing through the http port of the proxy server, and many different users use many different computers, some technical issues occasionally arise. Problems that tend to occur fall into four basic categories:
- Setting up Permissions so All Users Can Access Software Installed on the Local Hard Drive
- OS X Server Settings if Workgroup Manager is Used to Control Student Access
- Getting Web Start to Use the Right Proxy Server (Windows Issue Only)
- Getting Pedagogica to Use the Right Proxy Server
- Internet Filtering Software is Interfering with Java Web Start, Pedagogica, or Both
- Using a Proxy Server that Requires Authentication
Setting up Permissions so All Users Can Access Software Installed on the Local Hard Drive
All files and folders which are installed by dragging them to the hard drive after downloading them from our web site need their permissions set so that all users have read and write access to those files and folders. Below is a list of all the files and folders that would need their permissions set this way:
- PedagogicaActivities (folder)
- Pedagogica Activities.jnlp (file)
- MW.jnlp (file)
- workbench.jar (file and whatever folder this is stored inside - so create a separate folder for storing this file instead of just dragging it to, for example, Program Files or Applications, and place this folder where you want to store workbench.jar)
Depending on your operating system, the process for setting these permissions differs. If you need assistance in setting permissions, see the Guide to Setting Permission for Multi-user Environments.
You may want to create a CC Software folder and install all of the Concord Software there. Then you only need to set permissions on this one folder. For those schools where no access to the hard drive is allowed for security purposes this folder can be hidden so that users won't manually change or delete this folder. (Note: If the folder is hidden, you must place it in one of the recommended installation locations, so that users will not be asked to locate workspace.jar.)
OS X Server Settings if Workgroup Manager is Used to Control Student Access
If user access to the local machine is controlled using the Workgroup Manager software provided with the OS X Server, then you will need to do the following:
- Allow users to access the application "Java Web Start".
- Allow users to access UNIX tools.
Getting Web Start to Use the Right Proxy Server (Windows Issue Only)
Java Web Start should be able to automatically detect the correct proxy server to use. However, there are some instances when this doesn't happen and manual proxy information needs to be entered. If you find that Java Web Start is not working, it is a good idea to try typing in the proxy information manually.
Unfortunately, to use Java Web Start's GUI, this will need to be done once for each user*, so the user will need to open Java WebStart, edit the preferences, and manually enter the proxy information. See detailed instructions below:
- Open Java WebStart by either double-clicking on the Java WebStart icon that is on your desktop, or finding javaws.exe and double-clicking on that. This will launch the Java Web Start Application Manager.
- Choose the Edit->Preferences menu item, to bring up a screen that looks like:
- Then click on the "Network Settings..." button to bring up this window:
- Then click on the "Use proxy server" radio button and type in the appropriate information for your school.
* There is a way to set global preferences on the Windows platform so that each user does not need to enter this information:
- Determine the %SYSTEMROOT% by opening a console and typing: echo %SYSTEMROOT%
- If it doesn't already exist, create a directory at %SYSTEMROOT%/Sun/Java/Deployment (ex. for Windows 2000 this will be C:/WINNT/Sun/Java/Deployment)
- Create a file called deployment.properties using any text editor and type the following lines:
- javaws.cfg.proxy.httpport=port (where port = your proxy server port)
- javaws.cfg.proxy.http=host (where host = your proxy host IP)
- Then place this file in the directory you created above.
- Note: if an individual user sets these preferences by using the GUI method above, the user's preferences will override the global preferences. User preferences are stored in a text file also called deployment.properties, but it is stored in the user's home directory (ex. C:\Documents and Settings\ddamelin\Application Data\Sun\Java\Deployment).
Getting Pedagogica to Use the Right Proxy Server
Pedagogica will also need to know what proxy server to use. However, this needs to be entered once per machine, not once per user, and can be done by whoever is installing Pedagogica instead of having each student enter this information. The first time Pedagogica is launched it will pop up a window requesting the proxy server information. Enter the information and Pedagogica will store this for future use in a text file called command.properties.
If for some reason you need to use a proxy server, but Pedagogica doesn't request this information, you may need to create your own command.properties file by hand:
- Using a text editor, create a file called command.properties
- Add the following lines to this file:
- http.proxyHost=host (where host = your proxy host IP)
- http.proxyPort=port (where port = your proxy server port)
- Save this file into the PedagogicaActivities folder.
Internet Filtering Software is Interfering with Java Web Start, Pedagogica, or Both
Most schools have some sort of internet filtering software. Sometimes this software interferes with Java Web Start, Pedagogica or both of them.
Some typical results that indicate your problem may be due to internet filtering software:
- Java Web Start seems to hang and continually show a window which says "Checking new Version".
- Pedagogica repeatedly loses the connection and pops up a window asking if you want to reconnect.
Here are a few possible solutions :
- Tell the proxy/firewall/filtering to allow free access to the concord.org server. In other words have requests to and from any concord.org IP address bypass the proxy and internet filtering software.
- Set up a second proxy server within your school/district that does not have internet filtering and is only used by Java Web Start and Pedagogica (and any other safe applications that transfer data via the web, but are blocked by internet filtering)
- Use an outside proxy server that utilizes a different port than the one your proxy server is currently filtering. It is highly recommended that you set up your own second proxy if possible, because you don't have control over the stability of any publicly available proxy. Whoever is offering this publicly available proxy may at any time decide to no longer make it public or just stop running it.
To use a publicly available proxy server:
- Go to: http://www.stayinvisible.com/index.pl/proxy_list?order=port%20desc and choose a proxy that is close to you geographically and not using the same port your school is using for internet filtering.
- If webstart seems to be having a problem, follow the instructions above for manually entering this information into the Java Web Start preferences.
- If Pedagogica seems to be having a problem, edit (or create if not already present) the command.properties text file located in the PedagogicaActivities folder as described above, and change the proxy info to match the new proxy server you intend to use.
Using a Proxy Server that Requires Authentication
Some proxy servers require authentication, which often means that you have to input a user name and password to access the internet. Usually, this means that both Java Web Start and Pedagogica should request this information from you. In the cases where Java Web Start does ask for authentication and Pedagogica does not, then you need to modify a file called command.properties, located in your PedagogicaActivities folder. If this file does not exist, then create one using any simple text editor. (Be sure NOT to add the txt extension to the end of this file name).
- Open the command.properties file (or create one if necessary), and paste the following lines into it:
- Save this new command.properties file to the PedagogicaActivities folder.
If this solution works, Pedagogica should ask you for a user name and password, followed by the launching of your requested activity. If this doesn't solve your problem, then you may want to consider bypassing that proxy server altogether. See info on this above.
Typical Installation Flowcharts
Detailed Installation and Troubleshooting Flowchart for both Windows and OS X
show diagram in separate window
Recommended Installation Directories for Pedagogica
When determining a location for the PedagogicaActivities folder, it is recommended that it be installed in one of the following directories. If installed in a recommended directory, it can easily be found by the Pedagogica Launcher application which is launched when you click on a Java Web Start link in our database. If you decided to install other pieces of software from the Concord Consortium, then it is safe to place everything inside a folder called CC Software inside of one of the directories listed below.
Windows Recommended Installation Directories:
- root (ex, C:/)
- root/Program Files
- root/My Documents
- root/WINDOWS/All Users
- root/WINDOWS/All Users/Documents
- root/WINDOWS/All Users/Desktop
- root/Documents and Settings/All Users/Documents
- root/Documents and Settings/All Users/My Documents
- root/Documents and Settings/All Users/Desktop
- user.home/My Documents
- all of the above options but with /CC Software added to the end
OS X Recommended Installation Directories:
- root (ex, /)
- all of the above options but with /CC Software added to the end
Guide to Setting Permissions for Multi-user Environments
Windows 2000/XP (The screen shots are from Windows XP, but they are very similar to Windows 2000)
1. Right-click on the folder which is to have its permissions changed. This will bring up the following window. Then, click on the "Sharing" tab. 2. Click on the "Add" button. 3. You should now see this window. Type "everyone" as the group to add. 4. Select "Everyone" from the list of users and check all the permissions shown below.
Mac OS X:
1. Ctrl-click on the folder which is to have its permissions changed. This will bring up the following window. Then, click on the "Details" arrow. 2. For "Others" select "Read & Write" from the pull down menu. then click the "Apply to enclosed items..." button.