├── LICENSE
├── README.md
├── example_images
├── crossword1_blank.png
├── crossword1_filled.png
└── crossword2_plain_text_layout.png
├── index.html
└── layout_generator.js
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2018 Michael Wehar
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Crossword Layout Generator - Open Source
2 | ## Introduction
3 | A crossword consists of clues, answers, and a layout:
4 | - The answers are the hidden words that the player is trying to guess.
5 | - Each answer has a clue which is a sentence or phrase that helps the player to guess the associated answer.
6 | - The **crossword layout** describes where the answers are located in a two-dimensional grid.
7 |
8 | This crossword layout generator takes in a list of answers and outputs a crossword layout. Our program **does not** generate the answers or the clues.
9 |
10 | ## Input and Output Format
11 |
12 | An input is a list of answers in a JSON format. The clues can optionally be included with the input.
13 |
14 | Here is an example input:
15 |
16 | `[{"clue":"that which is established as a rule or model by authority, custom, or general consent","answer":"standard"},{"clue":"a machine that computes","answer":"computer"},{"clue":"the collective designation of items for a particular purpose","answer":"equipment"},{"clue":"an opening or entrance to an inclosed place","answer":"port"},{"clue":"a point where two things can connect and interact","answer":"interface"}]`
17 |
18 | The output is a crossword layout. That is, we associate a position, startx, starty, and orientation with each answer.
19 |
20 | Here is an example output:
21 |
22 | `[{"clue":"the collective designation of items for a particular purpose","answer":"equipment","startx":1,"starty":4,"position":1,"orientation":"across"},{"clue":"an opening or entrance to an inclosed place","answer":"port","startx":5,"starty":4,"position":2,"orientation":"down"},{"clue":"that which is established as a rule or model by authority, custom, or general consent","answer":"standard","startx":8,"starty":1,"position":3,"orientation":"down"},{"clue":"a machine that computes","answer":"computer","startx":3,"starty":2,"position":4,"orientation":"across"},{"clue":"a point where two things can connect and interact","answer":"interface","startx":1,"starty":1,"position":5,"orientation":"down"}]`
23 |
24 | One can visualize the output as follows:
25 |
26 | 
27 |
28 | ## Getting Started
29 |
30 | **Step 1:** Add the following line to the head of your html document:
31 |
32 | ``
33 |
34 | **Step 2:** In the body of your html document, you can add the following JavaScript:
35 |
36 | ```
37 |
47 | ```
48 |
49 | **Update:** Our crossword layout generator is now available as a package for Node.js applications. For more information, see the Node.js version of our README here: https://github.com/MichaelWehar/Crossword-Layout-Generator/blob/npm/README.md
50 |
51 | Also, see our package's npm listing here: https://www.npmjs.com/package/crossword-layout-generator
52 |
53 | ## Demo Website
54 |
55 | The demo website's source code can be found in `index.html`.
56 |
57 | The demo website shows:
58 |
59 | - how to generate the crossword layout in a JSON format
60 |
61 | - how to generate the crossword layout in a plain text grid format (using HTML line breaks).
62 |
63 | - how to turn your crossword layout into a **word search puzzle** with horizontal and vertical answers.
64 |
65 | **Demo:** http://michaelwehar.com/crosswords
66 |
67 | **Short Article:** https://makeprojects.com/project/crossword-layout-generator---open-source
68 |
69 | ## Information for Advanced Users
70 |
71 | - The generated layouts don't always contain all of the input words. If a word does not appear in the layout, then its orientation attribute will be set to "none".
72 |
73 | - The generated crossword layouts are not always connected. Occasionally, there will be islands of disconnected words.
74 |
75 | - The program is efficient on small word lists, but it runs noticably slower when the list contains more than 100 words.
76 |
77 | - We are still exploring potential ways to evaluate the quality of the generated crossword layouts. See [Issue #2](https://github.com/MichaelWehar/Crossword-Layout-Generator/issues/2).
78 |
79 | ## License
80 | - MIT
81 |
82 | ## Credits
83 | - Michael Wehar
84 | - Itay Livni
85 | - Michael Blättler
86 |
87 | ## Forked Repositories with Additional Features
88 |
89 | During Fall 2024, two teams of students in the Open Source Software Development course at Swarthmore College, taught by Chris Murphy, worked to improve this open source project by adding additional features.
90 |
91 | **Added features for AI integration and dark mode**
92 |
93 | Contributors: Abe P., Mina M., and Nick F.
94 |
95 | Link: https://github.com/nicholasyfu1/Crossword-Layout-Generator
96 |
97 | **Added features for generating PDF's and using synonyms**
98 |
99 | Contributors: Jayson B., Marcus W., and Sharvari T.
100 |
101 | Link: https://github.com/MarcusW03/Crossword-Layout-Generator
102 |
103 | ## Updates (December 2024)
104 |
105 | I also co-implemented an algorithm for automatic crossword puzzle filling. Take a look at the new repository here @ [Automatic Crossword Puzzle Filling](https://github.com/MichaelWehar/Automatic-Crossword-Puzzle-Filling)
106 |
107 | ## External Projects That Use Our Library
108 |
109 | - [WoordSchaap](https://github.com/erasche/woordschaap)
110 |
111 | - [Collaboration with TapNotion at PyCon 2018](https://pycon-archive.python.org/2018/schedule/presentation/179/)
112 |
--------------------------------------------------------------------------------
/example_images/crossword1_blank.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichaelWehar/Crossword-Layout-Generator/ff5ff36b223da58ca0d039c06ab29a8b91b32a94/example_images/crossword1_blank.png
--------------------------------------------------------------------------------
/example_images/crossword1_filled.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichaelWehar/Crossword-Layout-Generator/ff5ff36b223da58ca0d039c06ab29a8b91b32a94/example_images/crossword1_filled.png
--------------------------------------------------------------------------------
/example_images/crossword2_plain_text_layout.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MichaelWehar/Crossword-Layout-Generator/ff5ff36b223da58ca0d039c06ab29a8b91b32a94/example_images/crossword2_plain_text_layout.png
--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
1 |
2 |