Difference between revisions of "Integrating Applications Into Web Frontend"

Revision as of 20:14, 20 September 2010

About

This page describes the integration of an application (i.e. an app.bin) into the Web Frontend. The system has a dynamic plugin loader which enables your app.bin in the Webend Interface. The integration can be used for web applications that run in daemon-only mode, non-daemon-mode, or both.

Functions

The following types of integration are supported:

• create a starter icon for the Web Application
  • set the icon image
  • set the window size for the application window
  • reference a config page when one exists
  • remove the starter icon when the daemon isn't running
  • remove the starter icon if a plugin is removed from the WDTV

• create an entry for daemon status and start/stop option in the "Plugin Daemons" sidebar
  • show daemon status
  • start/stop daemon via Web Frontend

Activate

To activate an app.bin in webend you have to create a webend.conf file in your app.bin file (see below)
and add two commands to the app.bin's init script.

Modify your init script

Your application needs an init script in order to integrate with Web Frontend. Even if your application does not run in daemon mode, you will still need an init script. If you do not yet have an init script for your application, create one in the following location:
/apps/<your plugin dir>/etc/init.d/<script_name>

where script_name looks something like S88myplugin. The script name should probably start with an 'S' followed by a number higher than "66", and then the name of your plugin. Note that init scripts are executed in alphabetical order, so it is a good idea to make this a relatively high number to ensure it doesn't run until after any services that it relies upon have already started (which is why the number has to be higher than 66 - the Apache init script is "S66apache2", so you don't want your plugin to start until after Apache does).

If you are creating this file for the first time, add this as the first line of the script:

 #!/bin/sh

Add these two lines to your init script, following the instructions below:

add.webplugin <plugin_name> <path to webend.conf>
load.webplugin

• plugin_name: If your application can run in daemon mode, plugin_name must be the name of the process under which the daemon runs. This is how Web Frontend determines whether your daemon is started or stopped. If the application doesn't run in daemon mode, this name can be whatever you want.
• path to webend.conf: this is the full path to the directory in which you have placed webend.conf. For the sake of consistency, it is usually best to make this /apps/<your plugin name>/var/www/<your plugin name> and to place all of your web-related files (webend.conf, php code, icons, css, etc.) in that directory if you will be adding a startup icon for your application. If your application only runs in daemon mode without a web frontend icon (i.e. it should only show up in the left navigation bar), then you can put it directly under /apps/<your plugin name>.

These two lines can typically go at the very bottom of your init script. Take care, however, if you have any exit statements in your script; if so, you probably want to put these two lines before the exit statements.

Examples

1. Application with a Start icon ( with or without daemon support)

   add.webplugin DownloadDaemon /apps/downloadd/var/www/dd-client

   remember that if this runs in daemon mode "DownloadDaemon" would need to be the exact name of the process under which the daemon runs.

2. Add a daemon-only application

   add.webplugin daemon_only /apps/daemon_only_app

   again, "daemon_only" would need to be the exact name of the process under which the daemon runs.

Remember: webend.conf must be in the location specified in add.webplugin so the plugin loader can find it.
e.g. /apps/downloadd/var/www/dd-client/webend.conf

Creating webend.conf

The following is an example of a webend.conf file with all parameters and descriptions.

#### parameters for starter-icon for Web Frontend (not necessary for daemon-only apps)
#### all php and image files are relative to the directory that webend.conf is in
    # Reference to start page (e.g. index.php)
      TARGET=index.php
    # Reference to the image file for the Web Frontend icon
      IMAGE=ddclient-gui.png
    # Size of the popup window for your application in Web Frontend
      WINDOW_SIZE_HEIGHT=700
      WINDOW_SIZE_WIDTH=900
    # Whether the icon should disappear when plugin isn't found
      FLAG_EXISTS=YES
    # Reference to config page (e.g. config.php) - comment out if no configuration is necessary
      CONFIG_SIDE=config.php
    # Whether the icon should disappear if the daemon not running
    # NOTE: If this is set, you must also set DAEMON_NAME below
      ICON_DISAPPEAR_DAEMON_OFF=YES

#### parameter for daemon status and management (not needed for web-only apps)
  # daemon name - must exactly match the name of your daemon process (case-sensitive)
    DAEMON_NAME=DownloadDaemon
  # commands to start and stop your daemon - these must be Unix commands
    DAEMON_START_COMMAND="/apps/downloaddaemon/etc/init.d/S97downloadd forcestart"
    DAEMON_STOP_COMMAND="/apps/downloaddaemon/etc/init.d/S97downloadd stop"

Reboot

Reboot your WDTV. If all went well, you should see the icon for your application in Web Frontend the next time you log in.

Removing a Web Frontend plugin

References to the plugin will remain in the list of active plugins on a user's WDTV even if the app.bin is removed from their system. Under most circumstances, this is not a problem, and in fact is desirable; other than some warning messages in syslog, it causes no damage and ensures that the plugin will be found again if the app.bin is added back to the system.

However, there are some cases where you may want to explicitly remove a web plugin from the list. To do so, you can add the following command to an init script, or issue it from the command line:

 remove.webplugin <plugin_name>

Notably, add.webplugin will not change the name of a plugin if the path to that plugin is already present in the list. As a developer, this means that if you change the name of your plugin during the course of development you must run remove.webplugin <old_plugin_name> from the command line; otherwise Web Frontend will still look for your file under the old name even after you reboot the WDTV.

A bit more seriously, if you change the name of your application after releasing it to the public then you need to ensure the old plugin name is automatically removed. In this case, you should modify your init script to include the following line immediately above the two lines in which you add and load the plugin:

 remove.webplugin <old_plugin_name>