search

rich-p-rich / english-tutor-django-p4

0 stars 1 forks source link

readme

Welcome to PP4: Learn English Online!

For project four I have developed a site for learners of English as a Foreign Language. I am currently working at a university in Germany as an English Teacher, and thought an online resource for my students would be an interesting and fulfilling project to pursue.

Website-responsive

A note on Testing

I have separated the results of my site testing into a different file called Test Results.

Project Overview

This website is designed to allow Learners of English as a Foreign Language to create an account, make an online appointment with a tutor to discuss anything about the English language, and also practise some skills with our online games and exercises. This Minimum Viable Product (MVP) version has full 'Create - Read - Update - Delete' (CRUD) functionality as the signed-in user can:

CRUD Options

navbar-options

book-appointments

edit-cancel-appointments

It is built on the mobile-first principle around a Django framework in which I use Bootstrap elements to style the website and enhance the user experience across different browsers and devices. It is supported by a PostgreSQL database issued by the Code Institute. It is secured by a secret key which I generated randomly using https://randomkeygen.com/; the key is set in the env.py which is added to .gitignore, as shown on the 'I think therefore I blog' walk-through project. Additionally, the front-end and back-end security is provided by the @login_required decorator along with CSRF protection implemented via the {% csrf_token %} template tag. It also has a basic admin interface in which the superuser can do the following:

Why focus on appointments? I decided to implement the CRUD functionality around the appointment function to put some distance between my project and the 'I think therefore I blog' walk-through project; I was concerned I would end up copying too much of that project as I am obviously not capable of improving on it! However, a forum for users to discuss problems with the English language would be a good idea, and there exists an 'English Language and Usage' Stack Exchange (based on the more famous coding Stack Exchange); in a future interation, this would be an interesting feature to implement.

Key Technology

Structure

The most important apps and folders which I customised to my project include:

User Demographic

This game is aimed at learners of English as a foreign language of all ages. The exercises are set between the A2 and C1 levels; these levels are correspond to levels of language proficiency as defined by the Common European Framework of Reference for Languages (the CEFR). Broadly speaking, levels A - C equate to the following:

Each of these levels is divided into two subgroups to reflect progress in language learning. For the purposes of this project, I have provided exercises for the following groups:

as these are the groups I am most familiar with. A future iteration could easily cover A1 and C2 students.

My students come from around the globe; about half are German and the rest are from across Europe, the Middle East, across Africa, Asia and South America. It is often the case that language learners from a particular groups struggle with different aspects of the English language; German speakers find the difference between the past simple and present perfect difficult, for example, whereas Russian and Arabic speakers need extra practice with the definite and indefinite articles ('the' vs 'a / an' ). Learners of all languages find phrasal verbs and linking words challenging. So after teaching at this college for nearly five years, I have developed a decent grasp of what learners from each language group and level need. The exercises I have designed for this MVP are just the first step, and further iterations will both deepen and expand the offer to reflect this.

More information about the CEFR can be found here: https://www.coe.int/en/web/common-european-framework-reference-languages/home

UX and Design

Following the mobile-first approach of the Code Institute, as well as the educational purpose of the website itself, I have tried to keep the design and layout of this project as simple as possible.

Design

Some basic research showed me that educational or language learning-related websites utilise a mix of whites and blues / greens, e.g. Grammarly, the DeepL Translator, and DuoLingo. Websites like ChatGPT and Google Translate follow a similar aesthetic, and this Verpex Blog was very informative on the subject.

I therefore settled on a fairly muted mix of whites and blues to minimise distraction from the educational content, and to strike a fairly professional tone with my audience. Duolingo is notably different in that it utilises a range of symbols and stickers to liven up progress, but in order to get my MVP ready for submission by the set deadline, I decided against adapting this much more challenging approach as it would require not only significantly better coding skills, but I suspect extensive market research and analysis of on-site user behaviour!

I have included a more detailed PDF of the different wireframes I planned out with Balsamiq in my read-me_images folder. Here are the two main ones:

Wireframe: homepage - mobile

Wireframe: mobile

Wireframe: homepage - laptop&´/desktop

Wireframe: laptop / desktop

Brand Image The base colours are as follows:

Viennese Blue:

Viennese Blue

Taken from: https://icolorpalette.com/color/407aac

The image I used for the header (Pexels Image 87833):

Sky picture

Text vs Images

This website has fewer images than might be expected of a modern website. This is however deliberate. As the focus is on language practice, it is difficult to translate this into engaging images as is possible for, e.g. a food or travel site. There are some images, primarily around the 'make appointments' functionality but I have kept them to a minimum to avoid distraction, and I was concerned that superfluous images would detract from my goal to keep the design as lean as possible.

That being said, I think the homepage would benefit from one or two images in the next interation of this project.

Site overview

I have tried to build upon functionalities that we covered in Project 1, such as responsive design, using a hamburger menu for the mobile navbar, and so on.

What follows:

Note: all key functionalities are easily accessible from the navbar and / or pop-up modals.

Django DRY Templates

The header, navbar and footer are all stored in templates/base.html and all other templates are designed to allow this template inheritance; this is one feature of Django I particularly appreciate as it conforms to the 'Do Not Repeat Yourself' (DRY) principle. My base.html is therefore visible on all pages, including the custom 404 and 500 pages.

Homepage: cards and accordions

I chose to add some explainers to the homepage for several reasons.

I view the relationship between the two sections on the homepage like the front page of a newspaper: the cards are the top-fold of the website - what people see first - and the accordion elements are the bottom-fold, providing more information for those who are interested.

Homepage: Modals

As the CRUD functionality can only be accessed by registered and signed in users, I have added Modals to the two of the cards on the homepage to encourage users to either register or sign-up at relevant calls-to-action. Again, these are excellent for mobile devices.

Sky picture

Registration page

My registration page changed fairly late on before project submission. I originally wanted to include a custom registration page that allowed a toggle password function plus more customised validation messages. However, I struggled to get this working correctly and decided to leave this for a later iteration as none of this fuctionality would qualify under 'must' or 'should' have, based on the MoSCoW guideline (see more on MoSCow below)

However, you can register with this site with an absolute minimum of information. The benefits of this approach are:

Here is how I implemented the 'view password' functionality before removing it for the final MVP:

Catching a typo with toggle password:

toggle password

Next steps:

Sign In and Sign Out

Next steps:

Make an appointment

Next steps:

Manage appointments

This draws on the same model as the 'make an appointment' function; it therefore has the same form validation.

Both actions lead to confirmation screens.

Next steps:

Games and Exercises

Next steps:

Database overview

My database is supported by a PostgreSQL database issued by the Code Institute and is built around two models.

User Information Model

This is captured at the user-registration page and stored in the user_accounts app/model.py. In the future, this will be the basis for the user account section, where the User will be the ForeignKey around which other information will be arranged: the 'UserProfile' will establish a one-to-one relationship with the User to store additional details.

At present, it allows for the capture of a username, email (optional) and password on-screen when the user registers. For the purposes of this MVP, the name and surname fields are present in the model, but I have not yet provided a field for the user to enter them; the fields are visible in the admin section. In the future, this will happen in the 'user account' section which is not yet implemented.

UserProfile-Model

Next Steps

Appointments Model

This is stored in the appointments app/models.py. The user_profile captured at registration is the ForeignKey as the core of a one-to-many relationship, in that one user can have many appointments. At the point the user makes an appointment, the user is already signed-in so the information provided by the user_profile FK is present; by booking an appointment, the model captures meeting date and time, an option message provided by the user, and a hidden created_on = models.DateTimeField field; this is all then linked to the user_profile.

Appointments-Model

Diagram of the relationship

ForeignKey - Appointments

Explanation of the relationship. The UserProfile captured at registration provides the ForeignKey for the Appointment model; it links the meeting date, time and any message to the user currently signed-in to the website.

It also allows the ‘manage appointment’ feature to function, populating the field with any appointments already made (by clicking on 'manage appointments), and linking any changes to the appointment (time, date, cancellation) to that signed-in user.

Form Validation and Constraints. I have added the following validations and constraints on the appointments model by implementing the Django 'clean' method.

Note: this is set up with the idea that just one tutor is available.

Variables explanation:

Error messages: In each of the above cases, error messages are shown to the user to alert them to the problem:

Next steps

Planning and Agile Methodologies

I followed the Agile methodology as outlined in the "I think therefore I blog" walk-though according to MoSCoW prioritization. I have completed 17 user stories, with the rest divided between 'saved for later' (i.e. the post-MVP version) and 'did not finish'.

Here is the link to my Kanban board: https://github.com/users/rich-p-rich/projects/3/views/1

The nummeration of the user stories: I did not add the user stories to the Kanban board in order of priority, but according to theme as I was drawing the project up. In retrospect, I think it would have been better to add the initial user stories according to their priority as it would likely make the workflow easier for others to follow, and I will probably follow this principle in the future.

Note: the # of each story corresponds to their Number on the Kanban board.

Must have: all implemented

Should have: all implemented

Could have: implementation status varies

In addition to the CodeInstitute's overview of the Agile methodology, I found the following Atlassian resource very helpful: https://community.atlassian.com/t5/App-Central/Understanding-the-MoSCoW-prioritization-How-to-implement-it-into/ba-p/2463999

Challenges, changes and bugs

As mentioned at the top of my ReadMe, I have collected all testing information in a separate document here: Test Results.

The development of the appointments app

My plans regarding the 'make an appointment' functionality changed significantly during the course of development.

Originally, I wanted anyone - including unregistered users - to be able to book an appointment without setting up an account as I thought this would help covert a higher number of visitors to customers, and this is how I implemented it. In order to implement the rest of the CRUD functionality, the 'manage appointments' section was called 'search and edit appointments' so that the user could search for their appointments via email and surname. I took the idea from airlines that allow you to view your flight via surname and booking number without actually logging into the account.

In practice this worked fine, but it was an insecure approach as it was then possible for anyone with the email and surname combination to search and change appointments, which was obviously undesirable.

I therefore changed the approach and required anyone who wants to make / change / cancel and appointment to have registered an account and be signed in: this is why I added a model to the user_account app, as this stores the user_profle, and it is a much more secure approach.

My take-aways from that change in approach were (i) I learned how to implement that search functionality and, more importantly, (ii) pay more attention to the big picture during the early development phase.

Changes to the Games and Exercises App

I went through several different iterations of the Games and Exercises App. An initial version was implemented a drop-down menu, but as I added more exercises it became more unwieldy and hard to manage.

All exercises drop-down

I then switched to the admin section where the superuser can add a section and link the questions to the section.

Exercises admin

Add section

Add question

Next Steps

In order to get the MVP ready, however, I decided this was more of a 'Could' than 'Should' have task, so have not taken the time to work on it. However, for a post-MVP website, this is a 'Should have' task.

Although it is possible to link questions to sections, it needs a better admin panel where you can:

Microsoft Edge Two bugs which I have not been able to fix relates to how the site displays in the Microsoft Edge browser: I cannot get the burger-bar icon or the footer to function / display reliably in Microsoft edge. I have consulted multiple resources and the general advice seemed to be to either look at the cache for the icon, pr raise the Z-index of the footer, but this did not work for my project before my submission deadline.

Other problems of note:

Deployment

Here follows an overview of the steps I took to deploy the project.

GitHub and GitPod

GitHub User Stories

Django

Database

Sign-up to a database provider and get your database link

Heroku: set up

Heroku: deploy

Other technologies used

Acknowledgements

As ever, a huge thank you to my mentor, Dick Vlaanderen, who saved me from many errors and made many helpful and creative suggestions. All errors remaining in the site are of course my own responsibility. Thanks also to the CI Tutoring Team for their help on several occassions which saw me through some challenges! Big thanks to my family, my wife and three kids, who have been very patient and forgiving while I completed this project.

Some useful resources

I relied heavily on the 'I think therefore I blog' walk-through, which was great. Some other resources include the following:

The documenation for Bootstrap and Django were in general helpful, as was W3Schools:

Lessons learned during my first three projects also helped me: