add old readme etc

README.md

+# ACDH language game app
 
+> This repo hosts a so-far-untitled web app that gives language games to users, and returns their solutions to a database.
 
-# wugsy
+Key specs:
 
-wugsy is a _short description_. It is built with [Python][0] using the [Django Web Framework][1].
+* Python 3
+* Django
+* MySQL
+* Docker
+* CI and unittests
+* Zenodo
 
-This project has the following basic apps:
+## Backend
 
-* App1 (short desc)
-* App2 (short desc)
-* App3 (short desc)
+The backend receives a request for a game from a given user. It then extracts data from a language database, and generates the data needed for a game. There are a number of types of games, but most centre on linking words and concepts. Game data is transformed into JSON and sent to the frontend. When a game is finished, the frontend returns the results, which the backend then adds to a database.
 
-## Installation
+## The JSON
 
-### Quick start
+To make collaboration easier, we use JSON to exchange data between frontend and backend. Information about these schemata can be found in `./schemata/schemata.md`.
 
-To set up a development environment quickly, first install Python 3. It
-comes with virtualenv built-in. So create a virtual env by:
+The backend -> frontend format, which gives the frontend everything needed to set the look and behaviour of the game board, is provided in `schemata/new-game.json`.
 
-    1. `$ python3 -m venv wugsy`
-    2. `$ . wugsy/bin/activate`
+The frontend -> backend format, used to communicate game results, is provided in `schemata/end-game.json`.
 
-Install all dependencies:
+> JSON for user profiles will be done later.
 
-    pip install -r requirements.txt
+## Rules
 
-Run migrations:
+For each game type, there will be an associated rule list described in `./rules/`. For the game above, for example, in `./rules/game00.md` we may find:
 
-    python manage.py migrate
+```text
+* TITLE: "Describe the concept to your opponent without using any of the displayed words"
+* CARDS: each card shows text, can be deleted, but not selected
+* TIMER: countdown from 30 seconds
+* ENDING: when the user hits hits the 'Done' button
 
-### Detailed instructions
+... etc.
+```
 
-Take a look at the docs for more information.
+Backend developers will use the game rules to write code that extracts useful data from the database, and to store game results in a different database. Frontend developers will formulate each game as a class or method that can be applied to the game board in order to turn various functionalities on or off, to populate text fields, and so on.
 
-[0]: https://www.python.org/
-[1]: https://www.djangoproject.com/
+## Frontend
+
+The frontend receives JSON that can be used to start the right game, display the user's score and opponent, and populate the various fields with words and so on. All games share a fairly similar board, though game boards may not be identical. The board will contain:
+
+- A game title
+- Grid of cards, which will display a word or two (2x2, 3x3, 4x4, 5x5 and 6x6 possible)
+- A space beneath that will display a concept linking these words, or request one from the player
+- A text entry field, also below the cards, where a user can describe a concept
+- A countdown timer
+- A current score
+- A space that visualises an opponent when there is one (username, picture, score)
+- A button that can be pushed to mark a game as bad, which may provide a request for more information
+
+For the JSON shown above, the frontend would generate a 2x2 grid, with board functionality determined by code that implements `rules/game00.md`.
+
+The game should be aesthetically pleasing, minimalistic and clean. Animations, transitions etc. are not required for the prototype, but should be included later.

docker-compose.yml

+version: '3'
+
+services:
+  db:
+    image: mysql
+  web:
+    build: .
+    command: python3 manage.py runserver 0.0.0.0:8000
+    volumes:
+      - .:/code
+    ports:
+      - "8000:8000"
+    depends_on:
+      - db

requirements/base.txt

@@ -5,3 +5,4 @@ django-crispy-forms>=1.6.1
 django-admin-bootstrapped>=2.5.7
 django-authtools>=1.6.0
 easy-thumbnails>=2.4.1
+psycopg2

schemata/end-game.json

+{
+    "game_type": 0,
+    "time_remaining": 0.5,
+    "user_id": 1391,
+    "opponent_id": 2442,
+    "concept_space_text": "Fruits",
+    "bad_game_selected": false,
+    "bad_game_feedback": 
+        {
+            "rating": 2,
+            "reason": "Did not make sense",
+        },
+    "selected_cards": [0, 1, 5, 7, 8],
+    "deleted_cards": [2, 3, 4],
+    "card_order": [6, 2, 1, 7, 9],
+    
+}
\ No newline at end of file

schemata/new-game.json

+{
+  "game_type": 0,
+  "game_title": "Select words that match the concept!",
+  "opponent":
+    {
+      "id": 3124,
+      "username": "friendo89",
+      "score": 1378235,
+      "picture": "path/to/photo.jpg"
+    },
+  "cards":
+    [
+      {
+        "id": 0,
+        "colour": "#FFFFFF",
+        "card_text": "Apple",
+        "reverse": null,
+        "selected": false,
+        "in_theme": true
+      },
+
+      {
+        "id": 2,
+        "colour": "#FFFFFF",
+        "card_text": "Banana",
+        "reverse": null,
+        "selected": false,
+        "in_theme": true
+      },
+      {
+        "id": 3,
+        "colour": "#333333",
+        "text": "Table",
+        "reverse": null,
+        "selected": true,
+        "in_theme": false
+      }     
+    ],
+  "concept_space":
+    {
+      "ceoncept_text": "Fruits",
+      "colour": "#ffffff",
+      "hover_text": "Done!"
+    },
+  "user_text_entry_field": 
+    {
+      "placeholder": "enter text here!"
+    },
+  "user_info":
+    {
+      "id": 3130,
+      "username": "player34",
+      "score": 12465,
+      "picture": "path/to/photo2.jpg",
+    },
+  "extra": null
+}
\ No newline at end of file

schemata/schemata.md

+## JSON format for games
+
+It's important that we agree on JSON formats at two points:
+
+1. The data given to the frontend that can be used to display a game correctly
+2. The data returned to the backend at the end of a game
+
+The schemata might eventually be expanded, but the general structure should remain constant to aid the separate development groups.
+
+Values of `null` indicate places where there may eventually be more data, but where right now it's not important. For some games, some parts are not required. These fields can also be given `null`.
+
+```text
+cards (array of maps):
+  id (int): unique id for card
+  colour (hex): hex colour string for card
+  text (str): main text on the card
+  reverse (map): currently none, to be expanded for new games
+  in_theme (bool): probably hidden field, used to group cards into good/bad
+concept_space (map):
+  text (str): text to show as concept
+  colour (hex): colour for this box
+  hover (str): text to show on hover over
+extra (map): currently null, but something will end up here
+game_title (str): title/description of the game for players
+game_type (int): identifier for the ruleset to be used
+opponent (map):
+  username (str): chosen username
+  gender (str): m/f/other
+  score (int): how many points the user currently has
+  picture (str): path to profile picture
+user_info (map):
+  username (str): chosen username
+  score (int): current points
+  picture (str): path to profile picture
+user_text_entry_field (map):
+  placeholder (str): what the text field should say before user enters anything
+```
+
+
+## Data returned to backend
+
+When a game is over, pretty much any useful information needs to be returned. Format to be decided.

src/templates/game.html

@@ -109,9 +109,9 @@
           <form id="get-game" action = "/generate_data" method = "post">{% csrf_token %}
               <input type="submit" name="Generate game" value="submit" />
           </form>
-          <div id="json-space">JSON for a game will appear here</div>
-          <div id="game-space"></div>
       </div>
+    <div id="game-space"></div>
+    <div id="json-space">JSON for a game will appear here</div>
 
     </div><!-- /.container -->
     {% endblock container %}
@@ -156,7 +156,9 @@
               // now, you can call the code that builds and inserts a game
               buildGame(e)
               // here, have the json on screen :)
-              $("#json-space").text(JSON.stringify(e));
+              var jsonData = '<code align="left">' + JSON.stringify(e, null, 4) + '</code>'
+              jsonData = jsonData.replace(/\n/g, '<br>');
+              $("#json-space").html(jsonData);
             }
         });
     });

src/wugsy/decide.py

 import random
 
+# just some data to test the system
+CARDS = ['apple',
+         'Banana',
+         'pear',
+         'orange',
+         'a very long card that needs to look ok',
+         'card\twith\ttabs',
+         'ALL CAPS',
+         'automob ile']
+
 class DecideGame(object):
     """
     Class that generates a game from a request
@@ -39,10 +49,10 @@ class DecideGame(object):
         for i in range(0, cards_for_games.get(self._type, 16)):
             out.append(dict(id=i,
                             colour='#ffffff',
-                            card_text='dummy {}'.format(i),
+                            card_text='dummy {}'.format(random.choice(CARDS)),
                             reverse=None,
-                            selected=False,
-                            in_theme=True
+                            selected=random.choice([True, False]),
+                            in_theme=random.choice([True, False])
                             ))
         return out
 

src/wugsy/settings/base.py

@@ -99,9 +99,13 @@ WSGI_APPLICATION = 'wugsy.wsgi.application'
 # https://docs.djangoproject.com/en/dev/ref/settings/#databases
 
 DATABASES = {
-    # Raises ImproperlyConfigured exception if DATABASE_URL not in
-    # os.environ
-    'default': env.db(),
+    'default': {
+        'ENGINE': 'django.db.backends.mysql',
+        'NAME': 'mysql',
+        'USER': 'mysql',
+        'HOST': 'db',
+        'PORT': 5432,
+    }
 }
 
 # Internationalization