Web Engineering Coding Playground Template

This repository is designed as the foundation for coding playgrounds in the Web Engineering course. It offers a structured space for experimenting with and mastering various web development technologies and practices. The project is based on this repository from MDN.

The project introduces a lot of code smells for you to tackle. Lets get coding!

Submission Details and Deadlines

• Coding playgrounds are individual work
• There will be 2 serparate submissions:
  • Base Playgrounds: Submission Deadline 03.11.2024
  • Extended Playgrounds: Submission Deadline 16.01.2025
• The playgrounds will be guided through in our sessions - still there will be distance work!
• Use this base template to create your project repository.
• Each playground is linked in the corresponding course section.
• You can find the submissions at the bottom of the Moodle course.

Features

• Wonderful UI-design 😍
• Loads bear data using Wikipedia API 🐻
  • Original Wikipedia Page can be found here
• Worst JS coding practices 😰
• No Build and Dependency Management at all 🔥

Base Coding Playgrounds

K.O. Criteria

• No JS Frameworks allowed to solve the base coding playgrounds (e.g. Vue.js, Angular, React, Svelte,...) - don't panic we will come to them!
• No CSS Libraries allowed (e.g. Bootstrap, Material, Tailwind, ...)

Submission

Submit your coding repository link in Moodle. Send me an invitation to your repository if it is set to private:

GitHub: leonardo1710

GitLab: [email protected]

1. JS Playground (10 Pts.)

The provided base project template contains some bugs and bad JS coding practices for you to fix in your first playground. Take a look into the component files and get a grasp of the inner workings of the provided project.

ATTENTION: After finishing the JS Playground please create a commit or branch and link it below. Otherwise it is not possible to grade your 1. submission, since we will switch to TypeScript afterwards!

This is my JS Playground commit/branch: https://github.com/annaerdi/WebEngineering_BasePlayground/tree/Task-1-JS-Playground

Tasks: Fix application code and answer the questions:

• (2) Adapt the code to use async/await instead of the then()-callback hell and refactor the functions to use arrow function syntax instead of function()-syntax.
• (2) Add proper error handling to the code using try/catch and provide useful error messages to the users. Additionally, check the image URL availability before rendering the images in HTML. Provide placeholder images if the given URL does not exist.
• (1) Extract the range value from the provided Wikitext (response from the API). Examine the provided Wikitext format inside extractBears function.
• (1) Split the code into separate modules with regards to clean separation of concerns.
• (1) Eliminate all other bad coding practices you can find.
• (3) Answer the following questions and provide some examples inside the Readme.md file.

What bad coding practices did you find? Why is it a bad practice and how did you fix it?

• Using let or const instead of var is a good practice because it is block-scoped and not function-scoped.

  Also, variables declared with var are hoisted to the top of their scope, but they are not initialized until their original position in the code. This can cause unexpected behaviors. let and const are also hoisted, but they are in a temporal dead zone from the start of the block until the declaration is encountered, which means they cannot be accessed before the declaration. For example:

  console.log(a); // undefined (because of hoisting)
  var a = 5;
  
  console.log(b); // ReferenceError: Cannot access 'b' before initialization
  let b = 10;

• Another good practice is to use if(showHideText === 'Show comments') instead of if(showHideText == 'Show comments') because it is more strict and does not allow type coercion.

  In JavaScript, the == operator performs abstract equality comparison, which means it attempts to convert the operands to the same type before making the comparison. This can cause unexpected results if the variables have different types. For example:

  0 == '0'; // true
  false == '0'; // true
  null == undefined; // true

  To avoid this, it's recommended to use the === operator, which performs strict equality comparison. This means it checks for both value and type equality without performing type coercion. So by using ===, we ensure that showHideText is not only equal to 'Show comments' in value but also that it is of the same type, a.k.a. both are strings.

• Lastly, it is also a good practice to use inline variables when it would be reduntant otherwise for better readibility. For example:

  // instead of this:
  const imageUrl = page.imageinfo[0].url;
  return imageUrl;
  
  // use this:
  return page.imageinfo[0].url;

2. Dependency- and Build Management Playground (10 Pts.)

Build the application with npm and a build and a dependency management tool of your choice (e.g. Vite, Webpack, or others).

Here are some additional resources: Package Management and Bundling, Vite Tutorial, Webpack Tutorial.

Tasks:

• (1) Integrate npm and a build management tool into your project.
• (2) Configure your project to use Typescript as your primary development language and adapt the code and file extensions respectively.
• (2) Use ESLint and Prettier inside your project - rulesets can be found below.
• (1) Keep your builds clear and add dependencies to the right build (e.g. do not add dev dependencies inside the production build and vice versa).
• (1) Define the following tasks within npm scripts:
  • dev: starts the development server
  • build: runs the typescript compiler and bundles your application - bundling depends on your chosen build tool (e.g. Vite, Webpack) but typically bundles multiple files into one, applies optimizations like minification and obfuscation and outputs final results to a dist or build directory.
  • lint: runs ESLint on all .js and .ts files in your projects /src directory
  • lint:fix: runs and also fixes all issues found by ESLint
  • format: formats all .js and .ts files in your projects /src directory
  • format:check: checks if the files in the /src directory are formatted according to Prettier's rules.
• (1) Configure a pre-commit hook that lints and formats your code using husky and lint-staged. A tutorial can be found here.
• (2) Answer the question at the end of this section inside Readme.md file:

ESLint Configurations

Use ESLint configs standard-with-typescript and TypeScript ESLint Plugin. Your .eslintrc file should have the following extensions:

...
extends:
  - standard-with-typescript
  - plugin:@typescript-eslint/recommended
  - plugin:prettier/recommended
  - prettier
...

Prettier Configurations

Apply the following ruleset for Prettier:

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 2,
  "printWidth": 80
}

What improvements in your codebase were introduced by using TS instead of JS? Name at least 3 and explain why.

Present your findings here...

1. Added type annotations: Type annotations were added for function return types (e.g., fetchImageUrl, isImageAvailable, extractBears, and getBearData, etc..) and for function parameters (e.g., fileName: string, url: string, wikitext: string). This provides better code clarity and ensures type safety, reducing runtime errors by catching incorrect data types during development.
2. Type casting: it was used for specific objects, such as the page object in fetchImageUrl (const page = Object.values(pages)[0] as { imageinfo?: { url: string }[] };) and for DOM elements (const moreBearsSection = document.querySelector('.more_bears') as HTMLElement | null). By explicitly defining an expected type, if TypeScript cannot infer it automatically, then it prevents potential type-related bugs.
3. Defined custom type for the bears array items, specifying its structure (const bears: { name: string; binomial: string; image: string; range: string }[] = [];). This improves the maintainability of the codebase, making it easier to understand the structure of objects and reducing errors when modifying or using these objects throughout the code.

3. CI/CD Pipeline Playground (5 Pts.)

Implementation of a CI/CD pipeline to automate the development and deployment process – write automated tests.

Here are some additional resources: GitHub Actions Tutorial and GitHub Actions Docs.

Tasks:

• (1.5) Write at least 2 meaningful unit tests (use Vitest or Jest) for your project and configure the following tasks in npm scripts:
  • test: runs all files that include .test. or .spec., e.g.: example.test.ts
  • test:coverage: runs tests like test but also creates a test coverage report
• (1) Configure 2 Workflows in GitHub Actions, one for development and one for deployment:
  • Create a development branch inside your repository
  • (1) Development Workflow should at least test and lint your code when developers push to branch development
  • (1) Deployment Workflow is triggered when developers push into main branch. It should at least test, lint and build your source code. Afterwards the build artifacts of your application should be automatically deployed to Github Pages (or another hosting provider of your choice).
• (0.5) Reuse existing workflows or jobs whenever possible!

4. Accessibility Playground (5 Pts.)

You might have noticed that the base project has a number of accessibility issues - your task is to explore the existing site and fix them. Use the tools presented in our accessibility workshop to test the accessibility in your project.

(0.5) Color

Test the current color contrast (text/background), report the results of the test, and then fix them by changing the assigned colors.

Present your reports here.

Testing the color ratios was done using the WebAIM Contrast Checker.

To see the full report of accessibility, click here.

Because of the green background color, the contrast ratio was very low everywhere. To mitigate the problem, the color was changed to a lighter shade of green (#89C889) to fix the ratio everywhere. Additionally, the header text color was changed back.

Element(s)	Old Contrast Ratio
Header	Very low contrast (1.34:1)
Navigation bar + article body	Very low contrast (4.08:1)
Article headers + sidebar headers + footer	Very low contrast (2.79:1)
Sidebar with links	Very low contrast (1.82:1)

(0.5) Semantic HTML

Report on what happens when you try to navigate the page using a screen reader. Fix those navigation issues.

Currently, the screen reader (Narrator on Windows) only reads that "WebEngineering Code Playground has finished loading".

Changes made to fix this:

• Added roles and labels like role="banner", role="main", aria-label for better accessibility and navigation.
• Changed font tags to semantic headings (e.g., <h2>, <h3>, etc.) for better screen reader support.
• Added <label> elements to inputs in forms to ensure screen readers can identify the purpose of each field.
• Added alt attributes to images to describe them to screen readers.

(0.5) Audio

The <audio> player isn't accessible to hearing impaired (deaf) people — can you add some kind of accessible alternative for these users?

Changes made to fix this:

• Added a <figure> element to group the audio content with its transcript
• Implemented a collapsible transcript using the <details> and <summary> elements

(1) Forms

• The <input> element in the search form at the top could do with a label, but we don't want to add a visible text label that would potentially spoil the design and isn't really needed by sighted users. Fix this issue by adding a label that is only accessible to screen readers.
• The two <input> elements in the comment form have visible text labels, but they are not unambiguously associated with their labels — how do you achieve this? Note that you'll need to update some of the CSS rule as well.

Present your findings and fixes here.

Search Form:

• Added a visually hidden label using the .visually-hidden class
• The label is properly associated with the search input using the for attribute
• Screen readers will announce "Search the website" when focusing on the input

Comment Form:

• Updated the id attributes of the inputs to be unique and descriptive
• Properly associated labels with inputs using matching for and id attributes

(0.5) Comment section

The show/hide comment control button is not currently keyboard-accessible. Can you make it keyboard accessible, both in terms of focusing it using the tab key, and activating it using the return key?

Present your findings and fixes here.

To fix the keyboard accessibility of the show/hide comments button, the div element was changed to a button element, which is natively keyboard accessible. The element is focusable and can be activated using the Return (Enter) key.

(1) The table

The data table is not currently very accessible — it is hard for screen reader users to associate data rows and columns together, and the table also has no kind of summary to make it clear what it shows. Can you add some features to your HTML to fix this problem?

Explanation of the changes made:

• Added a <caption> element to provide a summary of the table content
• Added <th> elements to the table headers to make them distinguishable from the data cells
  • The scope="col" attribute specifies that the header relates to the entire column.
  • The scope="row" attribute specifies that the header relates to the entire row.

(1) More Findings

What other accessibility issues did you find? Explain how you did fix them.

Missing alt attributes for images. Fixed it by Adding alt attributes to all images to provide alternative text for screen readers.

Extended Coding Playgrounds

Please create a new independent Repository for these playgrounds and submit a link to it in the Moodle submission. Additionally, provide a description of how to start your frontend and backend services inside the README.md.

Submission

Submit your coding repository link in Moodle. Send me an invitation to your repository if it is set to private:

GitHub: leonardo1710

GitLab: [email protected]

5. Migrate to a Frontend Framework (10 pts.)

In this playground you will migrate your application to a frontend framework of your choice.

Tasks:

• Migrate your application to a frontend framework of your choice (e.g. React, Angular, Vue.js, Svelte,...)
  • All previous features should still work
  • The application still should use build and dependency management
• Adapt your npm scripts if necessary

6. Integrate a Backend Framework (10 pts.)

In this playground you will use a backend framework of your choice and connect it with an API to your frontend application.

Tasks:

• (3) Setup a backend framework of your choice
• (2) Create an API your frontend will be connected to (REST, GraphQL, gRPC, you choose...)
• (2) Your backend should now request the bear data from presented Wikipedia API
• (3) Replace the frontend Wikipedia API calls with calls to your backend - the functionality of your frontend should work as before!
• (Optional): you may want to introduce some sort of caching layer for Wikipedia API requests

7. Containerize your application (10 pts.)

Dockerize your frontend and backend applications. It should be possible to start all services in the corresponding mode (development, production) with a single command (e.g. use Docker Compose for this).

Tasks:

• (6) Create multi-stage Dockerfiles for your applications (depending on your frameworks):
  • The frontend Dockerfile should: 1. run the app in a development environment 2. build the app 3. serve build artefacts over Nginx
  • The backend Dockerfile should: 1. run the app in a development environment 2. build the app if there is a build step in your framework (optional) 3. serve the app
• (4) Create two docker-compose files to orchestrate you applications in development and production mode:
  • Define ports and dependencies
  • Define corresponding stage (development, production)
  • Use environment variables if possible
• Your application should start with the following commands:
  • Development: docker-compose -f docker-compose.yml up --build
  • Production: docker-compose -f docker-compose.prod.yml up --build