diff --git a/docs/images/desktop_header.png b/docs/images/desktop_header.png new file mode 100644 index 0000000000..a97be14530 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 0000000000..16503961df 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 0000000000..7235f63fb5 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 0000000000..091a15f1f6 --- /dev/null +++ b/docs/using_custom_header.rst @@ -0,0 +1,119 @@ +.. title:: Custom Header Component Documentation + +Custom Header Component +======================= + +Overview +-------- + +The ``Header`` component is used to display a header with a provided ``logo``, ``mainMenuItems``, +``secondaryMenuItems``, and ``userMenuItems`` props. If props are provided, the component will use them; otherwise, +If any of the props ``(logo, mainMenuItems, secondaryMenuItems, userMenuItems)`` are not provided, default +items are 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: + +``logo`` +******* + +The logo prop is an object containing `src`, `alt`, and `href` properties. If not passed, LOGO_URL from config will be used. +It is displayed on the left of the header in the desktop screen and in the center of the header on the mobile screen. + +Example: +:: + + { + src: 'path/to/logo.png', + alt: 'Logo Alt Text', + href: '/home' + } + +``mainMenuItems`` +***************** + +The main menu items is a list of menu items objects. On desktop screens, these items are displayed on the left, to the right of the logo icon and to the left of the secondary menu. +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
' + ], + }, + ] + +**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. + +User Menu is list of objects. Each object represent a group in 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, we can pass single group 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/example/headersData.js b/example/headersData.js new file mode 100644 index 0000000000..e22b5e6799 --- /dev/null +++ b/example/headersData.js @@ -0,0 +1,305 @@ + +export const learnerHomeHeaderData = { + mainMenu: [ + { + type: 'item', + href: `#`, + content: 'Courses', + }, + { + type: 'item', + href: `#`, + content: 'Programs', + }, + { + type: 'item', + href: `#`, + content: 'Discover New', + }, + ], + secondaryMenu: [ + { + type: 'item', + href: `#`, + content: 'Help', + }, + ], + userMenu: [ + { + heading: 'SWITCH DASHBOARD', + items: [ + { + type: 'item', + href: `#`, + content: 'Personal', + isActive: true, + }, + { + type: 'item', + href: `#`, + content: 'Enterprise Dashboard', + }, + ], + }, + { + heading: '', + items: [ + { + type: 'item', + href: `#`, + content: 'Profile', + }, + { + type: 'item', + href: `#`, + content: 'Account', + }, + { + type: 'item', + href: `#`, + content: 'Order History', + }, + ], + }, + { + heading: '', + items: [ + { + type: 'item', + href: `#`, + content: 'Sign Out', + }, + ], + }, + ] +}; + +export const publisherHeaderData = { + mainMenu: [ + { + type: 'item', + href: `#`, + content: 'Open Courses', + disabled: true, + }, + { + type: 'item', + href: `#`, + content: 'Executive Education', + }, + { + type: 'item', + href: `#`, + content: 'Bootcamps', + }, + ], + secondaryMenu: [], + userMenu: [ + { + heading: '', + items: [ + { + type: 'item', + href: `#`, + content: 'Sign Out', + }, + ], + }, + ] +}; + + +export const supportToolsHeaderData = { + mainMenu: [ + { + type: 'item', + content: 'Confluence', + href: '#', + }, + { + type: 'item', + content: 'Support Tools', + href: '#', + }, + { + type: 'submenu', + content: 'Escalations', + submenuContent: ( + <> +
Salesforce
+
CR Requests
+ + ), + }, + { + type: 'submenu', + content: 'Payment', + submenuContent: ( + <> +
Otto
+
Cybersource
+
Paypal
+
Enterprise Coupons
+ + ), + }, + { + type: 'submenu', + content: 'Courses', + submenuContent: ( + <> +
Publisher
+
Discovery
+
Course Catalogue
+ + ), + }, + { + type: 'item', + content: 'Proctoring', + href: '#', + }, + { + type: 'submenu', + content: 'Programs', + submenuContent: ( + <> +
Learner Record
+
Credentials Search
+
Programs Discovery
+ + ), + }, + ], + secondaryMenu: [], + userMenu: [ + { + heading: '', + items: [ + { + type: 'item', + href: `#`, + content: 'Dashboard', + }, + { + type: 'item', + href: `#`, + content: 'Profile', + }, + { + type: 'item', + href: `#`, + content: 'Account', + }, + { + type: 'item', + href: `#`, + content: 'Logout', + }, + ], + }, + ] +}; + +export const learnerPortalProgramsHeaderData = { + mainMenu: [], + secondaryMenu: [], + userMenu: [{ + heading: '', + items: [{ + type: 'item', + href: `#`, + content: 'Dashboard', + }, + { + type: 'item', + href: `#`, + content: 'My Masters Degree', + }, + { + type: 'item', + href: `#`, + content: 'My Profile', + }, + { + type: 'item', + href: `#`, + content: 'Account Settings', + }, + { + type: 'item', + href: `#`, + content: 'Sign Out', + }, + ]}], +}; + +export const learnerPortalEnterpriseHeaderData = { + logo: { + src: 'https://edxuploads.s3.amazonaws.com/enterprise/branding/d1303765-90f9-4e01-9eaa-654c943fbd60/logo_66507fdd-ab5c-40dc-a849-5ecfb653027d.png', + alt: 'Enterprise logo', + href: '#' + }, + mainMenu: [ + { + type: 'item', + href: `#`, + content: 'Dashboard', + }, + { + type: 'item', + href: `#`, + content: 'Find a Course', + }, + ], + secondaryMenu: [ + { + type: 'item', + href: `#`, + content: 'Help', + }, + ], + userMenu: [ + { + heading: 'SWITCH DASHBOARD', + items: [ + { + type: 'item', + href: `#`, + content: 'Personal', + }, + { + type: 'item', + href: `#`, + content: 'Pied Piper (Non-Integrated Test Company) Dashboard', + isActive: true, + }, + ], + }, + { + heading: '', + items: [ + { + type: 'item', + href: `#`, + content: 'Profile', + }, + { + type: 'item', + href: `#`, + content: 'Account', + }, + ], + }, + { + heading: '', + items: [ + { + type: 'item', + href: `#`, + content: 'Logout', + }, + ], + }, + ] +}; diff --git a/example/index.js b/example/index.js index 2559c03d48..ecdd6d3085 100644 --- a/example/index.js +++ b/example/index.js @@ -8,6 +8,13 @@ import Header from '@edx/frontend-component-header'; import './index.scss'; import StudioHeader from '../src/studio-header/StudioHeader'; +import CustomHeader from '@edx/frontend-component-header'; +import { + learnerHomeHeaderData, learnerPortalEnterpriseHeaderData, + learnerPortalProgramsHeaderData, + publisherHeaderData, + supportToolsHeaderData +} from "./headersData"; subscribe(APP_READY, () => { ReactDOM.render( @@ -17,7 +24,7 @@ subscribe(APP_READY, () => { authenticatedUser: null, config: getConfig(), }}> -
+
Logged out state
@@ -31,37 +38,131 @@ subscribe(APP_READY, () => { }, config: getConfig(), }}> -
+ <> +

Existing Normal header

+
+
+
+
+
+
+
+
+
+
+

Normal header

+ +
+
+
+
+
+
+
+
+
+

Learner home header

+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+

Publisher header

+ +
+
+
+
+
+

Support tools header

+ +
+
+
+
+
+
+
+
+
+
+

Learner Portal Programs header

+ +
+
+
+
+
+
+
+
+
+
+

Learner Portal Enterprise header

+ +
Logged in state
- - - -
Logged in state for Studio header
+ + {/**/} + {/* */} + {/**/} + {/*
Logged in state for Studio header
*/} , document.getElementById('root'), ); diff --git a/src/DesktopHeader.jsx b/src/DesktopHeader.jsx index 8bd142fb9e..58ec256167 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 ( - - - {appMenuContent} - - - {menuItems.map(({ type, href, content }) => ( - {content} - ))} - - - ); + 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 c0db257c72..694f27b69f 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,66 @@ subscribe(APP_CONFIG_INITIALIZED, () => { }, 'Header additional config'); }); -const Header = ({ intl }) => { +/** + * Header component for the application. + * Displays a header with the provided logo, main menu, secondary menu, and user menu when the user is authenticated. + * If any of the props (logo, 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 logo + * @param mainMenuItems + * @param secondaryMenuItems + * @param userMenuItems + */ +const Header = ({ + intl, logo, 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 = [ { @@ -89,20 +106,21 @@ const Header = ({ intl }) => { ]; const props = { - logo: config.LOGO_URL, - logoAltText: config.SITE_NAME, - logoDestination: `${config.LMS_BASE_URL}/dashboard`, + logo: logo?.src || config.LOGO_URL, + logoAltText: logo?.alt || config.SITE_NAME, + logoDestination: logo?.href || `${config.LMS_BASE_URL}/dashboard`, loggedIn: authenticatedUser !== null, 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 +130,37 @@ const Header = ({ intl }) => { ); }; +Header.defaultProps = { + logo: null, + mainMenuItems: null, + secondaryMenuItems: null, + userMenuItems: null, +}; + Header.propTypes = { intl: intlShape.isRequired, + logo: PropTypes.shape({ + src: PropTypes.string, + alt: PropTypes.string, + href: PropTypes.string, + }), + 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 506deb33d0..687f446571 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 }) => ( -
  • - {content} -
  • + return userMenu.map((group) => ( + group.items.map(({ + type, content, href, disabled, isActive, + }) => ( +
  • + + {content} + +
  • + )) )); } @@ -123,6 +146,7 @@ class MobileHeader extends React.Component { className="nav flex-column pin-left pin-right border-top shadow py-2" > {this.renderMainMenu()} + {this.renderSecondaryMenu()}
    @@ -157,11 +181,18 @@ 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, + isActive: PropTypes.bool, + })), })), loggedOutItems: PropTypes.arrayOf(PropTypes.shape({ type: PropTypes.oneOf(['item', 'menu']), @@ -182,6 +213,7 @@ MobileHeader.propTypes = { MobileHeader.defaultProps = { mainMenu: [], + secondaryMenu: [], userMenu: [], loggedOutItems: [], logo: null, diff --git a/src/index.jsx b/src/index.jsx index 9d36af355e..a9ce1058c3 100644 --- a/src/index.jsx +++ b/src/index.jsx @@ -1,8 +1,3 @@ import Header from './Header'; -import LearningHeader from './learning-header/LearningHeader'; -import messages from './i18n/index'; -import StudioHeader from './studio-header'; - -export { LearningHeader, messages, StudioHeader }; export default Header;