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 .


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.


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.