diff --git a/docs/images/desktop_header.png b/docs/images/desktop_header.png new file mode 100644 index 00000000..c035fecd 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 00000000..3a0989e8 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 00000000..2ccc7778 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 00000000..16a87d12 --- /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 item 1
+
Submenu item 2
+ + ), + }, + ] + +**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 4fa01f56..6c1f443f 100644 --- a/src/DesktopHeader.jsx +++ b/src/DesktopHeader.jsx @@ -20,25 +20,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} + ); } @@ -55,6 +61,16 @@ class DesktopHeader extends React.Component { }); } + renderMainMenu() { + const { mainMenu } = this.props; + return this.renderMenu(mainMenu); + } + + renderSecondaryMenu() { + const { secondaryMenu } = this.props; + return this.renderMenu(secondaryMenu); + } + renderUserMenu() { const { userMenu, @@ -86,10 +102,23 @@ class DesktopHeader extends React.Component { /> )} - {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 && } + ))} @@ -137,7 +166,13 @@ class DesktopHeader extends React.Component { aria-label={intl.formatMessage(messages['header.label.secondary.nav'])} className="nav secondary-menu-container align-items-center ml-auto" > - {loggedIn ? this.renderUserMenu() : this.renderLoggedOutItems()} + {loggedIn + ? ( + <> + {this.renderSecondaryMenu()} + {this.renderUserMenu()} + + ) : this.renderLoggedOutItems()} @@ -151,10 +186,19 @@ 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, + disabled: PropTypes.bool, + isActive: PropTypes.bool, + })), })), loggedOutItems: PropTypes.arrayOf(PropTypes.shape({ type: PropTypes.oneOf(['item', 'menu']), @@ -175,6 +219,7 @@ DesktopHeader.propTypes = { DesktopHeader.defaultProps = { mainMenu: [], + secondaryMenu: [], userMenu: [], loggedOutItems: [], logo: null, diff --git a/src/Header.jsx b/src/Header.jsx index 53329046..ae2f9cf1 100644 --- a/src/Header.jsx +++ b/src/Header.jsx @@ -13,6 +13,7 @@ import { } from '@edx/frontend-platform'; import { useEnterpriseConfig } from '@edx/frontend-enterprise-utils'; +import PropTypes from 'prop-types'; import DesktopHeader from './DesktopHeader'; import MobileHeader from './MobileHeader'; @@ -35,14 +36,31 @@ 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/edx/frontend-component-header-edx/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 { enterpriseLearnerPortalLink, enterpriseCustomerBrandingConfig, } = useEnterpriseConfig(authenticatedUser, config.ENTERPRISE_LEARNER_PORTAL_HOSTNAME, config.LMS_BASE_URL); - const mainMenu = [ + const defaultMainMenu = [ { type: 'item', href: `${config.LMS_BASE_URL}/dashboard`, @@ -78,12 +96,6 @@ const Header = ({ intl }) => { 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']), - }; - // If there is an Enterprise LP link, use that instead of the B2C Dashboard let baseUserMenuDashboardLinks = []; if (enterpriseLearnerPortalLink) { @@ -93,46 +105,57 @@ const Header = ({ intl }) => { } const careerItemContent = <>{intl.formatMessage(messages['header.user.menu.career'])}{intl.formatMessage(messages['header.user.menu.newAlert'])}; - let userMenu = authenticatedUser === null ? [] : [ - ...baseUserMenuDashboardLinks, - { - type: 'item', - href: 'https://careers.edx.org/', - content: careerItemContent, - onClick: () => { - sendTrackEvent( - 'edx.bi.user.menu.career.clicked', - { category: 'header', label: 'header' }, - ); + const defaultUserMenu = authenticatedUser === null ? [] : [{ + heading: '', + items: [ + ...baseUserMenuDashboardLinks, + { + type: 'item', + href: 'https://careers.edx.org/', + content: careerItemContent, + onClick: () => { + sendTrackEvent( + 'edx.bi.user.menu.career.clicked', + { category: 'header', label: 'header' }, + ); + }, }, - }, - { - 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']), - }, - logoutMenuItem, - ]; + { + 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 they do not have an available + // learner portal and have a ORDER_HISTORY_URL define in the environment, + // because an available learner portal currently means + // that they access content via B2B Subscriptions, in which context an "order" + // is not relevant. + ...(!enterpriseLearnerPortalLink && config.ORDER_HISTORY_URL ? [{ + type: 'item', + href: config.ORDER_HISTORY_URL, + content: intl.formatMessage(messages['header.user.menu.order.history']), + }] : []), + logoutMenuItem, + ], + }]; - // Users should only see Order History if they do not have an available - // learner portal and have a ORDER_HISTORY_URL define in the environment, - // because an available learner portal currently means - // that they access content via B2B Subscriptions, in which context an "order" - // is not relevant. - if (!enterpriseLearnerPortalLink && config.ORDER_HISTORY_URL) { - userMenu.splice(-1, 0, orderHistoryItem); - } + const mainMenu = mainMenuItems || defaultMainMenu; + const secondaryMenu = secondaryMenuItems || []; + let userMenu = authenticatedUser === null ? [] : userMenuItems || defaultUserMenu; if (getConfig().MINIMAL_HEADER && authenticatedUser !== null) { - userMenu = [ - dashboardMenuItem, - logoutMenuItem, - ]; + userMenu = [{ + heading: '', + items: [ + dashboardMenuItem, + logoutMenuItem, + ], + }]; } const loggedOutItems = [ @@ -158,6 +181,7 @@ const Header = ({ intl }) => { email: authenticatedUser !== null ? authenticatedUser.email : '', avatar: authenticatedUser !== null ? authenticatedUser.avatar : null, mainMenu: getConfig().MINIMAL_HEADER || getConfig().AUTHN_MINIMAL_HEADER ? [] : mainMenu, + secondaryMenu: getConfig().MINIMAL_HEADER || getConfig().AUTHN_MINIMAL_HEADER ? [] : secondaryMenu, userMenu: getConfig().AUTHN_MINIMAL_HEADER ? [] : userMenu, loggedOutItems: getConfig().AUTHN_MINIMAL_HEADER ? [] : loggedOutItems, }; @@ -171,7 +195,7 @@ const Header = ({ intl }) => { return ( <> - + @@ -181,8 +205,32 @@ 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, + disabled: PropTypes.bool, + isActive: PropTypes.bool, + })), + })), }; export default injectIntl(Header); diff --git a/src/MobileHeader.jsx b/src/MobileHeader.jsx index a2186c35..32a78f3c 100644 --- a/src/MobileHeader.jsx +++ b/src/MobileHeader.jsx @@ -20,25 +20,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} ); @@ -57,6 +61,16 @@ 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, name, email } = this.props; const userInfoItem = (name || email) ? ( @@ -65,10 +79,19 @@ class MobileHeader extends React.Component { ) : null; - const userMenuItems = userMenu.map(({ type, href, content }) => ( -
  • - {content} -
    • + const userMenuItems = userMenu.map((group) => ( + group.items.map(({ + type, content, href, disabled, isActive, + }) => ( +
  • + + {content} + +
    • + )) )); return userInfoItem ? [userInfoItem, ...userMenuItems] : userMenuItems; @@ -130,6 +153,7 @@ class MobileHeader extends React.Component { className="nav flex-column pin-left pin-right border-top shadow py-2" > {this.renderMainMenu()} + {this.renderSecondaryMenu()} @@ -165,11 +189,19 @@ MobileHeader.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, + disabled: PropTypes.bool, + isActive: PropTypes.bool, + })), })), loggedOutItems: PropTypes.arrayOf(PropTypes.shape({ type: PropTypes.oneOf(['item', 'menu']), @@ -191,6 +223,7 @@ MobileHeader.propTypes = { MobileHeader.defaultProps = { mainMenu: [], + secondaryMenu: [], userMenu: [], loggedOutItems: [], logo: null, diff --git a/src/index.scss b/src/index.scss index 1d31c9ba..94114bd4 100644 --- a/src/index.scss +++ b/src/index.scss @@ -88,6 +88,15 @@ $white: #fff; height: 100%; } } + .secondary-menu-container { + .nav-link:hover, + .nav-link:focus, + .nav-link.active, + .expanded .nav-link { + background: $component-active-bg; + color: $component-active-color; + } + } .main-nav { .nav-link { padding: 1.125rem 1rem;