1. Introduction
2. UX
   2.1 User Stories
3. Features and design
   3.1. Existing features
   3.1.1. Sign up and Login
   3.1.2. Landing page
   3.1.3. Navigation
   3.1.4. Taking the quiz
   3.1.5. Managing quizzes
   3.1.6. Managing questions
   3.1.6. Managing categories
   3.1.6. User feedback and alerts
   3.2. Features left to implement
   
4. Management via Django admin
5. Technologies
   5.1. Languages used
   5.2. Frameworks, libraries and programs used
6. Testing
7. Deployment
8. Credits

Teaze is a web-based application built for use as an internal self-testing tool in aid of training as well as for use in more fun team building activities. In the future, its use might be extended to external users as a marketing tool aiming at increasing the engagement of the existing and potential customers and encouraging them up for the company's newsletter.

At present, the application is at Stage 1 of development and the focus of the development efforts has been placed on achieving a functioning Minimum Viable Product (MVP) that allows the users to take and create quizzes. Further improvements to the application UI and functionality will be ventured after the main stakeholders' input and testing.

Link to the deployed app: https://teaze.herokuapp.com/accounts/login/

The initial user interface design idea was captured in the wireframes available here, while the flow of the application logic in a diagram available for viewing here. The design is driven by the user's needs and ease of use. It aims to replicate the process the user would usually go through when creating a quiz, but also offer flexibility by providing access to various features from different places in the application and at different stages of creating or managing a quiz (e.g. editing questions or adding and removing their options). With user experience in mind, the design of the application is kept simple with a primary focus placed on functionality.

The application was developed using Agile methodology, with User Stories managed within a Github Project. All completed and outstanding User Stories can be viewed here.

The application uses the Postgres relationship database to store its data and the data model is comprised of Quiz, Question, Option, Category, Assessment and Answer. The components of each model and the relationships between them are represented in a graphic model representation available here.

The decision to keep Quiz, Question and Options as separate models was driven by flexibility. This kind of approach allows maximum flexibility when creating quizzes and questions, as the user is not restricted to a pre-set structure, number of questions per quiz, options per question etc. It also allows for the questions to be reused even if the quiz has been deleted, as they are not inherently a part of the quiz either.

This approach, however, calls for careful consideration of the relationships between various models and what should happen if instances of these are deleted while related to an instance of another model. These considerations are still pending in Teaze app, and need to be addressed.

At present, the relationship between quiz and question is One-to-Many, though it would, arguably, be more beneficial to the user to be able to use the same question in more than one quiz. The deletion of questions, options and categories also poses a problem due to their links with other models for which cascading deletion is not an option. In the future, the Delete will be replaced with the Active/Disabled approach instead.

When first accessing the application, the user is directed to a Log in page. The page includes a link to a Sign up form, should the visitor not yet have an account. Sign up and Log in forms are delivered by Allauth Django app. The forms are fully validated for correct data input, and the Sign up form asks to confirm the inserted password and an option to provide an e-mail address.

Log in form

Sign up form

All users are managed via backend Django admin site, where superadmin user can assign users to the Admin group with advanced rights. At the moment, the application is not linked to any e-mail address and the passwords can only be reset via contact with the application admin. This will be fixed in the future, however, considering the internal nature of the application this is not affecting the app usability hugely at this stage.

After logging in, a standard User is redirected to their homepage, where they can see a list of quizzes that have been published (i.e. set to Approved. If the quiz has been completed it is marked as such, and the button for taking the quiz is replaced with Results that take the user to a page showing their results for that particular quiz.

Standard user's home page

Admin users, on the other hand, are redirected to a dashboard with an overview of quizzes, questions and categories existing in the application. From here, via an extended menu, they can manage (create, edit and delete) all of these elements.

Admin user's home page

The navigation menu is placed at the top of the page and changes depending on whether the user is authenticated or not, and also depending on the type of user.

Non-authenticated user's menu

Standard user's menu

Admin user's menu

The menu is also responsive and collapses into a button on smaller devices.

On their homepage, a standard User can see a list of all published quizzes available for them to take as well as those they have already taken. Upon clicking the Take quiz button, the user is taken to a page with a list of all questions.

Take quiz view

The quiz allows only one answer per question, however, not all questions have to be answered to submit the quiz. On submission, the User is redirected to a page showing their results - total score for the quiz and feedback for each of the questions. These quiz results are available for the User to view at any time via the links on each quiz card on their homepage.

Quiz results view

Each response is saved as an individual answer assigned to an assessment which is saved against the user and, at present, the user cannot take the same quiz more than once. This again is something to be discussed and agreed on with the stakeholders.

The Manage quizzes page can be accessed from the link in the card on the Home page or via the Menu at the top of the page. Each quiz has its own card with some basic information and links to delete or edit a quiz, as well as add a new one.

To create a new quiz, the user needs to be assigned relevant permissions by the superuser, e.g. by adding them to the Admin group. Adding a quiz is a simple process and can be done either directly from the Dashboard or the Manage quizzes page accessible from the Menu at the top of the page.

Adding quiz from Dashboad

Adding quiz from Manage quizzes

Clicking the Add button initiates the Add quiz form, where the user can fill in the quiz Title (required), Category (required), Description (optional), and Image (optional). The form is validated for required fields and checks if a quiz with the same title already exists.

Add quiz form

A quiz can only be assigned one category, and if the required category does not yet exist, it can be added from the Add quiz view as well.

Add category while creating new quiz

If the user decides not to save the changes, they can cancel the process at any point by clicking either the Cancel button or the X sign in the top right corner of the form.

Clicking Save, redirects the user to a view with quiz details.

After creating a quiz, the Admin user is redirected to a Quiz detail page, where they can see information about the quiz: title, status, category, description, image and quiz questions, if any already exist. If there are any questions in the database that are assigned the same category as the quiz and are not assigned to any other quiz, they are listed below the main quiz details and can be added to the quiz by clicking the small + icon showing to the right. Similarly, questions can be as easily removed from the quiz by clicking the x icon in the quiz questions list. Note that this action merely removes the question from the quiz and does not delete it.

List of questions availble for adding to the quiz

The Edit quiz button redirects the user to the Edit quiz page, where the user can make tweaks to the quiz details. The form mirrors the Add quiz form but is populated with existing quiz data.

A quiz can be set as either Draft or Approved. By default when created a quiz is given a status of Draft. Until the status is set to Draft, a quiz will not be visible to a standard User to prevent them from completing quizzes that have not been finished and verified. The quiz can be toggled to Approved in the Quiz detail page at any time, once an Admin user is finished setting it up.

On setting the quiz to Approved a pop-up alert informs the user that the status has been changed and the quiz is now available for all test-takers.

The user can upload an image to act as a feature image for the quiz which is uploaded directly from the form to Cloudinary. The uploaded images are then appearing as background on the quiz cards and can be set as showing as a background to the quiz in the Take Quiz and Resulsts pages in the future. Images appear on the Quiz details page as thumbnails and can be removed and updated as needed. There are certain considerations for using images in the application (in relation to size, colouring, ratios, etc.) that will be addressed in the Admin user training and controlled programmatically in the future.

Quiz details with image thumbnail

Once created, an Admin user has an option to check the quiz as it would appear to a standard User by using the Preview button on the quiz card in the Manage quizzes page. The Preview mimics the actual quiz-taking experience of a standard user. Admin users' quizzes get saved into the database to ensure everything is working correctly, but they can take the quiz more than once.

The Manage questions page can be accessed from the link in the card on the Home page or via the Menu at the top of the page.

In the Manage questions page the admin user sees a list of questions with their basic details, which are by default hidden to take less space on the page, and can filter them by category and quiz, and search by text that might show in the question text. Filtering options are collapsed by default to make the page cleaner but are easily accessible at the top of the page.

Filter optons

When a filter is applied a button Clear filters appears that clears all filters and shows all questions in the database.

Manage qestion page with Clear filter button

A new question can be added from the Quiz detail page, in which case the quiz and category properties of the question are set based on those of the quiz, or from the Manage questions page, where the question can be created without selecting a quiz or category and added to a quiz when needed.

Adding question from Quiz details page

Adding question from Manage questions page

A question can be assigned more than one category by holding down the Ctrl button (or Cmd on a Mac) and making a selection. The user is informed about this option on the form.

Once the user is happy with the information they provided and click Save, they are redirected to the Question detail page, which is also an editing view.

As in a quiz, a question can have a featured image with a view that some questions might require images for illustration purposes or which can be part of the question. The uploaded images are also uploaded into Cloudinary and the setup is the same way as in the case of quizzes.

The Question details follows the same layout as the Quiz details page, including the image preview as a thumbnail. For convenience, the user can edit question elements individually by clicking on the Edit icon. The edit form for each of the elements opens in a separate modal showing over the page, which helps the user stay focused on the task.

Question details page with modal open

On this page the user also gets an opportunity to manage options - they can create and delete them as required. Because options are not part of a question model but have a model of their own, the number of options per question is not determined by design and can be set individually per question. Creating and editing forms for options are also opened in modals for convenience.

At present, the quiz design allows only one option to be set as correct. To prevent the Admin user from setting more than one answer as correct, the tick box for `is_correczt is replaced with information that one correct option already exists if this is the case.

Adding option when correct answer already exists

As quizzes, questions have two statuses Draft and Approved. At present this feature is simply for the Admin user to keep track of questions that still need to be reviewed, but they can still be used in the quiz if the Admin wishes so. Draft questions are clearly indicated in the Quiz detail page and can be reviewed and approved before adding to the quiz and publishing the latter.

Draft questions indicated in the Quiz detail page

A question can be deleted from the Manage questions or Question details pages, however, a question can only be deleted if the question is not used in any of the existing quizzes. In the Manage questions page the Bin icon is replaced with a Warning sign and the Delete text is stricken through. On hover, a tooltip appears informing the user about the reason why options are not available. On the Question details page, the Delete button is replaced with a button instructing the user to unlink the question from the quiz if they wish to delete it. The button triggers the Edit question quiz form for ease.

Before the question is deleted, the application will also perform an additional check to see if it appears in any of the saved assessments. If yes, the user will be provided with appropriate feedback in a modal (this might be handled differently in the future), and the deletion is not possible. Options can be deleted from the Question details page as well, and are also checked for appearance in assessments to prevent ProtectedError and loss of data.

As explained above, considering the data model and the fact that assessments and answers need to be stored beyond the life-cycle of any quiz, question or option, the deletions need further consideration and will be replaced with an Active/Disabled approach instead.

Categories are the smallest model and are the simplest to manage. They can be added while creating a new quiz or from their own Manage categories page. Only categories that are not assigned to a quiz can be deleted and Delete is disabled on cards for these categories.

To increase users' engagement with the application the user is offered feedback on various operations via alerts as well as the use of Bootstrap's tooltips and title tags to help users navigate the page.

In the future, the user will have access to a page allowing them to manage their account: change their password, add an avatar etc.

Displaying one question per page would be especially helpful for questions using an image as part of their content.

At present, management of the assessments is only available to the admin user via the Django admin page after they have been set as Staff members by a user with superuser rights. In the future, this functionality would be available for Admin users from the front-end as well.

It is important to add to the application some degree of control over the navigation while using browser back/forward buttons as well as manually providing the browser with url paths. This is not controlled at the moment and might cause issues.

There are a lot of additional features that can be added to the application to improve the user experience and add functionality. These will be discussed with the stakeholders, changed into new User Stories and prioritised as appropriate.

As with any Django application, all models and functionality of the application can be managed via Django's administration site, provided the user is set as a Staff user.

Superuser has access to all content while Admin user has only certain specific permissions available to them.

Admin user Django admin access

To make the management easier in the Django admin site, the models have been set up to be viewed as sets of data (e.g. questions can be added within quiz and options within questions). The views also include filters and display information on the main page deemed most important. Again, this can be easily adjusted depending on the stakeholders and admin preferences.

Quiz details

Question list

Question details

Assessment list

Assessment_details

Answers

Programming languages used in the project:

• HTML and CSS3
• Python
• JavaScript

• Django: main application framework
• Bootstrap: CSS styling
• GitPod: primary code editor
• Git: for version control
• Git Hub: to store project files
• Python Tutor: used to help with debugging
• darw.io: to create the data model and program logic flow chart
• Balsamiq: for wireframes
• Cloudinary: to store image files uploaded by the user
• PostgreSQL Database: serving as main database
• Coverage: create reporting on level of tests
• AllAuth: user management
• django-bootstrap-modal-forms: to display forms in modals
• django-filter: used on the Manage questions page to filter the content
• Heroku: used to deploy the live version of the project
• whitenoise: to serve static files correctly in production
• Beautify: VSCode extension to format code
• Am I Responsive? site to generate the responsive mockup

The error handling is currently mostly handled by the inbuilt functionality of class-based views as well as some if-statement based checks within these. Going forward, the application will be using a more robust approach using a set of custom error classes.

Information about the application testing is available in a separate file here.

The program was deployed to Heroku at the start of the project to ensure its correct functioning and is accessible here:

The steps taken to deploy the app:

1. Updated the contents of the requirements file using the pip3 freeze > requirements.txt command in VS Code.
2. Checked the project structure and run the program to ensure everything is working as expected.
3. Created the Tease project on Heroku, giving it the name 'teaze'.
4. Added a new Postgres database:

• In the Resources tab, searched for Heroku Postgres add-in and selected the free Hobby Dev option.

5. In the Config Vars section of the Settings tab, added the environment variables to set up:

• Link to Postgres database
• Link to Cloudinary
• Disabled static files for the time of development
• App secret key

5. In the Deployment tab:

• selected GitHub as deployment method,
• selected Connect,
• authorised Heroku to access the GitHub account,
• searched for 'teaze' repository and confirmed the connection.

6. First time deployed the app using the manual Deploy Branch button, then enabled automatic deploys.
7. Once the first build was complete, changed the settings to deploy automatically.
8. Towards the end of development, enabled static files by changing the value of DISABLE_COLLECTSTATIC to 0. Resolved issues caused by settings for Cloudinary in the static files setup in the settings.py file (see Testing file for more details).
9. Installed Whitenoise to ensure static files are served in production mode.

All requirements are contained in the requirements.txt file.

A great thank you to:

• My mentor, Caleb Mbakwe, for invaluable advice on the best approach to the project, organisation of code, and support throughout.
• Stackoverflow community: for pointing in the right direction on so many issues it's not efficient to list them here, though specific mention should be given to Bishwa Karki for solving the issue of pulling author from the logged user rather than having to set it in the form.
• TO Izen Oku: for his blog post on creating a Quiz app and pointers on how to organise my database models.
• To PyPlane and Lara Code for their tutorials on creating a quiz in Django.
• Creators of Django and Heroku documentation as well as authors of all the plugins and libraries used in this application.