cwpuzzle.js - A crossword puzzle JavaScript framework

cwpuzzle.js provides a framework to present a crossword puzzle to the visitor of a web page. It handles the presentation of the puzzle and the interaction with the user.

cwpuzzle.js can be styled with CSS3. It tries to hard-wire any design decision. They are externalized in css. A properly working sample css is enclosed.

cwpuzzle.js is multilingual. This means it can be used with any language since the module allows any texts to be defined externally. All labels and such can be passed in via the respective methods. Fall-backs in English are used if no special value is provided.

Any artificial restrictions should have been avoided. Thus it is possible for instance to place several puzzles on one page.

Prerequisites

cwpuzzle.js requires that JQuery is loaded. It has been tested with version 1.7.2 but older versions might do it as well.

Elements on the Page

cwpuzzle.js supports the following elements which can be added to the HTML page:

• The field containing the rectangular puzzle to be filled.
• Clues for the words in across direction.
• Clues for the words in down direction.
• Controls (buttons) to request functionality.

The elements are included in the container which is specified at invocation. The clues and controls are optional. You decide what you need.

Usage

To start with you need to include some lines in the head of your HTML page:

<script src="jquery.min.js"></script>
<script src="cwpuzzle.js"> </script>
<link rel="stylesheet" type="text/css" href="cwpuzzle.css">

Note that JQuery can be included via CDN. See the samples for this technique.

The Function CWPuzzle()

The module cwpuzzle.js defined a single function CWPuzzle() which contains everything needed. This function creates a JavaScript object for the crossword puzzle and inserts a table for it. To start with you need a container, e.g. a div. The you can call the function CWPuzzle() to populate it:

<div id="my-puzzle"></div>
<script>
  CWPuzzle('#my-puzzle', 5, 3);
</script>

CWPuzzle() takes three arguments.

• The first argument is a JQuery selector pointing at the container element under which the field should be inserted.
• The second argument is the width of the field.
• The third argument is the height of the field.

The function returns a JavaScript object which can be used to invoke the methods described below.

The Method across()

The method across() adds a word across to the field and clues. It takes the following arguments

• The x coordinate to start with. This is 1 at the left border.
• The y coordinate to start with. This is 1 at the upper border.
• The word to be added. It usually contains letters only. They are translated to upper case internally.
• The clue associated with the word.

Note, that since the clue numbers are calculated automatically the clues have to be specified in ascending order.

The method across() returns the CWPuzzle object.

CWPuzzle('#my-puzzle', 5, 3)
    .across(1, 1, 'eta','greek letter')
    ...;

The Method down()

The method down() adds a word downwards to the field and clues. It
takes the following arguments

• The x coordinate to start with. This is 1 at the left border.
• The y coordinate to start with. This is 1 at the upper border.
• The word to be added. It usually contains letters only. They are translated to upper case internally.
• The clue associated with the word.

Note, that since the clue numbers are calculated automatically the clues have to be specified in ascending order.

The method down() returns the CWPuzzle object.

CWPuzzle('#my-puzzle', 5, 3)
    .down(1, 1, 'ervin','Second name of Knuth')
    ...;

The Method addAcrossClues()

The method addAcrossClues() adds the across clues to a container
element on the page. It takes the following arguments

• The JQuery selector pointing to the container for the across clues.
• Optionally the label for the across clues.

The method addAcrossClues() returns the CWPuzzle object.

CWPuzzle('#my-puzzle', 5, 3)
    ...
    .addAcrossClues('#across-clues', 'Across clues')
    ...;

The Method addDownClues()

The method addDownClues() adds the down clues to a container element on the page. It takes the following arguments

• The JQuery selector pointing to the container for the down clues.
• Optionally the label for the across clues.

The method addDownClues() returns the CWPuzzle object.

CWPuzzle('#my-puzzle', 5, 3)
    ...
    .addDownClues('#down-clues', 'Down clues')
    ...;

The Method addClues()

The method addClues() adds the across clues and the down clues to a container element on the page. It takes the following arguments

• The JQuery selector pointing to the container for the clues.
• Optionally the label for the across clues.
• Optionally the label for the down clues.

The method addClues() returns the CWPuzzle object.

CWPuzzle('#my-puzzle', 5, 3)
    ...
    .addClues('#clues', 'Across clues', 'Down clues')
    ...;

The Method addControls()

The method addControls() adds some controls to a container element on the page. It can be used several times to distribute the controls. It takes the following arguments

• The JQuery selector pointing to the container for the controls.
• The remaining arguments describe the controls to be added.

The control specification can be a string naming the control. It can be one of the values described in the next sections. In this case the built-in defaults for the parameters are used.

The control specification can be a map (object) to carry additional parameters. In any case the parameter control has to be given to name the control to be placed in the container. The arguments are described in the sections below.

The method addControls() returns the CWPuzzle object.

CWPuzzle('.puzzle', 5, 3)
  ...
 .addControls('.controls',
   'direction',
   { control: 'clear',
     label: 'Restart',
     tooltip: 'Clear all letters and restart from the start' },
   { control: 'check',
     label: 'Check' },
   { control: 'uncheck',
     label: 'Uncheck' },
   { control: 'reveal',
     label: 'Reveal'},
   { control: 'download',
     label: 'Download', 
     filename: 'crossword.ltx',
     comment: '© 2016 S.O. Meone\nno rights reserved' }
 );

The check Control

The check control provides a button (link) which checks the letters already entered and adds the CSS class cwp-ok to those which match the expected results and cwp-nok to those not matching. Empty cells are not marked.

It takes the following optional parameters:

• label the label on the button
• tooltip the tooltip behind the button

The clear Control

The clear control provides a button (link) which clears all letters already entered.

It takes the following optional parameters:

• label the label on the button
• tooltip the tooltip behind the button

The direction Control

The direction control provides a button (link) which indicates the writing direction.

It takes the following optional parameters:

• acrossLabel the label on the button for the writing direction across.
• downLabel the label on the button for the writing direction down.
• tooltip the tooltip behind the button

The download Control

The download control provides a button (link) which allows the user to download the LaTeX source for the puzzle. This source makes use of the cwpuzzle.sty (www.ctan.org).

It takes the following optional parameters:

• label the label on the button
• tooltip the tooltip behind the button
• filename the proposed file name for those browsers which support this feature
• comment the source code comment added to the beginning of the generated LaTeX source. It can span multiple lines. The TeX comment character is added automatically.

The reveal Control

The reveal control provides a button (link) which uncovers the expected solution.

It takes the following optional parameters:

• label the label on the button
• tooltip the tooltip behind the button

The uncheck Control

The uncheck control provides a button (link) which removes all marks added by the check control.

It takes the following optional parameters:

• label the label on the button
• tooltip the tooltip behind the button

CSS Styling

The styling via CSS uses the prefix cwp- for any CSS class used. This enables you to access many aspects of the representation and adapt it to your taste.

Known Problems

• Currently at most one direction control is supported for each puzzle.

Repository

The primary repository for cwpuzzle-js can be found on Sourceforge as cwpuzzle-js.

Copyright

This copyright covers the files

• cwpuzzle.js
• cwpuzzle.css

Copyright © 2016 Gerd Neugebauer

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

THE 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 AUTHORS OR COPYRIGHT HOLDERS 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.