The onWidgetFormat handler (and its more specific siblings, onWidgetFormatEvents, onWidgetFormatNews, onWidgetFormatProfiles, etc.) allow you to filter a widget’s variables just before they are displayed.

There are two unique aspects to onWidgetFormat you should keep in mind:

1. Since onWidgetFormat is executed in several contexts, it receives a $handler variable that lets you specify what context your code should affect. The most common use is “onDisplay”, as in the example below, but you may have code for the handlers “json”, “calendar”, or others.

2. You can use onWidgetFormatType($handler, $buffer) (replacing Type with Events, News, Profiles, etc.) instead of onWidgetFormat($type, $handler, $buffer) if you’re targeting just one type of widget. Always opt to use the type-specific one over the non-type-specific one when possible.

<?php
    $_LW->REGISTERED_APPS['my_app']=[
       'title'=>'My App',
       'handlers'=>['onWidgetFormatEvents'],
    ];

    class LiveWhaleApplicationMyApp {

      public function onWidgetFormatEvents($handler, $buffer) { 
        global $_LW;

        if ($handler=='onDisplay') {

          // Replace "until" with "through" in widget output for date ranges
          if (!empty($buffer['until'])) {
            $buffer['until'] = str_replace('until', 'through', $buffer['until'])
          };

          // Use a.m./p.m. in time strings
          if (!empty($buffer['time'])) {
            $buffer['time'] = str_replace(['am','pm'],['a.m','p.m'], $buffer['time']);
          };
          if (!empty($buffer['start_time'])) {
            $buffer['start_time'] = str_replace(['am','pm'],['a.m','p.m'], $buffer['start_time']);
          };
          if (!empty($buffer['end_time'])) {
            $buffer['end_time'] = str_replace(['am','pm'],['a.m','p.m'], $buffer['end_time']);
          };

        };

        return $buffer;
      }

   }
?>

You can also use handlers like “onRSS” or “onICAL” to target widget results that are being rendered as /live/ API requests. 

In this example (client/modules/custom_ical_fields/public.application.custom_ical_fields.php) a custom field for Room Number gets appended to ICAL/RSS results in the location field.

<?php

$_LW->REGISTERED_APPS['custom_ical_fields']=array(
        'title'=>'Custom iCal Fields',
        'handlers'=>array('onWidgetFormatEvents')
);

class LiveWhaleApplicationCustomIcalFields {

    public function onWidgetFormatEvents($handler, $buffer) {
        global $_LW;

        if ($handler == 'ical' || $handler == 'onICAL') {

            if (!empty($buffer['X-LIVEWHALE-CUSTOM_ROOM_NUMBER'])) {
                $buffer['location'] .= ', ' . $buffer['X-LIVEWHALE-CUSTOM_ROOM_NUMBER'];
            }

        
        } else if ($handler == 'onRSS') {

            if(!empty($buffer['livewhale:custom_room_number'])) {
                $buffer['georss:featurename'] .= ', ' . $buffer['livewhale:custom_room_number'];
            }

        }
        
        return $buffer;

    }

}