nextcloud / Dashboard

Archived repository

The dashboard app was rewritten as part of Nextcloud 20 and is now part of the server repository. Please head there for issue reporting and the app code.

Quick guide on how to build the app from git:

 $ git clone -b gridstack https://github.com/nextcloud/dashboard.git
 $ cd dashboard
 $ make npm

How to create a Widget:

• Generate an app (see app development documentation or use the app genreator from the app store.)
• Create a PHP class that implement IDashboardWidget:

1. getId() returns a unique ID of the widget
2. getName() returns the name of the widget
3. getDescription() returns a description of the widget
4. getTemplate() returns information about the template to load and css/js:
5. widgetSetup() returns optional information like size of the widget, additional menu entries and background jobs:
6. loadWidget($config) is called on external request (cf. requestWidget()). $config is an array that contains the current setup of the widget
7. requestWidget(WidgetRequest $request) is called after the loadWidget() after a new.requestWidget(object, callback) from JavaScript

• Add to appinfo/info.xml:

	<dashboard>
		<widget>OCA\YourApp\Widgets\MyFirstWidget</widget>
		<widget>OCA\YourApp\Widgets\AnOtherWidget</widget>
	</dashboard>

Event & Push

You can (almost) instantly push payload from Nextcloud to your widget:

• define the method to be called in the widgetSetup() array:

   'push'  =>  'your-javascript-function-to-call-on-event

• call the API from your PHP:

OCA\Dashboard\Api\v1\Dashboard::createEvent('your_widget_id', 'user_id', payload_in_JSON);

• the method set in widgetSetup()['push'] will receive the payload.

Note: you can manually generate events using the command line:

 ./occ dashboard:push widgetid userid payload

You can, this way, modify the displayed fortune for any user:

./occ dashboard:push fortunes cult "{\"fortune\": \"foobar\"}"

See the wiki, in particular this page about how the fortune widget works, for more background.