jimoquinn/dashboard

🍱 Dashboard gives you latest relevant information at a glance

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.