Current Version

Angular 13 and PrimeNG 13

Getting Started

Sakai is an application template for Angular and is distributed as a CLI project. In case CLI is not installed already, use the command below to set it up.

Dependencies

Sakai has no direct dependency other than PrimeNG. More information about dependencies is available at Why PrimeNG Templates article.

npm install -g @angular/cli

Once CLI is ready in your system, extract the contents of the Sakai zip file distribution, cd to the directory, install the libraries from npm and then execute "ng serve" to run the application in your local environment.

cd sakai-ng npm install ng serve

The application should run at http://localhost:4200/, you may now start with the development of your application.

Important CLI Commands

Following commands are derived from CLI.

Run 'ng serve' for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files. Run 'ng generate component component-name' to generate a new component. You can also use `ng generate directive/pipe/service/class/module`. Run 'ng build' to build the project. The build artifacts will be stored in the `dist/` directory. Use the `-prod` flag for a production build. Run 'ng test' to execute the unit tests via [Karma](https://karma-runner.github.io). Run 'ng e2e' to execute the end-to-end tests via [Protractor](http://www.protractortest.org/). Run 'ng help' for more options.

Structure

Sakai consists of 2 main parts; the application layout, layout resources. app.component.html inside app folder is the html template for the base layout, required resources for the layout are placed inside the src/assets/layout folder and similarly theme resources are inside src/assets/theme folder.

Application Template

Main layout is the html template of the app.main.component.ts, it is divided into a couple of sections such as topbar, sidebar, right panel and footer. Here is the code for the main template. The component class app.main.component.ts implements the logic such as opening menus and managing layout modes.

<div class="layout-wrapper" [ngClass]="{ 'layout-overlay':isOverlay(), 'layout-static':isStatic(), 'layout-theme-light': !app.darkMode, 'layout-theme-dark': app.darkMode, 'layout-overlay-sidebar-active': overlayMenuActive, 'layout-static-sidebar-inactive': staticMenuInactive, 'layout-mobile-sidebar-active': menuActiveMobile, 'p-ripple-disabled': !app.ripple, 'p-input-filled' : app.inputStyle === 'filled'}" <app-topbar></app-topbar> <div class="layout-sidebar"> <app-menu></app-menu> </div> <div class="layout-main-container"> <div class="layout-main"> <router-outlet></router-outlet> </div> <app-footer></app-footer> </div> <app-config></app-config> <div class="layout-mask p-component-overlay"></div> </div>

Menu

Menu is a separate component defined in app.menu.component.ts file based on PrimeNG MenuModel API. In order to define the menuitems, navigate to this file and define your own model as a nested structure. Here is the menu component from the sample application.

Integration with an Existing CLI Project

To setup Sakai in an existing project, follow the steps below;

• Copy the src/assets folder to your projects folder with the same name
• Copy all app.* files to the src/app folder of your application.

Install PrimeNG

npm install primeng@latest --save npm install primeicons@latest --save

Add PrimeNG CSS at styles section in angular.json.

"styles": [ "styles.scss" //your styles and overrides ],

Last part is adding theme and layout css files, in the CLI app they are defined using link tags in index.html so the demo can switch them on the fly by changing the path however if this is not a requirement, you may also add them to the styles configuration above so they go inside the bundle.

Theme

Sakai uses the free Saga, Arya and Vela themes which are distributed within PrimeNG, however it can be used with any PrimeNG theme as well such as material, tailwind and bootstrap.

SASS Variables

In case you'd like to customize the layout variables, open _variables.scss file under src/layout folder. Saving the changes will be reflected instantly at your browser.

src/assets/_variables.scss

A custom theme can be developed by the following steps.

• Choose a custom theme name such as "mytheme".
• Create a folder named "mytheme" under assets/theme folder.
• Create a file such as theme.scss under assets/theme/mytheme folder.
• Define the variables listed below in your file and import the ../../sass/theme/_theme.scss file.
• Build the scss to generate css
• Include the generated theme.css to your page.

Here are the variables required to create a theme.

$primaryLightColor: #777BF1; $primaryColor:#464DF2; $primaryDarkColor: #221ED9; $primaryDarkerColor: #1222B9; $primaryTextColor: #FFFFFF; $primaryLighterColor: rgba($primaryLightColor,.1); $highlightBg: $primaryColor; $highlightTextColor: $primaryTextColor; @import '../../sass/theme/_theme_light';

An example sass command to compile the css would be;

sass --update src/assets/theme/mytheme/theme.scss:src/assets/theme/mytheme/theme.css

Watch mode is handy to avoid compiling everytime when a change is made, instead use the following command so that sass generates the file whenever you make a customization. This builds all css files whenever a change is made to any scss file.

sass --watch src/assets/theme/mytheme/theme.scss:src/assets/theme/mytheme/theme.css

Same can also be applied to layout itself;

• Choose a layout name such as layout-myown.
• Create an empty file named layout-myown.scss inside assets/layout/css folder.
• Define the variables listed below and import the /sass/layout/_layout.scss file.
• Build the scss to generate css
• Serve the css by importing it using a link tag or a bundler.

Here are the variables required to create a layout.

@import '../../sass/layout/_layout_light';

SASS Variables

Both the theme and layout provides various variables to customize the design.

sass/variables/layout/_layout_common.scss

Common variables for light and dark application layout.

$fontSize:14px !default; $fontFamily:-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default; $mobileBreakpoint:991px !default; $borderRadius:24px !default; $animationDuration:.2s !default; $animationTimingFunction:cubic-bezier(.05,.74,.2,.99) !default; $letterSpacing:0.02em !default; $transitionDuration:.2s !default; $tabletBreakpoint:991px !default; $phoneBreakpoint:576px !default;

sass/variables/layout/_layout_light.scss

Variables of the light theme layout.

$bodyBgColor:#F2F4F6 !default; //text $textShade100:#3E4754 !default; $textShade200:rgba(41, 50, 65, 0.8) !default; $textShade300:rgba(41, 50, 65, 0.5) !default; //content $contentShade100:#ffffff !default; $contentShade200: #F7FAFF !default; $contentShade300: #EEF5FF !default; $contentShade400: #F7F7F8 !default; $dividerColor: #D4D6D9 !default; $menuTooltipBgColor:#293241!default; $menuTooltipTextColor:#ffffff !default; @import './_layout_common.scss';

sass/variables/theme/_theme_light

Variables of the light component theme, see the Theme Designer API for documentation.

Menu Modes

Menu has 2 modes, static and overlay. Layout container element in app.component.html is used to define which mode to use by adding specific classes. List below indicates the style classes for each mode.

• Static: "layout-wrapper layout-static"
• Overlay: "layout-wrapper layout-overlay"

For example to create a horizontal menu, the div element should be in following form;

<div class="layout-wrapper layout-sidebar">

It is also possible to leave the choice to the user by keeping the preference at a component and using an ngClass expression so that user can switch between modes. Sample application has an example implementation of such use case. Refer to app.component.ts for an example.

Grid CSS

Sakai uses PrimeNG Flex Grid CSS throughout the demos such as Dashboard, however any Grid library can be used with it since Sakai Layout itself does not depend on PrimeFlex CSS.

Customizing Styles

It is suggested to add your customizations in the following sass files under the "sass/overrides" folder instead of adding them to the scss files under sass folder to avoid maintenance issues after an update.

• _layout_variables: Variables of the layout.
• _layout_styles: Styles for the layout.
• _theme_variables: Variables of the theme.
• _theme_styles: Styles for the theme.

Migration Guide

Every change is included in CHANGELOG.md file at the root folder of the distribution along with the instructions to update.