Creating a Custom View

The Custom Views API provides the ability for you to register and use custom views in Pie Calendar.

Creating a View

To create your own custom view, first hook into the piecal_custom_views filter.

add_filter( 'piecal_custom_views', 'exampleCustomView', 100, 2 );

Next, create the exampleCustomView function to add your custom view definition to the custom views array.

function exampleCustomView( $customViews, $atts ) {
    $myCustomView = [
        "exampleCustomView" => [
            "type" => "listWeek",
            "duration" => [
                "months" => isset( $atts['duration'] ) ? intval( $atts['duration'] ) : 1
            ],
            "customProps" => [
                "niceName" => __( "Example Custom View", "piecal" ),
                "styles" => "
                    [data-view='exampleCustomView'] .fc-list-event-title {
                        display: none;
                    }
                "
            ]
        ]
    ];

    $customViews = array_merge($customViews, $myCustomView);
    return $customViews;
}

Explanation of keys:

• The "exampleCustomView" key is associated with the value of the view itself. You can have multiple views in the $myCustomView array, but we only included one for illustrative purposes here.
• The "type" key defines which core view your new view extends. It can be one of the following:
  • dayGridMonth
  • listMonth
  • timeGridWeek
  • listWeek
  • dayGridWeek
  • listDay.
• The "duration" key allows you to define the number of months the view should span. As shown in the example, you can also pass shortcode attributes into your view properties by using $atts['attributeName']. Passing the attribute makes it user-configurable, and will cause the Calendar Block to show a duration control when this view is selected in the Block Editor.
• The "customProps" key holds some information used for the display of the view.
  • "niceName" is used in view chooser drop-downs in the Block Editor and on the front-end.
  • "styles" holds a string of CSS that is output as an inline style on the front-end.
    • Use an attribute selector ([data-view='exampleCustomView']) to scope your styles to only your custom view.

These are all of the basic keys needed to register a new view.

Adding Event Handlers

If you want to modify calendar behavior when certain events happen, add the desired event handlers as keys in your view's array, after the "customProps" key. The supported event handlers are:

• eventDataTransform
• dateClick
• eventClick
• eventDidMount
• dayCellDidMount
• viewDidMount
• viewWillUnmount
• dayHeaderContent
• dayHeaderDidMount

Here's an example where we've added an eventClick handler to our custom view to skip the popover and go straight to the event's permalink instead:

$myCustomView = [
    "exampleCustomView" => [
        "type" => "listWeek",
        "duration" => [
            "months" => isset( $atts['duration'] ) ? intval( $atts['duration'] ) : 1
        ],
        "customProps" => [
            "niceName" => __( "Example Custom View", "piecal" ),
            "styles" => "
                [data-view='exampleCustomView'] .fc-list-event-title {
                    display: none;
                }
            "
        ],
        "eventClick" => "
            info = piecalJS.eventClick( info );

            Alpine.store('calendarEngine').showPopover = false;
            window.location.href = Alpine.store('calendarEngine').eventUrl ?? Alpine.store('calendarEngine').permalink;
        "
    ]
];

Registering custom event handlers for your views follows a typical pattern:

• First, you need to run the core handler from piecalJS: info = piecalJS.eventClick( info )
  • In the case of the eventDataTransform handler, use: event = piecalJS.eventDataTransform( event ) instead.
  • Optional: If you don't want the core event handler logic to fire, omit the piecalJS.{eventHandler} portion of the code and you'll be starting from scratch. This is not recommended and may break core functionalities in the calendar when using your view.
• Next, you can access Alpine.store('calendarEngine'), or do anything else via JavaScript that you'd like to have happen when that specific event fires.

Real-world Examples

Both the Pie Calendar "List - Upcoming" and the Pie Calendar Pro "Month - List with Image" views were created using this API.