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.
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.
data-*-hashesThere 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.
data-validatorsThe 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.
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.
param: Which fill index (within data-fill-classes) to validate.Validates whether there are no 2x2 regions with the same fill.
param: Which fill index (within data-fill-classes) to validate.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.
param: Which fill index (within data-fill-classes) to validate.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 (non-default) fill. Only highlights errors if a path is not a chain, or if both ends of the chain are on cells with different (non-default) fills.
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.
param: Any text to ignore.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.
param: Any text to ignore.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.
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:
puzzleValidators, using a key that equals the filename minus the trailing .js.getDescription to get a textual description, and validate to validate. Both functions take as input a puzzleGrid and an optional param.puzzleGrid to analyze the puzzle and optionally set success/incomplete/failure states within.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.
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:
cells: An array of cells in this group.complete: True if none of the cells contiguous to the group have a default fill, false otherwise.fillClass: The name of the fill class (within data-fill-classes) that the cells in this group share.fillIndex: The index of the fill class (within data-fill-classes) that the cells in this group share.Gets all groups of cells connectd by paths.
A path group has the following properties:
cells: An array of cells in this group.type: A classification of the path. If the value is "chain", then the cells are in sequence from one endpoint to the other. If the value is "loop", then the cells are in sequence with no particular starting point. If the value is "web", then the group contains at least one junction with more than two path routes leading out, and is therefore too complex to make connectivity assertions based on the array alone.Gets all groups of cells connectd by spokes.
A spoke group has the following properties:
cells: An array of cells in this group.level: The level of the spokes in this group. Always 1, unless data-spoke-levels is set.type: A classification of the group. If the value is "chain", then the cells are in sequence from one endpoint to the other. If the value is "loop", then the cells are in sequence with no particular starting point. If the value is "web", then the group contains at least one junction with more than two spoke routes leading out, and is therefore too complex to make connectivity assertions based on the array alone.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.
side Which side of the grid to retrieve outer checks for.An outer check has the following functions:
pass: Marks the outer check as having passed.incomplete: Marks the outer check as being incomplete.fail: Marks the outer check as having failed.Gets the value of a specific option, after all mode/inheritance rules are applied.
optionName: the name of the option.Gets the hash of the puzzle text.
secondary: if false, uses the same hashing scheme that data-text-hashes would use. If true, uses a different hashing scheme to produce a value not seen elsewhere in markup, and thus good for use in filenames on the server that can be accessed as a reward.Gets the hash of the puzzle fills.
secondary: if false, uses the same hashing scheme that data-fill-hashes would use. If true, uses a different hashing scheme to produce a value not seen elsewhere in markup, and thus good for use in filenames on the server that can be accessed as a reward.Gets the hash of the puzzle edges.
secondary: if false, uses the same hashing scheme that data-edge-hashes would use. If true, uses a different hashing scheme to produce a value not seen elsewhere in markup, and thus good for use in filenames on the server that can be accessed as a reward.Gets the hash of the puzzle paths.
secondary: if false, uses the same hashing scheme that data-path-hashes would use. If true, uses a different hashing scheme to produce a value not seen elsewhere in markup, and thus good for use in filenames on the server that can be accessed as a reward.Gets the hash of the puzzle spokes.
secondary: if false, uses the same hashing scheme that data-spoke-hashes would use. If true, uses a different hashing scheme to produce a value not seen elsewhere in markup, and thus good for use in filenames on the server that can be accessed as a reward.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".
level: if specified, a level of spoke (see data-spoke-levels). If unspecified, spokes of all levels are returned.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.