LangExBank is an open-source language testing platform that supports:
- corpus-based grammar and lexical quizzes based on data of REALEC corpus
- manually created IELTS-like Reading and Listening assignments
Prerequisites:
- Basic Docker knowledge
- Basic terminal knowledge
- IPython knowledge (for modifying database in interactive shell)
-
5.2. Creating new quiz
5.3. Editing created quiz
5.4. Previewing and taking a quiz
5.5. Deleting quizzes
-
6.1. Reading
6.2. Listening
-
8.1. Accessing reference materials
8.2. Adding and editing reference materials
Learner Corpora Laboratory uses Docker to deploy LangExBank.
Copy docker-compose.yml file from the root of this respository to your machine
Then, open your favourite text editor and create a file in the LangExBank folder called env.prod. This file will contain environment variables needed for LangExBank to run in a Docker environment. Fill the file with the following contents (Meaning of every variable will be explained later):
# ./LangExBank/env.prod
DEBUG=0
SECRET_KEY=please-change-me
DJANGO_ALLOWED_HOSTS=localhost yoursite.example.com
DJANGO_ENCRYPTION_KEYS=please-change-me
LANGEXBANK_ENC_KEY=please-change-me
LANGEXBANK_ENCODE_USERS=0
LANGEXBANK_OPEN_SIGNUP=1
PGDATA=/var/lib/postgresql/data/langexbank_data
REF_EDITOR_LOGIN=login
REF_EDITOR_PASSWORD=password
REF_SECRET_KEY=please-change-me
REF_URL_PREFIX=/reference_platform
REF_DATA_FOLDER=/usr/src/app/reference_data # check
TRIES=3
TIME_PER_TRY=10
DJANGO_SUPERUSER_USERNAME=Username
DJANGO_SUPERUSER_PASSWORD=Password
DJANGO_SUPERUSER_EMAIL=example@example.com
PRODUCTION=1 # check
Where:
DEBUG
|
Whether to run Django in debug mode. Only for testing purposes. |
DJANGO_ALLOWED_HOSTS
|
Text string separated by spaces. Allowed IPs and domain names for your LangExBank site. For examples, if your LangExBank site runs on yoursite.example.com or on server with IP 172.16.254.1 change it to localhost yoursite.example.com or localhost 172.16.254.1 respectively.
|
DJANGO_SECRET_KEY
|
Text or byte string, e.g. abcdef1234. Secret key used by Django to encrypt session data. Django will refuse to start if DJANGO_SECRET_KEY is not set. |
DJANGO_ENCRYPTION_KEYS
|
Text string (without spaces). Key to encode user passwords. Best generated by secrets.token_hex(32) in Python prompt.
|
LANGEXBANK_ENC_KEY
|
Text string. Encoding key to be used by LangExBank for encoding usernames while LANGEXBANK_ENCODE_USERS is set to 1, e.g. abcdef1234
|
LANGEXBANK_ENCODE_USERS
|
Boolean. Whether to enode usernames while displaying test results. |
LANGEXBANK_OPEN_SIGNUP
|
Whether to open registration for new users. This option will be later explained in New users registration section. |
PGDATA
|
The location of where data will be stored inside PostgreSQL container. Set it to "var/lib/postgresql/data/langexbank_data" (the value is not set implicitly due to architecture issues). |
REF_EDITOR_LOGIN
|
Login for the Reference platform administrator user |
REF_EDITOR_PASSWORD
|
Password for the Reference platform administrator user |
REF_SECRET_KEY
|
Secret key for the reference platform. Used to encrypt session data. Set it to a string value and keep secret. |
REF_URL_PREFIX
|
Set it to "/reference_platform" (the value is not set implicitly due to compatibility issues). |
REF_DATA_FOLDER
|
Folder inside Reference platform used to store it data. Set it to "/usr/src/app/reference_data" (The value is not set implicitly due to architecture issues). |
TRIES
|
How many tries (switches away from the tab with quiz) are allowed for quizzes without the "Allow access to reference" option checked (default = 3). |
TIME_PER_TRY
|
For how long a student user is allowed to stay away from the tab with quiz if option "Allow access to reference" is not checked (default = 10 seconds). |
DJANGO_SUPERUSER_USERNAME
|
Username for the LangExBank superuser (to be able to create/delete/update DB objects and dump/load data/files from Django-Admin web interface) |
DJANGO_SUPERUSER_PASSWORD
|
Password for the LangExBank superuser (to be able to create/delete/update DB objects and dump/load data/files from Django-Admin web interface) |
PRODUCTION
|
Set to 1 (the value is not set implicitly due to architecture issues). |
Change variables in LangExBank/env.prod to appropriate values.
Open docker-compose.yml file in your text editor.
Change in
ports:
- 12345:80
depends_on:
- web
"12345" to the port you want to run LangExBank on.
In your terminal emulator navigate to the folder containing docker-compose.yml and env.prod files and run the following command:
docker-compose up -dThen navigate to your domain or IP address in your web browser.
After initial setup uncomment (delete '# ' sequence from) line 16 of docker-compose.yml and comment out (add initial '# ' to) line 15.
To restart LangExBank navigate to the folder containing docker-compose.yml file and execute the following commands:
docker-compose down
docker-compose up -dTo update and restart LangExBanke navigate to the folder containing docker-compose.yml file and execute the following commands:
docker-compose pull
docker-compose down
docker-compose up -dNavigate to <URL-you-re-running-LangExBank-on>/admin/ to access the admin panel. Here you can create, edit and delete database objects as in a standard Django application admin site. Also you can execute some management commands if you go to <URL-you-re-running-LangExBank-on>/admin/management/
In this tab you can download all the database data from your LangExBank installation (for example, before migrating to another server). Leave field "App label" empty if you want to download all the data (including superuser data) or type in "main_app" if you want to download only LangExBank platform data. Select one of the 3 available output types (JSON, XML or YAML). Select identation level (for convieniently displaying downloaded file in a text editor) or leave the default value of 4. Type in the name of the output file or leave the default value "dump.json". Select whether you want to download your data file as a zip folder (selected by default). After choosing all the needed options click "Dump and download model data" and the download will start after some time (may take several minutes in case of a large number of database objects).
In this tab you can populate your LangExBank database with the saved data (for example, when migrating to another server). Select the file with your data dump and click "Load data from file".
In this file you can download media (audio, PDF) files from your LangExBank installation (for example, before migrating to another server). Type in the output filename or leave the default value "mediafiles.zip". Click "dump and download mediafiles" and the download will start after some time.
In this tab you can load media (audio, PDF) files into LangExBank (for example, when migrating to another server). Select your ZIP file with saved mediafiles and click "Load data from file" button.
In this you can generate K random users for the LangExBank platform (for example, for load testing purposes). Select or type in the number of users you want to generate and select the type of rights (Admin, Teacher or Student) you want to give to those users. Selected whether you want to save generated user data into a JSON file. If you selected the option to save data into a JSON file, you can specify the name of the output file or leave the default value "Generated_users.json". After specifying all the options click on "Generate random users" to proceed. If you have selected the option to save generated users data into a file, the file will be downloaded after some time.
In this tab you can download right answers for the selected quiz. Select a quiz name and then type in the output filename or leave the default value "Answers.json". Click the button "Download quiz results" and soon the download will start.
Click on link "Download user info data" on the Management section of Admin panel to download user info data.
LangExBank support three type of users: Admin, Teacher and Student. To start using LangExBank after deploy you will need to create at least 1 admin user.
You can create new users with two different approaches:
You can create, delete and edit users in Django IPython console. To do this type in your terminal emulator:
docker-compose exec web python manage.py shellYour terminal will change to IPython console. Then type the following to import LangExBank object-relational database mappings:
from main_app.models import *Now you will be able to create new users like this (Django docs):
u = User(login='admin', enc_password='please-change-me', rights='A', full_name='The Admin Admin'
u.save()where 'A' represents Admin rights, 'S' - Student rights and 'T' - Teacher rights.
To exit IPython session type the following in your terminal:
exit()You can also create users from admin panel. Navigate to <URL-you-re-running-LangExBank-on>/admin/, find "Users" link in the "MAIN_APP" panel and click "Add" button next to it. Enter Login and Full name (to be displayed in test results) of the user, select their Rights (Admin, Student or Teacher), enter their password and click the "SAVE" button.
You can allow new students to register on your LangExBank instance using embedded registration view. To enable this set LANGEXBANK_OPEN_SIGNUP to 1 in LangExBank/env.prod file. Then send yoursite.example.com/easy_register to your students. In order to register the students will be asked to type Full Name, Group id, username and password. In current version of LangExBank no e-mail confirmation is required to register.
You can create quizzes from questions imported from REALEC.
On the LangExBank main page navigate to the Questions panel to access question bank. Click on Add questions from REALEC button at the bottom to navigate to the question import page. At the question import page fill the following fields:
| Enter path to REALEC folder | Path to folder in REALEC corpus in POSIX format (e.g. /exam/exam2018/) |
| Select error tag from REALEC (selector) | 1 or more error tags from REALEC annotation scheme. By default errors with all tags will be included |
| Make questions multiple choice with distractor generation model (checkbox with selector) | Whether to generate multiple-choice questions. LangExBank includes two models of distrator generation: DisSelector and DisGen. DisGen supports Choice of lexical item, Choice of tense and Prepositions tags. DisSelector supports only Choice of lexical item tag, but has less restrictions on input and produces more coherent output. |
| Create new folder with name (checkbox) | Whether to create a new folder in LangExBank with recently generated questions. |
| Create new folder with name (text field) | Name for the new folder (if the option Create new folder with name is selected) |
After filling the form click on the Generate questions button. Generating questions may take several minutes especially in the case of multiple choice questions. Then you will be redirected to the Questions panel.
To create new quiz tick the boxes left to questions on Questions panel, enter quiz name in the Quiz name field at the bottom and click on the Create quiz button.
Navigate to the Quizzes panel and select created quiz. You can edit questions and answers to them, add right answers in case of short answer questions and add distractor oprions in case of multiple choice questions. If you made a mistake editing just click Restore to default in question or answer field to restore its text to value from the database. When you are done please click Save changes to apply your changes to quiz.
You can change whether you want the test takers to be able to access reference materials website with the option "allow acces to reference" (at the bottom of the page). If the option is not selected, the results of student are automatically submitted after TIME_PER_TRY seconds if they switch from the tab with test. Also the students can switch tabs without auto-submitting no more than TRIES times.
To preview a quiz just select Preview option right to quiz name at the Quizzes panel. To share quiz with your students copy URL from your adress bar at the preview page and send it to them. When you are ready click Submit answers at the bottom of the page. Then you will be redirected to the page with your results in quiz.
To delete a quiz simply navigate to Quizzes panel, find needed quiz and click on Delete.
You can create tests in IELTS format of Reading and Listening types on IELTS panel. (The following section of manual is yet to be written)
To create an exercise of type Reading select Reading option in Section type field
To create an exercise of type Listening select Listening option in Section type field
The processs of reviewing results is practicully the same for both corpus-based quizzes and IELTS-like tests.
To review results of either a corpus-based test or an IELTS-like test navigate to Quizzes or IELTS panel respectively and click Results right to the name of the needed quiz. Results will be presented in form of a table:
| Student | Group | Mark | |
| Student John Johnson | Group 1 | 0.9 | Details |
To review results of a particular student click Details right to the row with his name. Now you will be able to see answers submitted by the student as well as right answers to quiz questions. To edit mark for each question navigate your cursor to mark column and enter new mark in floating point number format (e.g. 0.9 or 2.0. If you think that the answer submotted by a student was correct click Mark as new correct below answer. (Warning: the answer will be counted as correct only for new test takers). Adding new correct answer is not supported for multiple choice questions. When you are done reviewing student results click Save changes at the bottom of the page to apply your changes.
Navigate to <URL-you-re-running-LangExBank-on>/reference_platform/ to access the Reference platform. Here you can view and edit study materials associated with REALEC error tags.
To access reference materials select the error tag from the panel on the left. You will be presented with the list of articles associated with it. Click the name of the article to access it. You can also view all articles if you go to <URL-you-re-running-LangExBank-on>/reference_platform/allArticles.
To access editing features of the Reference platform navigate to <URL-you-re-running-LangExBank-on>/reference_platform/auth and type in the login and password specified in REF_EDITOR_LOGIN and REF_EDITOR_PASSWORD variables. After that you will be redirected to the index page of Reference platform and the "+ Add article" link will appear in the left panel. Click on it and you will see the articled editor. Add a name for you article and select one or more error tags asscoiated with it. To save the article click the 'Save article" button.
To edit Reference materials after authentication click to "Edit" link displayed next to article name in the list of articles. To delete the article click on the "Delete" button next to "Edit" link.
You can download the data of Reference platform (for example, before migrating to another server). After authentication at Reference platform, type <URL-you-re-running-LangExBank-on>/reference_platform/dump_data in your browser and the download will start.
You can upload saved data to Reference platform (for example, after migrating to another server). After authentication at Reference platform, go to <URL-you-re-running-LangExBank-on>/reference_platform/, select the file with your previously saved reference data and click the "Upload data" button.