What it does
The CommunityEnhancements extension is designed to allow you to highlight third party integrations that users of your application can optionally take advantage of to further enhance their community. If your application requires a specific integration, then that integration is not strictly an "enhancement" and should not be highlighted in the Community Enhancements page. Extensions of this type will be shown under System > Community Enhancements and administrators will be able to review, enable and disable, and configure the enhancements as needed from this area. Some examples included with Invision Community are Viglink integration and Sendgrid integration.
How it works
The extension class defines four properties and four methods that allow you to configure the extension.
/**
* @brief Enhancement is enabled?
*/
public $enabled = FALSE;
The $enabled property specifies if the enhancement is enabled or not. Typically, you will want to have a setting stored in the database to determine if this enhancement is enabled or not, and then reset this property in the constructor (see below).
/**
* @brief IPS-provided enhancement?
*/
public $ips = FALSE;
The $ips property determines if the enhancement is provided by IPS. For all third party code, this property should be set to FALSE (which is the default).
/**
* @brief Enhancement has configuration options?
*/
public $hasOptions = TRUE;
If your enhancement has configuration settings that will need to be filled in, the $hasOptions property should be set to TRUE, otherwise this property can be set to FALSE. Most enhancements have one or more settings (e.g. to supply an API key or similar token value).
/**
* @brief Icon data
*/
public $icon = "";
You can specify the name of a file stored in the resources system for each theme to show an icon on the Community Enhancements page. See our article on adding resources for more information on adding the icon when your application is installed.
/**
* Constructor
*
* @return void
*/
public function __construct()
{
//$this->enabled = \IPS\Settings::i()->xxxxxx;
}
More often than not, you will want to reset the $enabled property based on a system setting, and you will do this in the constructor. You can perform any other setup work necessary in the constructor as well.
/**
* Edit
*
* @return void
*/
public function edit()
{
$form = new \IPS\Helpers\Form;
$form->add( new \IPS\Helpers\Form\YesNo( 'my_setting_key', \IPS\Settings::i()->my_setting_key ) );
if ( $form->values() )
{
$form->saveAsSettings();
\IPS\Session::i()->log( 'acplog__myappce_edited', array( 'enhancements__myapp_ExtensionKey' => TRUE ) );
\IPS\Output::i()->inlineMessage = \IPS\Member::loggedIn()->language()->addToStack('saved');
}
\IPS\Output::i()->output = \IPS\Theme::i()->getTemplate( 'global' )->block( 'enhancements__myapp_ExtensionKey', $form );
}
The edit() method is designed to allow you to generate a form in order to allow the administrator to configure your community enhancement. You can include as many form fields as you need/like, and you can also output additional sidebar buttons/links if you have any helpful links you would like to present to the administrator (for instance, you may wish to link to documentation about how the enhancement works, or link to a third party website to sign up for an API key in order to use the enhancement). During the save, it is recommended to store an admin log entry for future administrator reference. You use regular form helper objects in the edit() method and then pass the form to the output property, just as you would within a controller.
/**
* Enable/Disable
*
* @param $enabled bool Enable/Disable
* @return void
* @throws \LogicException
*/
public function toggle( $enabled )
{
if ( $enabled )
{
$this->testSettings();
}
//\IPS\Db::i()->update( 'core_sys_conf_settings', array( 'conf_value' => $enabled ), array( 'conf_key=?', 'xxxxxx' ) );
//unset( \IPS\Data\Store::i()->settings );
}
The toggle() method is called when an administrator attempts to toggle your enhancement enabled or disabled within the AdminCP. It is important to note that the administrator may not have yet configured your enhancement, so it is recommended to call testSettings() (described further below) if the administrator is attempting to enable the enhancement to be sure it will function correctly.
Typically, as outlined above discussing the $enabled class property, you will store the enabled/disabled flag in a setting, so you will then want to update the setting appropriately here and clear the settings data store cache.
/**
* Test Settings
*
* @return void
* @throws \LogicException
*/
protected function testSettings()
{
if ( FALSE )
{
throw new \LogicException( 'error' );
}
}
When your enhancement configuration is edited or toggled, the testSettings() method should be called in order to test the settings that have been supplied. This method should throw a LogicException exception if the test fails, which you should then catch and show an appropriate error message for. This is most frequently used to test configuration values supplied by the administrator, e.g. to call an API with a supplied API key to verify that the key is indeed valid and configured correctly. Doing so allows you to alert the administrator to any problems with the configuration right away instead of having to diagnose why something may not be working (or may be causing strange errors) later.
Report Document