AI-KIT: Common
This is the frontend library for the AI-KIT module Common.
Use it in conjunction with the django package django-ai-kit-common
in order to get a functioning Common running in your app in no time.
Installation
You can easily install AI-KIT: Common via npmjs. Using npm, run
npm install ai-kit-common
Using yarn, run
yarn add ai-kit-common
Quickstart
ai-kit-common
has a number of peer dependencies that you need to install yourself before you get started:
react@^16.8.0
@material-ui/core@^4.9.0
@material-ui/icons@^4.9.0
API Reference
-
Material Theme
Menu
DefaultTheme
This library provides the default Material Theme used by all AI-Kit Modules. You can use this theme for other projects as well or overwrite or extend it as you wish.
Usage
Wrap the Components that you want to be styled in a <ThemeProvider>
;;; ;
See the excellent Material-UI Docs on how to access the theme in a component.
Fonts
AI-Kit-Theme was designed with the Josefine Sans
and Nunito Sans
fonts in mind.
These fonts will not be automatically loaded by Material-UI.
The developer is responsible for loading all fonts used in their application.
An example of this would be using Google's CDN, pasting the following line in your index.html
's <head>
.
<link href="https://fonts.googleapis.com/css?family=Josefin+Sans:300i,400,600|Nunito+Sans:400,400i,600&display=swap" rel="stylesheet">
If you do decide to extend or edit the provided Default Theme, make sure to include the right fonts in all the necessary weights and styles.
DefaultPrimaryColor
DefaultPrimaryColor is a Color Palette providing the different HUE-values of the primary color used in the DefaultTheme. You can access a color via this object, should you somehow need it's color code in you Component.
DefaultSecondaryColor
DefaultSecondary is a Color Palette providing the different HUE-values of the secondary color used in the DefaultTheme. You can access a color via this object, should you somehow need it's color code in you Component.
Menu
MobileProps
This interface describes the props passed to several components which need to render depending on whether the layout is in mobile or desktop mode. Its fields are
mobile?: boolean
: whether or not the mobile version is rendered.onClose?: () => void
: a callback that closes the drawer in mobile mode.
Menu Description
In order to describe menus and submenus, you need to provide data structures
according to the MenuContent
interface. It contains the following fields:
label: string
: the name of the menu, displayed to the user. It should concisely and accurately describe the collection of submenu items or the action performed when this item is clicked.icon?: JSX.Element
: the icon is shown to the left of the label and is completely optionalaction: MenuContent[] | () => void | string
: if theaction
is a list of further contents, the element is treated as a submenu. If it is a function, it is treated as a terminal item, and the function is called whenever the menu item is clicked. If it is a string, it is treated as a location path, and a react routerNavLink
is wrapped around it in order to apply a different style if the corresponding route is active. When the link is clicked, the application navigates to the specified location.
Besides the general MenuContent
, there are more restrictive types which limit the
number of submenu levels. MenuLeaf
allows only functions or strings as actions, so there are
no submenus. MenuMaxOneLevel
allows for functions, strings, and lists of MenuLeaf
s, i.e.
it allows for menus with a maximum level of one. MenuMaxTwoLevels
allows for functions, strings
and lists of MenuMaxOneLevel
s, so it has a maximum level of two.
These limits are checked by typescript at compile time, so you can get around this
limitation by casting higher level menus via as
operator, or using plain javascript
in the first place, although it is not recommended.
Header Menu
This component renders a single menu bar at the top of your application. You can fill it with a logo, a classical popup-menu, toolbar items and user information. It is responsive, so on screens too small to contain all the content, the menu transforms to a drawer menu, which opens when the user clicks the menu icon.
Props
desktopClasses?: HeaderMenuDesktopClasses
: css classes to style the desktop version of the header menu. For a list of possible keys, see below.ToolbarClasses?: ToolbarProps['classes']
: css classes to style the toolbar. Refer to the Toolbar API for a precise definition.logo?: (props:
MobileProps
) => ReactElement
: the logo to be displayed on the left in desktop mode and on the right in mobile mode.user?: User|null
: Information about the logged in user, which will be shown on the right in desktop mode and in the drawer in mobile mode.null
means that no user is logged in and login/register buttons are shown if possible. TheUser
interface containsusername: string
: is shown in both desktop and mobile modesemail?: string
: is shown in mobile mode onlyavatar?: string
: a url to the image shown as the user's avatar image. If it is not provided, a colored circle with the username's first letter in it will be used instead. Only provide one ofuser
oruserElement
!
userElement?: null|(props:
MobileProps
) => ReactNode
: A custom display of user info, in case the default display does not suit your needs. A value ofnull
means that no user is logged in and login/register buttons are shown if possible. Only provide one ofuser
oruserElement
!userMenu?:
MenuMaxOneLevel
[]
: definition of the user menu. In desktop mode it is a popup menu, in mobile mode, the entries are rendered below the user information in the drawer.loggedOutActions?: LoggedOutActionProps
: callbacks for login and register actions.LoggedOutActionProps
contains the following fields:loginAction: string|() => void
: is visited or called when the login button is clicked. You could redirect to your login page or open a login modal for instance.registerAction?: string|() => void
: is visited or called when the register button is clicked. You could redirect to your register page or open a register modal for instance. IfloggedOutActions
is not provided, no login/register buttons are rendered. Likewise, if only theloginAction
is provided, only the login button is rendered.
toolbarContent?: (props:
MobileProps
) => ReactNode
: A list of toolbar items to be displayed in the menu bar, in both desktop and mobile mode. Toolbar items are displayed on the right, next to the user information in desktop mode and on the left, next to the menu icon, in mobile mode.menuDefinition?:
MenuMaxTwoLevels
[]
: a list of menu item definitions. In desktop mode, for each of the entries, a menu item is placed in the menu bar, which when clicked opens a popup beneath itself containing the submenu items. In mobile mode, all items are rendered as sections in the drawer.drawerWidth?: number|string
: width of the drawer that opens when clicking on the menu icon in mobile mode (default 330px)
Example
; ;
Side Menu
The side menu is a special material-ui Drawer. It accepts a few additional props and renders a menu among other things. As developer, you are responsible for managing the open state of it, meaning it is not responsive on its own.
Props
- All props inherited from Drawer
logo?: ReactNode
: The logo is shown in the top part of the drawer, in an area which is 90px tall and hides overflow.menuDefinition?:
MenuMaxOneLevel
[]
: a list of menu item definitions. All items are rendered as sections in the drawer.onClose?: () => void
: althoughDrawer
contains anonClose
property, notice the signature change. This function will be called whenever the user clicks on the background, hits the escape key, or clicks on a menu item that has no submenu. However, no parameters are passed to the function.drawerWidth?: number|string
: The width of the drawer, which is evaluated like css. Default: 330px.variant?: 'permanent'|'persistent'|'temporary'
: Same as inDrawer
, however, the default here is'permanent'
.open?: boolean
: Same as inDrawer
, however, the default here istrue
.menuRef?: MutableRefObject<HTMLDivElement|null>
: A reference, that will be pointed to the underlying<nav>
tag.
Example
; ;
Full Layout
The full layout combines a side menu and a header menu. In desktop mode on wide screens, it renders a permanent side menu and a header menu with separate menu items. The logo only appears in the side menu. In mobile mode on smaller screens, it renders a mobile mode header menu only, which brings with it its own drawer. For this mode, both menu descriptions are merged into one, so no menu items disappear between desktop and mobile mode.
Props
desktopClasses?: HeaderMenuDesktopClasses
: css classes to style the desktop version of the header menu. For a list of possible keys, see below.ToolbarClasses?: ToolbarProps['classes']
: css classes to style the toolbar. Refer to the Toolbar API for a precise definition.logo?: (props:
MobileProps
) => ReactElement
: the logo to be displayed on the left in desktop mode and on the right in mobile mode.user?: User|null
: Information about the logged in user, which will be shown on the right in desktop mode and in the drawer in mobile mode.null
means that no user is logged in and login/register buttons are shown if possible. TheUser
interface containsusername: string
: is shown in both desktop and mobile modesemail?: string
: is shown in mobile mode onlyavatar?: string
: a url to the image shown as the user's avatar image. If it is not provided, a colored circle with the username's first letter in it will be used instead. Only provide one ofuser
oruserElement
!
userElement?: null|(props:
MobileProps
) => ReactNode
: A custom display of user info, in case the default display does not suit your needs. A value ofnull
means that no user is logged in and login/register buttons are shown if possible. Only provide one ofuser
oruserElement
!userMenu?:
MenuMaxOneLevel
[]
: definition of the user menu. In desktop mode it is a popup menu, in mobile mode, the entries are rendered below the user information in the drawer.loggedOutActions?: LoggedOutActionProps
: callbacks for login and register actions.LoggedOutActionProps
contains the following fields:loginAction: string|() => void
: is visited or called when the login button is clicked. You could redirect to your login page or open a login modal for instance.registerAction?: string|() => void
: is visited or called when the register button is clicked. You could redirect to your register page or open a register modal for instance. IfloggedOutActions
is not provided, no login/register buttons are rendered. Likewise, if only theloginAction
is provided, only the login button is rendered.
toolbarContent?: (props:
MobileProps
) => ReactNode
: A list of toolbar items to be displayed in the menu bar, in both desktop and mobile mode. Toolbar items are displayed on the right, next to the user information in desktop mode and on the left, next to the menu icon, in mobile mode.headerMenuDefinition?:
MenuMaxTwoLevels
[]
: a list of menu item definitions. In desktop mode, for each of the entries, a menu item is placed in the menu bar, which when clicked opens a popup beneath itself containing the submenu items. In mobile mode, all items are rendered as sections in the drawer.sideMenuDefinition?:
MenuMaxOneLevel
[]
: a list of menu item definitions. These items are always displayed in the side menu bar.drawerWidth?: number|string
: width of the drawer that opens when clicking on the menu icon in mobile mode (default 330px)
Example
; ;