Uhuu Docs

Appearance

Methods and Events ​

Uhuu SDK defines a global $uhuu which provides following methods and event hooks.

payload() ​

A "template payload" refers to a predefined data structure (JSON) for sending data between template and uhuu. Access recent payload as following:

js
$uhuu.payload()

listen(event, callback) ​

Whenever an event (e.g. 'payload' ) is triggered by the uhuu SDK, the code inside the callback function will run. You can use this mechanism to handle editor changes in your template.

js
$uhuu.listen('payload', (data) => {
    // callback with recent payload data.
});

templateSetup(setup) ​

Setup how a template should be handled by uhuu editor, such as keys to be restored in template payload, how images should be edited and enable/disable optional features.

The templateSetup accepts a setup object with following parameters, each of which is optional.

preprocess ​

preprocess: Adjust data within the payload to ensure it's in the desired format for your template to work effectively.

js
$uhuu.templateSetup({
    preprocess : (payload) => {
        // implement various preprocessing tasks, 
        // such as data transformation, enrichment, custom logic.
        
        // Example: modify image URLs                 
        const images = payload?.listing?.images ?? [];                
        images.forEach((item) => {
            if(item.url.endsWith('width=200'))
                item.url = item.url.replace("width=200", "width=600");
        });
        return payload;
    }
});

uhuu_restore ​

uhuu_restore: An object with configurations for payload bindings, where each key represents a payload data path for restoring user edits.

js
$uhuu.templateSetup({
    uhuu_restore : {       
       title : { path: 'title', value: 'Default title'}
    }
});

templateSetup for restoring user edits with uhuu_restore.

filters ​

filters: An object containing custom filter functions for logic and data filtering.

js
$uhuu.templateSetup({
    uhuu_restore : {       
       cover_image : { filter: 'findImage', args: {index:0}}
    },
    filters: {
        // payload : Recent payload data
        // args :  Arguments object used for the filter.
        findImage : (payload, args) => {
            const images = payload?.listing?.images ?? [];                                
            return images.length > args.index ? images[args.index] : null;
        }   
    }
});

options: An object that configures specific template setup options, including imageGalleryPath for specifying the image path within the payload.

js
// path to look for images in the payload
$uhuu.templateSetup({
    options: {
        imageGalleryPath : 'images' 
    }
});

editDialog(options) ​

Open a dialog-based interaction within uhuu editor using the provided dialog configuration options.

Functionality: ​

  • The dialog allows users to make changes to a specific data path within the payload.
  • When users save their changes in the dialog, uhuu editor updates the payload.
  • The modified data is emitted using a payload event, which can then be processed in the template.

Parameters: ​

editDialog function accepts a configuration options object with the following parameters:

  • path: Specifies the data path within the payload to edit.
  • value (optional): Initial content for the specified path when the template is initialized.
  • subPath (optional): Indicates a sub-path relative to the specified path.
  • type (default: "textarea"): Defines the content type
    • textarea: Form with textarea element for editing text content.
      • rows : (default: 3)
    • select: Form with select element with predefined options.
      • options : Array of value/label objects [{value : "Value", label: "Label"}]
    • markdown: Markdown editor for editing markdown text content.
    • image: Edit image content.
      • imagePath (optional): An alias for subPath when editing images, eliminating the need for an extra type definition.
      • ratio (optional): Specifies the aspect ratio for image content (used with images).
  • panelSize (default: "md"): Form dialog panel size, can only be md | 3xl | 5xl
js
// Example usage of editDialog for editing a text field
const dialogConfig = {
  path: 'name', // Specify the data path within the payload to edit
  value: 'John Doe', // Initial content for the specified path when initialized
  type: 'textarea', // Content type is 'textarea' for editing text fields
  rows: 3,  // Default textarea rows 3
};

// Open the edit dialog for the text field
editDialog(dialogConfig);
js
// Example usage of $uhuu.editDialog for editing a select field (ice cream flavor selector)
$uhuu.editDialog({
  path: 'icecream', 
  value: 'strawberry',
  type: 'select', // Content type is 'select' for editing select fields
  options: [
    { value: 'chocolate', label: 'Chocolate' },
    { value: 'strawberry', label: 'Strawberry' },
    { value: 'vanilla', label: 'Vanilla' }
  ]
});

Start using editDialog

js
// Example usage of $uhuu.editDialog for editing an image field (cover image with a specified ratio)
$uhuu.editDialog({
  path: 'uhuu_restore.cover_image',
  subPath: 'url',
  type: 'image',
  ratio: 16 / 9
});

// Shorter version using 'imagePath' as an alias for 'subPath' (when editing images)
$uhuu.editDialog({
  path: 'uhuu_restore.cover_image',
  imagePath: 'url',
  ratio: 16 / 9
});

Image editing with editDialog

batchData() ​

The method allows developers to access complete batch data in JSON format.

js
$uhuu.batchData()

Batch data loaded locally in browser and is not sent to server during document export.

It's important to note that batch data is separate from the payload and is not sent to uhuu for document exporting unless modifications are emitted as payload using $uhuu.emitPayload(payload).

emitPayload(payload) ​

Developers can inform the Uhuu editor of payload modifications using the method.

js
$uhuu.emitPayload(payload)