Custom form field

On the front side

Creating the Vue component

Example of custom sharp field:

<template>
    <div>
        <input :value="value" [@change](https://github.com/change)="handleChanged">
        <emoji-picker :emoji-set="emojiSet"></emoji-picker>
    </div>
</template>

<script>
    export default {
        props: {
            value: String, // field value
            emojiSet: String   // custom added props (given in field definition)
        },
        methods: {
            handleChanged(e) {
                this.$emit('input', e.target.value); // emit input when the value change, form data is updated
            }
        }
    }
</script>

Exposed Props

Listened events

Register the custom field

Add sharp-plugin npm package to your project:

npm install -D sharp-plugin

Sharp plugin file

Add a separated .js file in your project to register fields components :

sharp-plugin.js

import Sharp from 'sharp-plugin';
import EmojiPicker from './components/EmojiPicker.vue';


Vue.use(Sharp, {
    customFields: {
        'emojiPicker': EmojiPicker
    }
})

Important: The key must be 'emojiPicker' for FIELD_TYPE = "custom-emojiPicker"

Vue is exposed to the window scope, it's the current Vue version used by sharp (cf. package.json).

::: warning It's not recommended to use other Vue plugins in this file because it may change the behavior of the Sharp front-end. :::

With Laravel Mix

webpack.mix.js

mix.js('/resources/assets/js/sharp-plugin.js', '/public/js')

::: warning The file name must be sharp-plugin.js in order to ensure Sharp will find it. :::

You can .version() this JS file if you want to.

With Vite

Publish views with:

php artisan vendor:publish --tag=sharp-views

Add your .js file to resources/views/vendor/sharp/partials/plugin-scripts.blade.php:

[@vite](https://github.com/vite)('resources/js/sharp-plugin.js')

On the back side

Activate custom fields in config

// config/sharp.php

'extensions' => [
   'activate_custom_fields' => true
],

// ...

Write the form field class and formatter

Next step is to build your form field class. It must extend Code16\Sharp\Form\Fields\SharpFormField.

Here's an example:

class SharpCustomFormFieldEmojiPicker extends SharpFormField
{
    const FIELD_TYPE = 'custom-emojiPicker';

    protected string $emojiSet = 'native';

    public static function make(string $key): self
    {
        return new static($key, static::FIELD_TYPE, new TextFormatter);
    }

    protected function validationRules(): array
    {
        return [
            'emojiSet' => 'in:native,apple,google',
        ];
    }

    public function toArray(): array
    {
        return parent::buildArray([
            'emojiSet' => $this->emojiSet,
        ]);
    }
}

A few things to note:

• The FIELD_TYPE const must be "custom-" + your custom field name, defined on the front side.
• To respect the Sharp API, you must define a static make function with at least the field key; this function must call the parent constructor, passing the $key, the FIELD_TYPE and a Formatter, which can also be a custom one ( see documentation and Code16\Sharp\Form\Fields\Formatters\SharpFieldFormatter base class).
• validationRules() implementation is optional, but advised.
• the toArray() function is mandatory, and must call parent::buildArray() with additional attributes.

Use it

Next step is using the new form field:

in some Code16\Sharp\Form\SharpForm subclass:

function buildFormFields(FieldsContainer $formFields): void
{
    $formFields->addField(
        SharpCustomFormFieldEmojiPicker::make('emoji')
            ->setLabel('Emoji')
    );
}