editorShape

Description

Optional. An array of objects containing settings for managing the appearance and functionality of the Kanban editor

Usage

editorShape?: [
    {
        // common parameters for all types
        type: string, 
        key: string, 
        label?: string, 
        
        // for a "dateRange" type only
        key: {
            start: string,
            end: string
        },

        // for "date" and "dateRange" types
        format?: string, 

        // for "combo", "select" and "multiselect" types only
        values?: [ 
            {
                id: string | number,
                label: string,
                avatar?: string // for a "multiselect" type only
            },
            {...} // other options
        ],

        // for a "color" type only
        values?: array, 
        config?: {
            placeholder?: string,
            clear?: boolean
        },

        // for "text" and "textarea" types only
        config?: {
            placeholder?: string,
            readonly?: boolean,
            focus?: boolean,
            disabled?: boolean,
            inputStyle?: string
        },

        // for a "progress" type only
        config?: {
            min?: number,
            max?: number,
            step?: number
        },
        
        // for a "files" type only
        uploadURL?: string | function,
        config?: {
            accept?: string,
            disabled?: boolean,
            multiple?: boolean,
            folder?: boolean
        },

        // for a "comments" type only
        config?: {
            format?: string,
            placement?: "page" | "editor",
            html?: boolean
        };
    },
    {...} // other fields settings
];

Parameters

To configure the editor appearance and functionality, you can specify the following parameters (fields):

- Common parameters for all types

• type - (required) an editor field type

important

In the Kanban editor you can use the following types of fields: combo, select, multiselect, color, text, textarea, progress, files, date, dateRange, comments and links

• key - (required) an editor field key. Here you need to use the value specified in the cardShape property. See the example below:

    // card appearance settings
    const cardShape = { 
        ...kanban.defaultCardShape,
        headerFields: [
            { // custom field
                label: "Custom field",
                css: "custom_style",
                key: "custom_key"
            }
        ]
    };
    // editor appearance settings
    const editorShape = [
        {
            label: "Custom field",
            type: "text",
            key: "custom_key"
        }
    ];

• label - (optional) an editor field label

- Parameters for a "dateRange" type

• key - (required) an object of keys of the editor field. Here you can specify the following parameters:
  • start - (required) a start date key
  • end - (required) an end date key

important

The values of these keys used in the cardShape property!

• format - (optional) defines format of "date" and "dateRange" controls. The available parameters can be found here

- Parameters for "combo", "select" and "multiselect" types

• values - (optional) an array of objects containing the dropdown options data. Here you can specify the following parameters:
  • id - (required) an option ID
  • label - (required) an option label
  • avatar - (optional) a path to the option preview image (for a "multiselect" type only)

important

To set the control for assigning one user, you need to use the "select" or "combo" types! For assigning several users, use the "multiselect" type.

- Parameters for a "color" type

• values - (optional) an array with valid HEX codes
• config - (optional) a configuration object of the "color" field. Here you can specify the following parameters:
  • placeholder - (optional) a placeholder value
  • clear - (optional) shows/hides a "clear" icon

- Parameters for "text" and "textarea" types

• config - (optional) a configuration object of the "text" and "textarea" fields. Here you can specify the following parameters:
  • placeholder - (optional) a placeholder value
  • readonly - (optional) enables/disables a readonly mode
  • focus - (optional) enables/disables a focus
  • disabled - (optional) enables/disables a field
  • inputStyle - (optional) a custom css style

- Parameters for a "progress" type

• config - (optional) a configuration object of the "progress" field. Here you can specify the following parameters:
  • min - (optional) a min value
  • max - (optional) a max value
  • step - (optional) a step of moving the progress bar slider

- Parameters for a "files" type

• uploadURL - (optional) a URL of the editor uploader. See the detail below

Details

The uploadURL property can be specified as string or function. The following example shows how to set upload URL via function:

uploadURL: rec => {
    const formData = new FormData();
    formData.append("upload", rec.file);

    const config = {
        method: "POST",
        body: formData,
        headers: {
            'Authorization': 'Bearer ' + token  // token or other headers here
        }
    };

    return fetch(url + "/uploads", config) // URL here
        .then(res => res.json())
        .then(
            data => {
                rec.id = data.id;
                return data;
            },
            () => ({ id: rec.id, status: "error" })
        )
        .catch();
}

where rec is the only parameter of the function and is an extended PointerEvent object (native type plus 4 our properties):

interface UploadEvent extends PointerEvent {
	id: number;
	status: "client" | "server" | "error"; // which means in plain English "not sent yet", "sent successfully", "something went wrong, so not sent"
	name: string; // the name of the file
	file: string | Blob; // the file
}

• config - (optional) a configuration object of the "files" field. Here you can specify the following parameters:
  • accept - (optional) a file type to be uploaded ("image/*", "video/*", "audio/*" and other)
  • disabled - (optional) enables/disables uploading files
  • multiple - (optional) enables/disables uploading multiple files
  • folder - (optional) enables/disables uploading folders

- Parameters for a "comments" type

• config - (optional) a configuration object of the "comments" field. Here you can specify the following parameters:
  • format - (optional) - a date format of the comments. The available formats can be found here
  • placement - (optional) - a place the comments will be displayed. You can set this property to the following values:
    • "editor" - comments will be displayed in the editor
    • "page" - comments will be displayed in a separate panel
  • html - (optional) - enables/disables using of the HTML markup in comments

info

Unless you specify the editor settings via the editorShape property, the widget will apply a defaultEditorShape set of parameters!

Default config

const defaultPriorities = [
    { id: 1, color: "#FF5252", label: "high" },
    { id: 2, color: "#FFC975", label: "medium" },
    { id: 3, color: "#0AB169", label: "low" }
];

const defaultColors = [ "#65D3B3", "#FFC975", "#58C3FE" ];

const defaultEditorShape = [
    { key: "label", type: "text", label: "Label" },
    { key: "description", type: "textarea", label: "Description" },
    { key: "priority", type: "combo", label: "Priority", values: defaultPriorities },
    { key: "color", type: "color", label: "Color", values: defaultColors },
    { key: "progress", type: "progress", label: "Progress" },
    { key: "start_date", type: "date", label: "Start date" },
    { key: "end_date", type: "date", label: "End date" }
];

Example

const users = [ // user data
    { id: 1, label: "John Smith", avatar: "../assets/user.jpg" },
    { id: 2, label: "Aaron Short" }
];

const editorShape = [ // editor settings
    ...kanban.defaultEditorShape, // include the default settings
    { // add custom fields
        type: "multiselect",
        key: "users",
        label: "Users",
        values: users
    },
    {
        type: "comments",
        key: "comments",
        label: "Comments",
        config: {
            format: "%M %d",
            placement: "page",
            html: true,
        },
    },
    {
        type: "links",
        key:"links",
        label: "Links",
    }
];

new kanban.Kanban("#root", {
    cards,
    columns,
    editorShape,
    // other parameters
});

Change log:

• The dateRange type was added in v1.3
• The comments and links types of editor, and format parameters were added in v1.4

Related articles: Configuration