HamfekranMenu

The HamfekranMenu library is an Angular component that provides a configurable header menu system for your web applications. It allows dynamic control over the menu's content and appearance. This library was generated using Angular CLI version 16.2.0 and supports Angular version ^16.2.0.

Installation

To use this library in your project, install it via npm:

npm install hmf-menu

Then import the HmfMenuModule into your Angular module:

import { HmfMenuModule } from 'hamfekran-menu';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    HmfMenuModule,
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Components

1. lib-hmf-header Component

The <lib-hf-header></lib-hf-header> component is the primary component in this library. It renders a configurable header with various inputs and outputs for dynamic content.

Inputs

| Name | Type | Description | |---------------------------|--------------------|-------------------------------------------------------------------------------------------------| | projectLogo | string | The URL to the logo image of your project. | | projectName | string | The name of your main project. | | subProjectName | string | The name of the sub-project (if applicable). | | ctsStyle | Lib_Colors | A custom style object for colors. Controls background and primary/secondary colors of the header. | | mode | 1 - 2 - 3 | The environment mode: 1 (Test), 2 (Demo), or 3 (Production). | | inputToken | string | The token used for authentication. | | mainProjectAddress | string | The base URL of the main project. | | panelHamfekranAddress | string | The URL to the Hamfekran panel for profile editing. | | currentProjectAddress | string | The URL of the current sub-project. | | showProjectsMenuState | boolean | Determines if the project menu will be shown (set to false as it's currently unavailable). | | showMenuIconOnMobile | boolean | Shows menu controller on mobile if set to true. | | logInUrl | string | The login URL for your project. | | gotLogInOnExpire | boolean | If true, redirects to the login page when access or profile methods expire. | | tokenEnum | string | The key of the token stored in localStorage or sessionStorage. | | isMultiLang | boolean | If true, enables a language selection box. | | profileUrlInput | string | Custom URL for the user profile. | | menuUrlInput | string | Custom input for the menu URL. Overrides the default behavior if provided. | | changePartnerUrlInput | string | Custom URL for changing partners. | | reloadUrlInput | string | Custom URL for reloading data. | | langOptions | Lib_Lang[] | Available languages for the project. | | sideBarState | boolean | Controls the visibility of the sidebar. | | mainLang | Lib_Lang | The base language for the header. Defaults to fa (Persian) if not specified. |

Outputs

| Name | Type | Description | |--------------------------|----------------------|-------------------------------------------------------------------------------------------------| | sideBarController | Lib_EmitData | Emits data related to the sidebar's state (opened or closed). | | accordionController | Lib_AccordionItem | Emits data about accordion items when clicked. | | menuController | Lib_MenuItem | Emits data related to menu item selection. | | getAccessApiRes | any | Emits the response from the access API. | | getProfilePicApiRes | any | Emits the response containing the user's profile picture. | | getProfileNameApiRes | any | Emits the response containing the user's profile name. | | isTokenExpire | any | Emits true if the token is expired. | | langChange | string | Emits the selected language code (fa, en, tr) after language selection. |

Model Definitions

Below are the model interfaces used by the component:

Lib_Menu

interface Lib_Menu {
  backgroundLogo: string;
  menuItems: Lib_MenuItem[];
}

Lib_MenuItem

interface Lib_MenuItem {
  logo: string;
  title: string;
  href: string;
}

Lib_AccordionItem

interface Lib_AccordionItem {
  title: string;
  href: string;
  logo: string;
  isSelected: boolean;
  partnerTypeId: number;
  partnerId: string;
}

Lib_Colors

interface Lib_Colors {
  backgroundColor: string;
  primaryColor: string;
  secondaryColor: string;
}

Lib_EmitData

interface Lib_EmitData {
  value: string;
  state: boolean;
}

Lib_Lang

interface Lib_Lang {
  value: string;
  icon: string;
  dir: string;
  isActive: boolean;
}

Token Priority

The library checks for tokens in the following order:

1. localStorage: If available, the token is retrieved from localStorage.
2. sessionStorage: If no token is found in localStorage, the component checks sessionStorage.
3. inputToken: If neither local nor session storage has the token, the component falls back to the provided inputToken.

Language Handling

• The base language is controlled by the mainLang input. If not specified, it defaults to fa (Persian).
• The isMultiLang input enables a language selection dropdown.
• When a language is selected, it is stored in localStorage under the key hmfLib_SelectedLang to persist across page reloads.

Example Usage

<lib-hf-header
  [projectLogo]="'https://example.com/logo.png'"
  [projectName]="'Main Project'"
  [subProjectName]="'Sub Project'"
  [ctsStyle]="{ backgroundColor: '#fff', primaryColor: '#007bff', secondaryColor: '#6c757d' }"
  [mode]="3"
  [inputToken]="'your-token-here'"
  [mainProjectAddress]="'https://example.com'"
  [panelHamfekranAddress]="'https://panel.example.com'"
  [currentProjectAddress]="'https://subproject.example.com'"
  [showProjectsMenuState]="false"
  [showMenuIconOnMobile]="true"
  [logInUrl]="'https://example.com/login'"
  [gotLogInOnExpire]="true"
  [tokenEnum]="'userToken'"
  [isMultiLang]="true"
  [profileUrlInput]="'https://example.com/profile'"
  [menuUrlInput]="'https://example.com/menu'"
  [changePartnerUrlInput]="'https://example.com/change-partner'"
  [reloadUrlInput]="'https://example.com/reload'"
  [langOptions]="[{ value: 'en', icon: '🇺🇸.svg', dir: 'ltr', isActive: true }]"
  [sideBarState]="false"
  [mainLang]="{ value: 'en', icon: '🇺🇸.svg', dir: 'ltr', isActive: true }"
  (sideBarController)="handleSidebar($event)"
  (accordionController)="handleAccordion($event)"
  (menuController)="handleMenu($event)"
  (getAccessApiRes)="handleAccessApiResponse($event)"
  (getProfilePicApiRes)="handleProfilePicResponse($event)"
  (getProfileNameApiRes)="handleProfileNameResponse($event)"
  (isTokenExpire)="handleTokenExpiration($event)"
  (langChange)="handleLanguageChange($event)">
</lib-hf-header>

2. lib-hmf-sidebar Component

The <lib-hmf-sidebar></lib-hmf-sidebar> component provides a configurable sidebar for navigation. It supports dynamic menu items, multi-language, and different device views (desktop, tablet, mobile).

Inputs

| Name | Type | Description | |---------------------------|-----------------------------|-------------------------------------------------------------------------------------------------| | sidebarState | boolean | Controls the sidebar state (open/close). | | mode | 1 -2 -3 | Sets the mode of the sidebar (1 test, 2 demo, 3 production). | | inputToken | any | Token for authentication. | | mainProjectAddress | string | Main project address URL. | | currentProjectAddress | string | Current project address URL. | | showLogOutItem | boolean | Shows/hides the logout item. | | showMainPageItem | boolean | Shows/hides the main page item. | | logOutUrl | string | URL for logout. | | logInUrl | string | URL for login. | | gotLogInOnExpire | boolean | Redirects to login on token expiration. | | isMultiLang | boolean | Enables/disables multi-language support. | | tokenEnum | string | Enum for token storage. | | menuUrlInput | string | URL for fetching menu items. | | identityUrlInput | string | URL for identity service. | | isHeaderExist | boolean | Shows/hides the header. | | isMinimalOnDesktop | boolean | Enables/disables minimal view on desktop. | | desktopMinimalController| Lib_DesktopCloseController| Controller for desktop minimal view. | | homeAndExitText | Lib_HomeAndExitText[] | Array of home and exit text for different languages. | | mobileCloseController | 0 - 1 - 2 | Controller for mobile close behavior (0: button, 1: screen, 2: both). | | tabletCloseController | 0 - 1 - 2 | Controller for tablet close behavior (0: button, 1: screen, 2: both). |

Outputs

| Name | Type | Description | |--------------------------|----------------------|-------------------------------------------------------------------------------------------------| | sideBarController | any | Emits sidebar state changes. | | sideBarItemsChange | any | Emits sidebar items changes. | | getMenuApiRes | any | Emits menu API response. | | isTokenExpire | any | Emits token expiration status. |

Example Usage

<lib-hmf-sidebar
  [sidebarState]="true"
  [mode]="1"
  [inputToken]="token"
  [mainProjectAddress]="'/main'"
  [currentProjectAddress]="'/current'"
  [showLogOutItem]="true"
  [showMainPageItem]="true"
  [logOutUrl]="'/logout'"
  [logInUrl]="'/login'"
  [gotLogInOnExpire]="true"
  [isMultiLang]="true"
  [tokenEnum]="'userToken'"
  [menuUrlInput]="'/menu'"
  [identityUrlInput]="'/identity'"
  [isHeaderExist]="true"
  [isMinimalOnDesktop]="true"
  [desktopMinimalController]="desktopController"
  [homeAndExitText]="homeExitText"
  [mobileCloseController]="1"
  [tabletCloseController]="1"
  (sideBarController)="onSideBarController($event)"
  (sideBarItemsChange)="onSideBarItemsChange($event)"
  (getMenuApiRes)="onGetMenuApiRes($event)"
  (isTokenExpire)="onIsTokenExpire($event)"
></lib-hmf-sidebar>

Model Definitions

Below are the model interfaces used by the component:

Lib_SideBarItem

interface Lib_SideBarItem {
  title: string;
  icon: string;
  href?: string;
  state: boolean;
  subItem?: Lib_SubItem[];
  subItemViewState: boolean;
  isLogOut?: boolean;
}

Lib_SubItem

interface Lib_SubItem {
  title: string;
  href: string;
  state: boolean;
}

Lib_HomeAndExitText

interface Lib_HomeAndExitText {
  home: string;
  exit: string;
  lang: string;
}

Lib_DesktopCloseController

interface Lib_DesktopCloseController {
  byHoverOpen: boolean;
  byClickOpen: boolean;
  byClickCloseConfig: {
    closeState: 0 | 1 | 2;
  };
}

desktop more than 1024px
tablest 1024px to 700px
mobile 700px to 0px

2. lib-hmf-container Component

The <lib-hmf-container></lib-hmf-container> component provides a configurable view that you can put the sidebar and your routeroutlet inside of it to controll view and sidebar states.

| Name | Type | Description | |---------------------------|-----------------------------|-------------------------------------------------------------------------------------------------| | isSidebarExist | boolean | true> in case of adding sidebar inside the container. | | sidbarState | boolean | sidebar state variable form header and sidebar.
| dir | string | container direction.
| overlapOnDesktop | boolean | in case of true the sidebar open will overlap on on container.
| isMinimalOnDesktop | boolean | in case of using sidebar in minimal view .
|

Example Usage

<lib-hmf-container [isSidebarExist]="isSidebarExist" [sidbarState]="sidebarState" [dir]="mainLang.dir" [overlapOnDesktop]="overlapOnDesktop" [isMinimalOnDesktop]="isMinimalOnDesktop"  >

  <lib-hmf-sidebar
    [sidebarState]="sidebarState"
    [mode]="mode"
    [inputToken]="inputToken"
    [mainProjectAddress]="mainProjectAddress"
    [currentProjectAddress]="currentProjectAddress"
    [showLogOutItem]="showLogOutItem"
    [showMainPageItem]="showMainPageItem"
    [logOutUrl]="logOutUrl"
    [logInUrl]="logInUrl"
    [gotLogInOnExpire]="gotLogInOnExpire"
    [isMultiLang]="isMultiLang"
    [tokenEnum]="tokenEnum"
    [menuUrlInput]="menuUrlInput"
    [identityUrlInput]="identityUrlInput"
    [isHeaderExist]="isHeaderExist"
    [isMinimalOnDesktop]="isMinimalOnDesktop"
    [desktopMinimalController]="desktopMinimalController"
    [homeAndExitText]="homeAndExitText"
    [mainLang]="mainLang"
    [mobileCloseController]="mobileCloseController"
    [tabletCloseController]="tabletCloseController"
    (sideBarController)="onSidebarGetSideBarState($event)"
    (sideBarItemsChange)="onSidebarItemChange($event)"
    (getMenuApiRes)="onSideBarGetMenuApiRes($event)"
    (isTokenExpire)="isTokenExpire($event)">

  </lib-hmf-sidebar>
  <div class="projectContainer">
    <div class="content1">1111</div>
    <div class="content2">2222</div>
  </div>

</lib-hmf-container>