Help

Using the JavaScript Paragrapher

Start Page

When you run jsParagrapher.jar, you will see a splash screen while the program loads, after which you will see the text input tab, shown below. This is where you will add your text.

The start page

You will see that at the top of the page are two <menus (1) & (2) and at the bottom of the page two buttons (3) & (4).

Button (3) will be inactive when you first open the program. It will only be active when you have successfully added a text and left this page. When it is active you can click it at any time to save your work as a .jpz file. This is an xml file which can be opened by the JavaScript Paragrapher and is useful for saving your work or keeping a backup copy after you have finished making the exercise. An example can be found in the sample folder that is included in jsParagrapher.zip.

Button (4) allows you to quit the program at any time. However you will lose your work if you have not saved it.

Clicking on the menu (1) or using the shortcut alt+F will open a menu containing familiar file options.

File Menu

When you open the program, not all options will be available. For the options that are available, you can either use your mouse to click on them or use a key combination. Most of these are self-explanatory.

Option (1) enables you to open a .txt file to use for the exercise. This is useful if you already have a text on your computer that you have saved from elsewhere. This option can only be used at this stage of the program.

Option (2) enables you to save the text input as a .txt file. This can be handy if you haven’t finished working on the text that you want to divide into paragraphs,, for example if you need to stop work and do something else. This option can only be used at this stage of the program.

Option (3) enables you to open a .jqz file that you have already made. This is available at any stage of the program, although most of the time you will use it when you start the program.

Option (4) allows you to save a .jpz file that you have opened. This is not available unless you are working on a file that you have already created.

Option (5) is used to save your work as a .jpz file in the same way that the Save button does. You will be shown a file chooser to decide where to save the file and what name to give it.

Option (6) allows you to exit the program in the same way that the Exit button does. You will lose any unsaved work.

Clicking on the menu (2) or using the shortcut alt+H will open a menu containing familiar file options.

Help Menu
Option (1) opens a copy of this information in your web browser.
Option (2) provides opens an online feedback page where you can make comments and suggestions about the program.
Option (3) provides information about the program, in particular the version.

Looking at the rest of the screen you will see that there are two input boxes (1) & (2) for text entry, together with a button (3).
Adding Text

Input box (1) is used to give your text a title. This is important – you can’t make an exercise unless you give it a title. This will also appear on the title bar of the web page that you make.

Input box (2) is used to enter the text that you are going to use. You can type your text or paste it in using the usual keyboard shortcut (Ctrl+V or Command+V depending on your operating system).

The format of your text is very important. You need to separate your paragraphs by inserting a blank line. If you don’t do this, the program won’t realise that you want to insert a paragraph.

The software will do it’s best to break the text up into sentences. However, punctuation in English is a bit of a nightmare. For example, full stops may be used to end a sentence, as part of an abbreviation (U.A.E.), as part of a shortened form of a word (Rev., et al.), in numbers ($23.80) or as ellipsis (… ). This makes the task of splitting text into sentences quite tricky. The program has been designed to do its best and should deal with the majority of cases (numbers, abbreviations, ellipsis, etc), but there are occasions when it will fail – for example if you have a question mark in parentheses for any other reason than as a final punctuation mark. If your text includes a “?” for some reason (no, I’m not sure why you would want to do this), then it will cause a problem. There are other, equally obscure occasions when it will fail. Don’t worry though, you will be given the opportunity to edit the text to remove any problems that do occur.

Of course, all the copyright restrictions connected with the use of the text still apply, and you should consider carefully whether you have permission to use the text. Copyright is a complex area and copyright law varies from country to country.

Button (3) is the first stage in making the exercise. You click this when you are happy with the text and ready to move on.When you click it you will see a new screen, where you can preview the text.

Preview page

This screen breaks the paragraphs up into a numbered list of sentences (1). You can check through this to make sure that no problems have occurred. Each paragraph is separated by two lines of white space (2).

If you are not happy with the way the text has been split up, you can use button (3) to take you back to the text input screen. Make any changes that you need and then come back here to check it again.

If you are completely happy with the text, click button (4) to move on to the next stage. Make sure you are happy as you can’t come back to edit the text. Now you will be taken to the next page where you can start to add feedback for the user.

Tab 2 – Feedback

The page you are taken to has four active tabs. These tabs provide navigation for the rest of the program. You are now on tab 2 – Feedback (1) which is where you write the feedback that you want the students to get when they have made a correct or incorrect choice.

Feedback

You will see two sentences which could be chosen to be the end of one paragraph (3) and the beginning of a new paragraph (4). The text input box (6) is where you add your feedback. The program will give you a reminder whether this is in fact where a paragraph begins, by outlining the text box in either red (wrong) or green (right) (5).

It is important to make this as helpful for the learner as possible. Simple feedback that just says “Yes, that’s right”, doesn’t really help the learner very much. Try to recreate the kind of feedback that you would give them in the classroom – feedback that will explain why something is right or wrong – so that they can be guided to making the correct choices and will enhance their understanding.

The numbered box (7) shows you which gap you are working on. You move between gaps by using the up and down arrows to the right of the number.

Use the tabs to move between the different stages of making an exercise. Clicking tab (2) Other Info will take you to form for adding additional details to the web page, for example contact details.

Tab 3 – Other Info

Tab (1) Other Info provides a form for adding some additional details to the web page, for example contact details.

Other info

For each item there is a check box (2). If you want to add an item you must first tick the check box. If you don’t add any information before ticking another check box, you will be warned that you have not filled in the required information.

You can use the Author box (3) to add your name to the exercise. It will also insert it in the meta author tag.

Use the Email box (4) to add a contact e-mail to the exercise. If you do this, the program will run some checks to make sure that you have entered a valid e-mail address.

Use the Date box (5) to add the date that you made the exercise.

Use the Text Source box (6) to add a reference for the text you have used. Remember that you need to comply with the copyright restrictions that apply to the text.

Use the Text URL box (7) to provide link to the original source of the text, or to information about the author of the text, etc. The requires a full URL and the system will check that the URL iis valid, although it will not check that the URL actually exists and is active.

Use the Next Page box (8) to provide a navigation button to enable the user to move to another page on your site. This should be a complete URL rather than a relative URL – again the system will check that you have entered a valid URL, although it will not check that the URL actually exists and is active.

Tab 4 – Fonts and Colours

Tab Fonts and Colours (1) provides the possibility to change some aspects of the appearance of the web page, if you are not happy with the default settings. The system provides web safe fonts, so there is a limited choice of fonts that can be used.
Fonts and Colours

Using button 2 you can set the size, colour and style of the title of the exercise.
Using button 3 you can set the size, colour and style of the instructions to the exercise.
Using button 4 you can set the size, colour and style of the feedback that the user gets.
Using button 5 you can change the background colour of the web page.
All the changes you make will be displayed in the preview area 6

Using button 7 you can set the size, colour and style of the title of the text.
Using button 8 you can set the size, colour and style of the text.
Using button 9 you can change the background colour of the text area.
All the changes you make will be displayed in the preview area 10

Tab 5 – Export Exercise

Tab Export Exercise (1) is used to create the final web exercise.
Export Exercise

Click on the Export button (2) when you are ready to make the exercise. This will open a file chooser for you to save the exercise in.htm format in a location of your choice. A good place to save it is in the html folder contained in the jsParagrapher folder; this is good because it already contains the .js and .css files that are necessary for the exercise to work successfully.

If you decide to save the .htm file in another folder, then you will need to copy the jParagrapher.js and jParagrapher.css files from the html folder contained in the jsParagrapher folder. Without these, the exercise will not work.

When you are ready, you can upload the files to your web server. You can upload as many exercises as you want to a folder, but you only need one copy of the jParagrapher.js and jParagrapher.css files in the folder. Each new folder, however, that contains a JavaScript Paragrapherexercise, will need a copy of these two files. This structure has been chosen as it is simplest to use.

If you want to organize your files differently, you can edit the htm file that you have made. lines 55-7 read:

<script src="jparagrapher.js">
</script>
<link rel="stylesheet" href="jparagrapher.css" />

These locations can be relative to the location of your.htm file, or you can use absolute links.