Forem: Felix Owino

Writing meaningful Git commit messages with semantic tags

Felix Owino — Fri, 02 Aug 2024 17:34:10 +0000

In version control systems like Git, commit messages are the best way to document your development progress. Commit messages tell other developers what you have done for each change you make in your code base. It's not just about other developers though, commit messages are important to you as well. Let's say you want to know what you did yesterday, how, and why, the commit messages history will always be your friend. Considering how important commit messages are in the sphere of software development, we cannot ignore the need to keep them clear and meaningful. Commit messages are important but not if they don't make sense. In this article, we will discuss how to write commit messages that clearly communicate changes and don't leave you or other developers wondering what happened during that change.

A well-written commit message has three parts: the commit tag, the subject, and the body. The tag classifies the change to a particular category. The subject declares the change in a single statement. The commit message body provides more details about the change. Look at the following commit message for example:

 refactor: Validate reference IDs after authenticating routes

          - Move the Reference ID validators and
            validation error handlers below the authentication
            middleware in the routes where ID is required

In the above commit message,

The word refactor is the message tag that classifies the change as a refactor (We will talk more about tags shortly).
The statement 'Validate reference ids after authenticating routes' is the subject of the message.
The longer sentence below the subject is the message body.

If you had no idea that a commit message has three parts, you can now see why that is so and appreciate their importance. The tag classifies the change. The subject tells you what the change is about without boring you with the details. Finally, the body outlines the details of the change.

In this article, we will talk about the semantic tag.

The Semantic tag.

The semantic tag helps to clarify what the change is about by classification. There are several semantic tags that can be used to classify changes in commit messages. Here are some of the tags that I have used and you can use too:

feat
refactor
fix
breaking
test
chore
revert
docs
style

The question you are probably asking yourself now is "What do these tags mean and how will I know when and where to use which one?". Relax, We have got you covered. Before the end of this article, We will have talked all about the above tags, what they mean, and when and where to use them. We will also throw in a few examples for you to see how you can use them in practice. Happy now? Let's get started with the feat tag.

1. The `feat` tag

The feat tag is used to classify a change that introduces a new feature or functionality in the system you are building. This is the tag you use on a commit message when the change you have just made has introduced a behavior that didn't exist in the system before.

For example, you are building an app that accepts user input and stores the data in a database. The system is working as expected, then you decide to validate user input. Now users can only input data that the system agrees with. The system will reject the data it considers invalid and accept only the data it considers valid. This is a behavior that did not exist earlier. The change has introduced a new behavior in the system. It is therefore classified as a feat. In this case, you will write your commit message as follows:

feat: Validate user input


     - Ensure users enter valid data before accepting their input

It's that simple, now you can spot a change that introduced something new without reading any further than the feat tag.

2. The `refactor` tag

Away from Git commit messages, refactoring code normally means changing the implementation of a program in a way that does not alter its behavior. For example, replacing double quotes with single quotes in a string initialization.

In relation to git commit messages, a change is classified as a refactor if the implementation of a program has changed but the program still does exactly what and how it was doing before the change.

For example, say you have a function that takes an array of numbers and returns the sum of the numbers.

function sumArray(numbers) {
    let sum = 0;
    for (let i = 0; i < numbers.length; i++) {
        sum += numbers[i];
    }
    return sum;
}

Then you decide to do something more simplified like this

function sumArray(numbers) {
    return numbers.reduce((sum, number) => sum + number, 0);
}

You see, you have reduced the implementation of the same function from 6 lines of code to 1 line and you still achieve the same goal. In this case, you would have a commit message that reads as follows:

refactor: Change the implementation of the sumArray function to a more
          simplified one

          - simplify the sumArray function using Array.reduce method

Changes that can be classified as refactor are not just limited to simplifying implementations of functions. The following changes can also be classified as refactor:

Renaming variables, functions, methods, or classes
Removing redundant utility functions
Extracting code into reusable functions or methods
Splitting a large function into smaller functions with single responsibilities
Replacing a library with another library that achieves the same purpose
Optimizing functionalities without changing their outputs
Reorganizing code logical structure or execution order without changing the output

The list of changes that can be classified as a refactor is endless. The most important thing to remember is that a refactor is any change that alters the code without adding, eliminating, or altering a functionality in your system.

3. The `fix` tag.

Just like it sounds, the fix tag is used to classify changes that fix problems in the system. Problems can be bugs, issues, errors, crashes, etc.

Now assume you are building an app that authenticates users before allowing access. The authentication works, unregistered users cannot access the system. That's what you want but you also have another behavior you don't want. Registered users cannot access the system either. Your registered users enter their correct emails and passwords but the system keeps saying the password is wrong.

You look through your code and realize that you are encrypting the user's password twice before saving it but decrypting once when trying to log in. Twice how? Once in the login controller and again in the User schema just before saving the new user document to the database.

You are relieved after finding out the problems. You remove the encryption at the controller and remain with one encryption process, at the data schema. Now new users can register and log in smoothly with their correct credentials.

The change in the paragraph above fixes an issue in the authentication of the system. This is the kind of change you classify as a fix and the commit message can read as follows:

fix: Resolve the issue preventing registered users from logging in with 
      correct credentials

    - Remove double encryption of user password during registration
    - Remove the encryption of passwords in the user registration
      controller and use the encryption in the user schema only.

The above commit message communicates what it does very clearly. You can spot the change that fixed a problem in the system without reading the whole commit message. That is how useful the fix tag can be.

An authentication issue fix is only one of the many kinds of changes that can be classified as a fix. The following kinds of changes can also be considered as fix:

Handling uncaught exceptions and errors
Handling rejected Promises
Implementing global error handlers to prevent an application from crushing due to unexpected errors
Correcting logical errors in calculation algorithms
Taking care of compatibility issues across browsers in web apps

4. The `breaking` tag

The breaking tag is used to classify breaking changes. Breaking changes are a little like refactors in that they do not introduce new functionalities to your system or codebase but they are more impactful than refactors. A breaking change forces changes in other parts of the system that depend on the part that has been changed. They break backward compatibility in systems and codebases. If a breaking change occurs in one component in the system, every component that depends on the changed component has to be updated as well.

An example can explain it better. Assume you have a base controller class called BaseController in the libraries folder of your system. The BaseController class has a constructor that accepts one parameter. Your system has 6 apps namely users, events, venues, venue types, event categories, and authenticator. Each of the six apps in the system has a controller class that inherits the BaseController class and implements a constructor.

You have decided to change the constructor of the BaseController class by adding one more parameter called appName. Now all the classes that extend the BaseController must update their constructors to match the new implementation. All the apps in the system will be affected because of one change in the base class. This is what we call a breaking change. The above change can be committed as follows.

breaking: Update the BaseController constructor to accept two 
          parameters

          - Add a new parameter called appName to the constructor of 
            the base controller class

Make sense? Yes. Altering the constructor of a base class is not the only kind of change that can be classified as a breaking change, here are a few more:

Adding a method or a field to an interface that is implemented by other components in the system or codebase.
Changing the return type of a method in a base class
Changing the structure or properties in a database schema
Renaming or removing a public method from a class
Altering method signatures by modifying the type of parameters, reducing or increasing the number of parameters in a function or a method.

That's it about breaking changes but not all. These are changes that demand attention from other parts of the system. In a development team, the impact of the change can go as far as affecting other developers' work too. When they pull the breaking changes, they will be forced to update their components that depend on the changed entity.

5. The `test` tag

The test tag is related to the practice of test-driven development. In test-driven development, we are always encouraged to write a failing test before we finish implementing a function, class, or whatever it is we are writing code for. Every time you write a test, you create a change you want to commit before you continue working on the implementation of the test subject. All changes related to tests are classified as test.

Say you are building a backend system, you want to implement POST route handlers for the users application. You have written unit tests with your favorite testing libraries. You want to commit this change before making any more changes to your code base. Because we are talking about tags and meaningful commit messages, you will write your commit message as follows:

test: Write tests for users POST route


      - Write test cases to test input validators, response status code
        and response body of users POST route

That simple! Tests are the most obvious and straightforward type of changes that you won't ever need to scratch your head to classify correctly.

You might think that the test tag is only usable for changes that involve writing unit tests. You may right, but what do you think about the following?

Creating mocks for classes, methods, functions, API endpoints, and data
Adding end-to-end tests that emulate real user scenarios
Refactoring and organizing testing code to improve maintainability
Creating a custom testing library by encapsulating the functionalities of a testing library

6. The `chore` tag

Just like it sounds, a chore is a change that keeps your project environment in order. These changes are not refactors - because they don't touch any lines of code, they are not fixes - because they don't resolve issues or bugs - and they do not introduce new features to the system. The chore changes are necessary for maintaining and improving the project in ways that do not affect the experience of the end user.

Now what kind of change do you suppose we can classify as a chore? Let's say you have been building and improving your project to the point that you have some files that you no longer use for the functionalities in your system. This could be a class file that you have replaced with a third-party library or UI components that you don't use anymore. The best thing to do about these files is to delete them. The resulting change of deleting an unused file does not affect the functionality or the codebase of your system but it does keep things clean in your project. This is the kind of change that you classify as a chore. If you were to write a commit message, it would look more or less like the following:

chore: Remove unused files

      - Delete the files for the ABC class and xyz components that are
        no longer used in the system

The chore changes are not limited to removing unused files, they may also include things like:

Containerizing your project by adding a Dockerfile
Updating README.md
Adding npm scripts to the package.json file
Installing dependencies and development dependencies
Configuring testing environment
Configuring development tools
Updating existing modules or packages.

That's not all about the chore tag but it's enough to give you an idea of what it's all about. Let's see what next.

7. The `revert` tag

The revert tag is used when you do a git revert, that is when you undo a change that had been committed so that your code base can look like nothing happened at all. A revert is not a kind of change that should leave you wondering about what just happened because you won't see it anywhere. A revert is a change that erases evidence of what was done before. Therefore it is very important that you tag all reversed changes as revert because unlike git reset, a revert does not leave unstaged changes in the working area.

Now, under what circumstances would you want to revert a commit? Assume you removed a functionality that allowed users to delete their information from the system. For some reason, you didn't want them to delete their details, at least not directly. You had committed the change as a feat below:

feat: Disable users from deleting their details from the system

That went well. After several other changes in the system, you now want users to be able to delete their details directly anyway. You don't want to rewrite the code that you had written in the past so you will simply do a git revert. This is when you use the revert tag on a commit message. In my experience revert messages tag and commit themselves but in case you are curious to see what it would look like, be my guest:

revert: Revert "feat: Disable users from deleting their details from 
        the system"

Just like any other kind of change, a revert can be done under several circumstances including:

The need to maintain integrity in the commit history. This is for teams that prefer to undo changes via a revert over a reset. They want to keep records of all changes including the ones you want to remove.
Undoing changes after they have been deployed. Assume you introduced a feature but it is misbehaving in production. The safest way to deal with it is to revert the change so you can work on a better implementation while the buggy feature is off the production code.
Undoing a mistaken commit, for example, you accidentally deleted important files from the project, committed the change and now you want them back.

That covers the revert tag, let's see about the docs tag.

8. The `docs` tag

A change is classified as docs if it involves writing or removing plain texts on a markdown file or on codebase as comments or docstrings. All changes to code documentation are considered docs including updating the content of the README file.

Let's say you have been working on a project on your own for some time. You want to invite a few team members to join you in the development. Inviting new members will require you to write some instructions on how to set up the project locally for their sake. You will write the instructions in the README.md or any other markdown file. Once you are done, you will commit the change with a message that looks more or less like this:

docs: Create instructions for setting up the project locally

Other changes where the docs tag is appropriate are :

Creating or updating a client or developer documentation
Adding or removing comments in a codebase
Updating or creating user manuals
Adding docstrings to a codebase

The list is surely longer than we can cover today. The bottom line is, that the docs tag is used when the change you are committing means that you are communicating something in plain words. This includes all cases where you are altering information from existing documentation.

9. The `style` tag

You might think that the style tag is used when you add style to user interfaces but that's very far from the truth. The style tag is used when you make a change that does not affect the logic or semantics of the code but affects the arrangement of the lines of code. These are changes related to the indentation of code, the amount of whitespace between lines of code, the position of curly braces in control structures of functions, whether you used curly braces to enclose one line of code in an else block, etc. The petty things that affect how your code visually looks are committed as style.

Assume you initially had a habit of writing very long lines of code without breaking into the next line. After reading the book Clean Code by Uncle Bob, you decide to make your code a little cleaner by breaking the lines to be shorter. This is not a refactor because you did not change any characters in the code. This is a style which can be committed as follows

style: Reformat code

      - Break long lines of code into shorter lines

The other changes that can be committed as style include:

Removing or adding whitespaces in the code file
Renaming variables and functions for the sake of conventional consistency
Reformatting comments and docstrings to improve readability
Aligning and indenting code within blocks for visual clarity
Rearranging methods in a class or function in a file
Altering the order of imports

That's enough to give you an idea of what kind of changes can be tagged as style.

The tags we have discussed above are not all that exists in the software engineering world but they are enough for a beginner to intermediate developer. The list grows longer as you get more experience as a developer. These tags are not hard rules in version control systems but a good practice in writing meaningful commit messages. They may not make a lot of sense now but the more you use them, the more you will appreciate them. Use these tags and more that you will learn along the way and you will always be proud of the commit messages you write.

Handling Bad JSON Input Error in Express app

Felix Owino — Fri, 02 Aug 2024 15:00:48 +0000

Have you ever experienced this error before or are you experiencing it now? I'll be honest and say I experienced it more than once but I didn't care so much at first. This error is normally thrown by the express body-parser as a syntax error. If you have a global error handler in your app, the error will always be sent to the user as an internal server error with status code 500. But you have a problem with that, don't you? Yes, so do I.

Why do we have a problem if it will be handled anyway? Well, the problem with this problem being sent as an internal server error is that it's not originating from our side. The error of bad JSON format is caused by bad JSON data, something like a trailing comma in a JSON object.

You see, that error is thrown because of a client mistake. The error is triggered by something from the client side. We want the client to know that they did something wrong. We don't want the client to get furious at us because of a problem they are responsible for, that's what happens when we respond with status code 500 for all errors. This error is a special one, caused by a bad input format from the client. We want to send status code 400 instead.

The error caused by bad JSON format is thrown by the body parser but we can't put the body parser in a try-catch block and do what we want with the error. We will let the body parser forward the error to the global error handler then we handle it there.

We know it is a SyntaxError, that's what we will be looking for. We also know that the message will say something about JSON. We use the type of the error and the error message to narrow down our action as done below:

const handleServerErrors = ( 
        err:Error, req: Request, res: Response, next: NextFunction) =>{
            if(err){
                if (err instanceof SyntaxError){

                    if(/JSON/i.test(err.message)){

                        res.status(400).json("Bad JSON format")

                    } else{
                        res.status(500).json(err.message)
                    }
                    console.log(err.message)

                } else{
                    res.status(500).json('Unexpected server error.')

                    console.log(`Name ${err.name}, 
                     Message:${err.message}`)

                    console.log(`Error Stack \n ${err.stack}`)
                }
          }
    }

Now we pass the above error handler to the express app as the last middleware in the system. If the client sends data in bad JSON format, we will respond with status code 400 and a message informing them about the problem in the response body.

Creating A Carousel with Vanilla JS

Felix Owino — Fri, 19 Jul 2024 10:43:45 +0000

In the real world, a carousel refers to a series of structures mounted on a circular platform that rotates around a central axis. Examples of carousels in the real world are things like merry-go-round and carousel rides. In the context of user interfaces, carousels are a series of items such as images, videos, files, or texts designed to be viewed one item at a time within a specific container on the screen in a linear sequence. Users can navigate through the items in the carousel by clicking its navigation buttons. Carousels can also be automated to self-navigate at specified intervals. In this article, we will learn how to create a carousel on a webpage using HTML, CSS, and vanilla JavaScript.

Carousels are interesting to view on user interfaces but implementing them is usually a little elusive to beginners. However, it's surprisingly simple to implement once you make sense of what parts of the carousel actually move.

In most cases, for example, an image carousel, we tend to imagine that the carousel is about the motion of the individual images. That assumption looks true from the viewer's point of view but very inaccurate from the engineering point of view. The truth is, that the motion is never about the individual images but the parent container of the images.

All the images in a carousel are children of one div container spread in a horizontal manner. The whole container moves with all its children but only one image is displayed within the viewing container. The other images remain hidden on either side of the viewing container. The viewing container? Yes, you heard me right. Does that mean we have another container apart from the one containing the images? Yes, this container gets to decide how big the displayed image will be and hides everything that does not fit within its borders.

Enough with the words, let us get practical. We will cover this activity in the following sections:

Structuring the carousel
Styling the Carousel
Getting the Carousel in Motion
- 3.1 Viewing the next image
- 3.2 Viewing the previous image
- 3.3 How the Translation works
- 3.4 Automating the rotation
Adding Indicators

We will start writing the HTML structure of the carousel.

1. Structuring the Carousel

We will use image files for this carousel. I downloaded my images. You can find sample images from Unsplash and download or copy their links for your practice. Below is the HTML code:

 <div class="viewing-container">
        <div class="carousel">
            <img src="./beautiful-home-1.avif" alt="beautiful home 1">
            <img src="/beautiful-home-2.avif" alt="beautiful home 2">
            <img src="./beautiful-home-3.avif" alt="beautiful home 3">
            <img src="./beautiful-home-5.avif" alt="beautiful home 4">
        </div>
        <button class="prev">
            <i class="fa-solid fa-angle-left"></i>
        </button>
        <button class="next">
            <i class="fa-solid fa-angle-right"></i>
        </button>
    </div>

The code snippet above renders the following components:

A viewing container that parents the carousel and the navigation buttons
The carousel container which contains four image files
Four image elements that render four image files
A previous navigation button with an icon (left angular brace)
A next navigation button with an icon (right angular brace)

We are using Font awesome icons for the angular braces. Font Awesome icons require an external stylesheet to work. Go to cdnjs font awesome library and copy the link tag to the stylesheet (marked with this icon - </>). You will find a long list of links, the first link on the list should work. Paste the link within the <head> of your HTML file. The head of your HTML file should resemble the one below. The Font Awesome link doesn't have to be an exact match because it is subject to change.

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="./style.css">

    <!-- Font Awesome Stylesheet -->
    <link rel="stylesheet" 
        href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.6.0/css/all.min.css" 
        integrity="sha512-Kc323vGBEqzTmouAECnVceyQqyqdsSiqLQISBL29aUW4U/M7pSPA/gEUZQqv1cwx4OnYxTxve5UMg5GT6L4JJg==" 
        crossorigin="anonymous" referrerpolicy="no-referrer" />

    <title>Carousel</title>
</head>

That is all the HTML we need for now, let us add some basic styles to the carousel.

2. Styling the Carousel

The following code snippet contains a few basic styles for the carousel:

body{
    padding-block-start: 4rem;
}

.carousel{
    display: flex;
}

.viewing-container{
    width: 25%;
    position: relative;
    border: solid 3px red;
}

.carousel img{
    width: 100%;
}

button{
    position: absolute;
    top: 50%;
    padding: .4rem .8rem;
    border:  none;
    background-color: rgba(0, 0, 0, 0.5);
    color: white;
    font-size: 1.5rem;
}

button.next{
    right: 1rem;
}

button.prev{
    left: 1rem;
}

See the result of the styles in the screenshot below then let me explain just what we have done.

Using the CSS styles above, we have done the following:

We have horizontally spread the images in the carousel container using flex
We have intentionally set the width of the viewing container to 25% to allow us to see all the images within the screen. If you have more than 4 images, 25% width won't have the same effect.
We have set the position property of the viewing container to relative to allow us to position the navigation buttons on it.
We have intentionally added a red solid border around the viewing container to distinguish it from the rest of the screen.
We have set every image to be 100% as wide as the viewing container.
We have set the positions of the buttons as absolute, vertically centered, and 1 rem from the edges of the viewing container.

We have intentionally left the styling unfinished (with overflow) so that you can see that creating a carousel begins by spreading all the images horizontally. We would also choose to do it vertically but we want to create a horizontal carousel. Before we finish the styling, we will get the carousel in motion using JavaScript.

3. Getting the Carousel in Motion

There are two ways to make a carousel go around. You can use the navigation buttons or make the carousel rotate automatically in specified intervals. We will implement both approaches starting with the navigation buttons.

There are two navigation buttons on the carousel viewing container: a previous button and a next button. If we want to see the images to the right, we will click the next button (the button to the right of the viewing container). Likewise, to view the images to the left of the viewing container, we click the previous button (the button to the left of the container).

Let's explore how we can program the carousel to enable viewing images on the right side of the container.

3.1 Viewing the next Image.

As you click the next button, you expect the image on the right side of the viewing container to be moved inside the viewing container. Let's implement that in the code snippet below:

const carousel = document.querySelector('.carousel');
const nextButton = document.querySelector('.next');

const carouselLength = document.querySelectorAll(
       '.carousel img').length;

let currentPositon = 0

nextButton.addEventListener('click', () => {
    currentPositon = currentPositon < carouselLength - 1 ? currentPositon + 1 : 0

    const offset = -100 * currentPositon
    carousel.style.transform = `translateX(${offset}%)`
})

Confused? Don't worry, you will understand what's going on in no time.

First, we get the carousel container, the div element that parents all the images.
Secondly, we get the next button, which is the button to the right of the viewing container.
Then we get the length of the carousel. This is equal to the number of images in the carousel. We get the length of the NodeList of all images in the carousel. The NodeList and all its contents are totally useless to us except its length.
We initialize our starting position to 0. This is where we are before the carousel begins to move. The current position represents the index (in NodeList) of the image displayed within the viewing container.

That's all for the variables, let's talk about the click event handler.

Here, we adjust the value of currentPosition by 1 to point to the next image in the carousel.

currentPositon = currentPositon < carouselLength - 1 ? currentPositon + 1 : 0

Take note that we do this conditionally, we only increment the position up to the time when it points to the last image in the carousel, and then we go back to 0. If we still want to view the next image after the last, we are returned back to where we started. Without the conditional checks, we will continue to view empty spaces.

The interesting part is saved for last,

    const offset = -100 * currentPositon
    carousel.style.transform = `translateX(${offset}%)`

we translate the carousel leftwards in relation to the value of the currentPosition. We negate the offset (translation distance) because we want the carousel to move leftwards. We multiply the currentPosition by 100 to calculate the offset as a percentage-based translation, ensuring that each item in the carousel is translated by its full width. Think about it as swiping left to see what's on the right.

Save your work and try clicking the next button to see for yourself how the carousel container moves to show you the next image.

You must have realized how rough and sudden the motion of the carousel is. It's not as gradual and smooth as you expect. Let's fix that by customizing the transition of the carousel using CSS.

.carousel{
    display: flex;
    transition-property: all;
    transition-duration: 2s;
    transition-delay: 0;
    transition-timing-function: ease;
}

Update the styles in the carousel class with the above properties and values and see how smooth and gradual the motion gets.

We are done with the next button. Let us make the previous button work just as well if not better.

3.2 Viewing the previous Image.

Calculating the position for the previous image takes the direct opposite of the calculation we performed when viewing the next image. We decrement the value of the current position until the value becomes 0. Once it reaches 0, instead of decrementing to -1, the currentPosition will be reinitialized to the last position in the carousel. If the value of currentPosition is zero, pressing the previous button will take you to the last image in the carousel, the end. The following code snippet extends the previous scripts:

const prevButton = document.querySelector('.prev');

prevButton.addEventListener('click', () =>{
    currentPositon = currentPositon > 0 ? currentPositon - 1 : carouselLength - 1

    const offset = -100 * currentPositon
    carousel.style.transform = `translateX(${offset}%)`
})

This is similar to swiping right to see what's on the left.

Have you noticed that we are still negating the offset even though we want the carousel to move rightwards? Why aren't we making it a positive translation here? Why is the calculation the same as what we did in the previous section but the effect looks like the opposite? You will understand what's happening shortly, but first, let's make the JavaScript code a little cleaner.

const carousel = document.querySelector('.carousel');
const prevButton = document.querySelector('.prev');
const nextButton = document.querySelector('.next');

const carouselLength = document.querySelectorAll('.carousel img').length;

let currentPositon = 0

const showImage = (currentPositon) =>{
    const offset = -100 * currentPositon
    carousel.style.transform = `translateX(${offset}%)`
}

nextButton.addEventListener('click', () => {
    currentPositon = currentPositon < carouselLength - 1 ? currentPositon + 1 : 0
    showImage(currentPositon)
})

prevButton.addEventListener('click', () =>{
    currentPositon = currentPositon > 0 ? currentPositon - 1 : carouselLength - 1
    showImage(currentPositon)
})

The code snippet above achieves the same goal with fewer lines of code in the click event handlers. We have refactored the code by encapsulating the translation and offset calculation in a reusable function, showImage.

Now let's learn why we are always doing a negative translation when it looks like we are changing directions.

3.3 How The Translation Works

In practice, the translation distance and the translation direction of an element are always calculated relative to its origin, the initial position of the element without any translation.

If the intended translation destination of an element lies to the right of the element before any translation, its translation direction will always be positive regardless of what it looks like in the display. Likewise, the translation direction of an element will always be negative if the translation destination lies to the left of its translation origin.

In our case, all the images in the carousel before translation are always on the right-hand side of the viewing container. It does not matter whether, from the look of things the images are to the left or right side of the viewing container, the computer will always reset to the original positions (right-hand side of the viewing container) before executing a translation.

Assume you want to see the image at position 4 in the carousel, the translation direction and translation distance will always be negative and 400% (-400%) respectively. The offset will always be -400% whether you are clicking the previous button or the next button.

I hope that helped clear your doubts if you had any. Now let's wind up by centering the viewing container, increasing its width, removing the border, and hiding the images that lie outside the viewing container using the following CSS rules:

.viewing-container{ 
    /*Remove the border*/
    position: relative;
    width: 50%; /* Increase from 25 to 50*/
    overflow: hidden; /*Hide overflow*/
    margin: auto; /*Center the container*/
}

The screenshot below shows the centered, enlarged, and borderless viewing container without overflows:

3.4 Automating the rotation.

Remember we did say earlier that the motion of the carousel can be automated. We can use the setInterval function to calculate the currentPosition and translate the carousel after specific intervals. The code snippet below implements the automation of a carousel to rotate after every 5 seconds.

setInterval(() =>{
    currentPositon = currentPositon < carouselLength -1 ? currentPositon + 1 : 0
    showImage(currentPositon)
}, 5000)

There is one problem you will experience by including this automation. There seems to be an interruption when you want to control the motion with the navigation buttons. To fix that problem, you can store the value returned by the setInterval function and use it to clear the intervals once a button is clicked. The code snippet below shows the complete code snippet with the fixes.

// // script.js
const prevButton = document.querySelector('.prev');
const carousel = document.querySelector('.carousel');
const carouselLength = document.querySelectorAll('.carousel img').length;
const nextButton = document.querySelector('.next');

let currentPositon = 0

const showImage = (currentPositon) =>{
    const offset = -100 * currentPositon
    carousel.style.transform = `translateX(${offset}%)`
}

const interval = setInterval(() =>{
    currentPositon = currentPositon < carouselLength -1 ? currentPositon + 1 : 0

    showImage(currentPositon)
}, 5000)

nextButton.addEventListener('click', () => {
    clearInterval(interval)

    currentPositon = currentPositon < carouselLength - 1 ? currentPositon + 1 : 0

    showImage(currentPositon)
})

prevButton.addEventListener('click', () =>{
    clearInterval(interval)

    currentPositon = currentPositon > 0 ? currentPositon - 1 : carouselLength - 1

    showImage(currentPositon)
})

With the latest adjustments, the carousel will autorotate only until you click either of the navigation buttons. Once the manual navigation takes over, the automated navigation will stop until the page reloads.

4 Adding Indicators

Indicators in a carousel help users know the number of images they have viewed and the ones they haven't viewed. We will create four circular dots at the bottom of the viewing container to act as indicators. We can create circles by adding 4 div elements to the markup. We can use CSS to set their height, width, border, and border radius to make them circular.

We will extend the viewing container with more elements as in the code snippet below.

    <div class="viewing-container">
//Initial content - carousel container and buttons
// go here
        <div class="indicators">
            <div class="indicator"></div>
            <div class="indicator"></div>
            <div class="indicator"></div>
            <div class="indicator"></div>
        </div>
    </div>

The following CSS styles will make the div elements look just like we want.

.indicators{
    display: flex;
    align-items: center;
    justify-content: center;
    gap: .8rem;
    position: absolute;
    bottom: 1rem;
    width: 100%;
}

.indicator{
    width: 8px;
    height: 8px;
    border: solid 1px white;
    border-radius: 50%;
    transition: background-color 2s ease;
}

After adding the markup and applying the styles, you should have a series of indicators that resemble the ones shown in the screenshot below.

Notice the four circular dots at the bottom of the screen.

Having successfully rendered and styled indicators, let us now make them do what they are supposed to do. We will get all the indicators from the DOM and create a function that changes the background color of the dots as the carousel moves. The following code snippet implements the actions described.

const indicators = document.querySelectorAll('.indicator')

const moveIndicator = (currentPositon) =>{
    indicators.forEach((indicator, index) =>{
        indicator.style.backgroundColor = currentPositon === index ? 
            'white': 'rgba(0,0,0,0.5)'
    })
}

In the code snippet above, we get all the indicators in a NodeList and create a function called moveIndicator. The function accepts the currentPosition as an argument, and iterates over the NodeList comparing the currentPosition with the index value of every indicator in the list. If the currentPosition equals the index, we set the background color to white, otherwise, we set it to a semi-transparent black color.

We have to call the function every time the carousel moves to update the indicator. Below is the final code snippet with the indicator working as expected.

// // script.js
const prevButton = document.querySelector('.prev');
const carousel = document.querySelector('.carousel');
const carouselLength = document.querySelectorAll('.carousel img').length;
const nextButton = document.querySelector('.next');
const indicators = document.querySelectorAll('.indicator')

let currentPositon = 0

const showImage = (currentPositon) =>{
    const offset = -100 * currentPositon
    carousel.style.transform = `translateX(${offset}%)`
}

const moveIndicator = (currentPositon) =>{
    indicators.forEach((indicator, index) =>{
        indicator.style.backgroundColor = currentPositon === index ?
            'white': 'rgba(0,0,0,0.5)'
    })
}

const interval = setInterval(() =>{
    currentPositon = currentPositon < carouselLength -1 ? 
        currentPositon + 1 : 0

    showImage(currentPositon)
    moveIndicator(currentPositon)
}, 5000)

nextButton.addEventListener('click', () => {
    clearInterval(interval)

    currentPositon = currentPositon < carouselLength - 1 ?
         currentPositon + 1 : 0

    showImage(currentPositon)
    moveIndicator(currentPositon)
})

prevButton.addEventListener('click', () =>{
    clearInterval(interval)

    currentPositon = currentPositon > 0 ? 
        currentPositon - 1 : carouselLength - 1

    showImage(currentPositon)
    moveIndicator(currentPositon)
})

The screenshot below indicates that we are currently viewing the second image in the carousel.

Finally, we are done creating a carousel with vanilla JavaScript (without third-party libraries). Carousels come in handy when you want to display a series of images, videos, documents, or texts within a limited space. Creating a carousel involves horizontally translating the parent container of the images or files that make up the carousel. The translation direction of a carousel will always be the same regardless of the position of the previous translations. The translation distance and translation direction for displaying the same image will always be the same regardless of the direction of navigation. Carousels can be navigated manually or automatically with set intervals.

Congratulations, now try creating your carousel from what you have learned. Feel free to say something in the comment section. Find out more about CSS translations from MDN.

Implementing File Input By Copy-Paste on the Web

Felix Owino — Wed, 17 Jul 2024 11:54:04 +0000

In the sphere of web development, there are multiple ways to upload files when collecting user input. One of the methods is copy-paste. Copy-paste for file input is a very intuitive method of uploading files from users. Copy-paste file input method relieves users of the need to memorize the location of the file they want to upload. In this article, we will discuss how you can implement file input by copy-paste on your website.

We will implement the copy-paste file input by taking advantage of the ClipboadEvent and the EventTarget interfaces. The ClipboardEvent interface provides information about the paste event, and the EventTarget interface allows us to listen to the paste event.

While listening to the paste event, we will attach an event handler function where we decide what to do with the pasted items. In our case, we will take the pasted file and render it instantly after it is completely loaded into the browser. We will begin with the HTML and the styles.

The HTML and the Styles

Let us start by creating the HTML markup of the paste area. The code snippet below is the HTML markup:



<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Copy-Paste File Input</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div 
        id="pasteArea" 
        contenteditable="true" 
        style="border: 2px dashed #ccc; padding: 20px;"
    >
        Paste your file here
    </div>
    <div id="preview"></div>
    <script src="script.js"></script>
</body>
</html>

The code snippet above renders a rectangular container within which we will be able to paste files. The container has an attribute called contenteditable set to true. The contenteditable attribute is important to enabling the pasting of files or any other items in the container. If the contenteditable attribute is changed to false or removed, the paste action will not work as expected. We also have a container with the id of preview. We will use the preview container to preview the image pasted by the user.

Let's add a few basic styles to our markup from style.css



*{
    font-family: Arial, Helvetica, sans-serif;
}

body{
    text-align: center;
    margin-block-start: 4rem;
}
#pasteArea {
    border: 2px dashed #ccc;
    padding: 20px;
    width: 300px;
    height: 200px;
    display: flex;
    align-items: center;
    justify-content: center;
    text-align: center;
    cursor: pointer;
    margin: auto;
    color: rgb(5, 89, 89);
}

#preview img {
    max-width: 100%;
    margin-top: 10px;
}

The above markup and style sheet creates a simple dash-bordered container with a simple prompt text as shown in the screenshot below:

Now that we have created the UI, let us add some useful functionalities with JavaScript in the next section.

The Script

In this section, we will use JavaScript to add a paste event listener to the paste area. Before we get the paste area from the DOM to attach the event listener, we first wait for the DOM content to be loaded as in the code snippet below.



document.addEventListener('DOMContentLoaded', () => {
    const pasteArea = document.querySelector('#pasteArea');

    pasteArea.addEventListener('paste', (event) => {

    });
});

In the code snippet above, we have added a listener for the DOMContentLoaded event. This allows us to wait for the DOM tree to be created before we can get the DOM elements. Next, we select the paste area container and append a paste event listener to it.

Getting the file from the pasted items

The paste event handler was left unimplemented in the previous code snippet. Let's implement it by getting the data from the event object and logging them in the console. We will do more with the data later in the article, for now, we just want to ensure that the files are received when items are pasted in the paste area. The code snippet below shows the minimal implementation of the paste event handler.



pasteArea.addEventListener('paste', (event) => {
        const items = event.clipboardData.items
        for (const item of items) {
            if (item.kind === 'file') {
                const file = item.getAsFile()

                console.log(file)
            }
        }
    })

In the code snippet above, we get items from the event.clipboardData object. The event.clipboardData.items is a DataTransferItemList which is a list-like object containing the content of the pasted items. The items are stored in a list because it is possible for a user to copy and paste multiple items at once.

Next, we iterate over the items using the for ...of loop. In the loop, we check if each of the items is a file. If the item is of king 'file', we get it as a file and print it on the browser's console.

Printing the file information on the console is not very useful to the users of your web page. Let's do something a little more interesting in the next section.

Previewing the uploaded file

It would be hard for a user to know that the file upload was successful after pasting the items for the clipboard if we don't show it anywhere. It is important to indicate that the file was successfully uploaded by displaying something that indicates success. What better way to indicate the success of an upload than displaying the uploaded file itself?

In this section, we will extend the paste event handler to create a URL from the received file. We will use the created URL to render the file once it's loaded into the browser. We will take advantage of the FileReader API to create a URL from the file as coded in the snippet below.



pasteArea.addEventListener('paste', (event) => {
        const items = event.clipboardData.items
        for (const item of items) {
            if (item.kind === 'file') {
                const file = item.getAsFile()


                const reader = new FileReader();

                reader.onloadend = (e) => {
                    const url = e.target.result
                    console.log(url)

                };
                reader.readAsDataURL(file);
            }
        }
    });

In the code snippet above, we have created an instance of the FileReader and used it to generate the data URL. We have also appended a loadend event listener to the FileReader object where we log the the result of the reading to the console. This is the first step towards previewing the file, we can now use the URL to display the file.

Assuming the user pasted image files, the following code snippet shows how we can extend the event handler to create a URL and display the image file.



 reader.onloadend = (e) => {
       const url = e.target.result
       const preview = document.querySelector('#preview')
       const img = document.createElement('img');

       img.src = url;
       preview.appendChild(img);
   };

In the code snippet above, we get the preview container from the DOM and create an img element for rendering the image. We assign the created URL as the src of the image and append the image to the preview container. Once the image is appended to the preview container, the user can now know that the image they pasted was successfully loaded into the web page.

Success! We have successfully implemented file uploads by copy-paste on a webpage. This method of file upload gives users the privilege of uploading files easily without the need to click several buttons to select the file to be uploaded. The ClipboadEvent interface provides an easy way to collect data from items pasted on the browser. The FileReader interface allows us to create a URL from the uploaded file and use it to preview the uploaded file.

Feel free to say something in the comment section. Find more about the ClipBoardEvent and the FileReader interfaces from MDN.

Implementing Drag-Drop for File Input on the Web.

Felix Owino — Tue, 16 Jul 2024 12:17:54 +0000

Drag-drop is one of the most engaging ways of transferring files between windows on a computer. All modern file explorers come with this functionality. Browsers also happen to have a default behavior to drag-drop. By default, the browser will try to open a file dropped into it unless it is programmed to do something else. In this article, we will learn how to program the browser to treat a drag-drop as a file input operation. We will also extend the program to allow us to open the file input dialog and select a file by clicking the drop-drop target.

Implementing actions during drag-drop can be done using the DragEvent interface provided in the browser by JavaScript. The DragEvent interface provides several events from when a drag begins to when it ends. In this article, we will leverage the power of the DragEvent interface to create a drag-drop file input user interface.

We will implement the proposed user interface in the following order:

Create the HTML Markup
Style the Markup
Make it interactive
Style the interaction
Make it clickable

Let's begin ...

1. Create the HTML Markup

Before going any further into the article, let us create a simple HTML markup.



index.html

<body>
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Drag and Drop File Upload</title>
      <link rel="stylesheet" href="./style.css">
    </head>
    <body>
      <div id="drop-zone" class="drop-zone">
        <p>Drag & drop files here or click to upload</p>
      </div>
      <script src="./drag-drop.js"></script>
    </body>
    </html>

</body>
</html>

2. Style the Markup

The following stylesheet provides a few basic styles for the page.



style.css

body {
    font-family: Arial, sans-serif;
    display: flex;
    justify-content: center;
    align-items: center;
    height: 100vh;
    margin: 0;
    background-color: #f0f0f0;
  }

  .drop-zone {
    width: 300px;
    height: 200px;
    border: 2px dashed #007bff;
    border-radius: 4px;
    display: flex;
    justify-content: center;
    align-items: center;
    text-align: center;
    color: #007bff;
    cursor: pointer;
    transition: background-color 0.2s ease;
  }

The above markup and style create a container with a blue dotted border and prompt text. The screenshot below shows what we have just created when opened in the browser.

3. Make it interactive

Dragging and dropping files into the dotted container or clicking it to input files won't work just yet. We need JavaScript for that part. In the script, we will add various event listeners to elements in the document. The first event we will listen for is the DOMContentLoaded event on the document.



document.addEventListener('DOMContentLoaded', () => {

})

You might be wondering what the DOMContentLoaded event is and how it is different from the load event. Even more, why did we choose to use it over the load event?

The DOMContentLoaded event is fired as soon as the DOM tree has been created. This event does not wait for other resources such as the styles, images, data, and other external resources to be loaded. The DOMContentLoaded is fired as soon as the elements of the page have been inserted into the DOM tree. On the other hand, the load event waits a little longer before it is fired. The load event is fired after all the resources of a page including styles, images, fetched data, and all other external resources have been loaded into the browser.

Our interest in this project has nothing to do with external resources but everything to do with a few DOM elements. This is the reason why we are choosing to use the DOMContentLoaded event over the load event. The load event could work just as well but we do not need to wait for that long. We want to attach the event listeners to the target element as soon as they are added to the DOM.

We will perform all subsequent operations and listen for all the other required events within the DOMContentLoaded event handler.

The drop zone container

We want to make the drop zone container aware of the drag-drop interaction. Here, we will tell the browser what to do when a file is dropped within the borders of the drop-zone container.

First, we need to get the drop zone container element from the DOM as done below.



document.addEventListener('DOMContentLoaded', () => {
    const dropZone = document.querySelector('#drop-zone')
})

Next, we attach the drop event to the drop zone container and provide an event handler.



dropZone.addEventListener('drop', (event) =>{

    })

In the event handler, we will program the browser to treat the drag-and-drop interactions as a file input. This means that if the file is dragged and dropped within the borders of the drop zone container, the browser will override its default behavior with the program in the event handler function. You can do anything with the dropped file. In our case, we will simply log the file information in the browser's console. Below is the implementation:



dropZone.addEventListener('dragover', (event) =>{
        event.preventDefault()

    })

 dropZone.addEventListener('drop', (event) =>{
        event.preventDefault()

        const files = event.dataTransfer.files

        console.log(files)
    })

The code snippet above adds two even listeners to the drop zone container, the dragover and the drop events.

Technically, we only care about dropping the file within the borders of the container. So why bother with the dragover event? We take care of the dragover event because we are dragging the file over the drop zone container before we can drop it and the browser has a default behavior to the dragover event. The least we can do about the default behavior of the browser is to prevent it. We access the files array from event.dataTransfer and log the list on the browser console.

Everything works well but the look, not very much so. In the next section, we will add styles to the process.

4. Style the interaction

What if you wanted to do more than prevent the default behavior of the browser? What if you intend to change the background color of the drag zone container throughout the process? Say one color when dragging over the drop zone container, a different color when you drag past the borders of the target container, and another color when you drop the file in the intended container. Well, that can easily be done as shown below.



 dropZone.addEventListener('dragover', (event) =>{
        event.preventDefault()

        dropZone.style.backgroundColor = '#e0e0e0'
    })

    dropZone.addEventListener('dragleave', () =>{
        dropZone.style.backgroundColor = '#eb6363a6'
    })

    dropZone.addEventListener('drop', (event) =>{
        event.preventDefault()

        dropZone.style.backgroundColor = '#f0f0f0'

        const files = event.dataTransfer.files

        console.log(files)
    })

The adjustments above involve altering the background color of the drop zone container from the initial background color to a gray color when the file is dragged into the drop zone container. The color changes to a shade of red if the drag leaves the container without dropping the file. Dropping the file resets the color to the initial background color.

That's all good but didn't we say we could also click it? Up next ...

5. Make it clickable

The prompt in the container says we can also click the box to input a file. Unfortunately, clicking the box now doesn't open the file explorer as promised. How can we fix that? You guessed it right, add a click event listener to the container.



 dropZone.addEventListener('click', () =>{

    })

We have added the click event listener, now what?

In standard user interfaces, we trigger the opening of the file explorer by clicking a file input element that is displayed on a web page. In our case, we don't want to display a file input element. Lucky for us, we can add the element to the DOM and hide it from display using the hidden attribute. We can also click it programmatically using JavaScript.

Extend the initial HTML markup to include the input element as shown below:



<body>
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Drag and Drop File Upload</title>
      <link rel="stylesheet" href="./style.css">
    </head>
    <body>
      <div id="drop-zone" class="drop-zone">
        <p>Drag & drop files here or click to upload</p>
        <input type="file" id="file-input" multiple hidden>
      </div>
      <script src="./drag-drop.js"></script>
    </body>
    </html>

</body>
</html>

The hidden attribute allows us to exclude the input element from the display while keeping it in the DOM tree.

Now that we have the input element in the DOM, we can access it from our JS scripts and click it programmatically when the drop zone container is clicked. The code snippet below implements the program.



dropZone.addEventListener('click', () =>{

    const fileInputElement = document.querySelector('input')
    fileInputElement.click()
})

Summary

That is how we create a clickable drag-drop file input user interface. The drag-drop file input user interface uses the DragEvent interface which provides the dragover, dragleave, drop, and other browser events. When implementing the drag-drop file input, it is important to alter the styles of the drop target to improve the user experience. In addition to the drag-drop input, users will always appreciate an additional option for clicking the drop zone to open the file explorer. You can add a hidden file input element to your markup and click it programmatically when the drop zone is clicked. That's all for the article, thanks for reading. Feel free to say something in the comments section. Bye bye.

Read more about the DragEvent interface on MDN.

Preview Your Images Instantly Before Uploading.

Felix Owino — Sat, 06 Jul 2024 18:01:07 +0000

We all have used modern websites where you get the pleasure of previewing the image you have selected for upload before you send it to the server. Image preview is such an interesting experience to have as user. You have seen this several times on social media. This is a common experience in most modern websites.

As upcoming developers, we only get to see the default behavior when uploading files, that is an ugly display of the name of the image file alongside an ugly button that says 'Choose a file'. Now are you eager to find out what magic the developers of your favorite social media sites perform to make you happy about your pictures before sending them to the rest of the world? Yes, and this article will show you how to preview images on your websites before uploading. Perhaps you can also make the users of your websites as happy as you always are.

Writing the Markup code

Previewing files is a such an easy task that we can accomplish with just about four lines of code. Before we go deeper into the magic of previewing the image, let us write some simple HTML code for selecting an image from your computer.



<style>
    *{
        font-family: sans-serif;
    }
    body{
        text-align: center;
        padding-block-start: 4rem;
    }
    button{
        background-color: #0369a1;
        color: #f1f5f9;
        border-radius: 4px;
        padding-inline: 1rem;
        padding-block: .5rem;
        border: none;
    }

    button:hover{
        opacity: .7;
        transition: all .75s;
    }

    input{
        display: none;
    }
</style>
<body>
    <h1>Preview Before Upload</h1>
    <input type="file" name="imageFile">
    <button>Select Image</button>
</body>

The code snippet above renders a heading, a HTML input element for a file and a button named 'Select Image'. We have also included some CSS styles to improve the look and feel.

In the styles we have set the display property for the input element to none. Another unusual thing we have done is adding a button called 'Select Image'. Wondering why we have done this? For one reason, the default file selection component has an ugly display graphic so we can hide it from display and use something easier to style as a button. Another reason why we have used the button is to trigger file selection dialog even if we do not have the input element on display. This means that the input element is only hidden from display but its very much active.

Selecting the file

The next thing we want to do is to give the button the ability to open the file selection dialog when clicked. Guessed how we are going to open the file input dialog using the button. Yes, you are right - by attaching a click event listener to the button. Well, that's true but what are we going to ask the browser in the event handler? Under default display conditions, we would click the file input element manually to open a file selection dialog. In this case we are going to ask the browser to click the file input element when the button is clicked. Once the event handler is executed the file input dialog for will be opened for us. Sounds brilliant, like an automation task, doesn't it? Enough with the words, let's implement what we have just said.



<script>
    const button  = document.querySelector('button')
    const fileInput = document.querySelector('input')

    button.addEventListener('click', () =>{
        fileInput.click()
    })
</script>

That's it, we have instructed the browser to open the file input dialog when the 'Select Image' button is clicked. We click the button which has the click even handler. The click even handler clicks the input element. The input element opens the file selection dialog on for us. The screenshot below shows how the result would look like.

Right now if we select a file from the input dialog, we don't see anything on the screen. That sucks, let see how to preview the image in the next section.

Displaying the Preview

Previewing an image on the client side requires one Browser API called the FileReader. The FileReader is provided readily to us by JavaSript. The FileReader allows us to asynchronously read content of a file in a way that can be displayed instantly. In the case of images, as data URL.

The task we have here is to tell the browser to load the fil and render it instantly after loading. How are we going to do this ? Have you ever heard of a change event? We can watch for the change event in the file input element, then do something when a file is selected.

Let's start small, addi a change event listener to the input element.



fileInput.addEventListener('change', (event) =>{
        //Do something here
   })

Next we will wait for the file to be loaded into the browser then get the image URL before trying to display it.

The code snippet below implements the task described above.



fileInput.addEventListener('change', (event) =>{

        //Get the file from files array
        const file = event.target.files[0]

        if(file){
            const fileReader = new FileReader() 

     //Set up event listener to the fileReader before begining to read
            fileReader.onloadend = () => {

                //Save the value read by the file reader in a variable
                const imageSrc = fileReader.result
            }

            // Tell the fileReader to read this file as URL
            fileReader.readAsDataURL(file) 
        }

    })

We now have a URL (imageSrc) that we can use to render an image. To render an image we need an <img> element. We can create an image element using the createElement method of the document library. After creating the <img> element we can use it to display the image we have just loaded into the browser.



 fileInput.addEventListener('change', (event) =>{

        //Get the file from files array
        const file = event.target.files[0]

        if(file){
            const fileReader = new FileReader() 

            fileReader.onloadend = () => {

                const imageSrc = fileReader.result

             // Create image element
                const img = document.createElement('img')

            // Assign value to the src attribute of the img element
                img.src = imageSrc

           // Add the image element to the body of the document
                document.body.appendChild(img)
            }

            fileReader.readAsDataURL(file) 
        }

    })

The code snippet added above enables us to preview before we can send it to the backend for storage. We created an image element,, assigned an image URL to it and rendered it. The image will be displayed instantly after selecting the file.

An example of what we meant to achieve looks like the following screenshot:

It looks like we have achieved what we wanted but we have a little problem. Have you tried selecting a second image? If you did then you must have realized that multiple images are displayed instead of the latest only. In this little experiment, we expect a new image to replace the existing image.

Preventing multiple image renders.

The solution to rendering multiple images involves cleaning up the DOM every time we are rendering a new image. We clean up to ensure that there is no other image in the body of the document that we don't intend to display.

The following code snippet finds and removes an <img> element if it exists in the body of the document.



... //the rest of the change event handler code
 fileReader.onloadend = () => {

                //Save the value read by the file reader in a variable
                const imageSrc = fileReader.result



                //try to select the img tag
              const existingImgElement = document.querySelector('img')

 //Check if the tag is not null, it then remove it before rendering the next
                if(existingImgElement){
                    document.body.removeChild(existingImgElement)
                }



                const img = document.createElement('img')
                img.src = imageSrc
                document.body.appendChild(img)
            }

...//The rest of the change event handler code

In the above code snippet, we remove an <img> tag from the body of the document just before creating a new one. We check if the value of the existing image element is truthy to avoid potential errors. Removing the existing <img> tag from the body fixes the unintended rendering of multiple images.

Finally, we have successfully learned how to preview an image instantly before uploading. Such a little improvement on your web apps can do a lot good to the user experience on your web apps. Previewing an image before upload can be done using the FileReader API provided by JavaScript. A loadend event handler can be added the FileReader to to render the image after complete loading. The FileReader reads the image as a data URL. The result of the file reader can be assigned directly to the src attribute of the img tag to display the image instantly after selecting it.

Understanding React States for Proper State Management.

Felix Owino — Mon, 12 Feb 2024 08:45:32 +0000

The most interesting thing any beginner gets to learn about React is the React state. Now the question is, what is the React state? Why do we call it a state? And most importantly, why do we need it in React applications? Not to forget about how we use it in React applications. In this article, we will learn about the React state, what it is, what it does, why we need it, and how to use it in React applications.

We want to make our work in this learning exercise as easy as possible. For that reason, we will break down this topic into the following sections:

Foundational understanding of React States.
The difference between States and Props.
Immutability in React states and why is it important to keep states immutable.

By covering the above subtopics, you will have more than what you need to start using React states in your components. Let us begin by looking at the foundations of the React state.

1. Foundational Understanding of React State.

Now if you are wondering about what React state is, this section will help you relax your mind about it. We will define what a state is with an example and discuss why React states are important.

Before thinking about states in the technical sense, consider a state as an English word. What comes into your mind when you hear the word state? The current condition of something? What is currently happening around you? Well, all those make sense as states in the real world.

In React, the state is a feature that enables React to keep track of the nature of data being rendered in each component. State enables a component to remember what it is supposed to render on every render. React provides an inbuilt hook called the usesState hook that is used to handle states.

Take for example a simple component that takes input of product quantity from the user and displays it on the screen:

The following code snippet describes the component that renders the elements shown in the screenshot above:

import { useState } from 'react'

const ProductQuantity = () => {
    const [quantity, setQuantity] = useState(0)

    return (
        <div>
            <input type="number" value={ quantity } onChange={
                (e) => setQuantity(Number(e.target.value))
            } />

            <h1> Current Quantity: { quantity }</h1>
        </div>
    )
}

The code snippet above does the following:

i). It initializes the state called quantity with the value 0 using the useState hook

ii). The useState hook returns an array containing the following two items:

A variable that keeps the initial value of the state
A function that can be used to update the state.

In this case, the state is stored in the variable named quantity and the function for updating the quantity is called is stored in a variable called setQuantity.

ii). The component renders a number input field with a default value of 0. The text input field has a change event handler; an anonymous function that calls the updater function, setQuantity with the value of the input.

iv). Finally, the component renders the value of the quantity in a heading tag.

The value of the quantity can be changed to any number and it will be displayed instantly, for example, say you want to input a new quantity as 10000. It would look something like this:

Without the state variable and the state setter function, the component would not know that the value of quantity has changed and therefore it should rerender the new value. States tell a component what to render.

2. The difference between props and states.

If you are sequentially learning React, you must have used props to supply data to components. Now you might be thinking that props also tell components what to render, why do we need to learn about this new concept called states? The thing is, props tell a component about the changes that occur outside the component and states tell a component what happens to the data inside itself.

Let us adjust our ProductQuantity component to accept a prop. This time, let us supply a new value called unitPrice to the component using a prop. We want to use this value to calculate the price of the products when we update the quantity. The final rendered component with a unitPrice of 240 would look like the screenshot below:

We can adjust our components to render the above information as follows:

import { useState } from 'react'

const ProductQuantity = ( { unitPrice }) => {
    const [quantity, setQuantity] = useState(0)

    return (
        <div>
            <input type="text" value={ quantity } onChange={
                (e) => setQuantity(Number(e.target.value))
            } />

            <h1> Current Quantity: { quantity }</h1>
            <h2>Unit Price: { unitPrice }</h2>
            <h3> Total Cost: {quantity * unitPrice }</h3>
        </div>
    )
}

The code snippet above does the following new things:

The component accepts a unit price prop (unitPrice) of type number
The component displays the unit price in a level 2 heading tag (h2)
Finally, the component calculates the total cost of the quantity of products entered and displays it in a level 3 heading tag h3.

As we said earlier, props are values supplied to a component by its parent component. We can call our updated component in a parent component to supply the value of the unitPrice prop, as shown below:

    import ProductQuantity from './ProductQuantity'

    function App() {
        const unitPrice = 240

        return (
            <div>
                <ProductQuantity unitPrice={unitPrice} />
            </div>

        )
    }

From the above code snippets, we can see that props transfer information about changes that occur in the parent component (App) while a state takes care of the changes that occur in the current component (ProductQuantity). The prop (unitPrice) is initialized and maintained in the parent component while the state (quantity) is initialized and maintained by the current component.

Now with the above setup, we can update the quantity of products and the total will be displayed instantly. For example, say we change the quantity of products to 29, the updated total will be displayed as shown below.

3.) Immutability in React states and why is it important to keep states immutable.

What does it mean for something to be immutable? An immutable object is an object that cannot be changed. React states are technically mutable but it is recommended to treat them as if they are immutable. This means you should not modify a state during an update but you should replace it.

For example, we can create a new component called PurchasedProduct that takes, name, quantity, and unitPrice input from the user. The product renders the values of the product properties including gross total on the screen as shown below.

The code snippet below renders the elements shown in the screenshot above:


import { useState } from 'react'

const PurchasedProduct = () => {
    const [product, setProduct] = useState({
        name: '',
        quantity: 0,
        unitPrice: 0
    })
    return (
        <div>
            <div>
                Name: <input type="text" />
                Quantity: <input type="number" />
                Unit price: <input type="number" />
            </div>
            <h1>Name: {product.name}</h1>
            <h1>Quantity: { product.quantity}</h1>
            <h1>Unit price: {product.unitPrice }</h1>
        </div>
    )
}

Notice that we have not handled any change events in the input fields. To learn the importance of keeping states immutable, we will break down this section into the following:

a) Problems associated with mutating states
b) How to maintain immutability while updating states
c) Using the spread operator to update states

a) Problems associated with mutating states.

One way to update the state of the product with the changes in input values would be to update every single property that is related to each input field. The code snippet is shown below.

import { useState } from 'react'

const PurchasedProduct = () => {
    const [product, setProduct] = useState({
        name: '',
        quantity: 0,
        unitPrice: 0
    }) 

    const updateName = (e) => { product.name = e.target.value }

    const updateQuantity = (e) =>{ product.quantity = Number(e.target.value) }

    const updateUnitPrice = (e) =>{ product.unitPrice = Number(e.target.value) }

    return (
        <div>
            <div>
                Name: <input type="text" onChange={updateName}/>
                Quantity: <input type="number" onChange={updateQuantity}/>
                Unit price: <input type="number" onChange={updateUnitPrice}/>
            </div>
            <h1>Name: {product.name}</h1>
            <h1>Quantity: { product.quantity}</h1>
            <h1>Unit price: {product.unitPrice }</h1>
        </div>
    )
}

Surprisingly, the code snippet above seems to be so simple and straight forward but it does not update any states. Nothing changes in the display at all when you try to change the values in the input field. The screenshot below shows all the input fields populated with input data but nothing new is rendered.

This is what happens when you try to change state directly like you would change the value of any variable. The state does not get updated at all and therefore no rerendering occurs.

Let us try doing it differently, this time we will use, the setProduct function to update the state.

const PurchasedProduct = () => {
    const [product, setProduct] = useState({
        name: '',
        quantity: 0,
        unitPrice: 0
    }) 

    const updateName = (e) => { setProduct({ name: e.target.value }) }

    const updateQuantity = (e) =>{ setProduct({ quantity:Number(e.target.value)} ) }

    const updateUnitPrice = (e) =>{ setProduct({ unitPrice: Number(e.target.value) }) }

    return (
        <div>
            <div>
                Name: <input type="text" onChange={updateName}/>
                Quantity: <input type="number" onChange={updateQuantity}/>
                Unit price: <input type="number" onChange={updateUnitPrice}/>
            </div>
            <h1>Name: {product.name}</h1>
            <h1>Quantity: { product.quantity}</h1>
            <h1>Unit price: {product.unitPrice }</h1>
        </div>
    )
}

Let's render our component with the above changes and see what happens. This time, we get something better.

The first value, name, updates as expected as shown below:

Let us try the second value, product quantity:

Now we have a problem here, the second value updates well but the first one disappears.

Let's see what happens with the last value, unitPrice:

Similarly, the unit price gets updated and rendered as expected but the rest of the values are not rerender as we expected.

What is happening here? According to our code, we are updating a single property of the product object at every input field. This means that we are trying to modify the product partially at every step.

The problem with this approach is that every time we update just one value, the initial object is replaced with a new object with just one property. When we update the name, we end up with a new object, {name: <new name>}. The new object does not know anything about unitPrice or quantity. Updating the next value, unitPrice does the same thing, it replaces the current object with a new object that has no name or quantity properties. Therefore, when the component is being rerendered, only one value gets rendered at a time, the most recent update.

b) How to maintain immutability when updating states.

The correct way to update the state in the PurchasedProduct component is to replace the whole product object with a new object containing all its properties. In other words, copy the object and only change the value you are interested in changing without losing the other values. The code snippet is shown below:

const PurchasedProduct = () => {
//The code that initializes the state goes here

    const updateName = (e) => { 
        setProduct(
            { 
                name: e.target.value,
                quantity: product.quantity,
                unitPrice: product.unitPrice 
            }
        ) 
    }

    const updateQuantity = (e) =>{ 
        setProduct(
            { 
                name: product.name,
                quantity:Number(e.target.value),
                unitPrice: product.unitPrice
            } 
        ) 
    }

    const updateUnitPrice = (e) =>{ 
        setProduct(
            { 
                name: product.name,
                quantity: product.quantity,
                unitPrice: Number(e.target.value) 
            }
        ) 
    }

    return (
        //JSX goes here
    )
}

With the changes described in the above code snippet, we can now get a component that behaves just as we expect. In the screenshot below, all the input fields are filled and all the values are displayed as expected.

This shows that states are managed better when they are treated as immutable. Every time you are updating a state, make sure you are replacing the whole state variable and not just modifying its parts. This approach applies to array variables too. When working with arrays in states, consider replacing the whole array when adding or removing an item from the array.

c) Using the spread operator.

A Less wordy approach to achieve the same goal above is to use the spread operator. The spread operator can save you a few lines of code and errors that you may introduce while copying the object. Below is a code snippet showing how the spread operator can make your life easier.

const PurchasedProduct = () => {
//State initialization goes here

    const updateName = (e) => { 
        setProduct(
            { 
                ...product,
                name: e.target.value
            }
        ) 
    }

    const updateQuantity = (e) =>{ 
        setProduct(
            { 
                ...product,
                quantity:Number(e.target.value),
            } 
        ) 
    }

    const updateUnitPrice = (e) =>{ 
        setProduct(
            { 
                ...product,
                unitPrice: Number(e.target.value) 
            }
        ) 
    }

    return (
       // JSX goes here
    )
}

The spread operator enables you to override one property of the product object and leave the rest as they are.

Conclusion

In conclusion, understanding the React state as the memory of a component is crucial to the success of your user interface projects. In this article, we have learned the following concepts about React state:

How to initialize state using the useState hook
How to update state using the set state function
The difference between states and props
Problems associated with mutating states
How to keep states immutable and why it is important to keep them immutable.
How to update states using the spread operator.

Visit the react documentation to learn more about how state triggers rerendering in React applications.

How to set and customize horizontal and vertical scrollbars with CSS

Felix Owino — Wed, 07 Feb 2024 07:56:05 +0000

Scrollbars are essential components of graphical user interfaces (UI). Scrollbars allow users to view content that extends beyond the width or height of their containers. Scrollbars also enable users to view content that extends past the screen width or height. By default, the browser includes a scrollbar for overflow on the body content. In other cases, the UI developer has to set a scrollbar to enable users to view content extending beyond the screen or a particular container. Each browser has a set of default styles for scrollbars. In some cases, you may have a good reason to customize the scrollbars. For example, you can customize scrollbar styles to match the look and feel of the website.

In this article, we will look at when to set horizontal and vertical scrollbars, how to set them, and how to customize their appearance with CSS.

We will cover this topic in the following sections:

Setting up a custom vertical scrollbar
Setting up a custom horizontal scrollbar
Customizing scrollbar styles

1. Setting up a custom vertical scrollbar

This is the most common type of scrollbar that users interact with on websites. The vertical scrollbar is so common because the browser sets a default vertical scrollbar for all websites. Apart from the default scrollbar, you can also set a custom vertical scrollbar within your website. A vertical scrollbar can help the users of your website view content that extends beyond the visible area of a container. For example, a sidebar navigation. You can style your sidebar to display a scrollable list of navigation items.

In this section, we will create a scrollable sidebar navigation as per the following steps:

a) Create a navigation bar with navigation items
b) Style the navigation bar into a sidebar
c) Set the sidebar position to fixed
d) Manage overflow of items using a scrollbar

a). Create a navigation bar with navigation items

To create a navigation bar, we will use the HTML nav element. Our navigation bar will contain the following items:

Home
Shop
Markets
Products
Sellers
Manufacturers
Distributors
Chain managers
Banks

Our aim in this step is to create a navigation bar shown in the screenshot below:

The initial navigation bar with the above items can be created using the code snippet shown below:



<style>
    a{
        padding: 1rem;
        color: rgb(38, 103, 216);
        text-decoration: none;
    }
</style>
<body>
    <nav>
         <a>Home</a>
        <a>Shop</a>
        <a>Markets</a>
        <a>Products</a>
        <a>Sellers</a>
        <a>Manufacturers</a>
        <a>Distributors</a>
        <a>Chain managers</a>
        <a>Banks</a>
    </nav>
</body>

b). Style the navigation bar into a sidebar.

After creating our horizontal navigation bar, we can style it into a vertical sidebar before setting a vertical scrollbar.

The following screenshot shows the sidebar that we are about to create:

To create the above sidebar, we will make the following changes in CSS:

Change the display of the navigation bar to flex with the direction set to column
Set the background color for the sidebar
Add a border to the bottom of the navigation links
Increase font size and font weight of the navigation links
Set a fixed width for the sidebar
Increase the height of the body to make it long enough for scrolling

The CSS code snippet below describes how to style the initial navigation bar into a sidebar and adjust the margin-bottom of the body.



    nav{
        display: flex;
        flex-direction: column;
        background-color: rgba(0, 0, 0, 0.1);
        width: 20vw; // Set fixed width for sidebar
        > a{
            border-bottom: solid 2px gray;
            font-weight: 500;
            font-size: 1.8rem;
        }
    }

    body{
        margin-bottom: 200vh; //Adjust the bottom margin of the body
    }

c). Set the sidebar position to fixed.

In this section, we'll focus on preventing the sidebar from moving when you scroll through the main content. We want to style the sidebar so that the body can scroll on its own without carrying the sidebar along with it.

The screenshot below shows the sidebar separated from the normal content flow:

The sidebar above has a fixed position. The body of the page continues to scroll but the sidebar remains within the user's view.

The following code snippet contains styles for setting the sidebar into a fixed position as shown in the above screenshot:



nav{
        /* previous styles go here */
        position: fixed;
        top: 4rem;
        bottom: 4rem;
        left: 0;
    }

In the code snippet above, we have set the sidebar distance from the top and bottom to 4rem. From the screenshot, the bottom of the sidebar doesn't look like it is set off the bottom. This is because the content is longer than the height of its container. In the next section, we will learn how to prevent the list of navigation items from displaying outside the sidebar.

d). Managing content overflow using a scrollbar

Preventing navigation items from displaying outside the sidebar is surprisingly easy. This can be done in one line of CSS code using the overflow-y property. Setting the overflow-y property to scroll creates a scrollable container for content exceeding its height. The items that extend beyond the sidebar will be obscured. A scrollbar will appear on the right side, allowing the users of your website to see everything.

The code snippet for hiding the extended content and showing the sidebar is as simple as shown below:



    nav{
        /* previous styles go here */
        overflow-y: scroll;
    }

More about the `overflow-y` property.

The overflow-y property accepts either of the two values; scroll or auto. Setting the value of the property to scroll instructs the browser to always add a scrollbar to the container. The container will always have a scrollbar whether it has content extending past its boundaries or not. On the other hand, if you set the value of the overflow-y property to auto, the browser will not add the scrollbar unless the target container has extended content. With the value of the overflow-y property set to auto, the browser will hide the scrollbar if there is no content extending beyond the boundaries of the container.

Congratulations! You have successfully created a vertical scrollbar. Take a break if you need one. In the next section, we will learn how to set a horizontal scrollbar.

2. Setting a custom horizontal Scrollbar.

You can add a horizontal scrollbar to a container within your webpage. The horizontal scrollbar can enable users to view a long series of horizontal content within a shorter container.

The screenshot below shows an orange container with a series of blue squares that extend beyond its width. The container would look much better if the container had a horizontal scrollbar.

Below is the code snippet for the above layout:



<style>
    .container{
        display: flex;
        flex-direction: row;
        width: 60%;
        margin: auto;
        margin-block-end: 6rem;
        gap: .5rem;
        padding: 1rem;
        background-color: rgb(226, 150, 9);
    }
    .box{
        min-width: 200px;
        height: 200px;
        background-color: rgb(0, 255, 213);
        width: 100%;
        padding: 4rem;
        font-size: xx-large;
    }
</style>
<body>
    <div class="container">
        <div class="box">1</div>
        <div class="box">2</div>
        <div class="box">3</div>
        <div class="box">4</div>
        <div class="box">5</div>
        <div class="box">6</div>
        <div class="box">7</div>
    </div>
</body>

The page has a default horizontal scrollbar at the bottom left corner of the screen but you don't want the users of your website to use this. Relying on the default scrollbar would mean that the users will have to scroll the whole page horizontally to see full content. The users will also be scrolling through content that does not need to be scrolled.

Your goal is to make sure that the blue squares can only be viewed within the orange container as shown in the layout below.

In the previous section, we added a scrollbar by setting the value of the overflow-y property to scroll. You can guess what this is going to be. You got it. The property is called overflow-x.

Set the value of the overflow-x property to scroll to make the container items scrollable as shown in the code snippet below.



 .container{
        /*previous container styles go here */

        overflow-x: scroll; //Managing oveflow with scroll.
    }

By setting the the value of overflow-x property to scroll, a horizontal scrollbar is added to the bottom of the container. The users of your website will be able to smoothly scroll through the content in the container.

You have successfully created both horizontal and vertical scrollbars. Let us move to the next section where we are going to discuss how to style the scrollbars.

3. Customizing scrollbar styles

One of the reasons why you would want to style the scrollbars of your website is to attain color harmony on the entire webpage. You may want to keep the number of colors used on your website to a set minimum. You may also want to use a different color for the scrollbar to make it easy to notice.

When styling the scrollbar, we can set desired values to the following properties:

width - the thickness of a vertical scrollbar
height - the thickness of a horizontal scrollbar
background-color of the scrollbar-thumb - the object that moves back and forth on a scrollbar as you scroll
background-color of the scrollbar-track - the path along which the scrollbar-thumb moves
border-radius for scrollbar-track, or scrollbar-thumb, or both. The border-radius property smoothens the extreme ends of the scrollbar component that it is set on.

In this section, we will explore the different ways of styling scrollbars as listed below:

a) Styling a specific scrollbar.
b) Styling the default scrollbar separately.
c) Styling all scrollbars at once

a). Styling a specific scrollbar.

There is an easy way to set specific styles to different an individual scrollbar on a website. This involves adding styles through the container that the scrollbar is set on. You can select the container by tag name or by class name and assign styles to it.

In this section, we will style the vertical scrollbar (sidebar) and the horizontal scrollbar (flexbox) separately.

Styling vertical scrollbar (sidebar scroll)

We will set the following styles on the sidebar (vertical) scrollbar.

Set the background-color of the scrollbar-track to blue
Set the background-color of the scrollbar-thumb to green
Set the width (thickness) of the scrollbar to 12px
Set the border-radius of the scrollbar-track and scrollbar-thumb to 12px.

The result we aim to create is shown in the screenshot below:

The following code snippet describes the styles used to achieve the above result:



    nav::-webkit-scrollbar{
        width: 12px;
    }

    nav::-webkit-scrollbar-track{
        background-color: rgb(21, 146, 171);
        border-radius: 12px;
    }

    nav::-webkit-scrollbar-thumb{
        background-color: rgb(31, 125, 2);
        border-radius: 12px;
    }

In the above code snippet, we select the sidebar using the nav tag.

Styling the horizontal scrollbar (flexbox scrollbar)

Styling the horizontal scrollbar is similar to styling a vertical scrollbar except for one property. The height property is used to set the thickness of a horizontal scrollbar instead of the width property.

In this exercise, we'll reuse previous styles, but we will set the thickness of the scrollbar using the height as described below:

Set the background-color of the scrollbar-track to blue
Set the background-color of the scrollbar-thumb to green
Set the height (thickness) of the scrollbar to 12px
Set the border-radius of the scrollbar-track and scrollbar-thumb to 12px.

After applying the styles as described above, the final flexbox container scrollbar should appear as shown below.

Below is the code snippet for customizing the horizontal scrollbar:



    .container::-webkit-scrollbar{
        height: 12px;
    }

    .container::-webkit-scrollbar-track{
        background-color: rgb(21, 146, 171);
        border-radius: 12px;
    }

    .container::-webkit-scrollbar-thumb{
        background-color: rgb(31, 125, 2);
        border-radius: 12px;
    }

In the above styles, we select the flexbox using its class name and apply styles to it.

b). Styling the default scrollbar

The default scrollbar appears on the right-hand side of a webpage. To style the default scrollbar, we select the body tag and add styles to it.

The screenshot below shows a default scrollbar with custom styles:

The code snippet below shows how you can add styles to the scrollbar using the body tag:



    body::-webkit-scrollbar{
        width: 12px;
    }

    body::-webkit-scrollbar-track{
        background-color: rgb(21, 146, 171);
        border-radius: 12px;
    }

    body::-webkit-scrollbar-thumb{
        background-color: rgb(31, 125, 2);
        border-radius: 12px;
    }

c). Styling all scrollbars at once.

In most cases, you will prefer to maintain a consistent style across all the vertical and horizontal scrollbars on your website.

To achieve uniform customization across all scrollbars, we can apply styles as follows:

Apply scrollbar styles without selecting any specific element, tag, or class name
Assign values to both height and width properties in the case where a website has both horizontal and vertical scrollbars.

The screenshot below shows horizontal and vertical scrollbars with consistent styles:

When applying CSS styles, make sure you set values for both the height and width properties. The value of the height will be applied to the thickness of the horizontal scrollbar. The value of the width will be applied to the thickness of the vertical scroll bar.

The following code snippet shows how you can apply styles to all scrollbars on the target webpage:



    ::-webkit-scrollbar{
        height: 12px;
        width: 12px;
    }

    ::-webkit-scrollbar-track{
        background-color: rgb(21, 146, 171);
        border-radius: 12px;
    }

    ::-webkit-scrollbar-thumb{
        background-color: rgb(31, 125, 2);
        border-radius: 12px;
    }

Notice in the above code that this time we are not selecting any element or class in specific. The styles are global; and applicable to all scrollbars on the document.

Conclusion

Scrollbars are a great way to improve the responsiveness and accessibility of your web application. This article has covered how to set and customize the appearance of scrollbars on a web page. In this article we have learned the following:

How to enable scrolling in containers with content that extends beyond their set boundaries.
How to make a scrollbar permanently visible in a container even if the content fits perfectly.
How to set a scrollbar that will only be visible if the content extends beyond the container.
How to add custom styles to scrollbars.

We have also learned how to style scrollbars using the -webkit CSS prefix. Find out more about the -webkit CSS prefix in this article. There are other ways to style scrollbars. For example, this article from MDN describes a different way to style scrollbars. Note that scrollbar customizations may not work on all browsers. Visit this MDN doc to find out more about browser compatibility with the styling method described in this article.

How to Populate Database with Test Data.

Felix Owino — Mon, 20 Nov 2023 22:02:28 +0000

Testing is vital in the software development life cycle. During the software development, you occasionally need to test your application against data. One way to acquire test data is through manual entry. The problem with manual entry is that it's limited. There is only so much data you can enter manually. A better option is to load the data to your database using a program separate from your application. In this article, we will learn how to write a program to upload test data to a test database.

To learn smoothly from this article, you should have a basic knowledge of the following.

Creating simple programs with Node JS
Working with Mongo DB
Working with a database abstraction library. We will use Mongoose in this article.

We will learn how to upload test data to the database by performing the following actions:

Create a data model.
Fetch raw data from an API.
Connect to the database.
Populate the database with documents.

1. Create data model

Data models are essential in loading test data to the database. Models define the shape and properties of the data to be uploaded. The shape of the data you upload should be compatible with the specifications of our application. You need to create the same models as they are in the application you intenf to test. In this article, we will assume a todos model.

To define a model we need to install Mongoose using the command below.

npm install mongoose

Then we define the Todo model as follows.

import { Model, Schema, model } from "mongoose"

interface ITodo{
    title: string
    completed?: boolean
}

type TodoModel = Model<ITodo>

const todoSchema = new Schema<ITodo, TodoModel>({
    title: String,
    completed: { type: Boolean, default: false}
})

export const Todo = model<ITodo, TodoModel>('Todo', todoSchema)

We will use the above model to upload data to the database.

Next, we fetch the raw data that we will use to create documents from the model.

2. Fetch data

In the previous step, we created a model for our data. In this section, we will get the raw data that we will use to create documents. We will fetch the raw data this fake data API.

Below is the code snippet that fetches the raw data.

(async() =>{
    try {
        const response = await fetch('https://jsonplaceholder.typicode.com/todos')
        const rawData = await response.json()


    } catch (error: any) {
        console.log(error.message)
    }

})()

After fetching the data from the API, let us connect the database in the next step before we can create documents.

3. Connect to the database.

Before sending data to the database, we need to connect to MongoDB. Get the connection string for your test database and connect to the database as shown in the code snippet below.

import mongoose from "mongoose"

(async() =>{
    try {
        const response = await fetch('https://jsonplaceholder.typicode.com/todos')
        const rawData = await response.json()

        const dbUri = 'Your db uri'

        if(dbUri){
            await mongoose.connect(dbUri)
        }

    } catch (error: any) {
        console.log(error.message)
    }

})()

Now we have a database ready to receive our data, let us create documents and save them to the database in the next section.

4. Populate the database with documents.

In this section, we will create and save Todo documents for each instance of data in the rawData array. The code snippet below creates and saves data using the Todo.create method. We also log the id of the document we create.

import mongoose from "mongoose"
import { Todo } from "./model"

(async() =>{
    try {
        const response = await fetch('https://jsonplaceholder.typicode.com/todos')
        const rawData = await response.json()

        const dbUri = process.env.MONGODB_URI

        if(dbUri){
            await mongoose.connect(dbUri)

            //Populated db with documents   
            rawData.forEach(async(todo:any) => {
                const todoDoc = await Todo.create({
                    title: todo?.title,
                    completed: false
                })

                console.log('Created: ', todoDoc.id)
            })
        }

    } catch (error: any) {
        console.log(error.message)
    }

})()

The execution of the above program populates the target database with Todo documents.

Finally, we have created a program that loads data that matches our model specification to the database. The program loads the data to the database by following steps listed below:

Create a model that fits the shape of the expected test data.
Fetch raw data from the jsonplaceholder API
Iterate over the test data and create a document for each instance of the raw data using the Todo model.
Save the documents to the database.

The code we have written in this article and other well refactored examples on the same topic is available on this repository.

Testing Express API Routes the Easy Way: Beginners' guide.

Felix Owino — Sun, 19 Nov 2023 04:50:31 +0000

Unit testing is one of the best practices in software development. In the development of web APIs, there is no question about the importance of unit testing. Unit testing is critical in ensuring that all the routes in a web API respond with the information expected from them.

Testing routes in a web API can be a nightmare if you don't structure your components well. One area that causes the most pain for beginners in testing APIs is the routes that involve database access. Database operations are inevitable. Often you are going to build CRUD applications as a beginner. In this article, we will learn how to test API routes with the least difficulty possible.

What will this article cover?

The main focus of this article is to show you how to test routes. Therefore, other related tests such as database tests are out of the scope of this article.

What does the article expect you to already know?

This article is not an introductory tutorial to unit testing or API development. Therefore, we assume that you have basic knowledge of the following topics:

Unit testing with JavaScript libraries like Jest.
Mocking expensive operations in unit tests with the Jest mock functions.
Creating simple CRUD APIs using Express.
Working with Mongoose for database operations.
Working with Typescript(optional but a plus if you know).

If you are new to Typescript, do not fret. Everything that we will cover in this article can be done even more easily with plain Javascript.

What technologies are we going to use?

We will use the following technologies, frameworks, and libraries in this article:

Jest
Supertest
Node v20
Typescript
Express
Mongoose

What should you expect to learn from this article?

At the end of this article, you will have learned how to do the following:

Separate your tests from the main application.
Modularize your application for easy testing.
Test routes that involve database operations without connecting to a database.
Run tests successfully regardless of whether your application runs on a server.

How are we going to learn?

Here is the order in which we are going to learn how to test API routes the easy way:

Configure a test environment.
Create a simple Express API.
Modularize your application for easy testing.
Write your first route test.
Write a test involving database operation.
Decouple the data-access logic from the web layer.
Introduce dependencies on the controller and the router.
Mock your data-access layer.
Replace the data access layer with the mock in the test file.

1. Configure a test environment.

In the spirit of "Do not repeat yourself," we will use a preexisting test environment. We will clone a configured test environment from a GitHub repository. This repository contains configurations for Jest and Typescript. In case you are interested in learning how to configure a test environment for Jest and Typescript, visit this article.

After cloning the repository, run the following command to install node modules.



npm install

That's it. We have a development and test environment ready for us to work on. Let's move to step 2 and create a simple Express API.

2. Create a simple Express API.

Because you already know how to create an API with Node and Express, we will go through this step quickly so we can start working on why you are here.

Run the following command on your terminal to install Express and it's types.



npm i express
npm i -D @types/express

In your src directory, create an app.ts file and paste the following code snippet.



app.ts


import express from "express"

const api = express()

api.use(express.urlencoded({ extended: true }))
api.use(express.json())

api.get('/', (req, res) =>{
    res.status(200).json({message: 'Welcome to my API'})
})

There we go. That's all we need for now. Notice that we are not connecting to a database or listening on a port. We do not need database connectivity or a running instance of our application to be able to test it.

3. Modularize your application for easy testing.

To enable efficient testing of the routes of our application, we need to modularize it into its individual components.

We will decouple our API into routes, controllers, and the main file(app.ts). We follow the steps below:

a). Modularize route handlers.

b). Modularize routes.

c). Refactor the main file

a). Modularize router handlers

Create a controller.ts file in the src directory. Create and export a route handler on the file as shown below.



controller.ts


import { Request, Response } from "express";

export const index = (req: Request, res: Response) =>{
    res.status(200).json({ message: 'Welcome to my API' })
}

b). Modularize routes

i). Create a routes.ts file in the src directory.

ii). Create a router from express.Router.

iii). Import the controller function, and set up a route as shown below.



routes.ts


import { Router } from "express";
import { index } from "./controller";

const router = Router()

router.get('/', index)

export {router}

c). Refactor the main file

Import the router into app.ts and replace the route handler as below.



app.ts


import express from "express"
import { router } from "./routes"

const api = express()

api.use(express.urlencoded({ extended: true }))
api.use(express.json())

api.use('/', router)

We have successfully modularized our application for easy testing. Get ready to write your first route test in the next step.

4. Write your first route test.

In the previous sections, we have created a simple Express API and modularised it for easy testing. Let us write a test for the index route (/home).

To write our first test, we will follow the steps below:
a). Create a separate instance of the API.

b). Install a routes testing library

c). Write a failing test.

d). Run the test.

e). Make the test pass.

a). Create a separate instance of the API.

An effective way to test routes of an API is to create a separate instance of the API. Create an app.test.ts file and copy the content of app.ts to it. Below is the code snippet.



app.test.ts


import express from "express"
import { router } from "./routes"

const api = express()

api.use(express.urlencoded({ extended: true }))
api.use(express.json())

api.use('/', router)

b). Install a routes testing library.

The Supertest can be used in union with Jest to test the routes of an API. Install the Supertest module and its types using the command below.



npm i -D supertest @types/supertest

c). Write a failing test.

An example of a test for the index route can be written as shown in the code snippet below.

Import required functions



app.test.ts
...//The previous imports go here

import request from 'supertest'
import { describe, test, expect} from '@jest/globals'

Write test:



app.test.ts


... //All imports go here

... //the API configurations go here

describe('Index Route', () =>{
    test("Responds with 200 status code", async() =>{
        const response = await request(api).get('/home')
        expect(response.status).toEqual(200)
    })

    test("Responds with json content", async() =>{
        const response = await request(api).get('/home')
        expect(response.headers['content-type']).toMatch(/json/)
    })

    test("Returns with \'welcome home\' message", async() =>{
        const response = await request(api).get('/home')
        expect(response.body.message).toMatch(/welcome home/i)
    })
})

Notice that the route we are testing does not exist in our application yet. We are doing this intentionally for this test to fail. It is good practice to have a failing test before you can write the code to make it pass.

d). Run the test.

Before we run any test, remove or skip any other test file in the directory you didn't write.

Now run this test using the following command to see that it fails.



npm test

As we see in the screenshot below, the test has failed.

Next, we make it pass in the last step.

e). Make the test pass.

To make the above test pass, we first need to declare a route handler in controller.ts



controller.ts


import { Request, Response } from "express";

export const home = (req: Request, res: Response) =>{

}

...//Other router handlers

Then we include the new path on the routes.ts file and import the route handler.



routes.ts

import { Router } from "express";
import { home, index } from "./controller";

const router = Router()

router.get('/home', home)

router.get('/', index)

export {router}

Our test is still failing, let us return a response that satisfies our test from the home controller function.



export const home = (req: Request, res: Response) =>{
    res.status(200).json({message: "Welcome home"})
}

With the above implementation, our test passes as shown in the screenshot below.

Success! You have written and run your fast test. In the next step, let us test a POST request that saves data to the database.

5. Write a test involving database operation.

We have seen how to test a simple GET route that responds with a simple message. Now let us create a test for a POST route /item that will do the following :

Receive input data from the user.
Create a Mongoose document and save it to the database.
Respond with a copy of the saved document.

We will accomplish the objective of this article in the following steps:

a). Write a failing test.

b). Create a model for the item.

c). Declare the route handle and configure the route.

d). Implement the route handler.

a). Write a failing test.

The test for the route that satisfies the above requirements would look like the following.



describe('POST item', () =>{
    test('Responds with json content', async() =>{
        const response = await request(api).post('/item')
            .send({ title : 'The Book Of Scretes', pages: 800})

        expect(response.headers['content-type']).toMatch(/json/)
    })

    test('Responds with 201 status ', async() =>{
        const response = await request(api).post('/item')
            .send({ title : 'The Book Of Scretes', pages: 800})

        expect(response.status).toEqual(201)
    })

    test('Responds with saved document', async() =>{
        const response = await request(api).post('/item')
            .send({ title : 'The Book Of Secretes', pages: 800})

        expect(response.body).toHaveProperty('item')
        expect(response.body.item).toHaveProperty('_id')
        expect(response.body.item.title).toMatch(/the book of secretes/i)
        expect(response.body.item.pages).toEqual(800)
    })
})

All the tests we have just added are failing as evident in the screenshot below.

b). Create a model for the item.

Before we try to make the test pass, we need to create a model that we will use to implement the database operation. Here is the code snippet for the model.

To create a model, we will use the mongoose module. Install mongoose using the command below.



npm i mongoose



item.model.ts


import mongoose, { HydratedDocument } from "mongoose"

interface IItem{
    title: string
    pages: number
}

type ItemModel = mongoose.Model<IItem>

const itemSchema = new mongoose.Schema<IItem, ItemModel>({
    title: String,
    pages: Number
})

export type HydratedItemDoc = HydratedDocument<IItem>
export const Item = mongoose.model<IItem, ItemModel>('Item', itemSchema)

Are you interested in learning how to create Mongoose models with Typescript? Be sure to check out this article.

c). Declare the route handler and configure the route.

The model created above will help us implement a database operation within the route handler.

Let us declare the route handler in controller.ts



controller.ts


import { Request, Response } from "express";
import { Item } from "./item.model";

export const addNewItem = async(req: Request, res: Response) =>{

}

...//Previous route handlers

and add it to the route in routes.ts.



routes.ts


import { Router } from "express";
import { addNewItem, home, index } from "./controller";

const router = Router()
router.post('/item', addNewItem)

...//previous routes

Remember that we reserve the implementation of the function until it is the last thing to do for the test to pass.

d). Implement the route handler.

The route handler can be implemented as follows.



controller.ts


import { Request, Response } from "express";
import { Item } from "./item.model";

export const addNewItem = async(req: Request, res: Response) =>{
    const { title, pages } = req.body

    const item = new Item({
        title, pages
    })

    const savedItem = await item.save()

    res.status(201).json({ item: savedItem })
}

...//Previous route handlers

You realize the test still doesn't pass but fails with a Mongoose error.

The test fails because we are not connecting to the database. However, connecting to the database will not be of great use either. Let us see how to resolve this in the coming steps.

6. Decouple data-access logic from the web layer.

The first step towards resolving the issue of database errors in testing routes is to extract the database operations into a separate file. In this step, we will create a data-access.ts file and move the data access logic to it as shown in the code snippet below.



data-access.ts


import { IItem, Item } from "./item.model";

export const createNewItem = async(data: IItem) =>{
    const item = new Item({
        title: data.title, 
        pages: data.pages
    })

    const savedItem = await item.save()
}

Then we call the function in the route handler.



import { Request, Response } from "express";
import { createNewItem } from "./data-access";

export const addNewItem = async(req: Request, res: Response) =>{
    const { title, pages } = req.body

    const savedItem = await createNewItem({ title, pages })

    res.status(201).json({ item: savedItem })
}

With that, we are two steps closer to resolving the problem. Let's introduce dependencies on the router and the controller in the next step.

7. Introduce dependencies on the controller and the router.

The point of introducing dependencies is to allow us to replace the data-access layer with mocks.

The easiest way to introduce dependencies in a file with related functions is to encapsulate all of them in a class. If the file consists of related function calls, we encapsulate them inside one function.

In this step, we will do the following activities:

a). Encapsulate the data access layer.

b). Encapsulate the controller (web layer).

c). Encapsulate the router.

d). Refactor the main file and the test file.

a). Encapsulate the data access layer.

We will first encapsulate the data access layer. We will create a class called APIDAL - API data access layer - to encapsulate database operations.



import { IItem, Item } from "./item.model";

export class APIDAL{
    public createNewItem = async(data: IItem) =>{
        const item = new Item({
            title: data.title, 
            pages: data.pages
        })

        const savedItem = await item.save()

        return ({
            title: savedItem.title,
            pages: savedItem.pages,
            _id: savedItem._id,
            id: savedItem.id
        })
    }
}

b). Encapsulate the controller.

We will create a class called APIController to encapsulate the controller functions. The APIController constructor accepts an object of the data-access layer class as a dependency.
Below is the code snippet.



controllers.ts

import { Request, Response } from "express";
import { APIDAL } from "./data-access";

export class APIController{
    private dal: APIDAL

    constructor(dataAccessLayer: APIDAL){
        this.dal = dataAccessLayer
    }
    public addNewItem = async(req: Request, res: Response) =>{
        const { title, pages } = req.body

        const savedItem = await this.dal.createNewItem({ title, pages })

        res.status(201).json({ item: savedItem })
    }

    public home = (req: Request, res: Response) =>{
        res.status(200).json({message: "Welcome home"})
    }
    public index = (req: Request, res: Response) =>{
        res.status(200).json({ message: 'Welcome to my API' })
    }
}

c). Encapsulate the router.

Our routes file consists of function calls. Therefore, we will encapsulate them in one function called apiRouter.



import { Router } from "express";
import { APIController} from "./controller";

const apiRouter = (controller: APIController) => {
    const router = Router()
    router.post('/item', controller.addNewItem)

    router.get('/home', controller.home)

    router.get('/', controller.index)

    return router

}
export {apiRouter}

d). Refactor the main file and the test file.

The above changes force us to change how we call the router in app.ts and app.test.ts. Here are the updates.

Main file.



app.ts

import express from "express"
import { apiRouter } from "./routes"
import { APIController } from "./controller"
import { APIDAL } from "./data-access"

const apiDAL = new APIDAL()
const controller = new APIController(apiDAL)
const api = express()

api.use(express.urlencoded({ extended: true }))
api.use(express.json())

api.use( apiRouter(controller))

Test File.



api.test.ts

...// Previous imports

import { apiRouter } from "./routes"
import { APIController } from "./controller"
import { APIDAL } from "./data-access"

const apiDAL = new APIDAL()
const controller = new APIController(apiDAL)
const api = express()

api.use(express.urlencoded({ extended: true }))
api.use(express.json())

api.use( apiRouter(controller))

...//Tests

Lastly, we replace the data access layer with a mock class. In the next section, let's create a mock class for the data access layer and import it into the test file.

8. Mock your data access layer.

Do you remember when we said we would not test the database operations? We meant to replace the database operations with fake functions.

In this step, we will create a new class with a function that imitates the one in the APIDAL class. We will create the file and the class with the same names in a different directory.

Here are the steps we will follow.

Create a subdirectory directory called mocks within the src directory.
Create a file called data-access.ts.
Create the APIDAL class on the file and copy-paste the code snippet below.



 import { IItem, Item } from "../item.model";

export class APIDAL{
    public createNewItem = jest.fn(async(data: IItem) =>{
        const item = new Item({
            title: data.title, 
            pages: data.pages
        })

       return ({
            title: item.title,
            pages: item.pages,
            _id: item._id,
            id: item.id
        })
    })
}

In the above code snippet, we have replaced the original function implementation with a mock.

9. Replace the data access layer with the mock in the test file.

After creating a mock for the data access layer, we import it into the test files as shown in the code snippet below.



app.test.ts


...//Previous imports are here

import { apiRouter } from "./routes"
import { APIController } from "./controller"
import { APIDAL } from "./mocks/data-access" //Imported mock class

const apiDAL = new APIDAL()
const controller = new APIController(apiDAL)
const api = express()

api.use(express.urlencoded({ extended: true }))
api.use(express.json())

api.use( apiRouter(controller))

...//All the written tests are below here

Now run your tests. They should all pass as shown in the screenshot below.

Conclusion

Finally, we have successfully explored and practiced how to test Express API routes the easy way. In this article we have learned how to do the following:

Separate unit test from the main application.
Modularize an Express application for easy testing.
Write unit tests for routes of an Express application.
Test routes involving database operations.
Run unit tests without connecting to the database or running your application on a dev server.

The code we have written in this article is available in this GitHub repository

Configuring Jest for Typescript Unit Tests

Felix Owino — Sat, 18 Nov 2023 08:02:46 +0000

Jest is a unit testing library for JavaScript. Testing JavaScript code with Jest is straightforward and doesn't require any additional configuration. When testing Typescript code without compiling it to JavaScript first, a few configurations are required. There are two ways for setting up Jest for Typescript unit test; via Babel or ts-jest. Babel is a popular multipurpose transpiler for JavaScript. ts-jest is an extension of the Typescript compiler tailored to work with Jest. In this article, we will explore and demonstrate how to configure Jest to test Typescript code via ts-jest.

To create a Typescript and Jest testing environment, we will execute the following sequence of activities:

Create an initialized working directory.
Install Typescript.
Configure Typescript.
Install Jest and its related dependencies.
Configure Jest for Typescript.
Edit package.json test script.
Try it out.

Let us start by creating an npm-initialized working directory.

1. Create an initialized working directory.

In this step, we will create a directory called jest-ts-tests and initialize it as a node project directory.

Create a directory named ts-jest-env and run

npm init

to generate package.json file

By executing the above instructions, we now have a directory ready for use. Let us go and install Typescript in the next step.

2. Install Typescript

In the previous step, we created a directory for us to work on. In this step, we will install Typescript as a development dependency as follows.

Run npm i -D typescript

We have successfully installed Typescript, let us configure it in the next step.

3. Configure Typescript

We will install ready-to-use Typescript base configurations instead of starting from scratch. In this article, we will use Typescript base configurations for node version 20. If you are using a different version of node, visit the tsconfig bases docs to find out what you need. You can also create a Typescript configuration file with settings that work for you.

Run the following command to install base Typescript configurations for node version 20.

npm i -D @tsconfig/node20

Create a tsconfig.json file and paste the following configs.

{
  "extends": "@tsconfig/node20/tsconfig.json",
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Node 20",
  "_version": "20.1.0",

  "compilerOptions": {
    "lib": ["es2023"],
    "module": "node16",
    "target": "es2022",

    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node16",
    "outDir": "./build",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"]
}

4. Install Jest and related dependencies.

We are now ready to write Typescript code. In this step, we will install Jest and all the necessary dependencies related to it.

Run the following command to install Jest and the other dependencies.

npm i -D jest ts-jest @types/jest @jest/globals

We need ts-jest to compile Typescript for Jest and @jest/globals to provide Jest global global utilities for typescript.

5. Configure Jest for Typescript

Here, we tell Jest to execute .ts files with ts-jest. To complete this configuration, we will generate a Jest configuration file with ts-jest presets using the following command.

npx ts-jest config:init

Executing the above command generates a jest.config.js file with ts-jest as a preset.

Well done, let us edit our npm test scripts in the next step.

6. Edit `package.json` test script.

We want to be able to run tests easily by using a simple npm command. To enable the command, edit the scripts object of package.json as follows:

 "scripts": {
    "test": "jest --watch",
}

The setting above allows us to run tests using the npm test command. The --watch flag tells Jest to run tests every time our code changes.

Next, we proceed to the actual testing to find and verify our configurations.

7. Try it out.

Up to this point, we have installed all the required dependencies for testing Typescript with Jest. Here, we will write a simple function and test it to verify that our configurations are on point.

Create an index.ts file and export a simple function that you want to test. Do not finish the implementation of the function until you write a failing test.

For example: A sum function,

export const sum(num1: number, num2: number): number =>{

}

Create index.test.ts and import sum.

index.test.ts

import {sum} from `index`

Import Jest globals.

index.test.ts

import {sum} from `index`
import { describe, test, expect } from "@jest/globals"

Write test.

index.test.ts

import {sum} from `index`
import { describe, test, expect } from "@jest/globals"

describe('Sum function', () =>{
    test('Returns correct value', () =>{
        expect(sum(2, 3)).toEqual(5)
    })
})

Run the following command to begin your tests:

npm test

Edit your sum function until your test passes.

Congratulations! That's the end of configuring Jest for Typescript unit tests. We have created a working test environment for testing Typescript code using Jest and ts-jest. The resultant directory is available on this GitHub repository. If you are interested in learning other ways of testing typescript code with Jest, feel free to visit the document on using Jest with typescript.

Hashing and Verifying Passwords in Mongoose Schema

Felix Owino — Thu, 16 Nov 2023 09:22:25 +0000

Are you creating a web application that is going to require users to sign in with passwords? It's a good security measure to store passwords in the database as hashed strings instead of plain strings. Hashing passwords is done to protect users' passwords. In case an attacker gains access to your database, they will see the hashed passwords but they won't be able to use them.

In this article, we will learn how to create a user schema that hashes users' passwords before saving them to the database. We will also learn how to add an instance method to the schema that verifies user passwords during login.

We will not cover other surrounding topics such as user authentication and user registration middleware in this article. The main goal of this article is to show you how to create a self-contained schema. This schema will make it easy for you to implement user registration and authentication middleware without worrying about password hashing.

We will use Typescript in this article. This article does not go into depth about how to create models and schema with Mongoose and Typescript. Therefore, this article assumes that you know how to create Mongoose schema using Typescript. If you are new to using Typescript, visit this article on creating Mongoose schema with Typescript before continuing.

Before we dive into coding, let us list out the procedure we are going to follow.

Initialize a working directory and configure Typescript.
Create the user schema.
Implement password hashing.
Implement password Verification.

Let us start by creating a working directory.

1. Initializing working directory and configure Typescript.

In this step, we will clone a pre-configured working directory from GitHub. You can also create your own directory with configurations of your choice. If you need help, see how to set up an initial project directory for Node and Typescript.

Your working directory should have something looking like this.

After successfully cloning the repository, install its dependencies using the following command:



npm install

With the working directory set up, let us create the user schema.

2. Creating the user schema.

To create a Mongoose schema, we need to install mongoose and import it to our models file.

Install mongoose using the following command:



npm install mongoose

Create the User.model.ts file in the src directory of your project and import Mongoose.



import mongoose from "mongoose"

Create an interface for the raw document as created in the code snippet below.



interface IUser{
    first_name: string,
    last_name: string,
    password: string,
    username: string
}

Create the user schema that implements the interface as created in the code snippet below.



const userSchema = new mongoose.Schema<IUser>({
    first_name: String,
    last_name: String,
    password: String,
    username: String
})

Now we have successfully created a user schema, let's add password hashing logic in step 3.

3. Implement password hashing.

In the last step, we implemented a simple user schema. Here, we will add a functionality that will hash every password entered by the user before saving.

To add a logic that is executed before saving a document, we use the pre hook of the Mongoose Schema.

We will use the bcrypt module to hash user passwords. Install the bcrypt module and its types using the following commands.



npm install bcrypt
npm install -D @types/bcrypt

Import the hash function from bcrypt as follows.



import { hash } from 'bcrypt'

The following code snippet shows how the password hashing on save can be implemented on the schema.




userSchema.pre('save', async function(next){

    const hashedPassword =  await hash(this.password, 10)
    this.password = hashedPassword

    next()
})

The above code snippet does the following:

Convert the raw password into a hash string.
Replace the original raw password with the hashed password.
Call the next callback function. The callback signals Mongoose that we are done hashing the password and it can now be saved to the database.

It is important not to assume the pre save hook to work across every database operation. The pre save hook only encrypts the password on the initial creation. The pre save hook is not invoked by any other database operation that does not call the save method. This means that an update operation will not invoke the password encryption function at all. If you want to change your password, you have to encrypt it in a separate program otherwise it will be stored in the database as plain text.

At this point, we are done with the password hashing functionality. Let us add an instance method to verify passwords in the next step.

4. Implement password verification.

In the previous section, we added password hashing to our schema. In this section, we will add a password verification method to the user schema.

Before adding the method to the schema, we need to create an interface for instance methods. The following code snippet shows the declaration of the interface with the signature for the verification function.



interface UserMethods{
    isValidPassword:(password: string) => Promise<boolean>
}

Next, we need to add the interface to the Schema constructor and Model type as follows.



type UserModel = Model<IUser,{}, UserMethods>

const userSchema = new mongoose.Schema<IUser, UserModel, UserMethods>({
    first_name: String,
    last_name: String,
    password: String,
    username: String
})

Finally, we implement the isValidPassword method as follows:

Import the compare function and implement the method.



import { compare } from 'bcrypt'



userSchema.method('isValidPassword', async function(
    password: string): Promise<boolean>{
    const isValid = await compare(password, this.password)
    return isValid
})

The isValidPassword method will be accessible through the user document. In the implementation of authentication, the method isValidPassword can be called on the user document. The method returns a promise. The promise resolves to true or false depending on whether the user entered the correct password or not.

Export the model as follows.



export const User = model<IUser, UserModel>('User', userSchema)

Conclusion

Finally, we have learned how to create a self-contained user schema. The schema can convert a password into a hash string before saving it to the database. The schema can also verify user passwords against the stored hashed passwords during authentication. Visit this article to learn more about creating Mongoose models with Typescript.

Forem: Felix Owino

Writing meaningful Git commit messages with semantic tags

The Semantic tag.

1. The feat tag

2. The refactor tag

3. The fix tag.

4. The breaking tag

5. The test tag

6. The chore tag

7. The revert tag

8. The docs tag

9. The style tag

Handling Bad JSON Input Error in Express app

Creating A Carousel with Vanilla JS

1. Structuring the Carousel

2. Styling the Carousel

3. Getting the Carousel in Motion

3.1 Viewing the next Image.

3.2 Viewing the previous Image.

3.3 How The Translation Works

3.4 Automating the rotation.

4 Adding Indicators

Implementing File Input By Copy-Paste on the Web

The HTML and the Styles

The Script

Getting the file from the pasted items

Previewing the uploaded file

Implementing Drag-Drop for File Input on the Web.

1. Create the HTML Markup

2. Style the Markup

3. Make it interactive

The drop zone container

4. Style the interaction

5. Make it clickable

Summary

Preview Your Images Instantly Before Uploading.

Writing the Markup code

Selecting the file

Displaying the Preview

Preventing multiple image renders.

Understanding React States for Proper State Management.

1. Foundational Understanding of React State.

2. The difference between props and states.

3.) Immutability in React states and why is it important to keep states immutable.

a) Problems associated with mutating states.

b) How to maintain immutability when updating states.

c) Using the spread operator.

Conclusion

How to set and customize horizontal and vertical scrollbars with CSS

1. Setting up a custom vertical scrollbar

a). Create a navigation bar with navigation items

b). Style the navigation bar into a sidebar.

c). Set the sidebar position to fixed.

d). Managing content overflow using a scrollbar

More about the overflow-y property.

2. Setting a custom horizontal Scrollbar.

3. Customizing scrollbar styles

a). Styling a specific scrollbar.

Styling vertical scrollbar (sidebar scroll)

Styling the horizontal scrollbar (flexbox scrollbar)

b). Styling the default scrollbar

c). Styling all scrollbars at once.

Conclusion

How to Populate Database with Test Data.

1. Create data model

2. Fetch data

3. Connect to the database.

4. Populate the database with documents.

Testing Express API Routes the Easy Way: Beginners' guide.

What will this article cover?

What does the article expect you to already know?

What technologies are we going to use?

What should you expect to learn from this article?

How are we going to learn?

1. Configure a test environment.

2. Create a simple Express API.

3. Modularize your application for easy testing.

a). Modularize router handlers

b). Modularize routes

c). Refactor the main file

1. The `feat` tag

2. The `refactor` tag

3. The `fix` tag.

4. The `breaking` tag

5. The `test` tag

6. The `chore` tag

7. The `revert` tag

8. The `docs` tag

9. The `style` tag

More about the `overflow-y` property.

6. Edit `package.json` test script.