# Custom Handler Schema Reference This guide is for plugin developers who want to add FrontEdit support for a custom Gutenberg block. It documents the public schema contract used by custom handler plugins. Custom handlers are experimental. Build and test them on a staging site before using them on production content. ## Compatibility requirement FrontEdit saves edits by parsing and serializing the native Gutenberg block: ```js wp.blocks.parse( rawBlockContent ); wp.blocks.serialize( blocks ); ``` Before writing a handler for a non-core block, confirm that its provider has already registered the block on the editable frontend page. This registration must include the block's client-side attributes and its matching `save` implementation. ```js wp.blocks.getBlockType( 'your-namespace/your-block' ); ``` The command must return a block definition. If it returns `undefined`, do not add a FrontEdit handler yet. An editor-only provider script is not compatible with FrontEdit and must not be enqueued from a custom handler. Loading an editor-only bundle on the frontend can cause fatal errors, missing browser dependencies, or serialized content that loses provider settings. Core WordPress blocks are registered by FrontEdit. For a custom or third-party block, the block provider is responsible for the compatible frontend registration surface. ## Create a custom handler plugin Copy the `templates/frontedit-live-block-editor-custom-handlers` folder shipped with FrontEdit into `wp-content/plugins`, rename it, and activate it. Its bootstrap registers a PHP handler file through the `mwpsfe_external_handler_files` filter. Handler classes use the `MWPSFE` namespace and extend FrontEdit's public abstract handler classes. Give every PHP class a unique name. A handler ID that matches a built-in ID intentionally replaces that built-in registration. An edit handler normally extends `MWPSFE_Abstract_Text_Edit_Handler` and implements `MWPSFE_Schema_Handler_Interface`. Pair it with a comment handler only when you want the block to support FrontEdit comments. ## Minimal edit handler ```php class My_Plugin_Handler_Notice extends MWPSFE_Abstract_Text_Edit_Handler implements MWPSFE_Schema_Handler_Interface { public function id() { return 'my_plugin_notice'; } public function title() { return 'Edit Notice'; } public function element_type() { return 'Notice'; } public function element_type_code() { return 'my-plugin-notice'; } public function description() { return 'Edit this notice.'; } public function call_to_action() { return 'Click to edit this notice.'; } public function get_supported_blocks() { return array( 'my-plugin/notice' ); } public function get_schema_definition() { return array( 'version' => 1, 'block' => array( 'name' => 'my-plugin/notice', 'type' => 'text', ), 'components' => array( array( 'id' => 'content', 'label' => 'Content', 'type' => 'text', 'selector' => '.my-plugin-notice__content', 'default' => true, 'required' => true, 'placeholder' => 'Add content', 'bindings' => array( array( 'path' => 'content', 'source' => 'html' ), ), 'editor' => array( 'enterMode' => 'never', 'formats' => array( array( 'undo', 'redo' ), array( 'bold', 'italic' ) ), 'operations' => $this->normalize_editor_operations( array( $this->get_editor_text_rewrite_operation( 'content' ), $this->get_editor_inline_format_change_operation( 'content', array( 'bold', 'italic' ) ), ) ), ), ), ), ); } } ``` ## Schema shape Every schema has these required keys: ```php array( 'version' => 1, 'block' => array( 'name' => 'namespace/block', 'type' => 'text' ), 'components' => array(), ) ``` `block.type` is `text` or `media`. A schema may contain both text and file components when a block supports both kinds of editing. ### Optional pristine-default identity declaration Only use this declaration when a block is Gutenberg's native default writing surface and you know its exact untouched serialization: ```php 'identity' => array( 'pristineDefaultInnerHTML' => '

', ), ``` It tells FrontEdit to defer the *first* UUID assignment only while the block has no UUID or shadow UUID, no other block attributes or inner blocks, and its trimmed parsed `innerHTML` exactly matches the declared markup. This is not a general empty-content setting. Once an element has an identifier, FrontEdit will retain it—even if its content is later emptied—so existing history remains attached to that element. ### Components A component describes one editable part of the rendered block. | Key | Required | Description | | --- | --- | --- | | `id` | Yes | Unique component ID within the schema. | | `label` | Yes | Editor-facing label. | | `type` | Yes | `text` or `file`. | | `selector` | Yes | CSS selector relative to the rendered block root. Use `:scope` for the root. | | `default` | No | Selects the component opened by default. | | `required` | No | Blocks saving an empty text component. | | `placeholder` | No | Editor-only placeholder text. | | `bindings` | Text components | Maps the edited DOM value to block attributes. | | `editor` | No | Toolbar, operations, and keyboard behavior. | | `missingUI` | No | Describes an optional text node that may be absent from saved markup. | Text bindings use an attribute `path` and `source`. Use `source: 'html'` for rich text markup and `source: 'text'` for plain text. Attribute paths can be nested, for example `style.typography.textAlign`. ### Optional text components Use `missingUI` when a provider omits an optional text node until it has content. ```php 'missingUI' => array( 'mode' => 'ghost', 'mountSelector' => ':scope', 'placement' => 'append', // append or prepend 'tag' => 'p', 'attributes' => array( 'class' => 'my-plugin-notice__description' ), 'when' => array( 'path' => 'showDescription', 'equals' => true ), 'placementWhen' => array( 'path' => 'descriptionPosition', 'equals' => 'above', 'placement' => 'prepend', ), ), ``` `when` controls whether the ghost appears. `placementWhen` optionally changes its placement when an attribute matches. Both conditions use a scalar `equals` value. ### File components Use `type: 'file'` for a media replacement surface. In addition to the standard component keys, it requires a `target` object: ```php 'target' => array( 'selector' => ':self', // or a selector relative to the component root 'attribute' => 'src', 'mediaType' => 'image', ), ``` `mediaType` is one of `image`, `audio`, `video`, `file`, `image_or_video`, or `icon`. The target attribute is normally `src` or `href`. File and text components may be combined in one schema; FrontEdit switches at component scope but still serializes the complete block. ### Repeated components Use `repeat` for a component that occurs in a table, list, or another repeated structure. Grid mode declares `rowSelector` and `cellSelector`; FrontEdit then resolves `{row}` and `{column}` placeholders in binding paths. ```php 'repeat' => array( 'rowSelector' => 'tbody tr', 'cellSelector' => 'td', ), ``` Nested tree mode uses `mode: 'tree_path'`, `itemSelector`, and an optional `pathKey` (default `path`). Use it for one block that owns nested repeated text surfaces, such as a list. ### Binding sources Bindings require `path` and `source`. A path uses dot notation and may include repeat placeholders. Supported sources are: - `html` - rich inner HTML, including supported inline formatting. - `plaintext` - trimmed text without markup. - `textAlignment` - the active text alignment value. - `url` and `id` - media URL or attachment ID. - `media_type` - derives `image` or `video` from a pending media change. - `list_block` - rebuilds a complete nested list block from the live DOM. Media `url` bindings may set `resolved: true` to use WordPress-resolved attachment data. Set `value` to `width` or `height` when that resolved field is needed instead of the URL. ### Editor formats and operations `editor.formats` controls the toolbar. Supported tokens include `undo`, `redo`, `align`, `textAlignment`, `headingLevels`, `bold`, `italic`, `strikethrough`, `link`, `buttonLink`, `orderedList`, `unorderedList`, `indent`, and `outdent`. Nest tokens in an array to group them. `enterMode` may be `auto`, `always`, `never`, or `linebreak`. `linkUIMode: 'manual'` suppresses automatic link UI while a user edits an existing anchor; omit it for the default `auto` behavior. `tabMode` can use `none`, `indent`, `outdent`, `nextComponent`, or `previousComponent` for its `tab` and `shiftTab` values. `editor.options.preserveNewlines` converts `
` elements to literal newlines before saving. `newlinesToBR` does the opposite. Use only when the native block uses that representation. Use the protected helper methods on the abstract edit handler to declare the matching operations. Common helpers are: - `get_editor_text_rewrite_operation( $component_id )` - `get_editor_inline_format_change_operation( $component_id, $formats )` - `get_editor_inline_attribute_change_operation( $component_id, 'link', $capabilities )` - `get_editor_block_attribute_change_operation( $operation_id, $component_id, $capability )` Pass the completed array through `normalize_editor_operations()`. ### Attribute capabilities Declare block attributes used by toolbar operations under `editor.attributeCapabilities`. ```php 'headingLevels' => array( 'attribute' => 'level', 'values' => array( 1, 2, 3, 4, 5, 6 ), 'unsetValue' => 2, ), 'textAlignment' => array( 'attribute' => 'style.typography.textAlign', 'values' => array( 'left', 'center', 'right', 'justify' ), 'unsetValue' => 'left', ), ``` `headingLevels` is the canonical token for a heading-level or element-tag menu. For blocks whose values are tags, use values such as `h1`, `p`, and `div`, plus `tagChange: true`. The corresponding block-attribute operation will update both the declared attribute and the editable element tag. For a text-alignment capability, `preview: 'inline_style'` applies the preview through `style.textAlign` on the resolved format target. Use it only when the block's native frontend styling does not use WordPress `has-text-align-*` classes. `editor.formatTargets` can direct a toolbar operation to a selector or an object with `scope` (`component`, `block`, or `column`), `selector`, and an optional column `contextKey`. For example, use `array( 'align' => 'block' )` when block alignment belongs on the wrapper rather than the editable text node. ### Inline formatting For standard text formatting, obtain the supported format declarations with: ```php $inline_format_capabilities = $this->get_inline_format_capabilities( array( 'bold', 'italic', 'strikethrough', 'link' ) ); ``` Attach that value to `editor.inlineFormatCapabilities` and create matching inline-format and link operations. ## Validation checklist Before publishing a handler, verify all of the following on the frontend: 1. `wp.blocks.getBlockType( blockName )` returns the provider block definition. 2. Parsing then serializing an unchanged saved block preserves the block and its unrelated attributes. 3. Each text, media, attribute, and inline-format operation saves correctly. 4. Optional components materialize only under their declared conditions. 5. A provider update has not changed the saved markup, attributes, or `save` behavior your handler relies on. If any compatibility check fails, disable or defer the handler rather than editing rendered HTML directly. FrontEdit custom handlers always use Gutenberg's native block serialization path. About us – Aliancy Travels
Inquire Now

About us

Discover Sri Lanka with Experts Who Know It Best

Welcome to Aliancy Travels, your gateway to the real Sri Lanka. We are not just planners, we are your local friends, passionate about sharing the island we call home. We believe the best journeys are woven from authentic moments, not just checklists.

Our packages are curated to show you more than the famous sights. They unlock hidden beaches, family recipes and stories you won’t find in any guidebook. Whether you dream of safari adventures, peaceful tea trails or ancient ruins, we create a personal journey just for you.

Our packages are curated to show you more than the famous sights. They unlock hidden beaches, family recipes and stories you won’t find in any guidebook. Whether you dream of safari adventures, peaceful tea trails or ancient ruins, we create a personal journey just for you.

We take care of every detail so you can simply relax and immerse yourself. Travel beyond the ordinary and feel what it is truly like to connect with this incredible island.

Let us show you the Sri Lanka we know and love. Your adventure starts here.

About Us

Your Gateway to Sri Lanka: Bridging the World and the Island Paradise

Welcome to Aliancy Travel, where a unique friendship bridges the vibrant heart of Sri Lanka with the bustling energy of the UK. Founded by two close friends separated by miles but united by a shared passion, we offer a truly special perspective on travel to Sri Lanka. One of us is immersed in the daily rhythm of life on the island, while the other understands the excitement and questions that come with planning an international adventure from the UK. This powerful combination is the foundation of our travel agency.

We are not a large impersonal company. We are a dedicated team of two partners who are personally invested in crafting your perfect Sri Lankan holiday. Our local partner on the ground in Sri Lanka ensures every experience is authentic, from a hidden street food stall in Colombo to a secluded beach only locals know about. Our UK-based partner is here to understand your needs, answer your questions and ensure a seamless planning process from start to finish.

This direct connection means we offer unparalleled insight and access. We handle all the details, creating bespoke travel packages and tailored Sri Lanka tours that are deeply personal and carefully curated. We are committed to sustainable tourism and responsible travel that benefits local communities and preserves the natural beauty of this island paradise for generations to come.

We built Aliancy Travel to be a bridge, a reliable and friendly gateway for travelers seeking more than just a standard vacation package. We invite you to experience the warmth, wonder and magic of Sri Lanka through the eyes of friends who know it best. Let us connect you to the soul of this incredible destination. Book your trip with us and discover the difference.

Vision

Bridging Worlds, Inspiring Journeys

Our vision is to be the most trusted bridge between Sri Lanka and the world. We strive to inspire transformative journeys that go beyond tourism fostering deep meaningful connections with people culture and nature. We are committed to creating travel experiences that are not only personalized and seamless but also responsible and sustainable. By honoring authentic local traditions and supporting community wellbeing we aim to protect the beautiful island we call home. We believe in building understanding one journey at a time and inspiring travelers to become lifelong ambassadors for Sri Lanka travel.

Mission

Travel with Meaning, Explore with Trust

Our mission at Aliancy Travel is to craft authentic Sri Lanka experiences that are both meaningful and effortless. We are your dedicated local experts, using our deep knowledge and passion to design personalized itineraries just for you. We connect you to the true heart of the island, from its vibrant culture and wildlife safaris to its pristine beaches. We are committed to ethical tourism and sustainable practices that protect our home and empower local communities. Your trust is our priority. We handle all the details so you can immerse yourself completely and explore with confidence.

Why Choose Us

Your Gateway to Sri Lanka

Choosing the right partner for your Sri Lanka adventure makes all the difference. At Aliancy Travel, we are not a large corporation. We are a personal travel agency founded by two friends with one simple goal: to be your trusted gateway to the authentic heart of the island.

Our unique advantage is our partnership. With one founder based in the UK and the other living right here in Sri Lanka, we offer a seamless blend of convenience and insider local expertise. You get a flawless planning process from someone who understands your needs, paired with on-the-ground knowledge that unlocks truly unique experiences. We have personally curated every tour package and bespoke itinerary to ensure it is authentic and respectful.

We specialize in personalized travel that goes beyond the tourist trail. Whether you dream of a family vacation, a luxury tour, a wildlife safari in Yala National Park, or a relaxing beach holiday, we craft journeys with care and passion. We are deeply committed to sustainable tourism and creating positive impacts for local communities.

Choose us for a truly unforgettable experience designed just for you. Let’s start planning your dream trip today

Local
Expertise

Seamless
Planning

Tailored
Tours

Dedicated
Support

Sustainable
Travel

Every tour package we create is deeply personalized. We take the time to listen and craft a truly unforgettable Sri Lanka vacation that is unique to your interests and travel style.

Get a Quote

Our local experts are available 24/7 to assist you whenever you need

What Our Travelers Say

Discover why travelers from around the world choose Aliancy Travels for their Sri Lankan adventures

“Avinra Travels made our Sri Lankan adventure absolutely magical! From the ancient temples of Anuradhapura to the pristine beaches of Mirissa, every moment was perfectly curated. Our guide was incredibly knowledgeable and passionate about sharing the beauty of his homeland.

Sarah Mitchell

United Kingdom

“Avinra Travels made our Sri Lankan adventure absolutely magical! From the ancient temples of Anuradhapura to the pristine beaches of Mirissa, every moment was perfectly curated. Our guide was incredibly knowledgeable and passionate about sharing the beauty of his homeland.

Sarah Mitchell

United Kingdom

“Avinra Travels made our Sri Lankan adventure absolutely magical! From the ancient temples of Anuradhapura to the pristine beaches of Mirissa, every moment was perfectly curated. Our guide was incredibly knowledgeable and passionate about sharing the beauty of his homeland.

Sarah Mitchell

United Kingdom

“Avinra Travels made our Sri Lankan adventure absolutely magical! From the ancient temples of Anuradhapura to the pristine beaches of Mirissa, every moment was perfectly curated. Our guide was incredibly knowledgeable and passionate about sharing the beauty of his homeland.

Sarah Mitchell

United Kingdom