What is the Masher?
         Next Topic

The Masher is a tool for automatically compiling batches of Hot Potatoes exercises into units. Imagine that you have five Hot Potatoes exercises that form a single unit of materials. You want to build HTML files from all the exercises, with the same colours and appearance settings; you also want to link the exercises together using the navigation buttons, and create an index file for the unit. The Masher will do that for you.

Here's how it works:

  1. Drag all the Hot Potatoes files you want to include in the unit into the main screen Files box . For each file, specify you will see a dialog box in which you can set the output (*.htm) file name, and some other options. For most of these options, you can accept the defaults for the moment, but make sure you choose the appropriate output type from the drop-down list.
  2. Use the arrow buttons to set up the right sequence for the exercises. Each time you move an exercise in the sequence, you will see the Next exercise file name settings adjusted appropriately.
  3. Specify the output folder for your unit. If you leave this blank, the program will use the folder in which the first page or exercise is located.
  4. Set the appropriate appearance options on the Appearance tab .
  5. Select which Navigation buttons you want to appear on the pages, and set their captions, on the Buttons tab.
  6. Optional, for advanced users only: If you use special Hot Potatoes source files for this project, set the appropriate folder for the program to find the source files. You can also use the source file tab to edit the code for the index page that the Masher will create.
  7. On the Index tab , set a title for the index page.
  8. Click on Build unit.

This is what happens next:

The Masher processes each file in turn, by launching the appropriate Hot Potato, loading the file into it, setting the configuration data, and compiling the Web page. Then, when all the Web pages are compiled, the program will create an index page for the entire unit. You can then view the index page, and access the exercises.

The Masher can also be used to upload files to your hotpotatoes.net account .


What's new in this version?

Version 6.2.3.1 of Hot Potatoes includes a new Show tooltips item on the Options menu. This menu item allows you to turn on and off the tooltip hints which appear when you place the mouse over a control in the Hot Potatoes interface. The image for on the menu item can be in a "down" or "up" position; when it's down (the default), tooltips will appear, and when it's up, they won't.

Version 6.2 of Hot Potatoes introduces support for SCORM 1.2 . You can now output a unit of exercises in the form of a SCORM package which can be imported into learning management systems that support SCORM.

In the process of adding this function, it became necessary to remap many of the shortcut keys on the Action menu. If you're in the habit of using the F-key shortcuts to access functions on this menu, please take a look at the new shortcuts by clicking on the menu itself.


Choosing files to include in your unit

The introductory page, What is the Masher? , explains the basic sequence of events in building a unit of Hot Potatoes materials automatically. This page and the following pages will explain the process in more detail.

The first thing to do in creating a Masher task is to specify the files you want to include in your unit. You can include two types of files:

1. Hot Potatoes data files, or

2. HTML files (such as presentation pages that you have created to go along with the exercises).

There are two ways to add files to the list:

1. Click on the Add files button, or

2. Drag and drop files from Explorer into the list box.

Each time you add a file to the list, a dialog box will appear ( shown here ). This dialog box allows you to specify an output file name (we recommend that you use the default that is provided). In the case of Hot Potatoes data files, you can also specify the output format (Standard, or in the case of JMatch and JMix, various drag-drop and flashcard options too). There is also a box for the "next exercise" filename, but you don't need to complete this -- the program will automatically handle this setting when you arrange the sequence of files. If you drop a list of files, you can click the OK to All button to accept the defaults and add all the files in one go.

You don't have to set the output file name or other options at the time you add the file -- you can always double-click on the file in the file list later to change any of these properties.


Setting up the sequence of files

Once you have loaded all the files you want to use into the list box, the next stage is to put them in the correct order. use the up / down arrows on the right of the list box to move files around until they are in the correct sequence. You will see the Next exercise file name settings change automatically as you move the files.

If you want to create a discontinuous sequence -- in other words, if you want an exercise to link on to a page which is not in the list -- then you can double click the file to change its Next exercise file name when its position is settled.

The last file in the sequence will not show a Next exercise file name by default. If you leave it blank, the button will lead back to the Index page, but you can add a URL if you wish.


Setting other options

Once you have decided on your file list, you can specify a number of other options:

1. The Output folder setting on the Files tab is the folder where all the exercises, HTML pages and the index will be placed when the unit is built. If you leave this blank, the program will use the folder where the first exercise or page in the file list is located. See The main screen: Files for more information on this tab.

2. The Appearance tab allows you to set the colours, font and background colour for the exercise output. This tab is essentially the same as the one in the Configuration screen of Hot Potatoes applications. By default, these settings will be used in all exercises which are output. However, if you have individual colour settings in exercise files and you want to retain these, select Use settings in configuration or data file at the top. Each exercise will then be compiled with its own appearance settings. See The main screen: Appearance for more information on this tab.

3. The User strings tab is an advanced option for use if you have modified the Hot Potatoes source files. See The main screen: User strings for more information on this tab.

4. The Buttons tab enables you to set up the navigation bar settings you will use in all your exercises. You can choose which navigation buttons to include, and set the captions for them. You can also choose to add navigation bars to any non-Hot Potatoes files you have included in your file list. See The main screen: Buttons for more information on this tab.

5. The Source tab enables you to choose the folder where the Hot Potatoes programs will look for source files when compiling the exercises. Most users will not need to make any changes here, but if you are an advanced user of Hot Potatoes and you have a special set of modified source files that you would like to use for your exercises, set the source folder appropriately. This tab also shows you the source file which will be used to create the unit index (this is actually a file called masher.ht_ in the source folder). You can edit the code of this page if you wish to change the appearance of the unit index file. Beware of changing any text in square brackets -- these are the placeholders used by the Masher when creating the index page. See The main screen: Source for more information on this tab.

6. The Index tab enables you to set the title and file name for the Index page. See The main screen: Index for more information on this tab.


Building a unit

When you have set all the options the way you want them, and you click on Build unit, the Masher starts its work. It processes each file in turn, by launching the appropriate Hot Potato, loading the file into it, setting the configuration data, and compiling the Web page. If the file is an HTML page, it will copy it to the correct output folder, adding a navigation bar if you have selected that option. Then, when all the Web pages are compiled, the program will create an index page for the entire unit. You can then view the index page, and access the exercises.

As the program works, you will see its progress in a progress bar. You should see the information about each file as it is loaded and processed.

NOTE: if you move the Masher executable file (masher.exe) out of the Hot Potatoes folder, it will not find the other Hot Potatoes programs, so the Build operation will fail.


Saving Masher files

Once you have set up and used a Masher configuration, you probably want to save it so that you can recompile the unit in the future, when exercises or pages are changed. Use File / Save or File / Save As to save the complete setup as a Masher file. Later, if you have made changes to the exercises or other pages, you can reload the Masher file and recompile the unit. Masher files are saved with the ".jms" extension

Note that you can also save complete sets of Masher files in a Masher batch file, so that you can compile several units all at once. See Building several units at once for more information on this.


Uploading files to hotpotatoes.net

The Masher is a key tool for managing your hotpotatoes.net account. When you upload an exercise to hotpotnet, you do so by exporting it from the Potato that created it, but sometimes you will want to upload a page or file that is not an exercise (such as a Word document or a PDF file). The Masher enables you to do this. Click on the hotpotatoes.net menu, and choose Upload file to hotpotatoes.net. You can then choose a file from your hard drive, and the program will upload it. If your file is a Web page (*.html or *.htm), then before uploading, the program will search for linked files (such as graphics or sound files) on your hard drive, and upload those too.

Please note that the hotpotatoes.net service is not free; you can create a demo account to test out the features, but if you want your pages to remain on the server for more than a couple of days, you will have to purchase an account. This is NOT the same as purchasing a Hot Potatoes licence, and purchasing a Hot Potatoes licence does NOT give you an account on the hotpotatoes.net server.


Creating a zip package

If you have inserted images or other media files into your exercises, it can be a little confusing trying to manage the project because the media files may be in different folders from your original data files or Web pages. To make it easier to move units of material around, complete with all their media, you can create single package in zip format using Create zip package in the Action menu.

When you click on Create zip package, you'll be asked to choose a location for your zip file. Then the program will create a zip file containing the following files:

1. An HTML file of each exercise, with all links to media files converted to simple file names.

2. A copy of each media file linked from each exercise.

3. An index page for your unit.

You can take this zip file and move it anywhere, and as long as you extract all of its files into the same folder, the unit should work.


Scorm 1.2 support

SCORM is a collection of standards brought together by Advanced Distributed Learning to enable the use of learning objects across a variety of learning management systems. Beginning with version 6.2, Hot Potatoes is able to provide support for SCORM 1.2 by creating a SCORM redistributable package which can be imported into a learning management system which supports SCORM 1.2. Each individual Potato can create a SCORM package for a single exercise, but the Masher can create a package for a complete unit. The package is in the form of a zip file containing the index, the exercise Web page, any associated media files, and some metadata and schema files. You can create a SCORM package by choosing Create SCORM 1.2 package from the Action Menu. Be patient: creating a SCORM package takes a long time!

When you insert it into your LMS, the exercise will be able to report back to the LMS about the actions taken by the student, including the time spent on the exercise, the student's score, and the way it finished (completed, incomplete, timed-out, etc.). Other information may be reported to the LMS as well, depending on the exercise type itself, and the capabilities of the LMS system. Please note that various learning management systems support SCORM in different ways, and to different degrees; some will store only the score and timing of the exercise, while others will store all the information submitted by the exercise. Hot Potatoes exercises submit quite a lot of information, including all answers chosen or checked by the student (including incorrect answers) and, for JCloze and JQuiz, scores for each individual item in the exercise.

The Masher enables you to create a SCORM package either with or without an index page. You should also consider whether to include navigation buttons or not. Generally, when you upload a SCORM package into an LMS system, it will show the materials to the student inside the context of a larger page, which contains navigation controls, so you may not want to include additional controls in the exercise, because they take up screen space, and also the may conflict with the navigation provided by the LMS. You'll need to experiment to find what works best for the LMS system you're using.

To learn more about SCORM, visit the Advanced Distributed Learning Website:

http://www.adlnet.gov/scorm/


Building several units at once

Building several units

Imagine that you are creating a large Website for a course consisting of 10 units. Each unit will have its own index, and its own sequence of exercises. As you create each unit, you also create a Masher file for it, so that you can build the unit easily.

When you have finished and built all ten units, your course is ready. However, you then decide that you want to change the colours for all the units, and you have also made some minor changes to some of the exercises. What you need to do is to rebuild all the units so that your Web pages are all up to date.

The Masher allows you to do this, using its batch file operations. Click on Actions / Batch processing, and you will see the Batch processing screen ( click here for a screenshot with more explanation). In this screen, you can create a "master" Masher file which is basically a list of all the other Masher files in the project. Then, you can load this master file into the batch processing screen and run all the build operations in one go.

This is how it works:

1. Set up the colours and output options the way you want them in the main Masher tabs.

2. Click on Actions / Batch processing to go to the batch processing screen.

3. Use the Add files button to add Masher files to the list. The order doesn't matter.

4. Choose options from the list of checkboxes as you want them. The checkboxes enable you to "lock" information in the main screen -- for example, if you want all your exercises to use the new output colours you have specified, but some of the Masher files involved have other colour settings in them, check the Lock colour information checkbox, so that when the Masher files are loaded in for processing, the colour settings inside them will be ignored, and your currently-selected colours will be used instead.

5. Press Go! to start the process.

Each Masher file will be processed in turn.


Saving Masher batch files

The Masher batch file screen has one menu item, File, which has standard file save commands. You can save and reload your batch file list and settings, just as you can save a standard Masher file. Masher batch files are saved with a ".bjm" extension. They are simple XML files.


Making a blank Web page

You may find that as you're building a unit of exercises, you'd like to include a Web page that isn't an exercise -- maybe a page presenting information, a reading text, or something like that. It's probably a good idea to make that page resemble the other pages in your unit, by using the same font and colour settings. You can create a blank page with the correct style settings incorporated into it using the Actions / Create blank Web page menu item. Choose a filename and location for your file (presumably the same folder as any other exercises in the same unit), and a page will be created, with a couple of placeholders for title, subtitle and content.

You can then edit the file in your own text or Web editor. Finally, if you include the file in your Masher unit, you can set the Masher to add navigation bars to it automatically.


Creating an external stylesheet

You may find it useful to create other Web pages based on the colours, layout and font settings used in your Hot Potatoes exercises. If you are building other pages, it's handy to have a CSS stylesheet based on the Hot Potatoes settings, and the Masher lets you create one. You can set up the colours etc. in the Appearance tab the way you want them, then press Actions / Create basic CSS stylesheet, then choose a file name and location, and your CSS file will be created.

You can also create a complete CSS stylesheet including all the settings in the hp6.cs_ source file, using Actions / Create complete HotPot stylesheet. This will use all the settings in the Masher interface to build a full CSS file that can be used instead of embedded CSS in the Hot Potatoes exercises.


The main screen: Files

Click on the graphic below to get more information about the features of this screen.


The main screen: Appearance

Click on the graphic below to get more information about the features of this screen.


The main screen: User strings

Click on the graphic below to get more information about the features of this screen.


The main screen: Buttons

Click on the graphic below to get more information about the features of this screen.


The main screen: Source

Click on the graphic below to get more information about the features of this screen.


The main screen: Index

Click on the graphic below to get more information about the features of this screen.


The file export settings screen

This screen appears when you add one or more files to the main screen Files box . Click on the graphic below to get more information about the features of this screen.


The batch processing screen

Click on the graphic below to get more information about the features of this screen. For more information about batch processing, see Building several units at once .


Translating the interface

Interface translation

Hot Potatoes allows you to translate its entire interface (menu items, tooltips, button captions etc.) into another language if you wish. You can make your own translation, load a translation file someone else has created, or reset the interface to the original English text. Every string of text (menu caption, tooltip, button caption, message etc.) can be translated, and the results saved in a file. You can then load this file to change the interface of the programs.

If you click on Options / Interface / Translate the interface, you'll see the interface translation screen. This is the same interface translation mechanism that is used in the rest of the Hot Potatoes suite, and you can get more detailed information on how to translate the interface, and load interface files, by consulting the Hot Potatoes Help file.


Registration
         Previous Topic

When you download and install Hot Potatoes, the Masher will only allow you to create units of up to three pages or exercises. To create larger units, you will need to get a registration key. THIS REGISTRATION KEY IS NOT THE SAME AS THE HOT POTATOES KEY. The Masher is a professional-level tool, so the key is only available to users who buy commercial licences for Hot Potatoes. When you buy a commercial licence for Hot Potatoes, you will receive a key for the Masher.

This is the URL for commercial licences for Hot Potatoes:

http://www.halfbakedsoftware.com

When you receive your registration key, click on Help / Register to enter it into the program.

Please note that a Hot Potatoes commercial licence is NOT the same as purchasing an account on www.hotpotatoes.net, and purchasing a Hot Potatoes licence does NOT give you an account on the hotpotatoes.net server.


Add and delete files buttons
Use these buttons to add and delete files from the list of Masher files in your batch operation.


Interface commands

Hot Potatoes allows you to translate its entire interface (menu items, tooltips, button captions etc.) into another language if you wish. You can make your own translation, load a translation file someone else has created, or reset the interface to the original English text. For more information on this, see the main Hot Potatoes Help file.


Add files
Use this button to bring up a dialog box where you can select files (Hot Potatoes data files or HTML files) to include in your unit. You can also drag and drop files onto the file list box.


Add navigation bar to HTML files
As well as including navigation bars in your Hot Potatoes exercises, if you have other HTML files (such as presentations or explanations) in your unit, you may also wish to add matching navigation bars to these files. The program will place the navigation bars in the file based on the position of the HTML open and close body tags.


Appearance settings
This is where you can specify the colours, font and background graphic for your exercises. It is identical to the configuration screen which does the same job inside each application in Hot Potatoes.


Appearance settings location
This setting determines where the Masher will find the appearance settings it uses when building the output exercises. If you select the first option, the settings for all exercises will be taken from the specifications below; if you choose the second option, then the Masher will use the particular settings specified inside the exercise file when building each exercise.


Add/Delete files

Add/Delete files (Batch screen)
These buttons allow you to add or remove Masher files in a batch operation in the Batch screen. Deleting a file does not affect the file itself on your hard drive; it just removes it from the batch list.


The Batch screen File menu
This menu contains New, Open, Save and Save As commands, so that you can save your batch operation as a Masher batch file (with a .bjm extension). You can reload a .bjm file at any time, and run the whole batch operation again.


Build indexes only
If you only want to build the index pages for these units, and not the exercises themselves, select this option. You might do this if you have made changes to the source file of the index pages to alter the appearance of the index pages, and you want to recreate them all.


Batch operations
This opens the Masher batch processing screen .


Build index only
Use this option if you just want to create (or recreate) the index page for the unit. Only the index page will be built; no other files will be created.


Build unit
Build all the exercises and HTML files into a unit, and create an index page. This is the main purpose of the Masher program.


Changing the order of files
You can change the order of files in your unit by selecting them and using these buttons to move them up and down in the sequence.


Delete file
Select files in the box and press this button to delete from from the unit. Note that this does not actually delete any files from your drive -- it just removes them from the Masher file list.


File list
This is the list of files to be included in your unit. You can change the order of the files by selecting one and using the arrow buttons on the right. You can also double-click on one of the files to change the output settings for that file. See Choosing files to include in your unit for more information on this.


OK Button
Press this button to accept the settings for the current file. You can always change these settings later by double-clicking on the file in the main screen Files tab .


OK to All button
If you open a number of files together, by dragging and dropping them into the files window or by selecting multiple files in the Add files dialog box, the File export settings dialog box will pop up for each file. If you want to use the same settings for all files, then you can just set them once and press OK to All; all files will then be added to the list box with the same settings.


Go!
Press this button to start your batch operation. The Masher will load and build each file in your list.


User-defined head code
Anything you type into this box will be placed inside the <head> tag of the output HTML page in any Hot Potatoes exercise. This is a simple way to add your own supplementary stylesheets, or extra JavaScript code, to the pages.


Help
This button opens the Help file.


Hot Potatoes file
This is the filename of the Hot Potatoes data file (or the HTML file, in the case of a presentation or explanation page) that will be used to create the output file in your unit.


Index page file name
By default, the index page for your unit will be saved with the filename "index.htm"; if you want to use a different file name (such as "index.asp", if you're using ASP on your site), then type it in here. Make sure you type a valid file name.


Index source file
This text box displays the current source file that will be used to create the Index page for your unit. If you are an HTML expert, and you have some experience in editing Hot Potatoes source files, then you may wish to customize the code to make the page look the way you want. Note that items in square brackets are the placeholders that will be replaced with data when the Index page is created, so it's not a good idea to alter or delete them. The buttons below enable you to save any changes you make, or to restore the default be reloading the current file from disk.
This option is for advanced users. If you don't understand it, then you probably don't need it.


Lock colour information
Each Masher file in a batch job will have its own appearance settings. However, if you want them all to use the same colour settings, then you can check this checkbox, and the Masher batch processor will ensure that any appearance settings in the individual Masher files are ignored in favour of the current settings in the main screen Appearance tab .


Lock index information
Each Masher file in a batch job will have its own index file settings. However, if you want them all to use the same settings, then you can check this checkbox, and the Masher batch processor will ensure that any index settings in the individual Masher files are ignored in favour of the current setting in the main screen Index tab .


Lock navigation button information
Each Masher file in a batch job will have its own navigation button settings. However, if you want them all to use the same settings for navigation buttons, then you can check this checkbox, and the Masher batch processor will ensure that any navigation button settings in the individual Masher files are ignored in favour of the current settings in the main screen Buttons tab .


Lock output folder information
Each Masher file in a batch job will have its own output folder settings. However, if you want them all to output to the same folder for some reason, then you can check this checkbox, and the Masher batch processor will ensure that any output folder settings in the individual Masher files are ignored in favour of the current setting in the main screen Files tab .


Lock source folder information
Each Masher file in a batch job will have its own source folder setting. However, if you want them all to use the same source folder settings, then you can check this checkbox, and the Masher batch processor will ensure that any source folder settings in the individual Masher files are ignored in favour of the current setting in the main screen Source tab .


Lock user strings information
Each Masher file in a batch job will have its own user strings settings. However, if you want to override this to force all the export operations to use the data that is currently in the main Masher window, then you can check this checkbox, and the Masher batch processor will ensure that any user strings settings in the individual Masher files are ignored in favour of the current setting in the Main screen User strings tab.


Masher file list
This is the list of Masher files which is included in your batch job. Each file represents one unit. You have to create each Masher file first, in the main part of the program, before you can include it in a batch job.


Navigation buttons
The navigation buttons settings are identical to those in the configuration screen of the Hot Potatoes programs. You can specify which navigation buttons you want to include, and what their captions are.


New Masher file
This creates a new blank Masher file. Most settings will be retained from the previous file, but the file list box will be emptied.


Next exercise file name
This is the file name of the next exercise or page in the sequence. It is used to create the Next Exercise navigation button when you build the unit. Generally, you don't have to change this -- the program will figure this information out automatically -- but if you do need to change it (for example if you wish to insert into the sequence a page that doesn't appear in the Index), then you can change it.


Open Masher file
This enables you to open a file you have previously saved.


Output file name
This is the file name of the page that will be created when you build the unit. It is created based on the file name in the box above. If you want to use a different file name for the output, you can change this.


Output folder
This is the folder where your unit will be created. If you leave this blank, the Masher will use the folder where the first file in your list is located. You can choose a folder by using the Browse button.


Output format
The Masher enables you to choose from one or more output formats for Hot Potatoes exercises, depending on the Hot Potatoes application itself. All applications can create standard output; and JMatch and JMix can create drag-drop output, and JMatch can also create a Flashcard format. Select the appropriate output format from the drop-down list.


Quit
Close the Masher program.


Save Masher file with a new name
Save the current Masher file with a new file name.


Save Masher file
Save the current Masher file with the current file name.


Source file folder
If you use different sets of Hot Potatoes source files for different projects, you may need to specify the location of your source files here. If you don't use different source files, then you can leave this blank, and the program will use the source files in the \source\ folder in the main Hot Potatoes folder.
This option is for advanced users. If you don't understand it, then you probably don't need it.


Unit title
This is the title that will appear on the Index page when your unit is created.


User-defined strings
User-defined strings are an advanced feature which are used in conjunction with modifications to the Hot Potatoes source files. If you modify the source files, and include certain placeholders in them (such as [strUserDefined1]), then the placeholders will be replaced by whatever you type in the appropriate text box here (or in the Hot Potatoes configuration screen). See the Hot Potatoes Help file for more information on using user-defined strings.


User strings settings location
This setting determines where the Masher will find the settings it uses for customized user strings when building the output exercises. If you select the first option, the settings for all exercises will be taken from the specifications below; if you choose the second option, then the Masher will use the particular settings specified inside the exercise file when building each exercise. See the Hot Potatoes Help file for more details on how User Strings customizations work.