@kleeen/core-react

kleeen-core-react

Access Control

Description

The idea behind Access Control is to provide an easy and generic way to manage the access control in your UI; kleeen-core exports a function that sets the role of the user in our context and a component to manage the content's visibility state.

Setting Access Control

setAccessControl:

The primary use for this function is to receive the permissions object and the user's role and provide a way to overwrite our acessControlChecker (the process that eval the permissions logic) and our customRenderView (function to eval the render of the permissions).

Properties

Type	Name	Description
object	accessControlSettings	The permissions object and the path to the role on the redux state
object	accessControlSettings.permissions	Permissions JSON base
string	accessControlSettings.setPathToRoleOnState	The path to the role property on redux state
function	customRenderView	Function to eval the render of the permissions
function	customAccessControlChecker	A function that eval the permissions logic

Note: the access control expects the user's role managed with redux, so it receives a redux path to the external user role. For example, if your redux store looks like this:

{
  ...moreEntities,
  user: {
    ...moreUserData,
    roleInfo: {
      ...moreRolesData,
      role: 'guest'
    }
  }
}

the path to the user role in redux should be user.roleInfo.role.

Example

import { setAccessControl } from '@kleeen/core-react';

const permissions = {
  WORKBENCH: {
    CHILDREN: {
      ACTIONS: {
        PERMISSIONS: {
          ADMIN: 'SHOW',
          GUEST: 'HIDE',
        },
      }
    }
  }
};

setAccessControl({ permissions, pathToRoleOnState: 'user.roleInfo.role' });

Access Control Component

Properties

Type	Name	Description
string	id	Permission id that should match some path on the permissions object
node	children	According to the permissions, it could be show/hide/disable
function	children	Executes the function with the user's permission to be used as the user required

Example

import { AccessControl } from "@kleeen/core-react";

// using children
<AccessControl id="LAYOUT.SEARCH_BOX">
  <input type="text" />
</AccessControl>

// using render prop
<AccessControl id="LAYOUT.HEALTH_SPARKLINE">
  {({ permission }) => (
    permission === 'SHOW'
      ? <input type="text" />
      : null
    )
  }
</AccessControl>

Note: our permissions evaluation only supports show/hide/disable, you can use others by implementing the customRenderView and/or the customAccessControlChecker and setting it on the setAccessControl function.

Icon Registry Provider

Description

Provider for using icons base on a registry (iconRegistry):

{
  name: { path: './path.svg', alt: 'Icon name' }
}

Init provider

import { IconRegistryProvider } from '@kleeen/core-react';

<KUICombineProviders providers={[
  TranslationProvider({ localeData, locale: 'en' }),
  ReduxProvider,
  IconRegistryProvider({ iconRegistry }) // take care only of this one for now
]}
>
  <App />
</KUICombineProviders>

Here we are setting more than one provider for our app, but don't worry about the KUICombineProviders or the other providers for now, basically IconRegistryProvider({ iconRegistry }) returns a react context provider so your app can have access to the icon registry anywhere (using the corresponding consumer).

Using the icon consumer

import { IconRegistryConsumer } from '@kleeen/core-react';

<IconRegistryConsumer>
  {({ getIcon }) => (
    <img className="icon" src={getIcon(kuiIcon).path} alt={getIcon(kuiIcon).alt} />
  )}
</IconRegistryConsumer>

Note: of course, we have an easy way to use an icon without the icon consumer, and it is the kui-icon (it use the consumer inside). This component and its documentation are on kleeen-components-react package.

Theming Provider

Description

Provider to change the theme of the application by adding or modifying the classes of the HTML tag.

Properties

Type	Name	Default Values
String	initialTheme

Init Provider

ThemingProvider({ themeName })

Usage

import { ThemingConsumer } from '@kleeen/core-react';

<ThemingConsumer>
  {({ setTheme }) => (
    {setTheme('newThemeName')}
  )}
</ThemingConsumer>

Translation Provider

Description

Provider for the internationalization of the application, it uses a translations object, and the structure is:

{
  "en": {
    "textKey": "English translation!"
  },
  "es": {
    "textKey": "¡Traducción español!"
  }
}

The first key means the language, plus a key for each text on your UI (or at least the strings that should support multiple languages).

This implementation bases on react-intl[https://github.com/yahoo/react-intl], and it supports the majority of features because of how the params flow.

Properties of the translation provider

Type	Name	Default Values
String	languaje	Navigator Languaje
Array	languageToSupport	[ es , en , fr , it ]
Json	localeData	{ }

You can send more params to be added to the IntlProvider from react-int.

Init Provider

TranslationProvider({ localeData, locale: 'en' })

Use for language change

import { ThemingConsumer } from '@kleeen/core-react';

<TranslationConsumer>
  {({ setLocale }) => (
    select onChange={e => setLocale(e.target.value)}>
      <option value="en">Ingles</option>
      <option value="es">Español</option>
    </select>
  )}
</TranslationConsumer>

You can consume the TranslationConsumer and change the data of the provider. You can also use the kuiConnect and receive directly through props the setLocale.

Use for translation

<Translate defaultMessage="content only for Admin">{'App.adminText'}</Translate>

you can also inject an translate function in your props in order to manage the translations with a function, this can be done with the kuiConnect.

<Fragment>{translate({ id: "App.adminText", defaultMessage: "content only for Admin" })}</Fragment>

or

<Fragment>{translate('App.adminText')}</Fragment>

KUIConnect

It allows access to all the KUI provider's context, much like the redux connect (only the concept, not in the implementation itself). So, for example, you can decorate a component with the kuiConnect, which receives a mapStateToProps function; the mapStateToProps function dictates the props injected into the decorated component (you have access to all the KUI providers context that you have in your app).

Example

import { KUIConnect } from '@kleeen/core-react';

const App = (props) => {
  render (
    const { translate, getIcon, setLocale } = props;
    return  (
     <div>
       ...
     </div>
    );
  );
};

compose(
  connect(state => state, ({ logIn })),
  KUIConnect(state => state), // injecting all that data of the providers that you have on your app.
)(App);

Combine Providers

Component that combines several providers, allows consuming components to subscribe to context changes. The properties for this function are children and providers.

Example

ReactDOM.render(
  <KUICombineProviders providers={[
    TranslationProvider({ localeData, locale: 'en' }),
    ReduxProvider,
    IconRegistryProvider({ iconRegistry }),
  ]}
  >
    <App />
  </KUICombineProviders>,
  document.getElementById('root'),
);

Combine Consumers

Function that subscribes to context changes. The properties for this function are children and consumers it should be use like the kuiConnect in a react context way.

Example

const KUIConsumers = ({ children }) => KUICombineConsumers({
  children,
  consumers: {
    theming: ThemingConsumer,
    icons: IconRegistryConsumer,
    translation: TranslationConsumer,
  },
});
<KUIConsumers>
  {({ icons, theming, translation }) => (
    {...some use for all the provider context}
  )}
</KUIConsumers>