BookMarks in an online book review site where users can share their opinions on books the have read and search for their next great read. Whether you love pipe smoking detectives and rainy cities, plucky farm animals banding together to save the day or even action packed battles in space; Share the books that you love with BookMarks. Give your marks and share your review with the community to help others to hear about your top reads and find your next all time favorite.
- BookMarks - Book reviews and recommendations
The aim of this project is to produce a website that allows book lovers to rate and review books which they have read and share their thoughts with a wider community. With a average rating system of marks out of 5 a user should be able to tell at a glance the general consensus regarding a given book and have the option to dive deeper into peoples opinions through access to full written reviews.
- Find and learn about new books
- Find a books average rating
- Search for books by parameters such as title, author and genre
- Find the currently highest rated books
- Add books to the site
- Write and post reviews for books
- View all reviews I have posted
- Edit/delete reviews that I have posted
- View reviews other people have written
- Edit/delete books I have added
- Log in to my account
- Log out of my account
- Easily understand the purpose of the site
- Learn about specific books
- View reviews other people have written
- Create an account
- Login to an admin account
- Log out of an admin account
- Edit the details of a book
- Delete a book
- Delete a user review (potentially offensive content)
Wireframes were created for mobile, tablet and desktop screen sizes with Figma
As the focus of this site is the books I chose to use a very simple colour pallet with only one colour. This single action colour makes it easy to identify important aspects of any page and avoids causing visual clutter when placed on a page with multiple book covers of varying colours and styles. The site uses consistent styling of elements throughout to further promote readability. The site uses materializes 12 column grid system to achieve a responsive layout.
The data for this project is stored using mongo db and uses two collections for data; One for books and one for users. This is how the data is organized.
- Books
{
"_id": <Object Id>,
"author": "Author Name" STRING REQUIRED,
"genre": "fantasy" STRING REQUIRED,
"image_url": "https://example-utl.com/image.jpg",
"summary": "Example book synopsis..." STRING REQUIRED,
"added_by": "123xyz STRING REQUIRED"
"reviews": [
{
"author": "123xyz" STRING REQUIRED,
"review": "Example book review..." STRING REQUIRED,
"rating": INT range(1,5),
},
{
"author": "123xyz" STRING REQUIRED,
"review": "Example book review..." STRING REQUIRED,
"rating": INT range(1,5) REQUIRED,
},
...
],
"editors_choice": true BOOLEAN REQUIRED,
"editors_choice_data": {
"picked_by": "123xyz" STRING,
"editors_comments": "editors comments on the book" STRING
},
}
- Users
{
"_id": ObjectId("619d4a4c50a386db90b5ad8b"),
"username": "123xyz" STRING REQUIRED,
"password": <hashed password> STRING REQUIRED,
}
The sites navigation section is located at the top of all pages. This section contains the BookMarks brand name and logo as well as the page navigation controls for larger displays
or an expandable navigation sidebar for these controls for smaller screens. Nav controls responsively employ materializes active styling to indicate to the user the current page.- When logged in the page links are as follows: Home - Books - Profile - Sign Out.
- When logged out the page links are as follows: Home - Books - Sign In - Register.
The footer section is located at the bottom of all pages and contains a copyright statement and links to facebook, instagram and twitter.
Flash messages are used across the site to give feedback to users in response to their inputs. These responses include confirmation of successful login, logout, register, add new book, add new review as well as informing users or errors such as incorrect username and/or password and username already in user. Flash messages are always rendered at the top of the page.
Throughout the site book previews are displayed as cards containing the books basic info such as title, author and average rating as well as the books cover art. Preview cards also function as links to that books details page where they can find further details and review for the title. These preview cards are displayed in one or two column grids depending on the users screen size and site section.
- Top rated books
The first section of the sites home page is dedicated to the books with the highest current average ratings. This section displays book previews for the current six highest rated books.
- Editors Picks
The editors pick section of the home page contains short write ups on some of the favorite picks of site editors, encouraging users to check out certain titles and engage with the community. Each write up also contains a preview card to direct the user to the books details page.
The books page displays book preview cards for all books using a one or two column layout depending on user screen size as discussed above.
- Add a Book
When logged in the books page will display a prompt to the user to add a new book at the top of the page. CLicking this will direst the user to the add a book page. See - Add a book
- Search
The search bar at the top of the books page allows the user to sort all books by designating a search term. The page will then display any books that contain matches to the designated term in the 'title', 'author', 'summary' or 'genre' fields.
When a search is submitted a response is given qualifying the number of results and the search term given. The book preview cards for the books matching the search term are displayed bellow this section.
When selecting the add book button from the books page you are directed to a form to input the details of the new title. The form requires the user to input the books title, author, genre, summary and provide an image url before submitting this information to the database. If an invalid image url is given a placeholder image will replace the invalid value.
Each book has it's own unique page containing all it's information, user reviews and controls.
- Delete/Edit book controls
If there is a user in session and that user is either the one that added the current book or the site admin a card containing edit and delete buttons will be displayed at the top of the page.
Selecting the delete book button will open a modal asking the user to confirm the books deletion.
Selecting delete will remove the book and all reviews from the database. Selecting cancel will close the modal.
Selecting Edit book will direct the user to the edit book page. See - Edit book
- Book details
The main section of the page contains the books details. This section is similar to the book preview cards but displays the books full description and the name of the user that added the book.
If the current user is not logged in, a prompt will render under the book details card directing them to login or register to add a review to the book.
If there is a user in session and they have not previously submitted a review for the current book a prompt will render directing them to add a review. see - Add a review
- Reviews
Reviews are rendered in a series of cards each containing the name of the user that wrote it and the star rating they gave. Clicking on the card causes it to expand and reveal the review in full. Only one card may be open at a time.
If the user viewing a review is in session and the one who submitted it they will also be presented with options to either delete or edit their review. If the current user is the site admin they will have access to only the delete review control.
Selecting the delete review button will open a modal asking the user to confirm the books deletion.
Selecting delete will remove the review from the database. Selecting cancel will close the modal.
Selecting edit review will direct the user to the edit review page. See - Edit review
- Add a review
Clicking the 'Add a review' button from a books details page will open a modal presenting the user with a form to input the details of their review. This form consists of a text box for the body of the review and a 5 star rating selector.
The star rating selector was adapted from This code written by Jordan-Simonds. It is highly tactile, interactive and pleasant to use.
Submitting the form will update the current book details page and display the new review.
- Selecting to edit a book will direct the user to form identical to the add book form but pre filled with the books current information. The user is free to make any edits they like then re submit the book updating the database.
- Selecting to edit a review will direct the user to form identical to the add review form but pre filled with the current review information. The user is free to make any edits they like then re submit the review updating the database.
- Account details
Each users profile page contains three sections. The first section is a full size banner displaying the Username and a count of the total number of reviews the user has added.
The next section contains all of a users submitted reviews. These review cards follow the same format as on the book details pages but displays the name of the book the review is for instead of the review authors username.
The final section displays book preview card/links for each book that the user has added to the site.
- Login
This page consists of a login form with fields for username and password, a submit button and a section to direct users to the register page if they do not currently have a registered account. Inputs are checked on submission and if they are valid and match a registered user they will be logged in. If the data is invalid/incorrect either a form prompt or flash message will give feedback to the user and direct them to try again.
- Register
The register page is similar in layout to the login page but the main form is to register a new account and the prompt section directs to the login page for already registered users. On submission details are checked against registered users to determine if the given username is unique. If it is unique a new user account will be registered, if it is not, a flash message will be displayed asking the user to pick a different username.
Site site uses custom error 404 and 500 pages which direct the user back to the site homepage without using browser controls.
For full testing documentation please see TESTING.md
- To clone the repository for this project first navigate to the Repository main page and click on the code button.
- To clone the repository using HTTPS, select the HTTPS tab under the clone section and click the icon to copy the provided url to the clipboard.
- Open Git Bash and navigate to the location you would like to store the cloned repository.
- Type
git clone
followed by the url you copied earlier.
$ git clone https://github.com/ChronoLogic12/bookmarks.git
- Press enter to create your cloned repository.
- Open the project in your IDE of choice and install dependencies from the requirements.txt file by running
$ pip3 install -r requirements.txt
in your terminal. - To run a local development server from Bash:
$ pipenv run dev
run on http://localhost:5000/home
For more details on cloning repositories click here
To use this application you will need to connect to mongodb (or similar database service).
- Go to Mongodb and login/register an account.
- Create a cluster and establish a database for the project.
- Within the database create two clusters; one for 'users' and one for 'books'
For more details on using mongodb click here
Environment variables
- To start create a .gitignore file and add the following filenames to prevent these files from being committed to our repository.
env.py
__pycache__/
- Create a env.py file in the route directory.
- Import os and set the necessary environment variables as shown bellow.
- To find your MONGO_URL go to your cluster overview page and select 'Connect'
- Click 'Connect your application'
- From here copy the connection string provided and update the
<password>
and<dbname>
sections with the root user password and the name of default database connection respectively.
Import os
os.environ.setdefault("IP", "IP")
os.environ.setdefault("PORT", "PORT")
os.environ.setdefault("SECRET_KEY", "SECRET_KEY")
os.environ.setdefault("MONGO_URI", "MONGO_URI")
os.environ.setdefault("MONGO_DBNAME", "DATABASE NAME")
os.environ.setdefault("FLASK_ENV", "development")
To deploy this application to heroku first we must make sure to establish a requirements.txt and Procfile as heroku needs these to operate. First type:
$ pip3 freeze --local > requirements.txt
into the terminal to establish your requirements.txt file. Then enter:
echo web: gunicorn app:app > Procfile
to insert the startup commands for heroku into a Procfile.
- Next, go to Heroku and login/register
- Navigate to your dashboard and select 'New' - 'Create new app'
- Enter a unique application name and select your region then click 'Create app'
- To connect your app and set up automatic deployment, select 'GitHub' under the 'Deployment method' section.
- Select your GitHub profile and the name of the repository containing your code.
- Add your config variables to Heroku by navigating to settings, scrolling down and clicking 'Reveal Config Vars'. Then input the key value pairs from your env.py file
- Return to the deploy tab and select 'Enable Automatic deployment'
- Once the app is deployed you can open the live site by selecting the 'Open app' button at the top right of the page.
- Report system: As most of the data displayed on the site is user added (book cover images, book summaries, reviews) a system to allow users to report potentially inappropriate content to admin for review and removal would be an essential addition to future builds.
- User defined book lists: A system to allow users to 'save' books to list such as 'planned to read' or 'favorites' for later viewing could be useful added functionality and encourage more return users.
- Materialize was used throughout site for layout, interactive components, element styling, colours and icons.
- Google fonts was used to link used fonts.
- Font Awesome was user for social icons in the site footer.
- Flask micro web framework
- Heroku application host.
- Gunicorn wsgi server.
- Mongodb non relational database.
- All brand artwork was created by me with use of Adobe Photoshop and Illustrator
- All images are served to the site Cloudinary CDN for improved performance.
- Code Institute learning material - general knowledge.
- Codecademy - general knowledge.
- w3schools - general knowledge.
- MND Web Docs - general knowledge.
- Stack Overflow - debugging.
- Interactive star rating element adapted from the work of Jordan-Simonds (jexordexan)
- Flask documentation
- Jinja documentation