Documentation by Black Sheep Research

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Option Changes Plugin ======

This plugin exists to make it easy to handle changes to component options (accessed by the "Options" button in the top right corner). Option changes are handled by Joomla and without a change handler, your component does not know they have happened. For some changes, this does not matter. But for others, you need to take some action when an option changes.

To make this easy, install the Option Changes Plugin and publish it. To make it work for you, add some code to your component install script. It is conveniently done as a method and you can use it with minimal changes:

	private function registerWithOptionsHandler(): bool
	{
		try
		{
			// Get the application
			$app = Factory::getApplication();
			
			// Register the component with the handler plugin
			$result = $app->triggerEvent('onRegisterComponent', [
				'com_yourcomponent',
				'YourNamespace\\Component\\YourComponent\\Administrator\\Helper\\OptionsHandler',
				'handleOptionsChange',
				true, // Call the method statically
				'com_config.component' // Context
			]);
			
			// Check if registration was successful
			if (isset($result[0]) && $result[0] === true)
			{
				// Registration successful
				Log::add(
					'Successfully registered com_yourcomponent with CompOptionsHandler plugin',
					Log::INFO,
					'com_yourcomponent'
				);
				
				return true;
			}
			else
			{
				// Registration failed or no plugin responded
				Log::add(
					'Failed to register com_yourcomponent with CompOptionsHandler plugin. Is the plugin installed and enabled?',
					Log::WARNING,
					'com_yourcomponent'
				);
				
				return false;
			}
		}
		catch (\Exception $e)
		{
			// Log any errors
			Log::add(
				'Error registering com_yourcomponent with CompOptionsHandler plugin: ' . $e->getMessage(),
				Log::ERROR,
				'com_yourcomponent'
			);
			
			return false;
		}
	}

For example, UserPoints uses the following:

            'com_userpoints',
            OptionChange::class,
            'handleOptionsChange',
            true

which relies on the use statement:

     use BlackSheepResearch\Component\UserPoints\Site\Problems\OptionChange;

If you specify a static method, the plugin will simply call it. If you specify a non-static call, the plugin will create a new object - although this will not work if you use a class that requires parameters.

===== Using the Option Changes Plugin =====

Once you have set this up, your method will be called if any of the options are changed through the Joomla administrator interface. [[optionchanges:handlingchanges | This page tells you how to use the information provided]], including a number of examples.