Puzzle.js Reference: Validators (Logic-based and Hash-based)

Note: while Puzzle.js puzzles store their state locally (via localStorage), that behavior is inhibited on this page to make it easiest to see exactly what markup produces exactly what result.

Overview

Many puzzles benefit from some kind of answer verification, or confirmation that the puzzle rules are/are not being followed. In puzzle.js, validation performs this service. There are two types: logic-based and hash-based.

A puzzle-entry can have several instances of puzzle-grid in it, some of which have a form of validation and some of which do not. The overall puzzle is considered to be validated if at least one grid supports validation, and if all grids that support validation are validated.

This feature is in beta, and many validator components still need to be written. For now, the use of validators is opt-in until the feature is more mature. You can opt in by setting data-validators-beta-opt-in="true" on your page’s body tag.

Hash-based Validation: data-*-hashes

There are five hash-based properties, and they all work the same way:

Each property can contain one or more hashes, separated by spaces. The puzzle is considered to be solved if any of the hashes is correct; this supports letter grids where symmetry allows them to be entered two ways, puzzles where the solver might either mark cells with fills or edges but need not do both, etc. If a puzzle needs several hashes to all be correct, a logic-based validator can easily fill that role.

The hashes themselves are easily generated using the designer, which is accessible on any page by pressing Shift + Ctrl + Alt + F12, or in a example by clicking “Open in designer”. From there make sure the puzzle is selected, enter the Validation section, and click the camera button (📸) for each hash that you need to create.

Logic-based Validation: data-validators

The format of the data-validators property is a space-delimited set of validator names; these can be built-in validators or custom validators. The validators folder contains the built-in validators; if the name of the validator ends in .js, it will be interpreted as a page-relative path for a custom validator whose name is the filename minus the extension.

Some validators take an optional parameter, which can be specified after the validator name with a | separator.

Built-in Logic-based Validators

Many more validators will be written.

Validates whether the text of any cell is repeated in its row, and highlights any duplicates. Uses data-text-characters for the list of values; if that property contains two or more copies of a value, they are considered to be distinct. In the example below, two 1’s are permitted but not three.

Validates whether the text of any cell is repeated in its column, and highlights any duplicates. Uses data-text-characters for the list of values; if that property contains two or more copies of a value, they are considered to be distinct. In the example below, two 1’s are permitted but not three.

Validates whether the text of any cell is repeated in its region (any shape bounded by edges), and highlights any duplicates. Uses data-text-characters for the list of values; if that property contains two or more copies of a value, they are considered to be distinct. In the example below, two 1’s are permitted but not three.

Validates whether the values in a region (any shape bounded by edges) can be mathematically combined to match a value provided by a clue within the region. If the clue provides an operator (+, -, x, or /), that operator must be used; otherwise, any one of the four operators can be used.

Validates whether a contiguously-connected group of cells, all with the same fill, has the size of its group in a single text field. Highlights errors if the size is too large, and only reports success if there are no unresolved neighbors.

Validates whether there are no 2x2 regions with the same fill.

Validates whether there is a single contiguously-connected group of cells, all with the same fill. Only highlights errors if at least one group has no unresolved neighbors.

Validates whether the outer clues of a puzzle specify the lengths of spans of fills with the same value. Currently, the only fill value checked is the second one ("black"), but this will be extended in the future. If data-outer-clue-checks is set to true, then indicators will be added to the edges of the grid to confirm success or highlight errors.

Validates whether all paths connect cells with the same value. Only highlights errors if a path is not a chain, or if both ends of the chain are on cells with different text.

Validates whether all paths connect cells with the same value, whose value is the length of the path. Only highlights errors if a path is not a chain, or if both ends of the chain are on cells whose text does not equal the path length.

Validates whether all paths avoid any interior text other than at their endpoints.

Validates whether all cells also contain a component of a path.

Validates whether all cells with text also contain a component of a path.

Validates whether the text in a cell matches the number of spokes leaving the cell.

Validates whether no scopes cross each other (i.e. diagonally).

Validates whether a chain of cells connected by spokes can be numbered 1..N sequentially, with all givens lining up with cell text.

Validates whether there is a single spoke group that is a chain, not a loop or a web.

Validates whether all cells also contain a component of a spoke.

Validates whether all cells with text also contain a component of a spoke.

Never succeeds; a useful way to borrow failure highlighting logic from some rules, but not allow overall success because not all rules have been written.

Logic-based Validator Structure

Note: This structure has changed somewhat from its initial beta form, to both require less code and open up new scenarios.

This is an extremely simple validator that marks the outer clue checks to pass or fail. It should be in its own file named reference-set-all-outer-checks.js; the script tag here is just to fit it into the documentation.

This validator:

  • A validator is a success if the call to validate generates no calls to incomplete() or fail() on any component of the puzzle.
  • A custom validator such as this can be used by providing its page-relative path, and a value for param can be provided after a | character.

    Validator API: puzzleGrid

    Many more functions will be written here, covering the full functionality of PuzzleJS.

    Gets all cells in the grid, grouped into rows.

    Gets all cells in the grid, grouped into columns.

    Gets all connected groups of cells with the same fill.

    A fill group has the following properties:

    Gets all groups of cells connectd by paths.

    A path group has the following properties:

    Gets all groups of cells connectd by spokes.

    A spoke group has the following properties:

    Gets all cells in the grid, grouped into regions (shapes bounded by edges).

    Gets all outer checks on a specific side of the grid. Does not get the values of the outer clues themselves; getOption can beused for that.

    An outer check has the following functions:

    Gets the value of a specific option, after all mode/inheritance rules are applied.

    Gets the hash of the puzzle text.

    Gets the hash of the puzzle fills.

    Gets the hash of the puzzle edges.

    Gets the hash of the puzzle paths.

    Gets the hash of the puzzle spokes.

    Validator API: cell

    Many more functions will be written here, covering the full functionality of PuzzleJS.

    Gets the DOM id of the cell, which is unique within the puzzleGrid.

    Gets the text in the middle of the cell.

    Gets true if the cell has one or more candidate values (typed using the Shift key); false otherwise.

    Gets the text of the inner clue on the cell, if any.

    Gets the name of the class that represents the fill of the cell, within data-fill-classes.

    Gets the index of the class that represents the fill of the cell, within data-fill-classes.

    Gets the name of the class that represents the extra style of the cell, within data-extra-style-classes.

    Gets the index of the class that represents the extra style of the cell, within data-extra-style-classes.

    Gets an array with a value for each direction a path takes within the cell. Values can be "top", "bottom", "left", or "right".

    Gets an array with a value for each direction a spoke takes within the cell. Values can be "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", or "bottom-right".

    Marks the cell as having passed. Doesn't really do anything and does not need to be called, only here for symmetry.

    Marks the cell as being incomplete.

    Marks the cell as having failed.