Skip to content

How the Fortunes widget works

Maxence Lange edited this page Oct 16, 2018 · 1 revision

The Fortunes app is made of few files:

The WidgetClass

What we will call WidgetClass in this pages is a PHP class that implements the IDashBoard interface from Nextcloud.

The WidgetClass is also defined in the file appinfo/info.xml of the app that host the Widget:

<dashboard>
	<widget>OCA\Dashboard\Widgets\FortunesWidget</widget>
</dashboard>

Now, let's have a look to each method from this interface that needs to be implemented in your WidgetClass:

  • getId(): string must returns a unique Id that identify the Widget. The string should only contains alphanumeric chars and no space.

  • getName(): string must returns a more detailed name of the Widget. It is used as a title and does not need to be a fied name (ie. can be translated)

  • getDescription(): string must returns a small description of the Widget. This description is displayed in the listing of the available widgets.

  • getWidgetTemplate(): WidgetTemplate: must returns a WidgetTemplate. WidgetTemplate is a data transfer object. This object must be created when the getWidgetTemplate() is called. As an example, this is how it is generated in our current example:

	public function getWidgetSetup(): WidgetSetup {
		$template = new WidgetTemplate();
		$template->addCss('widgets/fortunes')
			 ->addJs('widgets/fortunes')
			 ->setIcon('icon-fortunes')
			 ->setContent('widgets/fortunes')
			 ->setInitFunction('OCA.DashBoard.fortunes.init');
		return $template;
	}

More details about this object can be find later on this page

  • getWidgetSetup(): WidgetSetup must returns a WidgetTemplate. WidgetSetup is a data transfer object. This object must be created when the getWidgetSetup() is called. As an example, this is how it is generated in our current example:
	public function getWidgetSetup(): WidgetSetup {
		$setup = new WidgetSetup();
		$setup->addSize(WidgetSetup::SIZE_TYPE_MIN, 2, 1)
		      ->addSize(WidgetSetup::SIZE_TYPE_MAX, 4, 4)
		      ->addSize(WidgetSetup::SIZE_TYPE_DEFAULT, 3, 2);
		$setup->addMenuEntry('OCA.DashBoard.fortunes.getFortune', 'icon-fortunes', 'New Fortune');
		$setup->addDelayedJob('OCA.DashBoard.fortunes.getFortune', 300);
		$setup->setPush('OCA.DashBoard.fortunes.push');
		return $setup;
	}

More details about this object can be find later on this page

  • loadWidget(IWidgetConfig $settings) is called when a widget is loaded. A widget is loaded when displayed on a user's dashboard. It can be when the user add your widget to his dashboard, or when the dashboard app is opened/refreshed and your widget is already added to his dashboard and set to be displayed. The IWidgetConfig contains the current configuration of the widget for this user.

  • requestWidget(IWidgetRequest $request) is called when a widget (JS/front-end) wants to communicate with your WidgetClass (PHP/backend). The IWidgetRequest contains the data sent by the Javascript part of the widget. The request is done using the Javascript API like in our example:

	var request = {
		widget: 'fortunes',
		request: 'getFortunes'
	};

	net.requestWidget(request, fortunes.displayFortune);

More details about this can be find later on this page

WidgetTemplate (Data Transfer Object)

  • addCss(string $path) and addJs(string $path) are used to set the path to the CSS and Javascript file. If you look are the file tree, the files are stored in the css/ and js/ folder.

  • setIcon(string $class) define the CSS class of the icon, which is configured in the CSS file.

  • setContent(string $path) set the path of the HTML template of the Widget.

  • setInitFunction(string $class) define the Javascript function that is called when the wi*dget is loaded/displayed on the Dashboard. It is called when a user add your Widget on his Dashboard, or when the dashboard app is open and your widget is already set to be displayed on the dashboard.

WidgetTemplate (Data Transfer Object)

  • addSize(string $type, int $width, int $height) is used to set the different sizes. The type of the size can be 'default', 'min' or 'max'. width and height are integer. The size is defined using the grid of the dashboard.

  • addMenuEntry(string $class, string $icon, string $title) allows you to add an entry in the contextual menu available using the 3-dot icon displayed at the top right corner of your widget. You can add multiple entries. The class is a Javascript function that will be called when the use select the custom menu entry. The icon is the CSS class used to display an icon, and the title is the text displayed in the menu.

  • **addDelayedJob(string $class, int $delay) allows you to execute a Javascript function every n seconds. delay is the number of seconds between each execution.

  • **setPush(string $class) is used to defined the Javascript function to be called on Push event. Push event is initiated by the backend of the Dashboard app to communicate with the front-end. More information about this can be find at the bottom of this page

Widget Requests

Your javascript can request data from your PHP by using the Javascript API of the Dashboard app:

	var request = {
		widget: 'your_widget',
		request: 'keywordForYourRequest',
		value: 'some value - can be JSON'
	};

	net.requestWidget(request, callback);

When this API is called, the Dashboard will all the requestWidget() method of your WidgetClass, passing a IWidgetRequest as argument.

Some method are available to you to retreive the content of the request:

  • getWidgetId(): string returns he Id of the widget.

  • getWidget(): IDashboardWidget returns the Widget itself.

  • getRequest(): string returns the keyword set in the request ('keywordForYourRequest' in our case)

  • getValue(): string returns the value set in the request. Can be a string or a JSON.

  • addResult(string $key, string $value) should be used to returns data to the Javascript. The data is a string that will be returned to the callback function defined when calling the net.requestWidget() in your Javascript.

  • addResultArray(string $key, array $value) should be used to returns data to the Javascript. The data is an array that will be returned to the callback function defined when calling the net.requestWidget() in your Javascript.

  • getResult(): array returns the data that will be send to the callback function.

Push Events

The Dashboard allows you to communicate from your App (PHP) to your Widget (Javascript). This an be used to send notifications or update the data to be displayed on the dashboard of your users. The Fortunes widget comes with a small occ command as an example. If your have the Dashboard app opened with the Fortunes widget loaded, you can use this command to change the current fortune displayed on your screen:

In a terminal:

$ ./occ dashboard:push fortunes your_userId "{\"fortune\": \"This is a test\"}"

In this command, the payload is sent to the Javascript. In the WidgetSetup, we set up the push function:

	$setup->setPush('OCA.DashBoard.fortunes.push');

And in the Javascript, we receive the payload:

	push: function (payload) {
		if (payload.fortune === undefined) {
			return;
		}

		fortunes.divFortune.fadeOut(150, function () {
			$(this).text(payload.fortune).fadeIn(150);
		});
	}

Note The size of the payload is limited, meaning that if you want to send a lot of data, you should only send a trigger to the Javascript that will send a request back to the backend and retreive all needed data.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.