Community

Note: this manual is intended for experienced developers who are familiar with PHP, HTML, CSS, and the internal structure of the software.

Core Widget Components.

Widgets in phpListings are modular building blocks that add dynamic functionality and flexible content to your website. Each widget consists of three main components: the widget class, the view template, and a database record.

The widget class must be created in the /app/Widgets directory. Its file name and class name should both start with a capital letter, with all other letters in lowercase, and only English letters are allowed without any spaces or special characters.

The widget’s layout is handled by a view template stored in the /app/Views/default/widgets directory. The template filename can be chosen freely, but since file references are case-sensitive, the exact same spelling must be used in the class. For example, if the file is called WiDget.html.php, then the class must reference it as WiDget and not widget.

The database record for the widget is stored in the phpls_widgets table. The widget’s name is defined in JSON format, for instance {"en":"Widget Name"}, while the slug is always the lowercase version of the widget’s class name. If your widget class is Customwidget, the slug must be customwidget.

Widget class methods.

render()

The main logic of a widget is implemented in the render() method, which is responsible for linking the class with its corresponding view and providing the necessary settings and data. An example structure is:

public function render() {
    return view('widgets/example', [
        'settings' => $this->getSettings(),
        'data' => $this->getData(),
    ]);
}

This function can be extended to prepare any additional values you wish to pass into the template, using the $view variable. Inside the template file, $view->settings will provide access to the widget’s configuration values, while $view->data will provide data prepared by the class. These values can be added inside the render() method so that the template has all the necessary inputs for display.

getDefaultSettings()

The getDefaultSettings() method is used to declare default configuration values for the widget. A short example might look like:

public function getDefaultSettings() {
    return collect(['colorscheme' => 'bg-white', 'title' => 'My Widget']);
}

This ensures that the widget always has predefined setting values, even before a user makes any changes in the admin panel.

getForm()

The getForm() method defines the form fields that appear in the administration panel when editing the widget’s settings. For example:

public function getForm() {
    return form()->add('title', 'text', ['label' => 'Widget Title']);
}

This allows administrators to customize the widget by entering values into the fields that you provide, and those values will then be accessible through $view->settings in the template.

Each form field must correspond to a widget setting, so the field named title will map to $view->settings->title in the view template.

isMultiInstance()

Widget settings can be configured to behave in one of two ways: either as a shared configuration for all instances of the widget or as a separate configuration where each instance on different pages can be customized independently. If separate configuration is required, the isMultiInstance() method must be included in the class. A short example is:

public function isMultiInstance() { return true; }

Widget Template and Data Access.

The widget view itself is where the HTML and presentation logic reside. It is typically stored in the /app/Views/default/widgets directory and is connected to the widget class through the render() method. Within this file, developers can access $view->settings to retrieve configuration values such as a heading, a description, or color schemes, and $view->data to display dynamic content prepared by the widget, such as listings, reviews, or other records. For example, a simple template could display a heading using:

<h3><?php echo e($view->settings->title); ?></h3>

and iterate over data passed from the widget class like this:

<?php foreach ($view->data->reviews as $review) { ?>
    <p><?php echo e($review->title); ?> – <?php echo e($review->user->getName()); ?></p>
<?php } ?>

This approach keeps logic in the widget class while allowing templates to focus purely on presentation.