4AI hooks

You can modify or extend 4AI behavior programmatically by using one or more of the hooks listed below. Hooks let you modify internal PHP structures or results computed by 4AI to better accomodate your website specific requirements.

They are events that are triggered at various moments by 4AI, providing code you write with internal information and possibly letting you modify this information.

Hooks are not altered when 4AI is updated

All the customization you do using hooks will survive 4AI updates. The hooks definition themselves will not change or be removed, unless the corresponding feature is modified or removed from 4AI of course.

When using hooks with 4AI, the following apply:

we cannot provide any form of support to the customization you make. You are on your own and the below documentation is the extent of information we'll provide to you.
you'll need suitable programming knowledge and understanding of Joomla internals to be able to write your own hooks handler
you may have to study 4AI code to learn if what you want to do is possible and how to do it. Again, we won't help your there, at least as part of regular support.

Usage

If you added any hook handler, make sure to absolutely always mention that whenever you open a support ticket. Your custom hooks can alter the way 4AI works, and may have consequences. We need to be aware of the existence of your hooks at all times.

Types

There are 2 types of hooks: filters and actions. Both are events that are triggered at different moment and to which you can respond.

The difference between them is:

filters: you receive some data, and you can return modified data. 4AI will subsequently use your modified data
action: you receive some data, but you cannot modify it. Or rather, you can modify it but 4AI will not use the result anyway

How to

As hooks are basically events, you must register your custom handler with 4AI for any hook you want to use. 4AI will then call your handler when the hook is run.

The most convenient way to register your hooks handler and include your custom code is to use 4AI functions file. The function file is unique and lives at:

/libraries/weeblr/forseo_functions.php

Create the file if it does not exist yet. You can put all your custom code in that file, or just use it to interface with 4AI and include more PHP code from wherever you want.

The 4AI function file must always start with:

<?php
/**
 * 4AI hooks file
 *
 * You can use 2 variables to access 4AI content:
 *
 * $factory: access variables
 * $hooks: add handlers
 */

// no direct access
defined('WBLIB_EXEC') || die;

If this preamble is missing, just copy/paste it at the top of the file.

After that, you can add your hook handler and your custom code. Here is a typical example, which lets us customize the OpenGraph metadata 4AI outputs on a page:

$hooks->add(
    'forai_api_endpoint',
    function ($endpoint, $requestData) {

        $endpoint = 'https://example.com/my-custom-endpoint';

        return $endpoint;
    }
);

The $hooks variable shown in the example is always available to you inside the functions files, 4AI creates it for you.

Inside the functions file, you are inside of Joomla, meaning you can use Joomla API as you would in other contexts. You can for instance use the Joomla Factory class to access the application object. Make sure to add the proper namespace use statements if you do so.

Summary

4AI currently offers 11 actions in 3 groups.

4AI currently offers 20 filters in 12 groups.

Actions

4AI currently offers 11 actions in 3 groups.

Group: Api

`forai_on_request_completed`

Api action

Run hook with the request and response data after a request is completed.

@param \stdClass $provider @param array $requestDef @param array $request

@return void

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/model/provider.php
@line 350

Group: Content

`forai_content_prepared`

Content action

Action to let plugins obtain the finalized content for the current request

4AI currently offers 20 filters in 12 groups.

Group: Admin

`forai_admin_ui_constants`

Admin filter

Filter custom CSS for admin.

@param array $uiConstants List of constants related to the specific platform visual display.

@return array

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/view/admin.php
@line 71

`forai_categories_list`

Admin filter

Filter the list of categories on the site, for user display in the admin.

@param array $categories List of objects each describing a category.

@return array

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/api/controller/categories.php
@line 175

`forai_custom_admin_css`

Admin filter

Filter custom CSS for admin.

@param string $defaultStyles The raw css to be inserted as style tag in the page.

@return string

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/view/admin.php
@line 90

`forai_custom_admin_js`

Admin filter

Filter custom JS for admin.

@param string $js The javascript to be inserted into the page with a script tag.

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/view/admin.php
@line 226

`forai_extensions_list`

Admin filter

Filter the list of extensions installed on the site, for user display in the admin.

@param array $components List of objects each describing an extension.

@return array

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/api/controller/extensions.php
@line 85

Group: Api

`forai_api_endpoint`

Api filter

Filter the endpoint to which AI API provider requests are made.

@param string $endpoint @param array $endpoint Array of model name, prompts and temperature

@return array

@since 2.1.1

in /plugins/system/forai/vendor/weeblr/forai/helper/requester.php
@line 93

`forai_api_request_data`

Api filter

Filter the data sent to the AI API provider just before a request is made.

@param array $requestData Array of model name, prompts and temperature

@return array

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/helper/requester.php
@line 115

Group: Assistant

`forai_should_inject_assistant`

Assistant filter

Filter whether 4AI should inject the assistant in the current page. The filtered value
is the result of already applying basic checks and validation that 4AI is supposed to do.
Setting this to true will display the assistant but only if Joomla ACL are satisfied.
User permissions are checked after this filter and cannot be overridenn through this filter.

@param bool $shouldInject

@since 2.0.1

in /plugins/system/forai/vendor/weeblr/forai/controller/assistant.php
@line 244

Group: Bundle

`forai_admin_js_bundle_url`

Bundle filter

Filter main JS bundle URL.

@param string $url The url of the js bundle to be linked from the page.

@return string

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/view/admin.php
@line 108

`forai_custom_admin_js`

Bundle filter

Filter list of css files to be inserted after main bundle.
Each record added to the lsit must be:
[
'url' => '', mandatory
'options' => [], | []
'attr' => [], | []
]

@param array $cssDefs An array of array[url, options, attr], each defining a link to a css file.

@return string

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/view/admin.php
@line 360

Group: Config

`forai_config`

Config filter

Filter configuration right after creating it.

@param array $config @param string $scope

@return void

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/model/config.php
@line 83

`forai_config_loaded`

Config filter

Filter configuration right after loading it from the database.

@param array $config @param string $scope

@return void

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/model/config.php
@line 158

Group: Content

`forai_onContentPrepare`

Content filter

Hook to run the registered onContentPrepare handlers.

@param bool $modified Whether the content was modified. @param string $context The context of the content being passed to the plugin. @param mixed & $row An object with a "text" property @param mixed & $params Additional parameters. See {@see PlgContentContent()}. @param integer $page Optional page number. Unused. Defaults to zero.

@since 1.0.0

in /plugins/system/forai/forai.php
@line 219

Group: Events

`forai_onPrivacyCollectAdminCapabilities`

Events filter

Hook to run the registered onAfterInitialise handlers.

@since 1.0.0

in /plugins/system/forai/forai.php
@line 128

Group: Features

`forai_features_overrides`

Features filter

Filter features overrides

@param array $featuresOverrides

@return array

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/view/admin.php
@line 128

Group: Frontend

`forai_fe_is_likely_edit_page`

Frontend filter

Filter whether the current page is likely an edit page.
Can be used to display the assistant icon on more pages than the default
Joomla native edit pages already known by 4AI.

@param bool $isLikelyEditPage

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/controller/assistant.php
@line 100

Group: Image

`forai_created_images_metadata`

Image filter

Filter metadata to be injected in created images.

@param array $metadata

@return void

@since 4.1.0

in /plugins/system/forai/vendor/weeblr/forai/data/items/image.php
@line 317

Group: Output

`forai_onAfterRenderComplete_body`

Output filter

Filter the body of the CMS response at onAfterRender.

@param string $body Body of the current request.

@since 1.0.0

in /plugins/system/forai/forai.php
@line 475

`forai_onAfterRender_body`

Output filter

Filter the body of the CMS response at onAfterRender.

@param string $body Body of the current request.

@since 1.0.0

in /plugins/system/forai/forai.php
@line 419

Group: Request

`forai_request_info`

Request filter

Filter the list of dynamic variables used in content replacement.

@param array $expandedVariables Array of variable names/variable values to use in expansions.

@return array

@since 1.0.0

in /plugins/system/forai/vendor/weeblr/forai/data/requestinfo.php
@line 126