🧰 Q3 Admin

Containers

Admin

Q3 admin ships with a default component that handles most state and routing for you. As such, there's a lot of props available to customize this setup process. Most are optional and used in more advanced cases.

API

| Prop | Description | Type | | -------------------- | ---------------------------------------------------------------- | -------- | | AppProps.directory | The relative path where Q3 renders (i.e. /app/) | string | | AppProps.pages | Collections to render. See AbstractBuilder for data structure. | array |

Example

import React from 'react';
import Admin from 'q3-admin';
import { Builders } from 'q3-ui-forms';
import Tests from './components/Tests';

export default () => (
  <Admin AppProps={{ pages }}>
    <Tests path="/tests" />
  </Admin>
);

Detail

The container for viewing individual documents in Q3. When using the builders, properties of genDetail and genDetailProps are assembled into this container.

API

| Prop | Description | Type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------- | | registerOptions | Used to register custom UI elements in the detail side panel. Options can be programmatically setup or inferred (see example below). | func/array* | | registerPanels | Same as above for usage, though this prop is intended for lengthier content and actions. | func/array* |

Example

// programmatic method
export const registerOptions = (data, dispatchers, t) => {
  const out = [];
  if (data.isOn)
    out.push({
      title: t('titles:hello'),
      component: () => null,
    });

  return out;
};

// inferred method
export const registerPanels = [
  {
    // is localized
    title: 'hello',
    // receives all params from method above
    component: ({ data, dispatchers, t }) => null,
    // runs through comparisons for easy conditional rendering
    conditions: ['foo=1'],
  },
];

Gatekeeper

The container for checking user authentication. Redirects users if necessary.

API

| Prop | Description | Type | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | redirectCheck | Redirects users when the function returns a string. The function can take user profile as an argument. Note: redirectPathOnPublic and redirectPathOnSession are evaluated before this function. | func | | redirectPathOnSession | Redirects a user when logged in and this prop is a string. | string | | redirectPathOnPublic | Redirects a user when not logged in and this prop is a string | string | | children | children will be returned when none of conditions are true | node |

Example

import { Gatekeeper } from  'q3-admin/lib/containers';
import  IsBrowserReady  from  'gatsby-theme-q3/src/components/IsBrowserReady';

const shouldRedirect = (auth) => auth.role === 'Employer" ? '/employers' : undefined;

const AdminPrivateGateway = ({ children, ...rest }) => {
	return (
		<IsBrowserReady>
			<Gatekeeper
				redirectCheck={shouldRedirect}
				redirectPathOnPublic="/login"
				{...rest}
			>
				{children}
			</Gatekeeper>
		</IsBrowserReady>
	);
};

Components

SidePanelAction

This component standardizes the UI for single-click actions in the Detail SidePanel implementation.

API

| Prop | Description | Type | | ------------- | ------------------------------------ | --------- | | description | A key for the descriptions namespace | string* | | label | A key for the labels namespace | string* | | onClick | A callback for the default button | func* |

Example

import { SidePanelAction } from 'q3-admin/lib/components';

export default ({ isOn, update }) => (
  <SidePanelAction
    description="enableFeature"
    label={isOn ? 'off' : 'on'}
    onClick={update(!isOn)}
  />
);

Hooks

useIo

Returns exportCollection and importCollection for connecting to Q3 API's process automation. Both methods are curried and intended for use with click handlers. Note that this hook does not actual call React hooks API, so it may be used in non-components.

API

| Parameter | Description | Type | | --------- | ----------------------------------------------------------- | -------- | ------ | | ids | Document IDs to target in the bulk operation | string | array | | params | Location URL parameter methods (i.e. delete, set, toString) | object |

Example

import { useIo } from 'q3-admin/lib/hooks';
import { withLocation } from 'with-location';

export default withLocation(({ params }) => {
  const { exportCollection } = useIo(1, params);
  return (
    <button
      type="button"
      onClick={exportCollection('templateName')}
    >
      Export ID #1
    </button>
  );
});