Skip to main content

Groups

This is a collection of hooks and helpers for when requesting groups data from the API.


Underneath the hood we are using ReactQuery. So once groups have been loaded and cached, using the hook or one of these functions should give you back data immediately until the cache times out.

These functions are all read only, adding/modifying/deleting groups is not supported here.

In the current version, groups data is not returned in any specific order. It is expected your component will handle its own sorting for the time being. We may add additional features like sorting and searching in a future version. If you need those or any other functionality we are currently missing, please contact Cloud9erz and let us know so we can consider it for a future revision.


useGroups​

Purpose​

  • Gives your React component access to groups

Usage​

const { groups, groupsAreLoading } = useGroups()

Note, groups will always return as an array, so you don't ever have to worry about it being null.

There are two optional callbacks that can be passed in for onSuccess and onError. However, in many cases they will not be needed. useGroups will automatically display an error toast to the user and report the issue to the error reporting service if no onError is passed in. If you do provide one, you will be responsible for notifying the user, but we will still automatically report the error to the error reporting service.

Also, you should primarily rely on the groupsAreLoading boolean to determine when groups data has been made available, rather than tracking additional state if possible, so only use onSuccess if you need to trigger a side effect.

const { groups, groupsAreLoading } = useGroups({
  onError: (error) => {},
  onSuccess: () => {},
})

When a customer team has content visability set to only allow users to see things that belong to their group or child groups, we often restrict the list of available groups to only include ones they can access. The filter is available via the prop: filterHidden.

const { groups } = useGroups({ filterHidden: true })

Additionally, if you need to transform the data or apply your own client-side filter, you can pass a select function as you would with bare React Query.

const { groups: groupIds } = useGroups({
  select: (groups) => {
    return groups.map((group) => String(group.id))
  },
})

Example​

function MyComponent() {
  const { groups, groupsAreLoading } = useGroups({
    select: (groups) =>
      groups.map((group) => ({ ...group, value: group.name })),
  })

  return (
    <Filter>
      <MultiSelectSearch
        menuOpen
        menuMinWidth="100%"
        menuMaxWidth="100%"
        disabled={!groupsAreLoading}
        handleApply={applyFilter}
        listItems={groups}
      />
    </Filter>
  )
}


getGroups​

Purpose​

  • Allows your non-React module to request groups

Usage​

To get all groups:

const { groups, error } = await getGroups()

To get only groups visible to the user based on team content settings:

const { groups, error } = await getGroups({ filterHidden: true })

To get a specific list of groups:

const { groups } = await getGroups({ ids: [101, 222, 404] })

Note, error will come back undefined unless there is an error. And just like with useGroups, an error toast notification will be displayed automatically by default. An error reporting service report will be made regardlessly.

If you would like to suppress the built-in error toast and handle yourself, pass in the option { disableToast: true }

Example​

async function getRootGroups() {
  const { groups, error } = await getGroups({
    filterHidden: true,
    disableToasts: true,
  })

  if (error) {
    errorToast('My custom error message')
    return []
  }

  return groups.filter((group) => group.parent_id === null)
}


getGroupById​

Purpose​

  • Lets you request a single group

Usage​

const { group, error } = await getGroupById({ id: 123 })

Example​

async function getUsersGroupName() {
  const { user } = getAuthContext()
  const { group, error } = await getGroupById({ id: user.group.id })

  if (error) {
    handleError(error)
    return null
  }

  return group.name
}


refreshGroupsCache​

Purpose​

  • Executing this function will tell ReactQuery to mark the cache as stale, and will fetch new data when you trigger the next query. Note the old data will be displayed until the API has responded with fresh data just as it would after it has timed out normally.

⚠️ Warning: reloading groups is expensive and can take a very long time for some of our larger customers. This should be used sparingly

Usage​

refreshGroupsCache()