References Section in JavaScript with Next.js

For this article you'll probably need some HTML, JavaScript and/or CSS knowledge, but if you don't have any you should still be able to follow along.

Specification

If we wanted to write this as a ticket (and I usually do to make sure I know what I'm doing) we would need to write a specification. Nothing too technical on 'how' to do this, but we do need to be specific on 'what' we want, something like:

Setup

There are several ways to set this up, but the 2 main ones are:

• A helper
• A component

If we create a helper, we could use the code on any JS project, but if we have any CSS or HTML, we'll need to create that using JS only, which is a little restrictive. We would also need to attach our section to an ID or class that we would need to pass in to make sure the section is in the correct place, not a major issue, but can become difficult to understand the architecture of the project as it gets larger doing things in this way.

If we use a Next.js component, we are restricted to Next.js, even though the script can be used on any website JavaScript. We can add CSS and HTML as needed and separate out. We can add a component to other components where we need to, and the architecture is simple as the component is always used in the place it is called.

A component makes more sense in this situation so we'll go with that. Let's start:

1. Open any Next.js project (or create one like this Next.js Project Creator)
2. Create a folder caller ‘references’ within the ‘components’ folder
3. Create a file called ‘References.js’ in the references folder

NB. Watch your cases, camel case (starts lower case then each word starts upper case) for folders and functions, pascal case (start upper case then each word starts upper case) for files and components.

Also note I'm using .js not .ts for the file name, I’m using good old JavaScript not TypeScript here.

4. Add the code in the references.js file

   export function References(){
       return <h4>References</h4>
   }

5. In your app/page.js add in the references import at the top like 
   import {References} from "../references/References";
   and the <References /> component at the bottom (above a footer if you have one)

If you load up your app in the browser, you will see the page and at the bottom you’ll see a title ‘References’ in <h4>.

Content

To create a ‘References’ section we’ll need content with some links. We’ll need at least 2 links within the body text, and at least 1 link should duplicate at least once. We’ll also need links out of the site and links to pages internal to the site. This should allow us to test our code correctly.

If you have this setup already, move on to the coding section, if not, let’s create that.

1. Create 2 files in your app folder, 1 called test1.js and the called test2.js

2. In each file add the code (change the function/component name to Test2 for test2.js)

   export default function Test1(){
       return <h1>Test 1</h1>
   }

3. Go to the Lorem ipsum generator and hit the Generate Lorem Ipsum button at the bottom

4. Copy the first 4 paragraphs and paste them into your test 1 and test 2 pages making sure they are wrapped in <p> and the whole return is wrapped in a <div> so something like:

   export default function Test2(){
       return (
           <div>
               <h1>Test 2</h1>
               <p>Lorem ipsum dolor sit amet, consectetur adipiscing...</p>
           </div>
       );
   }

5. Add in a few links to Google and HuytonWeb.com, plus a few links to from test 1 to test 2 and vice-versa like:
   <Link href={'https://www.huytonweb.com/'}>Huyton Web Services</Link>
<Link href={'/test1'}>Test 1</Link> 
6. Add the references component into test 1 and test 2 pages so when we go to the test pages we see the title at the bottom.

Coding

Add in a div with a class name article around your test content, we will use this to select the links later. Also, add in the selector to the References in the test page so the page will look something like:

export default function Test2(){
    return (
        </>
            <div className={'article'}>
                <h1>Test 2</h1>
                <p>Lorem ipsum dolor sit amet, consectetur adipiscing...</p>
            </div>
            <References selector={'.article'} />
        </>
    );
}

Selector

Back in our references.js we need to get all the links in the page, but we want to protect against any recursion and allow a coder to have a link that does not go in the references e.g. an image to a larger image. To do this we’ll add a :not to our selector. We can console log this to make sure we’re picking up the links correctly.

We also want to make sure we only add links inside our selector, in this case .article. Let’s also give the component a default selector, the HTML element <article> is useful here.

If we run this, we’ll see an error telling us "document is undefined". This is because Next.js will render the page on the server where there is no DOM, so no document. We need to force the render on the client only (we could install plugins to allow document on the server, but this is unnecessary), to do this we simply add react useEffect.

Our reference.js now looks like:

import {useEffect} from "react";
export function References({ selector='article' }){
    useEffect(() => {
        const linkNodes = document.querySelectorAll(selector + ' a:not(.doNotReference)');
        console.log(linkNodes);
    });
    return <h4>References</h4>
}

If we check the console (F12 then the console tab) we can see our NodeList containing our nodes correctly.

HTML

We need to return these nodes to the page as links so we'll add in some test HTML to make sure it will work as we expect. Under the title, as the ticket specifies, add an <ol> and some <li> elements to make a numbered list then a test link (we'll need an import to the link) to the home page.

import Link from "next/link";
export function References({ selector='article' }){
    const linkNodes = document.querySelectorAll(selector + ' a:not(.doNotReference)');
    console.log(linkNodes);
    return (<>
        <div className="references">
            <h4>References</h4>
            <ol>
                <li>
                    <Link className={'reference doNotReference'} href={`/`}>Test link</Link>
                </li>
            </ol>
        </div>
    </>);
}

If we check this in the browser we will see the Reference section correctly.

NodeList to array

When we run our page and check the console, we can see our linkNodes is not an array, it’s a NodeList. We need an array so we can map it and do our sorting and filtering. While we are at it, we can map through and remove the useless bits from the nodes and keep only the url and title. Lastly, we can remove any nulls and we can use that later to filter links we don't want.

It’ll look like this:

…
let linkElementsArr = Array
    .from(linkNodes)
    .map(element => {
        return {url: element.href, title: element.innerHTML};
    })
    .filter(Boolean); // Remove the nulls
…

If you run it, you’ll get a lovely array. 

Filter

We need to remove the home page links, any HTML links like images and any links that have no title. Create a const with your main domain (I usually have this as an env var, but we'll add it here for completeness) like :

...
const mainDomain = 'localhost:3000';
...

Inside our .map above the return, null any links we don’t want with:

…
if (
    element.href === '/' ||
    (element.href.includes(mainDomain) && element.href.includes('#')) ||
    element.href === mainDomain ||
    element.href === mainDomain + '/' ||
    element.innerHTML !== element.innerText ||
    element.innerText === ''
)
    return null;
…

This will null 

• Home page links
• Internal links to places on pages
• Links where the HTML doesn't match the text i.e. links around HTML 
• Empty links

Prettify our titles

Our link titles should look like a titles, so let’s add in a function to capitalise words and run that on the element.innerHTML (I usuall make this function into a helper, but we can include it here to make things simple). Our function will be something like:

…
function capitaliseWords(sentence){
    const words = sentence.split(" ");
    for (let i = 0; i < words.length; i++) {
        words[i] = words[i].charAt(0).toUpperCase() + words[i].slice(1);
    }
    return words.join(" ");
} 
…

Duplicates

To remove any duplicates, add in a new empty array called seenArr above our linkElementsArr. We’ll add any links to this we’ve seen as we go through, then check against it to check for duplicates. Inside our map under our home link check we add the duplicate check so if the link is in the seen array we simply null it so when we run our filter for nulls it won't add it:

…
if(seenArr.includes(element.href))
    return null;
…

Add the URL to the seenArr so when we loop back around we can check for it.

…
seenArr.push(element.href);
…

Alphabetical order

We need another function (I usually add as a helper function and make it more functional, but we can add this to the top of the component) before the capitaliseWords function, add sortDataBy function:

…
function sortDataBy (data = [], key = ''){
    return data.sort(function(a,b){
        let x = a[key].toLowerCase();
        let y = b[key].toLowerCase();
        if(x>y){return 1;}
        if(x<y){return -1;}
        return 0;
    });
}
…

Code check

Your code should look like this:

import {useEffect} from "react";
import Link from "next/link";
const mainDomain = 'localhost:3000';
function capitaliseWords(sentence){
    const words = sentence.split(" ");
    for (let i = 0; i < words.length; i++) {
        words[i] = words[i].charAt(0).toUpperCase() + words[i].slice(1);
    }
    return words.join(" ");
}
function sortDataBy (data = [], key = ''){
    return data.sort(function(a,b){
        let x = a[key].toLowerCase();
        let y = b[key].toLowerCase();
        if(x>y){return 1;}
        if(x<y){return -1;}
        return 0;
    });
}
export function References({ selector='article' }){
    useEffect(() => {
        const linkNodes = document.querySelectorAll(selector + ' a:not(.doNotReference)');
        let seenArr = [];
        let linkElementsArr = Array
           .from(linkNodes)
           .map(element => {
           
                // Any home links should be returned null
                if (
                   element.href === '/' ||
                    element.href.includes(mainDomain) ||
                    element.innerHTML !== element.innerText ||
                    element.innerText === ''
                )
                   return null;
                   
                // We've already seen the URL
                if(seenArr.includes(element.href))
                   return null;
                   
                // Add this URL to the seen array
                seenArr.push(element.href);
                
                return {url: element.href, title: capitaliseWords(element.innerHTML) };
            })
           .filter(Boolean); // Remove the nulls
       linkElementsArr = sortDataBy(linkElementsArr, 'title');
       
       console.log(linkElementsArr);
    });
    
    return (<>
        <div className="references">
            <h4>References</h4>
            <ol>
                <li>
                    <Link className={'reference doNotReference'} href={`/`}>Test link</Link>
                </li>
            </ol>
        </div>
    </>);
} 

When you run this, you will see the links in the console with no duplicates, no HTML or image links and no links to the home page and everything will be in alphabetical order with titles looking pretty. If this isn’t the case, have a look at the code and see if you or I have missed anything. If you have, change make the change, if I have then let me know with a comment.

Adding the links to the HTML

We need to take our array and map it to create the list of links for our references, but this is where we start to see issues from Next and React.

Let’s swap our test link for an array map and see what happens:

…
<ol>
    {linkElementsArr.map((element, i) => (
        <li key={i}>
            {
                <Link className={'reference doNotReference'} href={element.url}>{element.title}</Link>
            }
        </li>
    ))}
</ol>
…

We should get a error and find anything inside the useEffect hook is not defined at render time, so we have no access to the array at this point. To fix this we can use state (there are other ways to fix this, but state is the correct way and will cause the least bugs). At the top of the component function just above the useEffect add:

…
export function References({ selector='article' }){
    const [currentReferences, setCurrentReferences] = useState(null);
    
    useEffect(() => {
…

After our linkElementsArr map, we can check if we have any links left in the array, and if we do sort the array and set our state:

…
if (linkElementsArr.length !== 0 ) {
    linkElementsArr = sortDataBy(linkElementsArr, 'title');
    setCurrentReferences(linkElementsArr);
}
…

Now, instead of mapping our array directly we can map the saved state with:

…
currentReferences.map((element, i)
…

We also need to check if there are any current references before we try to render so if there are no references we don't render the section at all. To our return we add a check:

…
return (<>
    {currentReferences &&
…
    }
</>);
…

There are 2 issues here, the first is the references will try to infinitely render and the second is if we go to another page, it will add the references from that page to the list and render the whole thing. 

The first issue 'infinitely loading' is because of the way useEffect works, we haven’t specified a dependency telling it when to render, so it will render over and over. 

We also want the array to reset on each change of the page, not add more to a list we already have.

Both of these can be fixed with by adding dependencies of router.path and our selector to our useEffect.

Add an import for useRouter at the top with our other imports:

import {useEffect, useState} from "react";
import Link from "next/link";
import {useRouter} from "next/router"; 
…

Under our component function declaration add the variable to use the router:

…
const router = useRouter();
…

At the end of the useEffect change }); to }, [router.asPath, selector]);

Target and No Referrer

If we look at the ticket we need to check if the link is internal to the site, if not add the target="_blank" and refs. We should also add a title so to our consts under the References function declaration add:

…
const router = useRouter();
const externalTitle = " link will open a new tab and take you off site";
…

We need to add our check to our HTML array map and render a different link depending on external or internal link. Change our <li>s to:

<li key={i}>
    {
        element?.url?.includes(mainDomain) ?
            <Link className={'reference doNotReference'} href={element.url}>{element.title}</Link>
        :
            <Link
                href={element.url}
                className="externalLink reference doNotReference"
                target="_blank"
                title={element.title + externalTitle }
                rel={"noopener noreferrer nofollow"}
            >{element.title}</Link>
    }
</li>

N.B. I'm checking for the main domain because my CMS creates all internal links with the full domain, but you could add other checks like '/' at the beginning. 

That’s it for the code, but we still have 1 more part of the specification to fulfil, the CSS.

Styling

Create a file next to out reference.js and call it References.module.css. At the top of the References.js add a new import:

...
import styles from "./References.module.css";
...

To use any styles in our CSS module instead of the global CSS we change our return HTML class from <div className="references"> to <div className={styles.references}>. We can create any styles for references with the class references in the module now. Let’s give our References a bit of space and an outline with:

.references{
    border-top: 2px solid #000000;
    margin-top: 60px;
    padding-top: 10px;
}

Since we don’t have the brand for our pages, we can’t really do much more than this, but feel free to come up with your own look. 

Full code

See the Huyton Web Services References Github repository for the full up-to-date code.

References.js

import {useEffect, useState} from "react";
import Link from "next/link";
import {useRouter} from "next/router";
import styles from "./References.module.css";
const mainDomain = 'localhost:3000';
function capitaliseWords(sentence){
   const words = sentence.split(" ");
   for (let i = 0; i < words.length; i++) {
       words[i] = words[i].charAt(0).toUpperCase() + words[i].slice(1);
   }
   return words.join(" ");
}
function sortDataBy (data = [], key = ''){
   return data.sort(function(a,b){
       let x = a[key].toLowerCase();
       let y = b[key].toLowerCase();
       if(x>y){return 1;}
       if(x<y){return -1;}
       return 0;
   });
}
export function References({ selector='article' }){
   const [currentReferences, setCurrentReferences] = useState(null);
   const router = useRouter();
   const externalTitle = " link will open a new tab and take you off site";
   useEffect(() => {
       const linkNodes = document.querySelectorAll(selector + ' a:not(.doNotReference)');
       let seenArr = [];
       let linkElementsArr = Array
           .from(linkNodes)
           .map(element => {
               // Any home links should be returned null
               if (
                   element.href === '/' ||
                   element.href.includes(mainDomain) ||
                   element.innerHTML !== element.innerText ||
                   element.innerText === ''
               )
                   return null;
               // We've already seen the URL
               if(seenArr.includes(element.href))
                   return null;
               // Add this URL to the seen array
               seenArr.push(element.href);
               // Return the array
               return {url: element.href, title: capitaliseWords(element.innerHTML)};
           })
           .filter(Boolean); // Remove the nulls
       if (linkElementsArr.length !== 0) {
           linkElementsArr = sortDataBy(linkElementsArr, 'title');
           setCurrentReferences(linkElementsArr);
       }
   }, [router.asPath]);
   return (<>
       {currentReferences &&
       <div className={styles.references}>
           <h4>References</h4>
           <ol>
               {currentReferences.map((element, i) => (
                   <li key={i}>
                       {
                           element?.url?.includes(mainDomain) ?
                               <Link className={'reference doNotReference'} href={element.url}>{element.title}</Link>
                               :
                               <Link
                                   href={element.url}
                                   className="externalLink reference doNotReference"
                                   target="_blank"
                                   title={element.title + externalTitle }
                                   rel={"noopener noreferrer nofollow"}
                               >{element.title}</Link>
                       }
                   </li>
               ))}
           </ol>
       </div>
       }
   </>);
}

References.module.css

.references{
   border-top: 2px solid #000000;
   margin-top: 60px;
   padding-top: 10px;
}

Summary

This simple React/Next.js took much more to explain than I first envisaged, but does show how much work goes into each and every component we create. In this tutorial we went over creating a ticket, setting up a component, adding the content to an app, how to pull in a list of links, the difference between an array and a nodeList, how to correctly create a link if it points to a page outside the site and much more.

For the full code see the Huyton Web Services References Github repository if you simply want to add it to your project.

As usual, if I've missed anything or if you know of a better way to do this please comment or contact us. Let us know if you've used this and how you did it or if you had any issues. Cheers