diff --git a/docs/images/desktop_header.png b/docs/images/desktop_header.png
new file mode 100644
index 000000000..a97be1453
Binary files /dev/null and b/docs/images/desktop_header.png differ
diff --git a/docs/images/mobile_main_menu.png b/docs/images/mobile_main_menu.png
new file mode 100644
index 000000000..16503961d
Binary files /dev/null and b/docs/images/mobile_main_menu.png differ
diff --git a/docs/images/mobile_user_menu.png b/docs/images/mobile_user_menu.png
new file mode 100644
index 000000000..7235f63fb
Binary files /dev/null and b/docs/images/mobile_user_menu.png differ
diff --git a/docs/using_custom_header.rst b/docs/using_custom_header.rst
new file mode 100644
index 000000000..16a87d120
--- /dev/null
+++ b/docs/using_custom_header.rst
@@ -0,0 +1,111 @@
+.. title:: Custom Header Component Documentation
+
+Custom Header Component
+=======================
+
+Overview
+--------
+
+The ``Header`` component is used to display a header with a provided ``mainMenuItems``,
+``secondaryMenuItems``, and ``userMenuItems`` props. If props are provided, the component will use them; otherwise,
+if any of the props ``(mainMenuItems, secondaryMenuItems, userMenuItems)`` are not provided, default
+items will be displayed. This component provides flexibility in customization, making it suitable for a wide
+range of applications.
+
+Props Details
+-------------
+
+The `Header` component accepts the following **optional** props for customization:
+
+``mainMenuItems``
+*****************
+
+The main menu items is a list of menu items objects. On desktop screens, these items are displayed on the left side next to the logo icon.
+On mobile screens, the main menu is displayed as a dropdown menu triggered by a hamburger icon. The main menu dropdown appears below the logo when opened.
+
+Example:
+::
+
+ [
+ { type: 'item', href: '/courses', content: 'Courses', isActive: true },
+ { type: 'item', href: '/programs', content: 'Programs' },
+ { type: 'item', href: '/discover', content: 'Discover New', disabled, true },
+ {
+ type: 'submenu',
+ content: 'Sub Menu Item',
+ submenuContent: (
+ <>
+
+
+ ),
+ },
+ ]
+
+**Submenu Implementation**
+
+To implement a submenu, set the type to ``submenu`` and provide a ``submenuContent`` property.
+The submenuContent should be a React component (as shown in above example) that can be rendered.
+
+**Note:**
+
+- The ``type`` should be ``item`` or ``submenu``. If type is ``submenu``, it should contain ``submenuContent`` instead of ``href``.
+
+- If any item is to be disabled, we can pass optional ``disabled: true`` in that item object and
+
+- If any item is to be active, we can pass optional ``isActive: true`` in that item object
+
+secondaryMenuItems
+******************
+
+The secondary menu items has same structure as ``mainMenuItems``. On desktop screen, these items are displayed on the right of header just before the userMenu avatar and on mobile screen,
+these items are displayed below the mainMenu items in dropdown.
+
+Example:
+::
+
+ [
+ { type: 'item', href: '/help', content: 'Help' },
+ ]
+
+userMenuItems
+*************
+
+The user menu items is list of objects. On desktop screens, these items are displayed as a dropdown menu on the most right side of the header. The dropdown is opened by clicking on the avatar icon, which is typically located at the far right of the header.
+On mobile screens, the user menu is also displayed as a dropdown menu, appearing under the avatar icon.
+
+Each object represents a group in the user menu. Each object contains the ``heading`` and
+list of menu items to be displayed in that group. Heading is optional and will be displayed only if passed. There can
+be multiple groups. For a normal user menu, a single group can be passed with empty heading.
+
+Example:
+::
+
+ [
+ {
+ heading: '',
+ items: [
+ { type: 'item', href: '/profile', content: 'Profile' },
+ { type: 'item', href: '/logout', content: 'Logout' }
+ ]
+ },
+ ]
+
+Screenshots
+***********
+
+Desktop:
+
+.. image:: ./images/desktop_header.png
+
+Mobile:
+
+.. image:: ./images/mobile_main_menu.png
+.. image:: ./images/mobile_user_menu.png
+
+Some Important Notes
+--------------------
+
+- Intl formatted strings should be passed in content attribute.
+- Only menu items in the main menu can be disabled.
+- Menu items in the main menu and user menu can have ``isActive`` prop.
diff --git a/src/DesktopHeader.jsx b/src/DesktopHeader.jsx
index 8bd142fb9..c0f111fdb 100644
--- a/src/DesktopHeader.jsx
+++ b/src/DesktopHeader.jsx
@@ -19,25 +19,31 @@ class DesktopHeader extends React.Component {
super(props);
}
- renderMainMenu() {
- const { mainMenu } = this.props;
-
+ renderMenu(menu) {
// Nodes are accepted as a prop
- if (!Array.isArray(mainMenu)) {
- return mainMenu;
+ if (!Array.isArray(menu)) {
+ return menu;
}
- return mainMenu.map((menuItem) => {
+ return menu.map((menuItem) => {
const {
type,
href,
content,
submenuContent,
+ disabled,
+ isActive,
} = menuItem;
if (type === 'item') {
return (
- {content}
+
+ {content}
+
);
}
@@ -54,22 +60,14 @@ class DesktopHeader extends React.Component {
});
}
- // Renders an optional App Menu for
- renderAppMenu() {
- const { appMenu } = this.props;
- const { content: appMenuContent, menuItems } = appMenu;
- return (
-
- );
+ renderMainMenu() {
+ const { mainMenu } = this.props;
+ return this.renderMenu(mainMenu);
+ }
+
+ renderSecondaryMenu() {
+ const { secondaryMenu } = this.props;
+ return this.renderMenu(secondaryMenu);
}
renderUserMenu() {
@@ -91,8 +89,23 @@ class DesktopHeader extends React.Component {
{username}
- {userMenu.map(({ type, href, content }) => (
- {content}
+ {userMenu.map((group, index) => (
+ // eslint-disable-next-line react/jsx-no-comment-textnodes,react/no-array-index-key
+
+ {group.heading &&
{group.heading}
}
+ {group.items.map(({
+ type, content, href, disabled, isActive,
+ }) => (
+
+ {content}
+
+ ))}
+ {index < userMenu.length - 1 && }
+
))}
@@ -120,7 +133,6 @@ class DesktopHeader extends React.Component {
logoDestination,
loggedIn,
intl,
- appMenu,
} = this.props;
const logoProps = { src: logo, alt: logoAltText, href: logoDestination };
const logoClasses = getConfig().AUTHN_MINIMAL_HEADER ? 'mw-100' : null;
@@ -137,19 +149,17 @@ class DesktopHeader extends React.Component {
>
{this.renderMainMenu()}
- {appMenu ? (
-
- ) : null}
@@ -163,10 +173,18 @@ DesktopHeader.propTypes = {
PropTypes.node,
PropTypes.array,
]),
+ secondaryMenu: PropTypes.oneOfType([
+ PropTypes.node,
+ PropTypes.array,
+ ]),
userMenu: PropTypes.arrayOf(PropTypes.shape({
- type: PropTypes.oneOf(['item', 'menu']),
- href: PropTypes.string,
- content: PropTypes.string,
+ heading: PropTypes.string,
+ items: PropTypes.arrayOf(PropTypes.shape({
+ type: PropTypes.oneOf(['item', 'menu']),
+ href: PropTypes.string,
+ content: PropTypes.string,
+ isActive: PropTypes.bool,
+ })),
})),
loggedOutItems: PropTypes.arrayOf(PropTypes.shape({
type: PropTypes.oneOf(['item', 'menu']),
@@ -182,24 +200,11 @@ DesktopHeader.propTypes = {
// i18n
intl: intlShape.isRequired,
-
- // appMenu
- appMenu: PropTypes.shape(
- {
- content: PropTypes.string,
- menuItems: PropTypes.arrayOf(
- PropTypes.shape({
- type: PropTypes.string,
- href: PropTypes.string,
- content: PropTypes.string,
- }),
- ),
- },
- ),
};
DesktopHeader.defaultProps = {
mainMenu: [],
+ secondaryMenu: [],
userMenu: [],
loggedOutItems: [],
logo: null,
@@ -208,7 +213,6 @@ DesktopHeader.defaultProps = {
avatar: null,
username: null,
loggedIn: false,
- appMenu: null,
};
export default injectIntl(DesktopHeader);
diff --git a/src/Header.jsx b/src/Header.jsx
index c0db257c7..bff801fe0 100644
--- a/src/Header.jsx
+++ b/src/Header.jsx
@@ -10,6 +10,7 @@ import {
subscribe,
} from '@edx/frontend-platform';
+import PropTypes from 'prop-types';
import DesktopHeader from './DesktopHeader';
import MobileHeader from './MobileHeader';
@@ -30,50 +31,68 @@ subscribe(APP_CONFIG_INITIALIZED, () => {
}, 'Header additional config');
});
-const Header = ({ intl }) => {
+/**
+ * Header component for the application.
+ * Displays a header with the provided main menu, secondary menu, and user menu when the user is authenticated.
+ * If any of the props (mainMenuItems, secondaryMenuItems, userMenuItems) are not provided, default
+ * items are displayed.
+ * For more details on how to use this component, please refer to this document:
+ * https://github.com/openedx/frontend-component-header/blob/master/docs/using_custom_header.rst
+ *
+ * @param {list} mainMenuItems - The list of main menu items to display.
+ * See the documentation for the structure of main menu item.
+ * @param {list} secondaryMenuItems - The list of secondary menu items to display.
+ * See the documentation for the structure of secondary menu item.
+ * @param {list} userMenuItems - The list of user menu items to display.
+ * See the documentation for the structure of user menu item.
+ */
+const Header = ({
+ intl, mainMenuItems, secondaryMenuItems, userMenuItems,
+}) => {
const { authenticatedUser, config } = useContext(AppContext);
- const mainMenu = [
+ const defaultMainMenu = [
{
type: 'item',
href: `${config.LMS_BASE_URL}/dashboard`,
content: intl.formatMessage(messages['header.links.courses']),
},
];
+ const defaultUserMenu = authenticatedUser === null ? [] : [{
+ heading: '',
+ items: [
+ {
+ type: 'item',
+ href: `${config.LMS_BASE_URL}/dashboard`,
+ content: intl.formatMessage(messages['header.user.menu.dashboard']),
+ },
+ {
+ type: 'item',
+ href: `${config.ACCOUNT_PROFILE_URL}/u/${authenticatedUser.username}`,
+ content: intl.formatMessage(messages['header.user.menu.profile']),
+ },
+ {
+ type: 'item',
+ href: config.ACCOUNT_SETTINGS_URL,
+ content: intl.formatMessage(messages['header.user.menu.account.settings']),
+ },
+ // Users should only see Order History if have a ORDER_HISTORY_URL define in the environment.
+ ...(config.ORDER_HISTORY_URL ? [{
+ type: 'item',
+ href: config.ORDER_HISTORY_URL,
+ content: intl.formatMessage(messages['header.user.menu.order.history']),
+ }] : []),
+ {
+ type: 'item',
+ href: config.LOGOUT_URL,
+ content: intl.formatMessage(messages['header.user.menu.logout']),
+ },
+ ],
+ }];
- const orderHistoryItem = {
- type: 'item',
- href: config.ORDER_HISTORY_URL,
- content: intl.formatMessage(messages['header.user.menu.order.history']),
- };
-
- const userMenu = authenticatedUser === null ? [] : [
- {
- type: 'item',
- href: `${config.LMS_BASE_URL}/dashboard`,
- content: intl.formatMessage(messages['header.user.menu.dashboard']),
- },
- {
- type: 'item',
- href: `${config.ACCOUNT_PROFILE_URL}/u/${authenticatedUser.username}`,
- content: intl.formatMessage(messages['header.user.menu.profile']),
- },
- {
- type: 'item',
- href: config.ACCOUNT_SETTINGS_URL,
- content: intl.formatMessage(messages['header.user.menu.account.settings']),
- },
- {
- type: 'item',
- href: config.LOGOUT_URL,
- content: intl.formatMessage(messages['header.user.menu.logout']),
- },
- ];
-
- // Users should only see Order History if have a ORDER_HISTORY_URL define in the environment.
- if (config.ORDER_HISTORY_URL) {
- userMenu.splice(-1, 0, orderHistoryItem);
- }
+ const mainMenu = mainMenuItems || defaultMainMenu;
+ const secondaryMenu = secondaryMenuItems || [];
+ const userMenu = authenticatedUser === null ? [] : userMenuItems || defaultUserMenu;
const loggedOutItems = [
{
@@ -96,13 +115,14 @@ const Header = ({ intl }) => {
username: authenticatedUser !== null ? authenticatedUser.username : null,
avatar: authenticatedUser !== null ? authenticatedUser.avatar : null,
mainMenu: getConfig().AUTHN_MINIMAL_HEADER ? [] : mainMenu,
+ secondaryMenu: getConfig().AUTHN_MINIMAL_HEADER ? [] : secondaryMenu,
userMenu: getConfig().AUTHN_MINIMAL_HEADER ? [] : userMenu,
loggedOutItems: getConfig().AUTHN_MINIMAL_HEADER ? [] : loggedOutItems,
};
return (
<>
-
+
@@ -112,8 +132,31 @@ const Header = ({ intl }) => {
);
};
+Header.defaultProps = {
+ mainMenuItems: null,
+ secondaryMenuItems: null,
+ userMenuItems: null,
+};
+
Header.propTypes = {
intl: intlShape.isRequired,
+ mainMenuItems: PropTypes.oneOfType([
+ PropTypes.node,
+ PropTypes.array,
+ ]),
+ secondaryMenuItems: PropTypes.oneOfType([
+ PropTypes.node,
+ PropTypes.array,
+ ]),
+ userMenuItems: PropTypes.arrayOf(PropTypes.shape({
+ heading: PropTypes.string,
+ items: PropTypes.arrayOf(PropTypes.shape({
+ type: PropTypes.oneOf(['item', 'menu']),
+ href: PropTypes.string,
+ content: PropTypes.string,
+ isActive: PropTypes.bool,
+ })),
+ })),
};
export default injectIntl(Header);
diff --git a/src/MobileHeader.jsx b/src/MobileHeader.jsx
index 506deb33d..128e2de81 100644
--- a/src/MobileHeader.jsx
+++ b/src/MobileHeader.jsx
@@ -19,25 +19,29 @@ class MobileHeader extends React.Component {
super(props);
}
- renderMainMenu() {
- const { mainMenu } = this.props;
-
+ renderMenu(menu) {
// Nodes are accepted as a prop
- if (!Array.isArray(mainMenu)) {
- return mainMenu;
+ if (!Array.isArray(menu)) {
+ return menu;
}
- return mainMenu.map((menuItem) => {
+ return menu.map((menuItem) => {
const {
type,
href,
content,
submenuContent,
+ disabled,
+ isActive,
} = menuItem;
if (type === 'item') {
return (
-
+
{content}
);
@@ -56,13 +60,32 @@ class MobileHeader extends React.Component {
});
}
+ renderMainMenu() {
+ const { mainMenu } = this.props;
+ return this.renderMenu(mainMenu);
+ }
+
+ renderSecondaryMenu() {
+ const { secondaryMenu } = this.props;
+ return this.renderMenu(secondaryMenu);
+ }
+
renderUserMenuItems() {
const { userMenu } = this.props;
- return userMenu.map(({ type, href, content }) => (
-