Portfolio Project 2 - JavaScript

A gentle reminder to all - to open links in a new tab, hold 'Ctrl' (or '⌘' on Apple devices) as you click!

Live Site

Repository

https://github.com/daveyjh/ci-portfolio-two

Objective

Design an interactive Mastermind game using JavaScript. The project should demonstrate competency with HTML, CSS and JavaScript.

The needs within this project are not genuine and are made purely for the purpose of completing my Code Institute project.

Brief

Mastermind - A Logic Game

The goal of this website is to provide an interactive version of the classic Mastermind game. The site should have:

an emotive and enjoyable, interactive Mastermind game written using JavaScript
a few difficulty options and settings
the rules of the game for those who have not played before
a brief intro and link to me as a developer
a consistent layout and design

UX - User Experience Design

User Requirements

Some example user stories which will affect the design:

"As a person who enjoys Mastermind, I want to get straight into playing the game. I have played other versions and find them a little aesthetically dull"

"As a person who hasn't played before, I would like to read the rules of the game. I want to know exactly how to play and what to expect"

"As a person that likes a challenge, I would like the option of a more difficult game"

"As an interested developer/employer, I would like to learn more about the developer of this site"

Initial Concept

I hope to provide a fully functioning version of the Mastermind game using JavaScript, HTML and CSS. I anticipate using a wooden colour scheme, perhaps with photographic textures, to add a little more style than some versions I have researched. The site should be simple to navigate, not allow errors during use and encourage users to play at increasing difficulty levels. The application is to be designed with 'mobile first' in mind.

The design process is detailed in more depth in the design-notes document.

Wireframes

See here for all mobile pages and other device types

Colour Scheme

With the game board of the site designed with a wood style background, I used instant eyedropper to obtain a couple of colours from the wood photographs. I then used coolors.co to generate a colour scheme.

The header uses the darkest colour from the scheme to contrast with the game board and allow a high contrast with the text colour. The main text content displayed in the rest of the site is set on a wood colour to maintain the style throughout. There are a few more sections with the dark colour background within the main site, these are highlighting calls-to-action, and the higher contrast helps to identify this.

Contrast checks have been carried out with the WebAIM contrast checker with regards to all main text content. I suspect the footer element is less likely to give a good result but I do not wish to detract from the site content and am happy to leave it this way.

Typography

The fonts used for the site are Orbitron and Rajdhani from google fonts.

Orbitron has been chosen as it has a geometric look that lends itself well to the content and feel of the site. It has been used for the main heading and the nav elements, all utilising the small-caps font variant.
Rajdhani has been chosen for the main text content of the site. The squared styling fits well with the Orbitron font and allows for a pleasant visual appearance with its slightly rounded corners.

Imagery

There are not many images in the site. The split-brain image in the header represents the colours of the game and the logic behind it. The repeating balls used as a background on the pages are there to break up the blank space behind sections. The favicon looks like it could be a side on version of the header image.
All the rules images are screenshot snips made using Windows Snipping Tool and are taken from the finished design of the game. The image on the about page is me, taken using a Samsung Galaxy S8. All other images were made using Paint3D.

All images have been converted to webp format using cloudconvert.

Features

Existing Features

The game is on the index page.

"As a person who enjoys Mastermind, I want to get straight into playing the game."

"...please don't force me to the rules"

The game is available to play with default settings on the index page. A user is able to play as soon as the site is loaded.

The rules page is available.

"As a person who hasn't played before, I would like to read the rules of the game."

"As a person who hasn't played before...I want to know exactly how to play and what to expect"

"...please don't force me to the rules"

The rules page is available for users who need it. It has images taken from the deployed product so they are accurate and informative.

There are a number of settings and a challenge.

"As a person that likes a challenge, I would like the option of a more difficult game"

"...different difficulty settings"

"I enjoy trying to complete the game within a set number guesses"

The settings overlay allows various difficulty settings to be changed. The challenge page allows users to play within a limited number of guesses.

The about page has some information about me.

"As an interested developer/employer, I would like to learn more about the developer of this site"

The about page has a brief introduction to me and has a contact form for any users who wish to reach out to me.

Audio settings

"...a little confirmation sound..."

There are audio confirmation sounds that can be toggled on or off. They are off as default to prevent bad UX.

Click controls

"...click rather than drag and drop"

The interface of the application allows users to single tap or click, rather than relying on a drag effect, to make their selections.

A clean and attractive design.

"...it would be nice to see a little more style"

The design considerations ensure an attractive application that is more appealing than other versions I found while researching. The photographed wood effect means the game board looks authentic.

User error preventative JavaScript.

"I don't want to waste a turn..."

The JavaScript is written in a way that prevents users from accidentally wasting a turn.

Best time and score elements.

"...know my best score"

The user is presented with their best score and best time for the session.

Scores and timers can be disabled.

"I don't enjoy seeing a timer"

The current time, best score and best time can be toggled via the settings.

Features Left to Implement

Style changes to incorporate tap target size for more than 4 balls.
- For smaller screens, the balls do not meet the minimum suggested tap target size of 40px. This could result in a bad UX.
- I think I would need to re-structure the HTML of the game to allow guess rows to be presented in a grid rather than a row. I may be able to achieve this by making style changes in the CSS. I need to spend time thinking about the most viable solution.
Tooltip to show what the results mean.
- To assist users who are unfamiliar with the game, a tooltip could help remind them of the meaning of the results.
- I came across this feature on another version of the game. It would be a nice feature for new players, but it may become annoying. It is something I would consider as a toggle option.
Offer an increase in difficulty for users on successful completion of the game.

"I like being offered a harder difficulty if I win"
- To encourage users to continue to play, and to improve their skill level, an option to increase the difficulty depending on current settings would improve UX.
- This could be implemented via a modal as opposed to the currently used confirm pop-ups. I would need to check the current settings and offer an increased number of colours or solution balls, or change the repeat settings depending on those currently selected.
Set the solution for an AI to solve.
- Have a separate page where the user can set a solution and the device calculates the correct answer within a set number of guesses.
- This could be done by utilising the Donald Knuth algorithm and having a set of controls to allow the user to progress through each stage.
Alternative patterns, instead of tooltips, for colour blind users.

"I don't want to play with colours, how about some animals or symbols instead"
- Change colours on the balls to different images/icons or patterns to enable a more user-friendly experience for colour blind users.
- This may be done through JavaScript by changing the background property to a linear background effect or an image/icon.

Technologies Used

Instant Eyedropper
- A quick and simple application to obtain hex values from any colour on my display. I downloaded this while playing around with my laptop layout/display settings. I have the app set to run on startup and remain minimized in my system tray. This allows quick access and if I click the colour, it automatically copies the value to my clipboard.
WebAIM Contrast Checker
- A basic contrast checking service for conformity to the Web Content Accessibility Guidelines. The service allows input of a foreground and background colour and displays the resulting contrast ratio, including a quick reference to meeting WCAG AA / AAA standards.
Windows Snipping Tool
- A screenshot tool built in to Windows. It allows quick, partial screenshots to be taken that can be saved as image files.
Paint3D
- Free software on Windows, allowing image editing and creation.
EmailJS
- An email client API that allows custom emails to be sent via a mix of HTML forms and JavaScript.
JSHint
- A static code analysis tool for JavaScript. Results here.
Balsamiq
- Balsamiq was used to create wireframes for the project.
CloudConvert
- All images within the project have been processed through their free file converter service
Font Awesome
- The project uses icons from Font Awesome version 5.
Coolors.co
- The colour scheme, and subsequent shades and tones, were generated via this application.
Chrome DevTools
- Once the website was made to a basic deployment level, this extension featured heavily as I modified sizings and spacings.
Google Fonts
- The fonts used in the website are imported from Google Fonts.
Favicon Converter
- A service to convert images to favicons
Multi Device Mockup Generator
- The image at the top of this document was created using a free service provided by TechSini.com
WebAIM Contrast Checker
- A contrast checker to test WCAG levels.
Wave Web Accessibility Evaluation Tool
- A tool to check for errors with accessibility. Results here.
W3C Markup Validation Service
- A service to check the HTML and CSS files for errors. During development, I copied the entire text from the files and ran them through the direct input method. Upon completion, I ran the deployed site through the 'Validate by URI' method with results here.
Visual Studio Code
- A free, streamlined code editor. The extensions available have allowed me to customize my workspace and become more efficient.

VSCode Extensions

Links to the website of each extension

Testing

I utilised the console in DevTools for some of the testing. This allowed me to check solutions without having to work them out, add rows without making 99 attempts and see stages of my JavaScript by using console.log().

//! delete before deployment
/** for testing
 * * testAddRows();
 * * aR = 97;
 * - complete first row (number border will remain)
 * - complete last row (99)
 */
function testAddRows() {
  while (guessRows.length < 98) {
    addRow();
  }
}

I used ar = (97); and testAddRows() to test the extremeLoss conditions.

Testing of internal and external links was done manually. All links directed to the intended location in the correct manner.
The challenge and default index settings were tested manually with all results as expected:
- Empty colour balls were selected and checked for functionality.
- Intended colours were selected and checked for correct placement.
- Colour balls with colours already chosen were selected to ensure the operation of the clear selector.
- Rows were completed to ensure the check result icon was displayed.
- Completed rows had a colour cleared to ensure the check result icon disappeared.
- console.log(solution) was used while checking the correct result peg operation by completing rows.
- Results were checked with all possible outcomes (number of white and black pegs).
- The game was completed in various times, using various numbers of rows, to ensure the correct function of the best score and time.
- The challenge was unsuccessful after 6 rows to ensure the loss condition worked correctly.
- The index game was unsuccessful after 7 rows to ensure new rows were added correctly.
- The colour blind option was selected and tested.
- The audio option was selected and tested for all audio instances.
- A screen reader was used to test all aria text and functions.
- The index settings were modified to test the correct operation and disablement of the checkboxes.
- The pause function of the current timer was tested by opening the settings overlay.
- The score and timer settings were tested on new games and by closing the settings overlay.
- The hint and give up icons were tested at various stages of the game to ensure correct function.
- The confirmation alerts were tested for positive and negative inputs.
- The text below the gameboard was checked in win and loss conditions.
The contact form was tested:
- Without a 'Name', 'Email' and 'Message' entry to ensure required was applied to the correct elements.
- Without a 'GitHub' entry to ensure this was not required.
- With various 'GitHub' styles to ensure the string modification worked correctly:
  - @Test
  - github.com/test
  - test
  - https://github.com/test
- By attempting to write a message longer than 250 characters.
- An example of the input and result:
The site was tested on multiple devices and browsers with all results as expected.

W3C Validator

HTML

There is a warning on the challenge page regarding a section without a heading. The section contains the gameboard and I am happy to leave it this way.

There is a warning on the about page regarding a second h1 element. The heading sits within an article and appears to be an acceptable practice. See here for reference.

CSS

There are some warnings returned by the CSS validator. One that occurs on all pages is a reference to the body color being the same as its background-color. All text is set on a different colour background, styled later in the CSS. Targeting the body font color allows fewer declarations.

There are other warnings that refer to vendor extensions. These are required to ensure styles are maintained across various browsers.

The majority of the warnings come from the FontAwesome CSS and are beyond my control.

Wave

No errors are reported on any of the pages. There are multiple alerts for font sizes, however these are for screen readers so I am happy to leave them in place.

JSHint

No errors are reported by JSHint. There are 3 warnings reported in the JavaScript files.

The warnings refer to functions that reference outer scoped variables and functions. This could be resolved by re-declaring the variables and functions within the function, but seems an unnecessary step as variables are descriptively named and docstrings are present for functions.

Lighthouse Testing

Mobile

Performance and SEO scores could be a little higher.

The image used for the background of the gameboard is delayed by some of the third-party stylesheets and could be re-designed to use linear-gradients. I tested this with commit 966c35d but found the style was not suitable. The slight difference in performance score did not warrant a reduction in UX.

The maximum cache time is set by GitHub pages at 10 minutes. This also reduces the performance score and is beyond my control.

Reference

SEO scores are affected by the small font size applied to screen reader assistive text.

Desktop

All scores are green and highly satisfactory.

Coverage

Chrome DevTools Coverage tab was used after searching for easy ways to check for unused CSS declarations. This allowed me to test all JavaScript was error-free and being used. There are a few untested lines in email.js that I cannot work out how to test manually.
Some of the CSS remains unused, mainly comment lines that help break up the styles into sections. The main CSS sheet could be separated a little more to reduce unused lines for the 'about' and 'rules' pages, but the other tests performed on those pages did not highlight a need to improve their performance.

I am unable to test the third-party files so have omitted their results where possible.

Index
Challenge
Rules
About

Bugs

Current

When playing the game on a mobile device and having the 'Colour Blind' setting enabled, the tooltip remains above the ball that is selected for a colour selection.

The bug is due to the .blur() method not working as intended on touch screen devices. I investigated ways to resolve this but found the impact on UX to be so minimal it did not warrant the time spent on it.

The completed row results and solution balls are not accessible via the tab key.

This could provide a poor UX for colour blind switch/keyboard users. I am unsure of how to resolve this issue as the elements are not interactive and so a tab-index attribute should not be used.

Resolved

When playing the game an error was generated in the console once line 99 had been attempted. Two errors were causing this:

Commit - bd06f93 - Corrected second line in extremeLoss() to correctly target the hintIcon.

Commit - bd06f93 - Added to line in reset() to prevent deactivateRow() when aR was equal to or greater than 98.

If the settings menu was opened with a keyboard and the focus jumped to the first button, the button would trigger. This revealed a number of other issues:

Commit - 2e48239 - Changed keydown in addEventListener to keyup. I was made aware of this by SiJiL82 after posing a question regarding the bug in the Code Institute Slack community. Thanks Sven!
This made me realise many of my functions would be made better with keyup to try and prevent bad UX in the case of users with slower motor skills.

Custom styled checkboxes were not giving good UX when disabled:

I spent a lot of time looking over various methods to resolve this issue. The main issue is for accessibility, being that a disabled checkbox is effectively removed from the DOM. This causes a bad UX for users with specialised controls and screen readers. After many attempts, I realised I could have achieved the intended result with fewer lines of code but I am happy with the logic that is being applied to my solution.

Links to element ids were not responding as expected on larger screens:

Commit - 8a50740 - Added JavaScript and extra spans to dynamically change href values.
When clicking on an internal link on a large screen, the top of the destination was overlayed by the header. This was due to position: sticky and was overcome by use of some positioned elements with a similar id to the target and a small JavaScript file to calculate if the destination should be modified.

When playing with more than 4 balls in the solution, if a new row was created, the balls would not be re-sized:

Commit - e762e7a - Added resizeBalls() to addRow()

With 'Colour Blind' active, it was possible to tap just outside the ball to bring up the tooltip without activating the button:

*Commit - 915aded - Modified .tooltip-holer to have border-radius: 50%.

Tooltips and aria text was not updating when using a hint:

Issue #17 - Modified addOneSolutionColor() and found setSolutionBallCount() needed an extra loop to set the original ball text.

Development

The site was made utilising GitHub and VSCode

GitHub

GitHub Website

Sign in to GitHub
I use a template that contains a template of my README file which can be accessed here and is available for public use via the Use this template button

Click and select
New from the panel on the left, next to Repositories

Select the template you wish to use

Give the repository a name and description and then click Create repository

The repository has now been created and is ready for editing

VSCode

VSCode Website

For general information on using GitHub with VSCode see their documentation here.
This section assumes you have successfully linked your GitHub account to the application

Cloning

Open the command panel using your keyboard shortcut or View > Command Palette...

With the command palette open, type clone and click Git: Clone and then Clone from GitHub

Type the GitHub username followed by / and the repository you wish to work on

Click the repository from the drop-down list and save it in a local directory
of your choosing

The repository is now ready for development

Extensions

Once the repository is open within VSCode, there are many extensions and aids that can assist with your development process. This is a list of extensions I use with a brief description of the main functions I utilise

Beautify - Auto-formatting of files
Better Comments - Colour comments for easier identification
Bracket Pair Colorizer 2 - Colours nested brackets and sequential brackets for more efficient workflow
GitHub Pull Request and Issue Provider - Allows better integration with GitHub
Highlight Matching Tag - Highlights paired tag for more efficient workflow
Markdown All in One - Auto updates contents section and other efficiency features when writing markdown documents
markdownlint - Highlights errors and best practices with markdown documents
Preview on Web Server - Allows live webserver via keyboard shortcut
Colored Regions - Allows collapsible sections of code by using certain comment strings. I have used these in my JavaScript files by using //#region [attribute here] and then ended by //#endregion

Editing

The explorer tab enables viewing of the files within the repository

Open files from the explorer tab in the editor window and perform changes as necessary

Save files as appropriate, add, commit and push them. There are multiple ways to do this
- VSCode Source Control
  - Select the Source Control tab that looks like a repository branch
  - Click the + sign next to files you wish to add to staged changes
  - Type a commit message and click the tick icon to commit
  - When ready to push your repository back to GitHub click the push/pull icon in the bar at the bottom of the application
  - I have many keyboard shortcuts set to speed up this process, they are configurable within the VSCode settings
- Terminal
  These steps assume you are in the root directory of your repository and typing in the terminal
  - Type git add . and press Enter to add all modified or untracked file
  - Type git add fileNameHere.extension assets/anotherFileHere.extension and press Enter to add specific files, remembering to include sub-directories where necessary
  - Type git commit -m "meaningful message here" to commit your staged files with the typed commit message
  - Type git push to push your repository to the remote repository held at GitHub
  - There are many other stages to editing, such as branches, git stash, reverting commit messages and others. For more information, refer to the git documentation

Deployment

Github Pages

Navigate to the relevant GitHub Repository here
Select Settings from the options below the name of the repository

Select Pages from the left-hand menu

Select Branch: main as the source and leave the directory as /(root)

Click the Save button
Take note of the URL provided

GitHub takes a short while to publish the page. The bar turns green if you refresh the pages tab and the page has been deployed

Click the link or copy the URL to a browser to reach the deployed page

https://daveyjh.github.io/ci-portfolio-two/

The site is now live and operational

Forking

If you wish to contribute to the site, this is most simply achieved by forking the repository.

Head over to GitHub and log in.
Search my username and repository in the bar provided

Select the repository
Click the fork icon in the top right

This creates a fork within your GitHub repositories
Edit the files as necessary using your preferred method
Add, commit and push your changes to your remote repository using your preferred method
In your repository on GitHub select Pull Requests

Click New Pull Request

Check the details of the pull request and then click Create pull request

Add a message explaining what your pull request adds to the repository and complete with Create pull request

I will receive the pull request and action it accordingly.

Credits

Content

Thanks to Donald Knuth for his algorithm information.

Media

The favicon image and header image are license-free, obtained from Pixabay.
The audio content is license-free and comes from ZapSplat.

Acknowledgements

Thanks again to Sven, SiJiL82, for drawing my attention to the use of keyup rather than keydown.
The custom checkboxes were originally based on an example found at W3Schools.
Some credit to the Code Institute course content for the basic timer function. I modified it quite a bit, but the general concept remains the same.
The modification owes credit to Joseph Marikle for his answer on Stack Overflow. The answer that applies only for positive integers works for this situation.

Personal Development

Accessibility

I would like to learn more about accessibility requirements. I feel I have a good understanding of some of the basics, however, I do not have enough knowledge of what various users would expect as 'normal behaviour'. As an addition to this, I should try and maintain designing things with more accessibility in mind at the initial stages.

JavaScript Structure

During this project, I have learned about many ways of working with JavaScript. One key aspect is the capability to pass variables and functions around a script. I have not utilised this enough in this project and will strive to design my future projects differently to allow less verbose code structures. Another point to consider is file size. Although I am comfortable with reading through my own code and have separated it into smaller functions, it does not lend itself to good readability and general maintenance. I hope to segregate my functions into relevant files in future projects.

GitHub Project Board and Issues

I took part in a hackathon event with a great team during the development of this site. I found the tracking, and workflow assistance that can be provided from it, to be very useful. I did not think to implement it on my own, solo project until very late in the development stages. In future projects, I intend to utilise the features far more often and to greater effect.

Name		Name	Last commit message	Last commit date
Latest commit History 517 Commits
assets		assets
node_modules/emailjs-com		node_modules/emailjs-com
readme-content		readme-content
.gitignore		.gitignore
README.md		README.md
about.html		about.html
challenge.html		challenge.html
index.html		index.html
package-lock.json		package-lock.json
rules.html		rules.html

DaveyJH/ci-portfolio-two

Folders and files

Latest commit

History

Repository files navigation