FreeFrom

FreeFrom Live Site

Contents

• Background
• Project Goals
• Site Owner Goals
• User Goals
• UX
  • Project Strategy
    • Opportunities Matrix
  • Project Scope
    • User Demographics
    • User Requirements
    • User Stories
    • Constraints
    • Functional Requirements
    • Business Rules
    • Key Features
  • Site Map
  • Wireframes
  • Design Choices
    • Fonts
    • Colours
• Technologies
  • Integrated Development Environment
  • Database
  • Languages
  • Frameworks Libraries and Tools
  • Browser Support
• Structure
  • Information Architecture
  • Features Implemented
    • Features Implemented in Phase 1
    • Features To Be Implemented In Future Development Phases
    • Design Changes During The Phase 1 Development
  • Responsive Styling
  • Python Code Logic
    • Products
    • Categories
    • Allergens
    • User Authentication
    • Mail
  • Python Code Refactoring
  • Form Validation
  • JavaScript Code Logic
• Testing
• Deployment
• Credits
• Acknowledgements

Background

EU law mandates that 14 major food allergens are listed in food product ingredients. It is currently quite difficult when shopping to identify products which are suitable for different allergies and intolerances - generally requiring the consumer to read the ingredients on individual product packaging, which can be quite time consuming. Additionally, since the COVID-19 pandemic, consumers are less comfortable picking up products in a supermarket, reading the ingredients and then putting the product back on the shelf.

Project Goals

To provide an online, open source, interactive information resource that enables consumers to identify products which are free from common allergens, and therefore suitable for food allergies and intolerances. The site could also be expanded in the future to include for example products suitable for vegans, products which are free from palm oil, and products which are ethically sourced.

Site Owner Goals

Developing the site will serve as a learning experience for the developer. The finished website will act as a showcase for the developer's skills and will also help to raise the developer's profile. If the site becomes very popular, it may be possible to generate advertising revenue in the future.

User Goals

To find products which are free from allergens and therefore suitable for food intolerances and allergies, and to add intolerance and allergy safe food products to the information resource.

UX

Project Strategy

Opportunities Matrix

The following opportunities were identified and ranked using a score of 1 - 5 for importance and viability:

Opportunity	Description	Importance	Viability	Opportunity ID
Create database	Create an online, searchable database that enables consumers to identify products which are suitable for food allergies and intolerances	5	3	Op-1
Enable User contribution	Enable users to contribute to the database	5	3	Op-2
Showcase developer's skills	The site will serve as a showcase for the developer's skills, and increase the developer's standing within the tech community	4	3	Op-3

Project Scope

User Demographics

• The primary users of the site will be consumers with food allergies and intolerances, and consumers with children or relatives who have food allergies and intolerances.
• A simple, well layed out site with the key information being easy to find and easy to contribute to would suit this demographic.

User Requirements

• Simple and well layed out.
• Easy to find key information.
• Easy to contribute to.
• Responsive design is required as users may be viewing the site on Mobile, Tablet or Desktop.

User Stories

• As a User, I would like to be able to register on the site.
• As a User, I would like to be able to sign in to the site.
• As a User, I would like to be able to sign out of the site.
• As a User, I am searching for a product which is free from one or more allergens.
• As a User, I have found a product which is free from one or more allergens, and I want to add it to the database.
• As a User, I have tried a product and would like to rate it.
• As a User, I have tried a product and would like to review it.
• As a User, I would like to edit an existing product.
• As a User, I would like to delete an existing product.
• As a User, I would like to add a new product category.
• As a User, I would like to edit an existing product category.
• As a User, I would like to delete an existing product category.
• As a User, I would like to add a new allergen.
• As a User, I would like to edit an existing allergen.
• As a User, I would like to delete an existing allergen.
• As a User, I would like to be able to contact the developer.

Constraints

• Developer skill set - the Developer is currently learning Python, Flask and MongoDB. This may impact on which features can be succesfully implemented during the phase 1 development.
• Developer's available time - the developer is working full time whilst studying. This coupled with the developer's current skills constraints may impact which features can be succesfully implemented during the phase 1 development.

Functional Requirements

• The User needs to be able to register.
• The User needs to be able to sign in.
• The User needs to be able to sign out.
• The User needs to be able to search for products which are free from one or more allergens.
• The User needs to be able to add products.
• The User needs to be able to rate products.
• The User needs to be able to review products.
• The User needs to be able to edit products.
• The User needs to be able to delete products (this should be restricted to users with the correct privileges).
• The User needs to be able to add product categories (this should be restricted to users with the correct privileges).
• The User needs to be able to edit product categories (this should be restricted to users with the correct privileges).
• The User needs to be able to delete product categories (this should be restricted to users with the correct privileges).
• The User needs to be able to add allergens (this should be restricted to users with the correct privileges).
• The User needs to be able to edit allergens (this should be restricted to users with the correct privileges).
• The User needs to be able to delete allergens (this should be restricted to users with the correct privileges).
• The User needs to be able to contact the developer.

Business Rules

• It is not envisaged that the site will generate profits. It is intended to be used as an independent source of information for consumers. If the site becomes very popular, it may be possible to generate advertising revenue in the future.

Key Features

The following key features have been identified and scored from 1 - 5 for importance and viability. Each feature is mapped back to the Opportunities Matrix. The proposed development phase has also been indicated:

Feature	Description	Importance	Viability	Opportunity ID	Development Phase
Registration Form	User registration form	5	3	Op-2	1
Login/Logout	User login/logout form	5	3	Op-2	1
Search	Enables users to search the database based on one or more allergies or intolerances	5	3	Op-1	1
Add Product	Enables users to add a product to the database	3	3	Op-2	1
Add Category	Enables users with required privileges to add product categories to the database	3	3	Op-1, Op-2	1
Edit Category	Enables users with required privileges to edit product categories in the database	3	3	Op-1, Op-2	1
Delete Category	Enables users with required privileges to delete product categories from the database	3	3	Op-1, Op-2	1
Add Allergen	Enables users with the required privileges to add allergens to the database	3	3	Op-1, Op-2	1
Edit Allergen	Enables users with the required privileges to edit allergens in the database	3	3	Op-1, Op-2	1
Delete Allergen	Enables users with the required privileges to delete allergens in the database	3	3	Op-1, Op-2	1
Rate Product	Enables users to give a star rating to a product	2	2	Op-2	1
Review Product	Enables users to review a product	2	2	Op-2	1
Contact Form	Form to contact developer	4	5	Op-3	1
GitHub Link	Link to developer github page	4	5	Op-3	1
Upload Pictures	Enables users to add pictures of products and ingredients	1	2	Op-2	2
Barcode Scanner	Enables users to automatically add products by scanning a product barcode with their device camera	1	1	Op-2	2

Site Map

An initial Site Map was produced, and is shown below:

Wireframes

Initial Wireframes were produced showing the Home, Sign In, Register, View Product, Edit Product, Add Product, Add Category, Edit Category, Delete Category, Add Allergen, Edit Allergen, Delete Allergen and Contact Developer page layouts. The Home page is shown below:

Responsive design wireframes were then produced showing the Home page layout on Tablet and Phone. The Responsive design wireframes are shown below:

Design Choices

Fonts

Architect's Daughter has been chosen as the logo font for the FreeFrom logo. The font has a hand drawn appearence, looks very attractive with the dove logo and fits well with the overall site theme.

• font-family: "Architects Daughter", sans-serif;

Montserrat has been chosen as the title font and is used for the navigation menu, controls, forms and footer links. Montserrat has a simple, clean, rounded look and is available in a good selection of weights.

• font-family: "Montserrat", sans-serif;

Open Sans has been chosen as the body font and is used for the search results and review tables. Open Sans is complimentary to Montserrat and has a similar clean look and feel but is not quite as wide, which will allow for more information to be displayed in the search results and review tables. Open Sans is also available in a good selection of weights.

• font-family: "Open Sans", sans-serif;

Architect's Daughter and Montserrat are available from Google Fonts and are licensed under the Open Font License.
Open Sans is available from Google Fonts and is licensed under the Apache License, Version 2.0.

Colours

White was chosen as the background colour to enable a simple and clear design to be implemented.
Bright foreground colours were chosen to contrast with the white background. Colour ideas were generated using the ColorSpace Colour Palette generator. The final Colour Palette selected is shown below:

• #FFFFFF - "White" - used for the background.
• #009EA3 - "Vividian Green" - used for results and review table links.
• #E97C72 - "Salmon" - used for form control borders and results and review table next and previous buttons.
• #E35B4F - "Fire Opal" - used for navbar background, buttons, results table header backround, inputs and footer links.
• #C22C1E - "Venetian Red" - used as a higlighting colour for items coloured with "Fire Opal".
• #F5B800 - "Orange Yellow" - used for alerts, buttons, results and review table row borders and stars.
• #CC9900 - "Lemon Curry" - used as a higlighting colour for items coloured with "Orange Yellow".

Technologies

Integrated Development Environment

• GitHub

Database

• Mongo DB

Languages

• HTML
• CSS
• JavaScript
• Python

Frameworks Libraries and Tools

• Bootstrap - to assist with responsive design.
• Font Awesome - for icons.
• Google Fonts - for fonts.
• jQuery - to assist with JavaScript coding and DOM manipulation.
• PyMongo - to enable interaction with Mongo DB.
• Flask - to render and display web pages.
• DataTables - to enable easy display of data tables.
• WTForms - for Form Validation.
• wftorms-validators - for additional form validators.
• Jinja - to enable easy display of database information using templating.
• Werkzeug - to enable generation and checking of secure password hashes.
• SMTPLib - to enable contact emails to be sent.
• unittest - framework for Python Unit Testing.
• mongomock - used to create a "mock" of the Mongo DB for Python Unit Testing.

Browser Support

The following browsers are all supported by FreeFrom.

• Google Chrome
• Microsoft Edge
• Safari
• Firefox
• Opera

For further information please see the Browser Compatibility section in TESTING.md.

Structure

Information Architecture

Mongo DB has been selected to host the back end database for FreeFrom. Mongo DB is a non relational NoSQL database hosting platform, which provides an easily scalable platform to base the FreeFrom site on.

The project data schema was modelled using Moon Modeller and is shown below:

As shown in the schema diagram, there are four collections, Users, Products, Categories and Allergens.

Please note that the field allergens_suitability in the Products collection was renamed to free_from_allergens. This change was not picked up in the note below the "products" collection in the schema diagram shown above and unfortunately the free 14 day trial for the software ended.

FreeFrom is deployed using Heroku. For further information see Deployment.

Features Implemented

Please note that an account with Admin privileges has been created for testing purposes. This will facilitate testing of features which require Admin privileges. The username is testadmin1 and the password is testadmin1.

Features Implemented in Phase 1

• Home Page, enables users to search for products which are free from one or more allergens:

• FreeFrom logo, links to home page if selected:

• Home Page Alert, explains the purpose of the site, shows user name if signed in:

• Navigation Menu, enables navigation to the Home and Sign In pages if the user is not Signed In. If the user is Signed In, enables Sign Out. If the user is signed in with Admin privileges, displays the Allergens and Categories menus:

• Search Input, allows the user to optionally input product search criteria to filter search results:

• Category Selector, allows the user to optionally select category to filter search results:

• Search Button, searches the database and returns matched products in the Product Results Table. Resizes if the user is not signed in and add button is not displayed:

• Add Button, links to the Product Add form. Only shown if the user is signed in:

• Allergen Selector, allows the user to optionally select allergens to filter search results:

• Product Results Table, displays product search results. Product name links to Product View page:

• Sign In, displays form allowing the user to sign in. Includes link to Register:

• Register, displays form allowing the user to register:

• Product View, displays Product details. If the user is signed in, allows review and rating to be added or updated.
  Add button enables the user to review and rate Product.
  Add button text is changed to Update if the user has already reviewed the Product.
  Update button updates review and rating if Product has already been reviewed by the user.
  Product Edit button links to Product Edit page.
  User reviews are shown below in the User Reviews Table:

• Product Edit, displays form allowing Product to be edited. If the Product has been added by the signed in User, or if the signed in User has Admin privileges, Delete button is shown:

• Product Delete Confirm, displays form confirming Product should be deleted:

• Product Add, displays form allowing Product to be added:

• Allergen Add, displays form allowing Allergen to be added:

• Allergen Edit, displays form allowing Allergen to be edited:

• Allergen Delete, displays form allowing Allergen to be deleted:

• Allergen Delete Confirm, displays form confirming Allergen should be deleted:

• Category Add, displays form allowing Category to be added:

• Category Edit, displays form allowing Category to be edited:

• Category Delete, displays form allowing Category to be deleted:

• Category Delete Confirm, displays form confirming Category should be deleted:

• Footer Contact Developer Link, links to Contact Developer form:

• Footer GitHub Link, links to developer page on GitHub:

• Contact Developer, enables developer to be contacted by email:

• Error Page, returns a customised error message and link to the Home page if an error is encountered:

Features To Be Implemented In Future Development Phases

• Currently, when the user navigates back to the Home page from the Product View page, the previous search results are not displayed. Adding this functionality was investigated and is likely to involve significant restructuring and re-testing of the python code. This feature is recommended to be implemented in a Future Development Phase.
• Functionality for deleting user accounts should be added. Currently this has to be done in the Mongo DB back end.
• Functionality for enabling the user to change their password should be added.
• Functionality to enable an Admin user to assign Admin rights to another user, which would allow the user to edit Categories and Allergens. Currently Admin rights have to be assigned in the Mongo DB back end.
• Functionality to enable pictures of Products to be uploaded.
• Functionality to enable Products to be added by scanning barcodes.

Design Changes During The Phase 1 Development

The following design changes were implemented following initial user feedback:

• The Home and Product View page alerts were updated to include links to Sign In and Register if the user is not signed in:

• The Home page search button was updated to take up the space of the search and add buttons if the user is not signed in:

• The Register form was updated to include a link to Sign In:

• The Product Add route was updated to redirect to the Product View of the successfully added product.

• The Product View form was updated to include an Add Product button:

• Form Validation for the Product form was updated to allow special characters (e.g. "&", "-" etc) in product names, and to allow Product and Manufacturer names to be a minumum of 3 characters long.

• Selection highlighting was turned off on the Product View form fields.

• Font sizes were increased slightly.

• Additional error checking was implemented.

Responsive Styling

• The Navigation Menu is collapsible, and collapses to an icon on small devices less than 768 pixels wide. This is implemented using the Bootstrap Navbar component.
• The Search Input, Category Selector, Search Button and Add Button are responsively styled, and stack on small devices less than 768 pixels wide.
• The Product Results Table and User Reviews Table are responsively styled, so that columns are collapsed on smaller devices. This is implemented using the DataTables Responsive Extension. The class responsive is added to the table html classes. Table columns are assigned a prioirity by adding the data-priority attribute to the table header html.

See Responsive Design section in TESTING.md for further information and Responsive Testing screen prints.

Python Code Logic

The Python Code for the project has been split into the following modules, using the Flask Blueprint function:

• Application - Flask routes and functions related to the Flask Application and Error Handling.
• Database - Functions related to the Mongo Database.
• Products - Flask routes and functions related to Products.
• Allergens - Flask routes and functions related to Allergens.
• Categories - Flask routes and functions related to Categories.
• Forms - WTForms form class definitions.
• User Authentication - Flask routes and functions related to User Authentication.
• Mail - Flask routes and functions related to sending an email via the Contact Developer form.

The high level code logic is explained in the UML Diagrams below:

Products

Allergens

Categories

User Authentication

Mail

Python Code Refactoring

After attending an online Code Institute seminar on Python Classes given by Ben Kavanagh, consideration was given to refactoring the code using an object orientated approach. A new Class branch was created on in the Project Code Repository. Classes and class methods were created in the products, allergens, categories and userauth python code modules. The class orientated approach was succesfully implemented as a test on the Product View route, which resulted in a significant simplification of the code. Unfortunately, due to time constraints, it was not possible to implement the object orientated approach across the project, but this should definitely be considered for a future project development phase, and as a better method of working for future projects.

Due to time constraints, the developer decided to refactor the Python Code using Procedural Programming. The code was reviewed at a high level, and functions that could be split out and re-used were identified. A Refactor branch was created in the Project Code Repository. The Products, Categories, Allergens, User Authentication and Mail modules were refactored, the site was re-tested and the Refactor branch was merged into the Master branch in the Project Code Repository. The refactoring has greatly improved the readability of the code and will make any further future development and bug fixes much easier to incorporate.

Form Validation

Form validation is achieved in Python using WTForms. Custom Form Classes are defined within the Forms module for each required form. Additional custom validators have been imported from wftorms-validators and implemented. See below table for form validation implemented using WTForms:

Form	Field	WTForms Field Type	Required	Minimum Length	Maximum Length	Notes
Sign In	User Name	StringField	Yes	5	25	May only contain letters or numbers
Sign In	Password	PasswordField	Yes	5	25
Register	User Name	StringField	Yes	5	25	Inherits field from Sign In form class
Register	Password	PasswordField	Yes	5	25	Inherits field from Sign In form class
Register	Email	PasswordField	Yes	5	None	Inherits field from Sign In form class
Register	Confirm Password	PasswordField	Yes	None	None	Must match Password
Contact	Name	StringField	Yes	3	100	May only contain letters or spaces
Contact	Email	StringField	Yes	5	None
Contact	Message	TextAreaField	Yes	10	500
Product Add	Name	StringField	Yes	3	50
Product Add	Manufacturer	StringField	Yes	3	50
Product Add	FreeFrom	StringField	No	None	None	Automatically populated from check boxes
Product Add	Review	TextAreaField	Yes	5	50
Product Add	Rating	StringField	No	1	1	Automatically populated using JavaScript event handlers
Product View	Name	StringField	No	None	None	Read Only
Product View	Manufacturer	StringField	No	None	None	Read Only
Product View	FreeFrom	StringField	No	None	None	Read Only
Product View	Review	TextAreaField	Yes	5	250
Product View	Rating	StringField	No	1	1	Automatically populated using JavaScript event handlers
Product Edit	Name	StringField	Yes	3	50
Product Edit	Manufacturer	StringField	Yes	3	50
Product Edit	FreeFrom	StringField	No	None	None	Automatically populated from check boxes
Allergen Add	Name	StringField	Yes	3	20	May only contain letters or spaces
Allergen Edit	Name	StringField	Yes	3	20	May only contain letters or spaces
Category Add	Name	StringField	Yes	3	30	May only contain letters or spaces
Category Edit	Name	StringField	Yes	3	30	May only contain letters or spaces

JavaScript Code Logic

JavaScript has been used to implement the following features:

• Initialisation of DataTables, which are used to display the Product search results on the Home page and the Reviews on the Product View page in a searchable, sortable, paginated data table format using a plug in.

• Clickable Rating stars on the Product View and Product Add forms. When the star icons are clicked on the Product View and Product Add forms, a hidden form input with the id of "Rating" is updated to the correct "star" rating between 1 and 5 using the JavaScript on click event handlers defined in the Events module.

• When the Product View form is ready, the hidden form input with id "Rating" is read and the Rating star icons are updated to reflect the correct rating value.

See UML Diagram below:

Testing

Further testing information and screen prints can be found in TESTING.md.

Deployment

The project has been developed using Gitpod and GitHub. The project was regularly commited to GitHub during the initial development phase. The website resides as a repository in GitHub, and has been been deployed using Heroku.

In order to make a Fork or Clone of the project, a GitHub account is required. The Gitpod Browser Extension is also recommended.

The project may be Forked by following these steps:

• Go to the Project Code Repository Location on GitHub.
• In the top-right corner of the page, click Fork.

For further information on Forking a GitHub repository, see the GitHub Documentation.

The project may be Cloned by following these steps:

• Go to the Project Code Repository Location on GitHub.
• Select the Code dropdown and choose GitHub CLI under Clone. This will give you a URL that may be copied into the clipboard.
• Open the Git Bash command line interface in Gitpod.
• Change the current working directory to the location where you would like the cloned directory to reside.
• Type git clone, and then paste the URL copied earlier, eg:
  $ git clone https://github.com/richardhenyash/free-from
• Press Enter to create the local clone.
• Any required Python dependencies should be installed locally using $ pip install -r requirements.txt.

The code may also be downloaded to a local computer by following these steps:

• Go to the Project Code Repository Location on GitHub.
• Select the Code dropdown and choose the Download ZIP option.
• This will download a copy of the entire project locally as a .zip file.
• Any required Python dependencies should be installed locally using the terminal command $ pip install -r requirements.txt.

For further information on Cloning a GitHub repository, see the GitHub Documentation.

To set up the local testing environment once the code has been Cloned or Forked, an env.py file should be created in the root directory. The env.py file should be included in the gitignore file, as it contains sensitive information and should not be committed to a public GitHub repository. The env.py file should include the following environment variables:

Variable	Value
IP	0.0.0.0
PORT	5000
SECRET_KEY	your_secret_key
MONGO_DBNAME	The Mongo database name, currently set to freefrom
MONGO_URI	The Mongo connection string, currently set to mongodb+srv://<username>:<password>@<clustername>.z6xjx.mongodb.net/<database_name>?retryWrites=true&w=majority
MAIL_USERNAME	The mail account that Contact emails will be sent to. Currently set to freefrom.contact@gmail.com
MAIL_PASSWORD	The mail password associated with the mail account that Contact emails will be sent to.

Please see Example env.py file.

The steps required to deploy the website to Heroku are as follows:

• Use the pip freeze > requirements.txt terminal command to to create a requirements.txt file, which lists all the Python dependencies.
• Use the echo web: python app.py > Procfile terminal command to create a Procfile, which declares the process type. Note that the Procfile should have one line that reads web: python app.py, with no empty white space or lines.
• Push the newly created requirements.txt and Procfile files to the the GitHub repository using the git add, git commit and git push commands.
• Log in to Heroku, and create a new App by clicking the New button in the top right of your Dashboard and selecting Create new app. Give the new App a name and set the region to your closest geographical region, then click Create app.
• Select the new App from your Heroku Dashboard, then from your App Dashboard, click on the Deploy menu > Deployment method section and select GitHub.
• Search for your GitHub repository then click Connect to connect.
• Confirm that the App is connected to the correct GitHub repository.
• In the Dashboard for the new application, click on Settings menu > Reveal Config Vars.
• Set the following Config Vars:

Variable	Value
IP	0.0.0.0
PORT	5000
SECRET_KEY	your_secret_key
MONGO_DBNAME	The Mongo database name, currently set to freefrom
MONGO_URI	The Mongo connection string, currently set to mongodb+srv://<username>:<password>@<clustername>.z6xjx.mongodb.net/<database_name>?retryWrites=true&w=majority
MAIL_USERNAME	The mail account that Contact emails will be sent to. Currently set to freefrom.contact@gmail.com
MAIL_PASSWORD	The mail password associated with the mail account that Contact emails will be sent to.

• To get the correct MongoDB connection string, go to the Cluster dashboard in MongoDB, click on Connect > Connect your application, select Python, select version 3.11 or later and the connection string is displayed below. For more information see Mongo DB Connection String.
• In the Dashboard for the new application, click on Deploy menu > Automatic deploys, choose the Branch which you would like to connect and select Enable Automatic Deploys.
• In the Manual deploy section, select the branch which you would like to deploy and click the Deploy Branch button.
• Heroku will receive the code from GitHub and build the App with the required packages and dependencies.
• Once complete, you should see the message Your app was succesfully deployed.
• Heroku is now succesfully connected to GitHub and any changes made in the GitHub repository will be automatically pushed to Heroku.

Credits

• Vector Stock for the attractive dove logo.
• DataTables for the brilliant tables plug in.
• WTForms for the excellent form validation library and Crash Course which I followed to implement the Form Validation.
• wftorms-validators for the awesome additional form validation library.
• My mentor Reuben Ferrante for the examples which helped me implement the Form Validation, Flask Blueprints and Python Unit Testing.
• Google Fonts for the attractive fonts used on the site, which enabled me to get started quickly.
• hex 2 rgba for the hex to RGBA conversion tool.
• The excellent Code Institute course material which enabled me to succefully implement the project.
• ColorSpace for the colour ideas generated using the colour pallete generator.
• favicon.io for the favicon conversion tool.
• The following link for information on DataTables page and page number styling.
• The following link for information on unittest, used for Python Unit Testing.
• The following link for information on mongomock, used to create a "mock" of the Mongo DB for Python Unit Testing.

Acknowledgements

Many thanks to the following for help and inspiration during this project:

• My mentor Reuben Ferrante for helping to get me started off on the right footing, for the insightful review and comments on the site and for the help with Form validation, Flask Blueprints, Python Code Refactoring and Python Unit Testing.
• Neringa Bickmore for your encouragement with my project idea.
• Ben Kavanagh for the very helpful comments on the site and general encouragement, and for the excellent online seminar on Python Classes.
• The Code Institute slack community, for all your encouragement and help.