@openimis/fe-core
v1.8.0
Published
openIMIS Frontend Core reference module
Downloads
197
Keywords
Readme
openIMIS Frontend Core reference module
This repository holds the files of the openIMIS Frontend Core reference module. It is dedicated to be deployed as a module of openimis-fe_js and provides
- openIMIS core mechanisms (authentication,...)
- openIMIS core components (Application iteself, MainMenu, JournalDrawer,...)
- openIMIS ModulesManager (loading, configuring and wiring all modules)
- many Generic components to be (re)used in other (business-focused) openimis components
- various helpers (building GraphQL queries,...)
Core Components
App
: application pages container (all openIMIS pages are loaded within that container)AppWrapper
: wrapping main menu around each application pageJournalDrawer
: side bar in which mutation journal is displayedAlertDialog
: pop up (modal) dialog to display an alert message (one 'ok' button)ConfirmDialog
: pop up (modal) dialog to display a confirmation message (with 'cancel' / 'confirm' buttons)SelectDialog
: pop up (modal) dialog to display a message and take an action between two options (yes/no, do/do not, continue/go back) - with editable (through the props) button labels, message content and dialog title, without using Redux store and actionsFataError
: page for non-recoverable backend access errorsHelp
: main menu entry for Help (link to manual)Logout
: main menu entry to logoutKeepLegacyAlive
: component to be registered in core.Boot contribution to keep legacy openIMIS session alive while interacting with new openIMIS pagesErrorPage
: displays error messages with status, title, and optional logo. Includes navigation button to the homepage.PermissionCheck
: controls access to content based on user rights (403 error). Renders content if user has required rights, otherwise showsForbiddenPage
.ForbiddenPage
: shown when a user lacks permission to access a specific page or resource. Displays an access denied message.NotFoundPage
: appears when a user visits a non-existent route (404 error). Informs the user that the page is unavailable and suggests navigation option.InternalServerErrorPage
: displays a message for a 500 Internal Server Error, informing users of a server-side issue in the application.
LanguageQuickPicker
is a component that allows users to quickly switch between different languages. Available on user's navbar.
Generic Components (to be reused along business-focused components)
MainMenuContribution
: generic class for main menu specific contributions (with route,...)AutoSuggestion
: generic suggest-as-you-type (text)input fieldNote: cope with both pre-fetched (cached) suggestion list and query as you type (with debounce)
ConstantBasePicker
: fixed list select input fieldPicker
: dialog-based (i.e. with search criteria) picker (handles pagination,...)Contributions
: generic component to open business components for contributionsControlledField
: field that is skipped based on module configurationTextInput
,NumberInput
,AmountInput
&SelectInput
: generic input components for the various data typesValidatedTextInput
: generic input component which checks the uniqueness of entered data and gives the appropriate information about itFieldLabel
: formatting a label in a formFormattedMessage
: translated text (module/key)ProgressOrError
: display progress during component's asynchronous calls... and hide or diaply error message when asynchronous call returnsSearcher
: generic searcher page (with criteria form and result table)SearcherActionButton
: represents an action button used within a search interface.Form
: generic form. Manage dirty state, displays add/save button,...Table
: generic table. Headers (with -sort-actions), rows, optional setting - showOrdinalNumber that will show column with ordinal number as first column, ...
Helpers
Contexts
ToastContext
: This context provides toast notification functionality within the application. It enables you to easily display success, error, warning, or informational messages as toast notifications. To use it, you need to importuseToast
from@openimis/fe-core
and use one of the provided functions (e.g.,showSuccess
,showError
,showWarning
,showInfo
) to trigger different types of toast notifications.
redux actions helpers
journalize
: helper to trigger theCORE_MUTATION_ADD
action (which register a mutation in the journal)graphql
: helper to send the GraphQL queries (HTTP POST) and dispatch appropriate actions to reduxcoreAlert
: helper to open the alert modal pop (cfr. AlertDialog)coreConfirm
: helper to open the confirm modal pop (cfr. ConfirmDialog)
api
formatQuery
: helper to format a simple GraphQL query (filters and projections)formatPageQuery
: helper to format a GraphQL query (filters and projections), with pagination (edges and node)formatPageQueryWithCount
: helper to format a GraphQL query, with pagination and totalCountformatMutation
: helper to format a mutation (with clientMutationId and clientMutationLabel){de|en}codeId
: decoder|encoder for Graphene specific id mechanismparseData
: navigate thru GraphQL standard edges|node structure and parse data from json to js objectpageInfo
: extract GraphQL standard pagination info (hasNextPage,...)dispatchMutation{Req|Resp|Err}
: helper to submit a mutation and wait for response/errorformatServerError
: helper to format server error (error 500,...)formatGraphQLError
: helper to format a graphql response returning (standard) erroropenBlob
: helper to open a Blob (pdf,...) as a result of an asynchronous call
i18n
formatMessage
: provide the translation of a module-prefixed key (fall back on openimis-fe_js/translations/ref.json)formatMessageWithValues
: provide the translation of a module-prefixed key, for messages with vairable partsformatAmount
: format an amount as a stringformatDateFromISO
: parse ISO date into (local) datetimeNote: depends on the selected calendar (Gregorian vs. Nepali)
toISODate
: format local date to ISO formatNote: depends on the selected calendar (Gregorian vs. Nepali)
JSON handler
createFieldsBasedOnJSON
: Creates additional fields from a JSON string and returns an array of field objects.renderInputComponent
: Renders the appropriate input component based on the field type and value.
navigation
withHistory
: helper to inject history to any openIMIS component (allow navigation)historyPush
: helper to push a new route to openIMIS navigation
modules
withModulesManager
: helper to inject modulesManager to any openiMIS component
Available Contribution Points
core.Boot
: register components that should be mounted at application start. It allows business modules to load cache at application startup, register to redux events (even when module not yet accessed),... The components registered for this contribution should not render any HTML (render should return null)core.AppBar
: ability to add entries in the AppBar (known usage: insuree Enquiry component)core.MainMenu
: ability to add main menu entries from modules (known usage: claim, insuree,...)core.Router
: ability to register routes in client-side routing (known usage: claim, insuree,...)core.UnauthenticatedRouter
: ability to register routes in client-side routing for pages that don't require user authenticationcore.LoginPage
: ability to add components to the menu login page
Contributions
core.Boot
- KeepLegacyAlive: contributing to own contribution point in order to register the component that pings the Legacy openIMIS application to prevent session timeout while in the new part.core.Router
: registeringroles
,roles/role
routes in openIMIS client-side routeradmin.MainMenu
:Roles Management (
roleManagement.label
translation key)
Published Components
core.DatePicker
, configured date picker (Gregorian vs. Nepali)core.YearPicker
, pick a year within a rangecore.MonthPicker
, contant-based month picker. Translation keysmonth.null
,month.1
,...core.LanguagePicker
, pick from available languagescore.WarningBox
, simple alert component to show warnings or messages, with options to customize its look and size.
Dispatched Redux Actions
CORE_ALERT{_CLEAR}
: display/close the AlertDialog modal pop upCORE_CONFIRM{_CLEAR}
: display/close the ConfirmDialog modal pop upCORE_USERS_CURRENT_USER_{REQ|RESP|ERR}
: retrieve authenticated info (language, rights,...)CORE_MUTATION_{ADD|REQ|RESP|ERR}
: mutation lifecycle (request,...)CORE_HISTORICAL_MUTATIONS_{REQ|RESP|ERR}
: retrieve mutations from previous sessions (init JournalDrawer)CORE_ROLE_MUTATION_{REQ|ERR}
: sending a mutation on RoleCORE_ROLES_{REQ|RESP|ERR}
: retrieve RolesCORE_MODULEPERMISSIONS_{REQ|RESP|ERR}
: retrieve permissions of all modulesCORE_LANGUAGES_{REQ|RESP|ERR}
: retrieve available languages and their codesCORE_ROLE_{REQ|RESP|ERR}
: retrieve a single RoleCORE_ROLERIGHTS_{REQ|RESP|ERR}
: retrieve rights/permissions of a single RoleCORE_CREATE_ROLE_RESP
: receive a result of create Role mutationCORE_UPDATE_ROLE_RESP
: receive a result of update Role mutationCORE_DUPLICATE_ROLE_RESP
: receive a result of duplicate Role mutationCORE_DELETE_ROLE_RESP
: receive a result of delete Role mutationCORE_CALENDAR_TYPE_TOGGLE
: set calendar switch status between gregorian and other calendar
Other Modules Listened Redux Actions
None
Configurations Options
core.PublicPage
: This contributions point serves as the Public Page for the OpenIMIS App. To enable its use, it must be exposed as a core.PublicPage contribution point. Additionally, the database configuration variable App.enablePublicPage must be set totrue
.showJournalSidebar
: This determines whether to render the Journal sidebar or not. IMPORTANT: The Journal provides crucial information about the state of mutations, including whether they succeeded or failed. If you choose to hide it, you must ensure the user is informed of the mutation outcome - consider using toast notifications. This configuration only hides the Journal. It does not automatically add toast notifications out of the box..datePicker
: the concrete date picker to publish ascore.DatePicker
component ("ad"= Gregorian DatePicker, "ne"= Nepali calendar date picker )useDynPermalinks
: use ?dyn= when opening in new tab (prevent sending client-side routes to server while) (Default: false)core.JournalDrawer.pollInterval
: poll interval (in ms) to check for mutation status once submitted (Default: 2000)core.KeepLegacyAlive.pollInterval
: poll interval (in ms) to send the ping to legacy openIMIS (to prevent session timeout). (Default: 300000 = 5')journalDrawer.pageSize
: page size when loading (historical) mutations (Default:5
)AutoSuggestion.limitDisplay
: threshold to limit the number of items in the auto suggestions (adding 'more options...' message), default: 10AmountInput.currencyPosition
: position of the currency for the AmountInput. Choices arestart
andend
(default:start
)menuLeft
: position menu in the Drawer component on the left site of the applicationcalendarSwitch
: enable calendar switcher toggle on the navbar of the webpage. Currently supports nepali calendar. Default false.secondCalendarFormatting
: formatting options for second calendar (both picker and display), default: "DD-MM-YYYY"secondCalendarFormattingLang
: formatting language for second calendar (when displayed as saved data, not in pickers), default: "en"redirectToCoreMISConfluenceUrl
: clicking on questionmark icon will take you to coreMIS confluence page, default openIMIS manualApp.economicUnitConfig
: In the specified configuration, when the parameter is set to true, it necessitates that users are associated with an Economic Unit. If a user lacks this association, a modal will be displayed to prompt them to establish it. Until the user is linked to a unit, their only authorized action is to log out. The default configuration is false.LogoutButton.showMPassProvider
: when activated, routes the user to the saml logout page for secure session terminationLoginPage.showMPassProvider
: redirects users to the saml login page, facilitating access to mPass-protected resourcessecondCalendarType
: type of secondary calendar picker (if enabled), default "nepali"secondCalendarLocale
: locale for secondary calendar picker (if enabled), default "nepali_en"