On this page
Widget provides an interface to generate content such as carousel, slider, map etc to be attached to a specified position on a page, product or other apps' record. The content may be generated using PHP or a remote API endpoint (Remote Widget).
Developers can utilize SiteGUI App Builder to define new widgets and save template files for widget editing and rendering. To create a Remote Widget, just choose Remote Widget as the app type and then enter the API endpoint into the Handler field. The endpoint should be the base URL for all the operations e.g: if the endpoint is https://your-domain.com/api/widget, the edit operation will connect to https://your-domain.com/api/widget/edit to retrieve a ViewBlock to render with the "Edit Template" already saved by App Builder.
Remote Widget can be activated and used right away while PHP based widgets must be submitted to the SiteGUI Appstore for reviewing and publishing before it can be used. Therefore, always create a widget in remote mode first and test it thoroughly before converting it to PHP based widget. PHP based widgets should be used if connecting to remote API endpoint is slow.
The remote API endpoint or the PHP code should support the following operations: edit, render and update. The response should include a key named "result" with the value "success" to indicate a successful operation, PHP should return response in array format while remote API should return in JSON format. Widget does not support custom settings or authentication.
For the update operation, the response should include a key named "data" containing the widget data, cached HTML content and its expiry date can also be returned. For the edit and render operation, just a single ViewBlock is expected.
Sample Request Data
{
"site_config": {
"id": 123,
"name": "Sample",
"url": "sample.com",
"language": "en",
"...": "other site properties"
},
"id": 123,
"type": "xyz",
"name": "sample",
"data": {
"en": "Data for English",
"fr": "Data for French"
},
"cache": {
"en": "Cache Content for English",
"fr": "CacheContent for French"
},
"expire": 123456789,
"version": "1.2"
}
Sample Response Data for "update" operation
{
"result": "success",
"data": "data to save",
"cache": "HTML content to cache",
"expire": "Unix timestamp when the cache should expire"
}
Sample Response Data for "edit" and "render" operation
{
"result": "success",
"block": {
"api": {
"page": {
"id": 123,
"content": "sample"
},
"config": {
"name": "Blog",
"banner": []
}
},
"html": {
"show_author": 0
},
"template": {
"file": "widget_name_edit"
}
}
}
Sample Widget
<?php
namespace SiteGUI\Widget;
class Text {
public function __construct($site_config, $view){
$this->site_config = $site_config['site'];
$this->view = $view;
}
public function edit($widget) {
$response['result'] = 'success';
//$response['block']['api']['variable'] = "anything"; //assign custom vars to use with the template below, original widget data is available thru $api.widget
$response['block']['template']['file'] = 'widget_text_edit'; //use App Builder to save this template file
return $response;
}
public function update($widget){
if(!empty($widget['data'])) { //$widget['data'] contains multilingual string
$response['result'] = 'success';
$response['data'] = $widget['data'];
$response['cache'] = $widget['data']; //use data as cache as it is HTML/text content already
$response['expire'] = 2147483647; //max int
} else {
$response['result'] = 'error';
$response['message'] = 'Invalid widget data';
}
return $response;
}
//the render method may not be used as cache content is loaded instead
public function render($widget){
if(!empty($widget['data'])) {
$response['result'] = 'success';
$response['output'] = html_entity_decode($this->getRightLanguage($widget['data']), ENT_QUOTES);
} else {
$response['result'] = 'error';
$response['message'] = 'Invalid widget data';
}
return $response;
}
protected function getRightLanguage($data) {
if ($data) {
$c = $this->site_config;
$language = strtolower( $c['locale']??$c['language']??'en' );
if (isset($data[$language])) { //use isset just in case the var is empty
return $data[$language];
} elseif (isset($data['en'])) {
return $data['en'];
} elseif (isset($data[0])) {
return $data[0];
} else {
return 'Error: Cannot retrieve translated string';
}
}
return '';
}
}
?>