Documentation

Getting Started

Diamond is an application template for React based on the popular Next.js framework with new App Router. Current versions are Next v13, React v18, Typescript with PrimeReact v10.

To get started, extract the contents of the zip file, cd to the directory and install the dependencies with npm or yarn.

"npm install" or "yarn"

Next step is running the application using the start script and navigate to http://localhost:3000/ to view the application. That is it, you may now start with the development of your application using the Diamond template.

"npm run dev" or "yarn dev"
Dependencies

Dependencies of Diamond are listed below and needs to be defined at package.json.

"primereact": "^9.6.2",                    //required: PrimeReact components
"primeicons": "^6.0.1",                    //required: Icons
"primeflex": "^3.3.0",                     //required: Utility CSS classes
Structure

Diamond consists of a couple folders, demos and core has been separated so that you can easily remove what is not necessary for your application.

There are two route groups under the app folder; (main) represents the pages that reside in the main dashboard layout whereas (full-page) groups the pages with full page content such as landing page or a login page.

  • layout: Main layout files, needs to be present
  • demo: Contains demo related utilities and helpers
  • app: Demo pages
  • public/demo: Assets used in demos
  • public/layout: Assets used in layout such as logo
  • styles/demo: CSS files only used in demos
  • styles/layout: SCSS files of the core layout
Route Groups

Root Layout is the main of the application and it is defined at app/layout.tsx file. It contains the style imports and layout context provider.

"use client"
import { LayoutProvider } from "../layout/context/layoutcontext";
import { PrimeReactProvider } from "primereact/api";

import '../styles/layout/layout.scss';
...
import 'primereact/resources/primereact.css';
import '../styles/demo/Demos.scss';

interface RootLayoutProps {
  children: React.ReactNode;
}

export default function RootLayout({ children }: RootLayoutProps) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <link
          id="theme-link"
          href={`/theme/theme-light/blue/theme.css`}
          rel="stylesheet"
        ></link>
      </head>
      <body>
        <PrimeReactProvider>
            <LayoutProvider>{children}</LayoutProvider>
        </PrimeReactProvider>
      </body>
    </html>
  );
}

The pages that are using the main dashboard layout need to be defined under the app/(main)/ folder. Those pages use the app/(main)/layout.tsx as the root layout.

import { Metadata } from "next";
import Layout from '../../layout/layout';
interface MainLayoutProps {
    children: React.ReactNode;
}

export const metadata: Metadata = {
    title: "PrimeReact Diamond",
    ...
  };

export default function MainLayout({ children }: MainLayoutProps) {
    return <Layout>{children}</Layout>;
}

Only the full page content pages are required to be defined under the app/(full-page)/ folder since they are outside of the dashboard layout. Those pages use the app/(full-page)/layout.tsx as the root layout.

import { Metadata } from "next";
import AppConfig from '../../layout/AppConfig';
import React from 'react';

interface FullPageLayoutProps {
    children: React.ReactNode;
}

export const metadata: Metadata = {
    title: "PrimeReact Diamond",
    ...
};

export default function FullPageLayout({ children }: FullPageLayoutProps) {
    return (
        <React.Fragment>
            {children}
            <AppConfig minimal />
        </React.Fragment>
    );
}
Default Configuration

Initial layout configuration can be defined at the layout/context/layoutcontext.js file, this step is optional and only necessary when customizing the defaults.

"use client"
import React, { useState } from 'react';
import Head from 'next/head';

export const LayoutContext = React.createContext();

export const LayoutProvider = (props) => {
    const [breadcrumbs, setBreadcrumbs] = useState({});
    const [layoutConfig, setLayoutConfig] = useState({
        ripple: true,                      //toggles ripple on and off
        inputStyle: 'outlined',             //default style for input elements
        menuMode: 'static',                 //layout mode of the menu, valid values are "static", "overlay", "slim", "compact", "reveal", "drawer" and "horizontal"
        colorScheme: 'light',               //color scheme of the template, valid values are "light", "dim" and "dark"
        theme: 'blue',                      //default component theme for PrimeNG, see theme section for available values  
        menuTheme: "darkgray",              //theme of the menu, see menu theme section for available values  
        scale: 14                           //size of the body font size to scale the whole application
    });
}
Menu

Menu is a separate component defined in layout/AppMenu.js file. In order to define the menuitems, navigate to this file and define your own model as a nested structure.

import React from 'react';
import AppMenuitem from './AppMenuitem';
import { MenuProvider } from './context/menucontext';

const AppMenu = () => {
    const model = [
        {
            label: 'Dashboards',
            icon: 'pi pi-home',
            items: [
                {
                    label: 'E-Commerce',
                    icon: 'pi pi-fw pi-home',
                    to: '/'
                },
                {
                    label: 'Banking',
                    icon: 'pi pi-fw pi-image',
                    to: '/dashboard-banking'
                }
            ]
        },
            //...
        ];
}
Breadcrumb

The Breadcrumb component at the topbar section is dynamic and generates the current route information from the rendered menu items.

Theme

Diamond provides 30 PrimeReact themes out of the box. Setup of a theme is simple by including the CSS of the theme to your bundle that are located inside public/theme/folder such as public/theme/theme-light/blue/theme.css.

  • blue
  • cyan
  • deeppurple
  • green
  • indigo
  • lightgreen
  • orange
  • pink
  • purple
  • teal

A custom theme can be developed by the following steps.

  • Choose a custom theme name such as “mytheme“.
  • Create a folder named “mytheme“ under theme/theme-light/ folder.
  • Create a file such as theme.scss inside your “mytheme“ folder.
  • Define the variables listed below in your file and import the dependencies.
  • Include the theme.scss to your application.

Here are the variables required to create a theme.

$primaryColor: #3B82F6 !default;
$primaryLightColor: #BFDBFE !default;
$primaryDarkColor: #2563eb !default;
$primaryDarkerColor: #1D4ED8 !default;
$primaryTextColor: #ffffff !default;
$primary500:#3B82F6 !default;

$highlightBg: #EFF6FF !default;
$highlightTextColor: $primaryDarkerColor !default;

@import '../_variables';
@import '../../theme-base/_components';
@import '../_extensions';
Theme Switcher

Dynamic theming is built-in to the template and implemented by including the theme via a link tag instead of bundling the theme along with a configurator component to switch it. In order to switch your theme dynamically as well, it needs to be compiled to css. An example sass command to compile the css would be;

sass --update public/theme/mytheme/theme.scss:public/theme/mytheme/theme.css

*Note: The sass command above is supported by Dart Sass. Please use Dart Sass instead of Ruby Sass.

Menu Theme

Menu skin has 13 alternatives to choose from in light mode, note that in dark and dim modes menu theme is not applied by design. Possible values for the menu theme are the following.

  • blue
  • bluegray
  • brown
  • cyan
  • darkgray
  • deeppurple
  • green
  • indigo
  • orange
  • pink
  • purple
  • teal
  • white

A custom menu theme can be developed by steps below.

  • Choose a custom theme name such as ‘mymenu‘.
  • Create a file named ‘_mymenu.scss‘ under styles/layout/sidebar/themes folder.
  • Define the variables listed below in your file.
  • Import the file at styles/layout/layout.scss.
  • Configure the menutheme property at layoutservice with the name of your sidebar theme e.g. mymenu.

 .layout-sidebar-mymenu &#123;
    --d-sidebar-bg-color:#2196F3; 
    --d-sidebar-bg-color-alt:#1769aa;
    --d-sidebar-border:0 none;
    --d-app-name-color:#ffffff; 
    --d-menu-separator-border: 1px solid rgba(255,255,255,0.2);
    --d-menuitem-root-text-color: rgba(255,255,255,0.6);
    --d-menuitem-text-color: rgba(255,255,255,0.8);
    --d-menuitem-hover-bg: rgba(255,255,255,0.1);
    --d-menuitem-active-bg: rgba(255,255,255,0.1);
    --d-menuitem-text-active-color: #ffffff;
    --d-menuitem-focus-shadow: 0 0 0 0.2rem rgba(255,255,255,0.1); &#125;

Figma Design

Figma design file of Diamond is available at no extra cost at PrimeStore. The download dialog both displays the figma files and source code that are made accessible. The design file is accessible in preview mode for trial purposes.

Please note that Diamond design file mostly covers the layout and does not include the PrimeReact UI components design which is covered by the official UI Kit that requires a separate license and purchase.

Migration

Every important change is included in CHANGELOG.md file at the root folder of the distribution along with the instructions to update. Migration process mainly requires updating the layout folder and styles/layout folders.

diamond-layoutDIAMOND
© Your Organization - 2023