E-Library

E-Library is a web-based application designed to provide a comprehensive platform for managing and accessing a digital library. The application is built using Django and JavaScript, with package management handled by pip for Python and npm for JavaScript.

The application allows users to browse through a vast collection of digital books, each associated with its respective author. Users can also borrow and return books, providing a dynamic and interactive library experience.

The application has two main user roles: User and Administrator. A User can browse the library, borrow books, and return them when finished. An Administrator, on the other hand, has the ability to add, delete, and modify books and authors in the library, providing comprehensive management of the library's content.

The application ensures secure user authentication and role-based access to various features. It also includes robust error handling and user notifications for a smooth user experience.

The project uses a PostgreSQL database for data storage, managed through Django's ORM. It also leverages Cloudinary for efficient and scalable media management.

The application's user interface is designed to be intuitive and user-friendly, ensuring a seamless user experience.

---

View live project here

The application implements the following features:

• Access to the application is only possible through a login and password.
• The application has 2 user roles: Reader and Administrator.
• Registration of a new user (with the role of Reader) through the user interface.

Common functionality for both roles includes:

• Logging into the application through a login form.
• Viewing all books in the library.
• Editing information in the profile about the current user logged into the system, including changing the photo.
• If the user will try to access the route that is not exist, the user will be redirected to the 404 page.
• There are tooltips for all interactive elements in the application which provide additional information about the action that will be performed after clicking on the element.
• There are toasts for all create, update and delete operations which provide current user details about what he\she has just done.
• All input fields in this application are mandatory and have a validation on the client side.

Reader functionality:

• Borrowing books from the library.
• Returning books to the library.
• Seeing books that are unavailable and who is reading them.
• Does not have access to the authors' page, if the user tries to access this page, the user will be redirected to the 403 page.
• On the profile page, view the books that the reader is currently reading.
• There was also implemented a special error handling for 500 error, which is simulated on the server side. To see it, you need to check checkbox on profile page.

Administrator functionality:

• Adding new book authors.
• Editing book authors.
• For Adding and Editing book authors operations, implemented complex validations on client and server sides.
  • Client side: the input field cannot be empty and should be at least 1 character long.
  • Server side: each word must start with a capital letter separated by a space.
• Deleting book authors.
• Adding new books.
• Editing existing books.
• Deleting existing books.
• If a book is already being read by someone, such a book cannot be edited and the author of such a book also cannot be edited. The book must be returned by the reader before it can be edited or deleted.

Existing Features

• Books

  • Administrator:

    • View all books in the library.

    • Add a new book to the library.

    • Edit an existing book in the library.

    • Delete a book from the library.

      

    • The book must be return before deleting or editing.

      

  • User:

    • View all books in the library.

      

    • Borrow a book from the library.

      

    • Return a book to the library.

      

    • See if someone is reading the book.

      

• Authors

  • Administrator:

    • Add a new author to the library.

    • Edit an existing author in the library.

    • Delete an author from the library.

      

    • See if the book is taken by any reader.

  • User:

    • Do not have access to see this page.

    • If a user tries to access this page, they will be redirected to the 403 page.

      

• My Profile

  • Administrator:
    • Edit information about itself:
      • First name.
      • Last name.
      • Email.
      • Profile image
  • User:
    • See the books that are currently reading.
    • Edit information about itself:
      • First name.
      • Last name.
      • Email.
      • Profile image.
    • Simulate error on server to see how work error handling for 500 error.

Features Left to Implement

• Protection of routes by roles through decorators.
• Make a check so that you cannot enter the same title of a book by the same author twice.
• Pagination, if there is a lot of content.
• Use ajax to avoid page reloading.
• Returning a book from the profile page.
• External link field in the books from which the book content could be accessed.

GitHub Project Board

The project was managed using a GitHub Project Board

Data model

1. User Model: This is a built-in Django model that represents the users of your application. It includes fields for username, password, email, first name, and last name. The User model is used for authentication and authorization in the Django framework.

2. ProfileImage Model: This model is related to the User model with a one-to-one relationship. It represents the profile image of a user. It includes the following fields:

   • user: A one-to-one field linking to the User model. When a User instance is deleted, the associated ProfileImage instance will also be deleted.
   • image: A field that stores the image of the user's profile. It uses the Cloudinary service for image hosting.

3. Author Model: This model represents the authors of the books in your application. It includes the following field:

   • name: A character field with a maximum length of 200 characters that stores the name of the author.

4. Book Model: This model represents the books in your application. It includes the following fields:

   • title: A character field with a maximum length of 200 characters that stores the title of the book.
   • author: A foreign key field linking to the Author model. When an Author instance is deleted, the associated Book instances will not be deleted but the author field will be set to NULL.
   • reader: A foreign key field linking to the User model. It represents the user who is currently reading the book. When a User instance is deleted, the reader field in the associated Book instances will be set to NULL.

The User model handles user authentication, the ProfileImage model handles user profile images, the Author model represents book authors, and the Book model represents the books in application and their current reader.

Technologies Used

Languages Used

• HTML5
• CSS3
• JavaScript
• Python 3.9.19

Frameworks, Libraries & Programs Used

1. Google Fonts:
   • Google fonts were used to import the 'Open Sans' font into the style.css file which is used on all pages throughout the project.
2. Font Awesome 6.5.2:
   • Font Awesome was used on all pages throughout the website to add icons for aesthetic and UX purposes.
3. Bootstrap 5.3.3:
   • Bootstrap was used to assist with the responsiveness and styling of the website.
4. jQuery 3.7.1:
   • jQuery came with Bootstrap to make the navbar responsive but was also used to show tooltips.
5. Google Chrome 124.0.6367.62:
   • Google Chrome was used as a browser to render and debug this project.
6. Django 4.1.13:
   • Django is a high-level Python web framework that encourages rapid development and clean, pragmatic design.
   • There were also used other libraries in this project.
7. ElephantSQL:
   • ElephantSQL was used to store data.
8. Cloudinary:
   • Cloudinary was used to store images.
9. Node.js 20.12.2:
   • Node.js was used to run JavaScript unit-tests.
10. npm 10.7.0:
    • npm was used as a package manager for installing dependencies.
11. JSHint:
    • JSHint was used to check the quality of JavaScript code.
12. Jest 26.6.3:
    • Jest was used for writing unit-test for JavaScript part of this Project.
13. Coverage 7.4.4:
    • Coverage was used to measure code coverage of Python code.
14. Git 2.39.1:
    • Git was used for version control to commit and Push code to GitHub.
15. GitHub:
    • GitHub was used to store the projects code after being pushed from Git.
16. Heroku:
    • Heroku was used to deploy the project.
17. Bash 5.2.12:
    • Bash was used to automate running Test Coverage reports.
18. GitHack:
    • GitHack was used to render Code coverage reports when you click on it on this page.
19. Far Manager 3.0.5700.0:
    • Far Manager was used to work with files.
20. PyCharm 2024.1:
    • PyCharm was used to write all code for this project.
21. Microsoft Windows 10.0.19045 Enterprise:
    • Windows was used as an operating system for development this project.

Manual Testing

Testing Login Functionality

1. Testing login with correct credentials

   • Navigate to the login page.
   • Enter the correct username and password.
   • Click the "Sign in" button.
   • Verify that you are redirected to the book page of the application.

2. Testing login with incorrect credentials

   • Navigate to the login page.
   • Enter incorrect username and password.
   • Click the "Sign in" button.
   • Verify that an error message is displayed.

Testing Registration Functionality

1. Testing registration with correct data

   • Navigate to the registration page.
   • Enter correct data into all form fields.
   • Click the "Sign Up" button.
   • Verify that you are redirected to the book page with a successful login message.

2. Testing registration with incorrect data

   • Navigate to the registration page.
   • Enter incorrect data into one or more form fields.
   • Click the "Sign Up" button.
   • Verify that an error message is displayed.

Testing Book Viewing Functionality

1. Testing viewing the list of books

   • Navigate to the books page.
   • Verify that a list of all books is displayed.

2. Testing viewing book details

   • Login as an Administrator.
   • Navigate to the books page.
   • Click on edit button one of the books.
   • Verify that a page with details of the selected book is displayed.

All additional features and functionality not explicitly mentioned in this section have also been thoroughly tested and are confirmed to be working correctly.

Automation Testing

The entire project is covered by unit tests. Test coverage reports can be viewed in the following links:

• Django Test Coverage Report
• JavaScript Test Coverage Report

Validator Testing

• HTML
  • All errors found by official W3C validator were fixed in separate commit.
• CSS
  • No errors were found when passing through the official (Jigsaw) validator
• JavaScript
  • No errors were found when passing through the JSHint validator according to settings.
• Python - All errors found by CI Python Linter were fixed in separate commit.
• Accessibility
  • I confirm that the colors and fonts chosen are easy to read and accessible by running it through lighthouse in devtools.

Unfixed Bugs

• Due to the fact that as an initial template I took an open source template and modified it, there may be unused classes in HTML and CSS, because I did not find tool that can check it automatically, I tried to find and remove it manually.

Deployment

By default, all console commands should be run in git bash terminal.

Deployment To Heroku

The project was deployed to Heroku.

The process of deploying this project to Heroku is consist of these main steps.

1. You should have accounts on GitHub, Heroku, Cloudinary, ElephantSQL.
2. You should create database on ElephantSQL and create models.
3. Deploy the project to Heroku.

Cloudinary

To get the CLOUDINARY_URL, you need to create an account on Cloudinary and follow the instructions to get the URL:

1. Log in to your Cloudinary account.
2. Go to the "Dashboard" in section "Product Environment Credentials" you will see "API environment variable". It is your CLOUDINARY_URL.

ElephantSQL

To get the DATABASE_URL and SECRET_KEY, you need to create an account on ElephantSQL and follow the instructions to get the URL:

1. Log in to your ElephantSQL account.
2. Click on "Create New Instance".
3. Name your database and select the "Tiny Turtle Free" plan.
4. Select the data center near you and click "Review".
5. Click "Create Instance".
6. Click on your new database instance you just created in section Details you will see Password and URL, this corresponds to the SECRET_KEY and DATABASE_URL.

Creating models on ElephantSQL

To create models on ElephantSQL you need to do the following steps:

1. Clone the project to your local machine, to do it run this command in your terminal:

   git clone https://github.com/SVDotsenko/portfolio-project-4.git

2. Follow the instruction in env.md file.
3. On your local machine, must be installed Python 3.9.19 or higher.
4. Create a virtual environment by running this command in your terminal:

   python -m venv .venv

5. Activate the virtual environment by running this command in your terminal:

   source .venv/Scripts/activate

6. Install all dependencies from the requirements.txt file by running this command in your terminal:

   pip install -r requirements.txt

7. Run the following command in your terminal to create models on ElephantSQL:

   python manage.py migrate

8. Create a superuser by running this command in your terminal:

    python manage.py createsuperuser

9. The users with role Reader can be created through the sign-up form.

Heroku

1. Fork this project into you GitHub account:

2. Log in to your Heroku account.

3. Click on the "New" button and select "Create new app".

4. Choose a unique name for your app, select the region and click "Create app".

5. Go to the "Settings" tab and click on "Reveal Config Vars".

6. Add the following config vars from your env.py file

   • DATABASE_URL: Your ElephantSQL database URL.
   • SECRET_KEY: Your ElephantSQL secret key.
   • CLOUDINARY_URL: Your Cloudinary URL.
   • DJANGO_DEBUG: False.

7. In the "Deploy" tab, select "GitHub" as the deployment method.

8. Search for the repository you forked earlier and click "Search".

9. Click "Connect" to connect the repository to Heroku.

10. Scroll down to the "Manual deploy" section and click "Deploy Branch".

11. Once the deployment is complete, click "View" to open the live app.

How to run this project locally

To run this project locally, you need to do the following steps:

1. Follow the instruction from section Creating models on ElephantSQL in this file.

2. Run this command:

   python manage.py runserver

How to run unit tests locally and see coverage reports

To run unit tests locally and see coverage reports, you need:

1. On your machine must be installed Node.js.
2. Install dependencies from the package.json file by running this command:

   npm install

3. Run this command to run unit tests:

   ./coverage.sh

4. The browser should be opened a new tabs with the coverage reports.

Credits

This template was adopted for the project.