README

What it's about

This plugin is a small React app that interacts with the Wordpress global store. It expoeses a custom React hook on the window property 24hrchecklist to handle state and easily keep it in sync with the global store.

In the future I'm planning to create an npm package for the hook since it isn't the most optimal to get it from the window since you'll have to take into account how the scripts loads.

Download

You can download the plugin here.

Install

Extract the zip file into your wordpress plugins folder like any other plugin and then activate it.

How to use

Okay, let the fun begin. You want to render a component with an input field that you want to display the valid status of in the checklist. So how do we do that?

Before we begin

One important first step is to make sure the checklist script is loaded BEFORE our component that want to use it. To do that you'll have to add 24hr_checklist_script to dependency in wp_register_script function in your block plugin.

Example:

wp_register_script(
    'components-resurs-block-js',
    plugins_url( '/dist/blocks.build.js', dirname( __FILE__ ) ),
    array( '24hr_checklist_script', 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-editor' ), // <-- Important!
    null,
    true // Enqueue the script in the footer.
);

Now we can be assured that the checklist script is loaded before our block/blocks.

Use the hook

The plugin exposes a property called _24hrchecklist_ on the window object which is the whole store instance with some different methods attached to it. We want to use the useChecklist function since this is the hook we're after.

The useChecklist hooks has the following takes the following argument:

const [value, setValue] = useChecklist(label: string, defaultValue: any, options: {
    validator?: function(field: object): boolean,
    description?: string,
    descriptionOnInvalid?: boolean,
    useInitialValue?: boolean, // Whether to treat the initialValue as a reference and watch it for changes. Defaults to false.
})

The custom validator option is a callback which receives the field object.

// Field object
{
    id: string,
    value: any,
    valid: boolean,
    name: string,
    description?: any, // React elements can be passed!
    descriptionOnInvalid?: boolean
}

Example

const { useChecklist } = window._24hrchecklist_; // If this fails, make sure you've added the script as dependency

// This will make name required to not be empty.
const [name, setName] = useChecklist('Name', '');

// Only valid if age is more than 18
const [age, setAge] = useChecklist('Age', 'Enter your age...', {
    validator: field => parseInt(field.value) > 18,
});

// You can also pass it a description. This will show a tooltip next to the item in the checklist.
const [age, setAge] = useChecklist('Age', '', {
    validator: field => parseInt(field.value) >= 18,
    description: <p>You'll need to be 18 or more for this to work.</p>,
    // If you only want to display the description if the field is invalid. Defaults to false:
    descriptionOnInvalid: true,
});

// If you set data in your attributes and want to keep the required status in sync with that value
// you can pass it as a reference with the useInitialValue option set to true.
// With this you don't have to call the set function whenever the value of the initialValue changes. You can of course do it if you want to.
const [age] = useChecklist('Age', props.attributes.age, {
    validator: field => parseInt(field.value) >= 18,
    description: <p>You'll need to be 18 or more for this to work.</p>,
    useInitialValue: true,
});

// Use the age
<input value={age.value} onChange={e => setAge(e.target.value)} />;

// Use the age as an attribute
<input value={age.value} onChange={e => props.setAttributes({ age: e.target.value })} />;

That's cool and all, but where's the list?

You'll find the list in the Document menu to the right. invalid

When a field is invalid it has a red background and it also disabled the save button. When valid it looks like this: invalid

24hr / checklist-gutenberg-plugin

Maintainers

Details