Evolution: Widgets for plugins

Version 1.56

Feature
Finished

Ability for plugins to provide their own widgets. Sample plugin to test with: https://www.directadmin.com/hello_world-1.1.tar.gz but rename it to hello_world.tar.gz before installing it, as DA would end up calling it hello_world-1 and the links inside would be broken. This 1.1 path is just temporary for testing. ===== PLUGIN.CONF similar structure to skin.conf, eg: admin_widgets=WGT_PLUGINS_ADMIN_HELLO_WORLD:WGT_PLUGINS_ADMIN_HELLO_MARS admin_widgets_default=WGT_PLUGINS_ADMIN_HELLO_WORLD reseller_widgets=WGT_PLUGINS_RESELLER_HELLO_WORLD reseller_widgets_default= user_widgets=WGT_PLUGINS_HELLO_WORLD user_widgets_default=WGT_PLUGINS_HELLO_WORLD WGT_PLUGINS_ADMIN_HELLO_MARS=Hello Mars Where the format should start with the given level, as per above (eg: WGT_PLUGINS_ADMIN to match an admin level call) ========== WIDGET TEXT Can have multiple widgets for each level, separated by a colon. By default, the plugin.conf: "name=" vaule will be the text for the plugin. For other names, or if you have more than one widget, you can set that widget name in the plugin.conf, eg: WGT_PLUGINS_ADMIN_HELLO_MARS=Hello Mars TODO: language/translation ability for widget texts. ========== NAMING RULES Your plugin widget name mus start with one of: WGT_PLUGINS_ADMIN_ WGT_PLUGINS_RESELLER_ WGT_PLUGINS_ the suffix after this naming can be anything you want, but best to keep it unified with something similar to your plugin name. This is to avoid duplicates. ========== WIDGET TABS The default request: CMD_WIDGETS?json=yes&level=user will include any plugin widgets/names in the usual area (eg: user_widgets), but any extra widget tabs will be in an array beside user_widgets, eg: , "user_widgets_tabs": { "WGT_PLUGINS_HELLO_WORLD": { "img": "CMD_PLUGINS_ADMIN/hello_world/images/hello_world.svg", "tab": "Details from tab.html", "title": "Hello World!", "url": "CMD_PLUGINS/hello_world/index.html" } } where, if a widget is listed there, this should take precedence (As you'd likely not be able to get the info from anywhere else). Although in reality, if you see it listed there, it's not likely a usual widget, so use it's data either way. Similar for reseller_widgets_tabs, admin_widgets_tabs. ========== SHOWING THE WIDGET new command options for CMD_WIDGET, eg: CMD_WIDGET?json=yes&show=WGT_PLUGINS_ADMIN_HELLO_WORLD&item=both where we want to "show" the current plugin widget. The "item" can be one of: item=tab item=main item=both where tab is the left side html to click each widget. main is the right side that fills the widget content and both returns both the tab and main content (default if no "item" is passed) The "level" variable is not required, as DA can decipher it from the WGT name. ========== SHOWING MULTIPLE WIDGETS Similar to the above show= call, you can alternatively use: CMD_WIDGET?json=yes&item=main&select0=WGT_PLUGINS_ADMIN_HELLO_WORLD&select1=WGT_PLUGINS_ADMIN_HELLO_MARS for example, in addition to the rest of the requests. You can still use show= in addition to select0+. Note that select0 is the trigger to look for the list, so you cannot start from select1 and go up.. must start from 0.. then any number is fine (does not need to be in order) ========== PLUGIN FILES plugins/YOURPLUGIN/widgets/WGT_PLUGINS_ADMIN_HELLO_WORLD/tab.html plugins/YOURPLUGIN/widgets/WGT_PLUGINS_ADMIN_HELLO_WORLD/url.html plugins/YOURPLUGIN/widgets/WGT_PLUGINS_ADMIN_HELLO_WORLD/main.html plugins/YOURPLUGIN/widgets/WGT_PLUGINS_ADMIN_HELLO_WORLD/img.html plugins/YOURPLUGIN/widgets/WGT_PLUGINS_ADMIN_HELLO_WORLD/vue.html plugins/YOURPLUGIN/widgets/WGT_PLUGINS_ADMIN_HELLO_WORLD/title.html which will be run through the plugin system, so you can execute code there as need, but not if it's ever going to be slow. --- REQUIRED The tab.html is the basic description inside the tab itself, but should not include the tab title. See the WIDGET_TEXT, above for that. --- REQUIRED The url.html would need to echo something like this: CMD_PLUGINS/hello_world/index.html *without a trailing newline* pointing to where you want the "view full details" link to take you, usually a link with the full output, rather than the minimal output from main.html --- REQUIRED main.html is the right-side of the widget.. the html data shown when you click that widget's tab. Can be tables, whatever you'd like.. a staging point, etc.. but as mentioned, it's best that if it's slow, you use ajax to load some other data. The widget call won't return until everything is ready to go, so if you have a slow call, it will hold up the entire widget page. Instead, use ajax to make a call to your plugin, perhaps in an iframe or something like that, to load the data in later on.. so the page can be shown more quickly, and then the widget main data just filled in once the ajax call is done. To avoid JS conflicts with the skin, and to satisfy the quick page loads, it's likely simplest to use an iframe in main.html, and load your other page inside that iframe. --- OPTIONAL img.html returns a URL the skin can use as an image/icon to be shown in the tab itself. Use .svg if you can, square aspect ratio. Do not output a trailing newline character. --- OPTIONAL vue.html, similar to the other one-line URL output script, this will output the URL to access to your /vue/* files. --- OPTIONAL title.html - the title of the widget. This is a script, like all others, and the LANGUAGE env variable is set (Eg: to 'en' or other) So if you want your plugin widgets to support different languages, check this variable and output as needed. Stick with UTF-8 encoding, which is what Evolution uses. If you do not plan on translating your plugin, then we don't recommend using this file, in order to improve performance. If absent, DA will grab the "name=" from your plugin.conf instead.. Or if the widget name is set in the plugin.conf, you can override the title that way too eg in plugin.conf: WGT_PLUGINS_ADMIN_HELLO_MARS=Hello Mars! ========== FILLING MAIN AREA widgets are typically loaded with ajax or in real-time when you click that widget tab. So the main html area usually should *not* be your final data.. instead it should contain code to write that content to the widget, so as to not slow down the loading of the widget list. If running the tab or main code is not a time-intensive run, then you could just load your final data directly from the tab/main html files. But if they could ever be slow, you could have the main/tab code be fully static (more or less), and have the time-intensive call be done, loaded from a CMD_PLUGIN/yourplugin/user_widget.html, or example, and load that into the main area, using ajax/JS type code from your main.html =========== REFRESH INTERVALS you can specify: refresh_interval=10 in the plugin.conf to have all plugin widget to refresh every 10 seconds, done automatically by the skin. Will basically just reload the main.html area. You can restrict it to only given widget with: refresh_interval=10:WGT_PLUGINS_ADMIN_HELLO_MARS to only have WGT_PLUGINS_ADMIN_HELLO_MARS refresh every 10 seconds, but all other widgets in the plugin will not refresh at all. Span all levels with this setting. Cannot currently specify different interval =========== DELETING A PLUGIN When deleting a plugin, the user_widgets value in the user.conf (and other levels) will not be immediately touched. The full list of possible skin and plugin widgets is known, so if the combined list of possible widgets does not list a given widget that the user.conf is trying to use, it's not shown, and removed from the user.conf's user_widgets list.

Interested to try DirectAdmin? Get a 30-day Free Trial!