Jump to main content Jump to doc navigation

The File Dashboard Widget Type runs a file on the filesystem, which can either:

  • Return the output of the file, rendering it in the content pane of the widget
  • Return the name of a class that extends modDashboardWidgetInterface, a MODX-provided abstract class, that has a render() method that will return the output to render to the content pane of the widget


Simply place the name of the file in the content textarea of the widget. You can use the following placeholders to reference the widget path:

  • [[++base_path]]
  • [[++core_path]]
  • [[++manager_path]]
  • [[++assets_path]]
  • [[++manager_theme]]

Returning the Output

There are two methods in your external file to return the content of the widget. The first is simply returning the output, like so:

return 'Hello, world!';

Will render "Hello, world!" in the content panel of the widget.

Returning a Class Name

You can also return a class name of a class you have defined in your external file that extends the class modDashboardWidgetInterface, which is an abstract class provided by MODX for rendering of widgets. This is useful for widget developers who want an OOP approach that unit tests can be run against.

An example class-based widget would look like this:

class modDashboardWidgetHelloWorld extends modDashboardWidgetInterface {
    public $version = '1.0';

    public function render() {
        $o = 'Hello, World! Version: '.$this->version;
        return $o;
return 'modDashboardWidgetHelloWorld';

This widget would return as its content:

Hello, World! Version: 1.0

Available Variables

File-based widgets have the following PHP variables available to them:

  • $modx - A reference to the MODX instance.
  • $scriptProperties - An array of properties of this Dashboard Widget, as if toArray() were run on the widget object.

See Also

  1. Dashboard Widget Type - File
  2. Dashboard Widget Type - HTML
  3. Dashboard Widget Type - Inline PHP
  4. Dashboard Widget Type - Snippet

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.



$0 per month—let's make that $500!

Learn more