@webiny/app-aco v5.39.5

@webiny/app-aco

A set of frontend aco-related utilities.

Table of Contents

• Installation
• Overview
• Reference
  • Components
    • FoldersProvider
    • FolderTree
    • FolderDialogCreate
    • FolderDialogUpdate
    • FolderDialogDelete
  • Hooks
    • useFolder
    • useLinks

Installation

npm install --save @webiny/app-aco

Or if you prefer yarn:

yarn add @webiny/app-aco

Overview

The @webiny/app-aco package contains essential aco-related utilities (Advanced Content Organisation), that can be used within a React app. These include the FoldersProvider provider component, the useFolders and useLinks hooks, which can be used to retrieve the current folder and link information and interact with them.

ℹ️ INFO

Internally, the FoldersProvider provider retrieves information from the Webiny's default GraphQL API. Because of this, note that this project relies on @webiny/api-aco when it comes to retrieving folders and links information (via GraphQL).

Reference

Components

FoldersProvider

export declare const FoldersProvider: React.FC;

The FoldersProvider is a provider component, which retrieves the folders and links information. The component also makes it possible to use the useFolders and useLinks hook, which can be used to list, create, update or delete folders and links within the React app.

import React from "react";
import { FoldersProvider } from "@webiny/app-aco";

export const App = () => {
  return (
    <FoldersProvider>
      <MyApp />
    </FoldersProvider>
  );
};

FolderTree

import { NodeModel } from "@minoru/react-dnd-treeview";
import { DndItemData } from "~/types";

interface Props {
    type: string;
    title: string;
    onFolderClick: (data: NodeModel<DndItemData>["data"]) => void;
    onTitleClick?: (event: React.MouseEvent<HTMLElement>) => void;
    focusedFolderId?: string;
}

declare function FolderTree(props: Props): React.FC;

FolderTree component shows the tree list of folders for a particular type.

import React from "react";
import { FolderTree } from "@webiny/app-aco";

export const MyComponent = () => {
    return (
        <FolderTree
            type={"page"}
            title={"All pages"}
            onFolderClick={item => console.log(item)}
            onTitleClick={() => console.log("Do whatever you like on title click")}
            focusedFolderId={"anyExistingId"}
        />
    );
};

ℹ️ INFO

Internally, the FolderTree uses react-dnd-treeview to render and manage the folder list: DO NOT rely on any of this package features, we might change it in the future.

FolderDialogCreate

import { DialogOnClose } from "@webiny/ui/Dialog";

interface Props {
    type: string;
    open: boolean;
    onClose: DialogOnClose;
    parentId?: string | null;
}

declare function FolderDialogCreate(props: Props): React.FC;

FolderDialogCreate component shows a dialog to allow users to create a new folder.

import React, { useState } from "react";
import { FolderDialogCreate } from "@webiny/app-aco";

export const MyComponent = () => {
    const [dialogOpen, setDialogOpen] = useState(false);
    
    return (
        <>
            <button onClick={() => setDialogOpen(true)}>Create folder</button>
            <FolderDialogCreate
                type={"page"}
                open={dialogOpen}
                onClose={() => setDialogOpen(false)}
                parentId={"anyParentId"}
            />
        </>
    );
};

FolderDialogUpdate

import { DialogOnClose } from "@webiny/ui/Dialog";

interface Props {
    folder: FolderItem;
    open: boolean;
    onClose: DialogOnClose;
}

declare function FolderDialogUpdate(props: Props): React.FC;

FolderDialogUpdate component shows a dialog to allow users to update an existing folder.

import React, { useState } from "react";
import { FolderDialogUpdate } from "@webiny/app-aco";

type Props = {
    folder: FolderItem;
}

export const MyComponent = ({ folder }: Props) => {
    const [dialogOpen, setDialogOpen] = useState(false);
    
    return (
        <>
            <button onClick={() => setDialogOpen(true)}>Edit folder</button>
            <FolderDialogUpdate
                folder={folder}
                open={dialogOpen}
                onClose={() => setDialogOpen(false)}
            />
        </>
    );
};

FolderDialogDelete

import { DialogOnClose } from "@webiny/ui/Dialog";

interface Props {
    folder: FolderItem;
    open: boolean;
    onClose: DialogOnClose;
}

declare function FolderDialogDelete(props: Props): React.FC;

FolderDialogDelete component shows a dialog to allow users to delete an existing folder.

import React, { useState } from "react";
import { FolderDialogDelete } from "@webiny/app-aco";

type Props = {
    folder: FolderItem;
}

export const MyComponent = ({ folder }: Props) => {
    const [dialogOpen, setDialogOpen] = useState(false);
    
    return (
        <>
            <button onClick={() => setDialogOpen(true)}>Delete folder</button>
            <FolderDialogDelete
                folder={folder}
                open={dialogOpen}
                onClose={() => setDialogOpen(false)}
            />
        </>
    );
};

Hooks

useFolders

import {FolderItem, FoldersActions} from "./types";

interface UseFoldersHook {
    folders: FolderItem[];
    loading: Record<FoldersActions, boolean>;
    getFolder: (id: string) => Promise<FolderItem>;
    createFolder: (folder: Omit<FolderItem, "id">) => Promise<FolderItem>;
    updateFolder: (folder: FolderItem) => Promise<FolderItem>;
    deleteFolder(folder: FolderItem): Promise<true>;
}

export declare function useFolders(type: string): UseFoldersHook;

useFolders hook allows you to interact with folders state and related APIs while building your custom component.

import React from "react";
import { useFolders } from "@webiny/app-aco";

export const MyComponent = () => {
    const { folders } = useFolders("page");
    
    if (folders) {
        return folders.map(folder => {
            return <span key={folder.id}>{folder.name}</span>;
        });
    }
    
    return <span>No folders to show</span>;
};

As you might notice, there is not listFolders method available from useFolders() hook: this is because on first mount, listFolders is called internally, which will either issue a network request, or load folders from cache.

You don't need to store the result of it to any local state; that is managed by the context provider.

useLinks

import { LinkItem, LinksActions } from "./types";

interface UseLinksHook {
    links: LinkItem[];
    loading: Record<LinksActions, boolean>;
    getLink: (id: string, folderId: string) => Promise<LinkItem>;
    createLink: (link: Omit<LinkItem, "linkId">) => Promise<LinkItem>;
    updateLink: (link: LinkItem, contextFolderId: string) => Promise<LinkItem>;
    deleteLink(link: LinkItem): Promise<true>;
}

export declare function useLinks(folderId: string): UseLinksHook;

useLinks() hook allows you to interact with folders links state and related APIs while building your custom component.

import React, { useEffect, useState } from "react";
import { useLinks } from "@webiny/app-aco";

import { getEntryDetails } from "./any-custom-hook"

export const MyComponent = () => {
    const { links } = useLinks("anyFolderId");
    const [entries, setEntries] = useState([]);
    
    useEffect(() => {
        const details = getEntryDetails(links);
        setEntries(details)
    }, [links])
    
    if (entries) {
        return entries.map(entry => {
            return <span key={entry.id}>{entry.name}</span>;
        });
    }
    
    return <span>No entries to show</span>;
};

As you might notice, there is not listLinks method available from useLinks() hook: this is because on first mount, listLinks is called internally, which will either issue a network request, or load links from cache.

You don't need to store the result of it to any local state; that is managed by the context provider.