This document relates to all files within the src directory, excluding those covered in Backend and Authentication. Please see those sections before reading this one, as some of the concepts discussed are used here.

The Ant Design UI library was used for some pre-made components.

This section relates to the files within src/services.

These files contain functions for communicating with the backend. These functions perform HTTP requests, add the correct headers, handle errors, and create notifications. Some functions are wrapped in a React Hook for single fetches, like fetching profile data. Some functions are wrapped in a React Context to make data accessible to all components, like the list of all keywords.

The src/services/notifications/notifications.ts file contains a thin wrapper for Ant Design Messages. These are used to notify the user of loading, success, and errors.

Here's an example of the function to register an account:

src/services/register-account.ts

import type {
  RegisterAccountParams,
  RegisterAccountRes,
} from "../pages/api/register-account";
import ApiRoutes from "../routing/api-routes";
import { en } from "./context/language-ctx";
import getAuthHeader from "./headers/auth-header";
import { contentTypeJsonHeader } from "./headers/content-type-headers";
import Notification from "./notifications/notification";

export default async function registerAccount(
  params: RegisterAccountParams
): Promise<RegisterAccountRes | null> {
  const authHeader = await getAuthHeader();
  if (!authHeader) return null;

  const notification = new Notification();
  try {
    notification.loading(
      en ? "Registering Account..." : "Compte d'enregistrement..."
    );
    const res = await fetch(ApiRoutes.registerAccount, {
      method: "PUT",
      headers: { ...authHeader, ...contentTypeJsonHeader },
      body: JSON.stringify(params),
    });
    if (!res.ok) throw await res.text();
    notification.success();
    return await res.json();
  } catch (e: any) {
    notification.error(e);
    return null;
  }
}

This function does the following:

• Defines the correct parameter type and return type (imported from the backend file).
• Gets the authorization header containing the access token
• Displays a "registering account" notification
• Makes the HTTP request with the correct method, headers, and stringified body.
• Checks the return status of the request (res.ok means status is 200)
• If successful: displays a success notification and returns the result
• If not successful: displays an error notification and returns null (notification.error also logs the error to the console)

Here's an example of the hook to retrieve an account profile:

src/services/use-account.ts

import { useEffect, useState } from "react";
import ApiRoutes from "../routing/api-routes";
import getAuthHeader from "./headers/auth-header";
import type { AccountInfo } from "./_types";

export default function useAccount(id: number) {
  const [account, setAccount] = useState<AccountInfo | null>(null);
  const [loading, setLoading] = useState(true);

  async function fetchAccount(id: number) {
    try {
      const authHeader = await getAuthHeader();
      if (!authHeader) return;
      setLoading(true);
      const result = await fetch(ApiRoutes.account(id), {
        headers: authHeader,
      });
      if (!result.ok) return console.error(await result.text());
      const account = await result.json();
      setAccount(account);
    } catch (e: any) {
      console.error(e);
    } finally {
      setLoading(false);
    }
  }

  useEffect(() => {
    fetchAccount(id);
  }, [id]);

  function refresh() {
    fetchAccount(id);
  }

  return { account, setAccount, loading, refresh };
}

The hook wraps a simple service function, but provides a state variable for React components to use, which will re-render the UI on change.

The hook also provides a mechanism to let components know if the data is loading.

It also provides a mechanism to overwrite the account in local memory, in the case we have updated the account using another service function, which returned the new value.

And finally it provides a function to re-fetch the account data.

The syntax for using the hook is just:

const { account, setAccount, loading, refresh } = useAccount(id);

You can see this hook being used in src/components/accounts/account-profile.tsx

React Contexts provide a way to easily cache data and share it between components. This is useful for immediately fetching tables that are not expected to change, such as the list of all faculties, and the list of all member types.

As this application was designed with a small database in mind, the list of all members, the list of all keywords, and the list of all accounts (if the user is an admin) are also fetched and cached on application load, to make the experience faster for the user.

A context is also responsible for managing the current user, as discussed in Authentication.

There is also a context that manages the user's preferred language, and stores the value in local storage to ensure it remains the same across sessions. src/services/context/language-ctx.tsx

Finally there is a context that manages if the user has unsaved changes, and prevents navigation with a save changes prompt. src/services/context/save-changes-ctx.tsx

Here's the context that fetches the list of faculties src/services/context/faculties-ctx.tsx:

First we create the simple service function, no need for loading or success notifications since this will be happening in the background:

async function fetchAllFaculties(): Promise<faculty[]> {
  try {
    const res = await fetch(ApiRoutes.allFaculties);
    if (!res.ok) throw await res.text();
    return await res.json();
  } catch (e: any) {
    new Notification().error(e);
    return [];
  }
}

Then we create a context that defines what data and functions are exposed:

export const FacultiesCtx = createContext<{
  faculties: faculty[];
  refresh: () => void;
}>(null as any);

You can provide a default value instad of null, but there's not much point as the default value should never be accessible.

Then we create a provider, which is a React component that will manage the context and provide it to all of it's children.

export const FacultiesCtxProvider: FC<PropsWithChildren> = ({ children }) => {
  const [faculties, setFaculties] = useState<faculty[]>([]);
  const { en } = useContext(LanguageCtx);

  async function getFaculties() {
    setFaculties((await fetchAllFaculties()).sort(en ? enSorter : frSorter));
  }

  useEffect(() => {
    getFaculties();
  }, []);

  useEffect(() => {
    setFaculties((prev) => [...prev].sort(en ? enSorter : frSorter));
  }, [en]);

  function refresh() {
    getFaculties();
  }

  return <FacultiesCtx.Provider value={{ faculties, refresh }}>{children}</FacultiesCtx.Provider>;
};

To integrate the context into the application, we simply wrap the entire app in this component. But since there are quite a few contexts, we bundle them into a single component in src/services/context/_ctx-bundler.tsx

const AllContextProviders: FC<PropsWithChildren> = [
  ActiveAccountCtxProvider,
  LanguageCtxProvider,
  MemberTypesCtxProvider,
  FacultiesCtxProvider,
  SaveChangesCtxProvider,
  AllKeywordsCtxProvider,
  AllAccountsCtxProvider,
  AllMembersCtxProvider,
].reduceRight((Accumulator, Parent) => {
  const Provider: FC<PropsWithChildren> = ({ children }) => (
    <Parent>
      <Accumulator>{children}</Accumulator>
    </Parent>
  );
  return Provider;
});

export default AllContextProviders;

Now we just need to wrap the entire app with AllContextProviders, which is done in src/pages/_app.tsx, the file that renders Next.js pages.

<AllContextProviders>
  <Navbar />
  <div className="next-page-container">
    <Component {...pageProps} />
  </div>
</AllContextProviders>

Now any component can access a context with the following syntax:

const { faculties } = useContext(FacultiesCtx);

Next.js Pages are how Next.js handles routing.

Routes are generated based on the file names within src/pages. For example, pages/register.tsx generates a route at <domain root>/register.

The file name index will resolve to the path of the parent directory. For example, pages/members/index.tsx generates a route at <domain root>/members

You can also include parameters in routes with square brackets. For example pages/members/[id]/public will generate a route that accepts any string in place of [id], such as <domain root>/members/123/public.

Each of these files should have a React component as their default export. When a user travels to one of these routes, that component gets rendered.

Its best not to have too much logic in these files, and just use this directory to render a single component from src/components. Routing paths can be subject to change, and you don't want to be moving around a lot of code when that happens.

For example, here's the file for a member's public profile:

src/pages/members/[id]/public.tsx

import { useRouter } from "next/router";
import type { NextPage } from "next/types";
import PublicMemberProfile from "../../../components/members/member-public-profile";

const PublicMemberPage: NextPage = () => {
  const router = useRouter();
  const { id } = router.query;
  if (!(typeof id === "string")) return null;
  return <PublicMemberProfile id={parseInt(id)} />;
};

export default PublicMemberPage;

All we're doing is parsing the route parameter and rendering another component, passing the id through.

To avoid hardcoded strings during navigation, routes for every page are stored in src/routing/page-routes.ts.

Navigation can be performed using the Next.js Router

router.push(PageRoutes.accountProfile(id));

Although the backend is protected against unauthorized requests, we'd prefer if unauthorized requests didn't happen at all.

If a user tries to navigate to a route that is not meant for them to see, we should not load the page, and instead redirect the user or display a message.

This application handles that case with a PageAuthGuard component.

There are 4 types of authorizations defined:

src/components/auth-guard/authorizations.ts

enum Authorizations {
  admin = "admin", // admins only
  registered = "registered", // any registered account
  matchAccountId = "match account id", // must have matching account id to a route
  matchMemberId = "match member id", // must have matching member id to a route
}

The component just takes what authorizations are required, and decides whether or not to render its children based on the current active user. If the user is not authorized it will display a message.

src/components/auth-guard/page-auth-guard.tsx

type Props = {
  auths: Authorizations[],
  id?: number,
  loadingIcon?: ReactElement,
};

const PageAuthGuard: FC<PropsWithChildren<Props>> = ({
  auths,
  id,
  loadingIcon,
  children,
}) => {
  const { localAccount, loading } = useContext(ActiveAccountCtx);
  const { en } = useContext(LanguageCtx);

  if (loading) return loadingIcon || <CenteredSpinner />;

  const notAuthorized = (
    <h1 style={{ textAlign: "center" }}>
      {en
        ? "You are not authorized to view this page."
        : "Vous n'êtes pas autorisé à afficher cette page."}
    </h1>
  );

  const c = <>{children}</>;

  if (!localAccount) return notAuthorized;
  if (auths.includes(Authorizations.registered)) return c;
  if (auths.includes(Authorizations.admin) && localAccount.is_admin) return c;
  if (auths.includes(Authorizations.matchAccountId) && localAccount.id === id)
    return c;
  if (!localAccount.member) return notAuthorized;
  if (
    auths.includes(Authorizations.matchMemberId) &&
    localAccount.member.id === id
  )
    return c;
  return notAuthorized;
};

Here's an example of using it to stop an unauthorized user from attempting to load the accounts interface:

src/pages/accounts/index.tsx

const AccountsPage: NextPage = () => {
  return (
    <PageAuthGuard
      auths={[Authorizations.admin]}
      loadingIcon={<Table loading></Table>}
    >
      <AllAccounts />
    </PageAuthGuard>
  );
};

React Components are what make up the user interface. All of the components in this application are Function Components, as opposed to Class Components.

These UI components are located in src/components.

Here is a list of each component and it's description:

These are Custom Ant Design Form Controls

These are helpers functions that return a list of member names

Users can navigate to the Events tab to initiate the exploration process. Here, an array of events awaits, as depicted in the illustrative figure below:

Upon spotting an event of interest, users can click on it to gain a summary view of the event. In the example below, Event 1 has been selected, leading to a dedicated page that presents a concise summary of the chosen event:

Under the summarized table mentioned above, a button placed and labeled "Journey of Event". Clicking this button provides a hierarchical view specific to the chosen event. The visualization below illustrates this feature:

In our development, we have categorized an event into two parts:

1. Event Summary Expansion( ) ;
2. Next Event Expansion( )

In the event summary (), it displays the title of the event, type of event, start date and number of next event/s. Once a user expands, the user can see a detailed view of the member involved, grant, partner involved, and any product has resulted such as book, paper etc.

Once the user clicks on the ( ), it will display the event's child event, if any.

To achiche the abouve pages, a journey folder was created at /src/pages/joe, followed by previous development. Following is the code in this folder:

import { useRouter } from "next/router";
import type { NextPage } from "next/types";
import { useContext, useEffect } from "react";
import { ActiveAccountCtx } from "../../../services/context/active-account-ctx";
import CardSkeleton from "../../../components/loading/card-skeleton";
import PageRoutes from "../../../routing/page-routes";

const PrivatejoePage: NextPage = () => {
  const router = useRouter();
  const { localAccount, loading } = useContext(ActiveAccountCtx);
  const { id: idString } = router.query;

  useEffect(() => {
    if (!(typeof idString === "string")) {
      return;
    }
    if (loading) return;

    const id = parseInt(idString);

    if (localAccount?.is_admin) {
      router.replace(PageRoutes.privateEventProfile(id));
      return;
    } else {
      router.replace(PageRoutes.publicEventProfile(id));
    }
  }, [localAccount, loading, idString, router]);

  return <CardSkeleton />;
};

export default PrivatejoePage;

To route these page above, it has been added to our routing page at src/routing/page-routes.ts as joe: (id: number) => "/joe/" + id + "/private"

This application using SCSS which is a superset of CSS, so all vanilla CSS is still valid.

All SCSS files are located in src/styles.

Only src/styles/_globals.scss is imported into the application (in src/pages/_app.tsx. So when creating a new stylesheet just import it into _globals.scss.

If just doing a small amount of styling somewhere specific, you can always use React inline styling instead.