— Check My Attendance —

This repository uses the gh-pages npm package to build and deploy a React application. See a live, interactive version of the website here.

Getting Started: Contributing

1. Clone the repository

1. Navigate to the desired directory where the project will be stored.

2. Clone the repository by executing the following command.

   git clone https://github.com/csong202/check-my-attendance.git

2. Install the required dependencies

1. Install the required dependencies by executing the following command.

   npm i

   It is assumed that npm is already installed. If not, refer to the official documentation.

3. Preview the React app

1. Start a local server with the following command.

   npm start

   Executing the command above will open a live server which features hot reloading at the following address: localhost:3000.

4. Deploy the React app

1. Commit and push any untracked files to the GitHub repository.

2. Build the app.

   npm run deploy

   By executing the command above, the predeploy and deploy scripts will run and the React app will be deployed. Internally, the predeploy script creates a distributable version of the app and the build script pushes the compiled app to a commit in the gh-pages branch. The gh-pages package will deploy the application to the specified URL whenever the npm run deploy command is executed. A GitHub workflow will link the GitHub page with the source files in the gh-pages branch, and once it is completed, the deployed app with the newest changes will be reflected here.

Common Issues

Broken Media Display

More than likely, images and/or videos will not render in the deployed site using common src linking:

<img src="./images/img-1.jpg" />

Since the website is deployed under the homepage URL, it will not recognize the source file for the image or video using local pathing. To overcome this, follow the steps below to change all src linking, depending on the use case.

1. Diagnose the type of media.

   1. Background Image

      1. Open the .css file that imports an image with the background-image property.

      2. Change the format of the url() value.

         * {
         	background-image: url("https://csong202.github.io/check-my-attendance/images/img-1.jpg");
         }

         The url() value should follow this format: https://{github_username}.github.io/{repo_name}/{file_path}

   2. Image/Video Tag

      1. Open the .html file that utilizes the <img/> or <video/> tag.

      2. Change the format of the src attribute.

         <img src={process.env.PUBLIC_URL + "/images/img-1.jpg"} />

         The src attribute's value should follow this format: process.env.PUBLIC_URL + "/{file_path}"

   Alternatively, run the following two commands to match the two cases above:

   cd $(git rev-parse --show-cdup)/src

   grep -RIlxP --include=\*.{html,css,js} '^.*\b(?:src=|background\-image:).*$'

   grep is a utility for searching strings through multiple text files. Here, it is invoked with the following parameters:

   • R — reads all files under each directory, recursively, across all symbolic links
   • I — ignore binary files; process a binary file as if it did not contain matching data
   • l — print the name of each file for which a match was found
   • x — select only those matches that exactly match the whole line
   • P — interpret patterns as Perl-compatible regular expressions (PCREs)
   • --include= — search only files whose base name matches the pattern
   • Regex — find an explanation for the regular expression here

2. Push these changes to the remote repository and deploy the application. The global process.env.PUBLIC_URL variable allows for the images to be displayed when running locally and when being deployed to the remote.

Blank Page

Upon opening the deployed GitHub Pages site, the page might be blank until refreshing the browser. Follow the steps below to fix this.

1. Identify any BrowserRouter tags in the codebase.

2. Add the following property.

   basename={process.env.PUBLIC_URL}

   Alternatively, run the following two commands to identify and replace the property:

   cd $(git rev-parse --show-cdup)/src

   grep -RIl --include=\*.js '<BrowserRouter' | xargs sed -i 's/<BrowserRouter/<BrowserRouter basename={process.env.PUBLIC_URL}/g'

Specifying the basename={process.env.PUBLIC_URL} in the routing root allows the router to extract the base URL of the project and properly display the site.