Fmstrat/HOOKS.md

## HOOKS.md

      
    Raw
  

              HOOKS.md
            
          
    Hook Documentation

In progress documentation on hooks for plugins.
This documentation may not be up to date. Please see https://git.tt-rss.org/fox/tt-rss/wiki/Plugins for the most recent plugin documentation, or https://git.tt-rss.org/fox/tt-rss/src/master/classes/pluginhost.php#L21 to see the latest list of hooks.
Feed Fetch Hooks

These hooks run in the background when feed data is fetched.


Hook
Description
Inputs
Return


HOOK_FEED_BASIC_INFO
Used to replace basic feed information prior to fetching from the provider.
$basic_info - Blank array that is also returned
$fetch_url - URL of feed
$owner_uid - The user who owns the feed
$feed - Feed object
$auth_login - Auth user if requred
$auth_pass - Auth password if requred
$basic_info


HOOK_FETCH_FEED
Used to update feed data right before it is fetched from the provider URL.
$feed_data - Blank feed data that is also returned
 $fetch_url - URL of feed
 $owner_uid - The user who owns the feed
 $feed - Feed object
 0 - Unknown
 $auth_login - Auth user if requred
 $auth_pass - Auth password if requred
$feed_data


HOOK_FEED_FETCHED
Used to update feed data right after it is fetched from the provider URL.
$feed_data - Populated feed data that is also returned
 $fetch_url - URL of feed
 $owner_uid - The user who owns the feed
 $feed - Feed object
$feed_data


HOOK_FEED_PARSED
Unknown. Runs after the Feed Parser inits.
$rss - Feed parser object
None


HOOK_ARTICLE_FILTER
Used to update inidividual articles after the feed is fetched and parsed.
$article - Object containing an article
$article


HOOK_FILTER_TRIGGERED
Used to change the filters that match an article.
$feed - Feed object
 $owner_uid - The user who owns the feed
 $article - Object containing an article
 $matched_filters - Array of matched filters
 $matched_rules - Array of matched rules
 $article_filters - All filters
None


HOOK_ARTICLE_FILTER_ACTION
Used to update an article as filter actions are applied.
$article - Object containing an article
 $pfaction - The filter action
 $matched_rules - Array of matched rules
 $article_filters - All filters
$article


HOOK_HOUSE_KEEPING
Used to run code at the end of processing.
No inputs
None


Page Load Hooks

These hooks run when the page loads.


Hook
Description
Inputs
Return


HOOK_MAIN_TOOLBAR_BUTTON
Used to add HTML/buttons to the main toolbar area at the top left.
No inputs
HTML string


HOOK_TOOLBAR_BUTTON
Used to add HTML/dropdowns to the main toolbar area at the top right.
No inputs
HTML string


HOOK_ACTION_ITEM
Used to add options to the upper right action drop-down menu.
No inputs
HTML string


Grabbing Hooks

These hooks run when an article is grabbed, reguardless of client (mobile/HTML/etc).


Hook
Description
Inputs
Return


HOOK_RENDER_ARTICLE_API
Used to alter the article object (and headline object) as it is returned to the client. Format of object can be found here: https://gitlab.com/gothfox/tt-rss/blob/master/classes/api.php#L349
array("article" => $article) - The article object as a single element array
$article


HOOK_QUERY_HEADLINES
Used to alter the headlines as they are queried.
$line - The headline object
 $excerpt_length - The length of content to display
 true - Unknown
$line


Feed Display Hooks

These hooks run when the page loads a feed.


Hook
Description
Inputs
Return


HOOK_HEADLINE_TOOLBAR_BUTTON
Used to add options to the upper-right menu titled Select.
$feed_id - The feed id of the current feed displayed
 $is_cat - The category of that feed
HTML code


HOOK_HEADLINES_BEFORE
Used to add HTML code before the headlines are displayed.
$feed - The feed object
 $cat_view - The category view
 $qfh_ret - Unknown
HTML code


HOOK_QUERY_HEADLINES
Used to alter listing previews as they are added to the display.
$line - The object containing that headline's content preview.
 250 - Unknown (Character length?)
 false - Unknown
$line


HOOK_ARTICLE_EXPORT_FEED
Runs after HOOK_QUERY_HEADLINES but only for public feeds.
$line - Array of lines of HTML code)
 $feed - Object with feed info and the array of articles (populates each article after this runs)
 $is_cat - Category
$line


Article Display Hooks

These hooks run when the page loads an article.


Hook
Description
Inputs
Return


HOOK_ARTICLE_LEFT_BUTTON
Used to add buttons to the left of each individual article as it is displayed.
$line - Object of article data.
$line["buttons_left"]


HOOK_ARTICLE_BUTTON
Used to add buttons to the top of each individual article as it is displayed.
$line - Object of article data.
$line["buttons"]


HOOK_RENDER_ARTICLE_CDM
Used to alter article content or anything else in the displayed article.
$line - Object of article data.
$line


HOOK_RENDER_ARTICLE
Used to alter article content or anything else in the displayed article before everything has been placed into html. Note: This only runs on public feeds.
$line - Object of article data.
$line


HOOK_FORMAT_ARTICLE
Used to alter article content or anything else in the displayed article after everything has been placed into html (including buttons). Note: This only runs on public feeds.
$rv - The HTML to be returned for each article
 $line - Object of article data.
 true - Unknown
$rv


Embedded Media Hooks

Used to alter embedded media containers.


Hook
Description
Inputs
Return


HOOK_FORMAT_ENCLOSURES
Used to add content and replace default enclosures for media (url, content types, width, title, etc).
$rv - The HTML code for the enclosure
 $result - Lines of entries
 $id - Unknown
 $always_display_enclosures - Unknown
 $article_content - Content of the article
 $hide_images - Whether images are displayed
$retval ([0] = $rv, [1] = $result)


HOOK_ENCLOSURE_ENTRY
Used to alter each media item.
$line - The information on that item (url, width, title, etc)
$line


HOOK_RENDER_ENCLOSURE
Used to alter HTML as the media item is displayed.
$entry - The media item
 $hide_images - If hide images is on or off
HTML code placed in the IMG tag


Interaction Hooks

Runs when an action is executed int the client.


Hook
Description
Inputs
Return


HOOK_SUBSCRIBE_FEED
Used to alto feed content as a feed is subscribed to, right after the data is pulled.
$contents - Contents of the feed after first pull
 $url - URL of the feed
 $auth_login - Auth user if requred
 $auth_pass - Auth password if requred
$content


HOOK_UNSUBSCRIBE_FEED
Used to run code when a feed is unsubscribed.
$id - The feed id
 $owner_uid - The owner of the feed
Boolean for success


HOOK_SEARCH
Used to alter search results.
$search - The search object
The search list


HOOK_AUTH_USER
Used to add authentication methods.
$login - Username
 $password - Password
$user_id


Settings Hooks

These hooks alter settings and preferences.


Hook
Description
Inputs
Return


HOOK_HOTKEY_INFO
Used to alter the information returned about hotkeys.
$hotkeys - Object of hotkey info
$hotkeys


HOOK_HOTKEY_MAP
Used to add/alter hotkeys.
$hotkeys - Array of hotkeys
$hotkeys


HOOK_PREFS_EDIT_FEED
Used to alter a feed when the settings screen for a feed is displayed.
$feed_id - The feed's id
None


HOOK_PREFS_SAVE_FEED
Used to execute commands when a feed is saved (before commit).
$feed_id - The feed's id
None


HOOK_PREFS_TAB_SECTION
Used to run code when preferences tabs are loaded.
No inputs
None


HOOK_PREFS_TAB
Used to run code inside a preference tab.
No inputs
None


HOOK_PREFS_TABS
Used to add HTML tabs to the top of preferences.
No inputs
None


Misc Hooks

Other hooks.


Hook
Description
Inputs
Return


HOOK_SANITIZE
Runs whenever content is sanitized.
$doc - Unknown
 $site_url - Unknown 
 $allowed_elements - HTML ellements allowed in fields
 $disallowed_attributes - HTML elements not allowed in fields
 $article_id - The current article id
$retval ([0] = $doc, [1] = $allowed_elements, [2] = $disallowed_attributes)


HOOK_SEND_LOCAL_FILE
Runs when a local file is sent to a client (such as proxied media).
$filename - The file being sent
Boolean for success (not used)


HOOK_SEND_MAIL
Used to execute an action when email is sent.
$this - The current object
 $params - See https://gitlab.com/gothfox/tt-rss/blob/master/classes/mailer.php#L9
$rc (See https://gitlab.com/gothfox/tt-rss/blob/master/classes/mailer.php#L24)


HOOK_UPDATE_TASK
Unknown
No inputs
None
Hook	Description	Inputs	Return
`HOOK_FEED_BASIC_INFO`	Used to replace basic feed information prior to fetching from the provider.	`$basic_info` - Blank array that is also returned `$fetch_url` - URL of feed `$owner_uid` - The user who owns the feed `$feed` - Feed object `$auth_login` - Auth user if requred `$auth_pass` - Auth password if requred	`$basic_info`
`HOOK_FETCH_FEED`	Used to update feed data right before it is fetched from the provider URL.	`$feed_data` - Blank feed data that is also returned `$fetch_url` - URL of feed `$owner_uid` - The user who owns the feed `$feed` - Feed object `0` - Unknown `$auth_login` - Auth user if requred `$auth_pass` - Auth password if requred	`$feed_data`
`HOOK_FEED_FETCHED`	Used to update feed data right after it is fetched from the provider URL.	`$feed_data` - Populated feed data that is also returned `$fetch_url` - URL of feed `$owner_uid` - The user who owns the feed `$feed` - Feed object	`$feed_data`
`HOOK_FEED_PARSED`	Unknown. Runs after the Feed Parser inits.	`$rss` - Feed parser object	None
`HOOK_ARTICLE_FILTER`	Used to update inidividual articles after the feed is fetched and parsed.	`$article` - Object containing an article	`$article`
`HOOK_FILTER_TRIGGERED`	Used to change the filters that match an article.	`$feed` - Feed object `$owner_uid` - The user who owns the feed `$article` - Object containing an article `$matched_filters` - Array of matched filters `$matched_rules` - Array of matched rules `$article_filters` - All filters	None
`HOOK_ARTICLE_FILTER_ACTION`	Used to update an article as filter actions are applied.	`$article` - Object containing an article `$pfaction` - The filter action `$matched_rules` - Array of matched rules `$article_filters` - All filters	`$article`
`HOOK_HOUSE_KEEPING`	Used to run code at the end of processing.	No inputs	None
Hook	Description	Inputs	Return
`HOOK_MAIN_TOOLBAR_BUTTON`	Used to add HTML/buttons to the main toolbar area at the top left.	No inputs	HTML string
`HOOK_TOOLBAR_BUTTON`	Used to add HTML/dropdowns to the main toolbar area at the top right.	No inputs	HTML string
`HOOK_ACTION_ITEM`	Used to add options to the upper right action drop-down menu.	No inputs	HTML string
Hook	Description	Inputs	Return
`HOOK_RENDER_ARTICLE_API`	Used to alter the article object (and headline object) as it is returned to the client. Format of object can be found here: https://gitlab.com/gothfox/tt-rss/blob/master/classes/api.php#L349	`array("article" => $article)` - The article object as a single element array	`$article`
`HOOK_QUERY_HEADLINES`	Used to alter the headlines as they are queried.	`$line` - The headline object `$excerpt_length` - The length of content to display `true` - Unknown	`$line`
Hook	Description	Inputs	Return
`HOOK_HEADLINE_TOOLBAR_BUTTON`	Used to add options to the upper-right menu titled Select.	`$feed_id` - The feed id of the current feed displayed `$is_cat` - The category of that feed	HTML code
`HOOK_HEADLINES_BEFORE`	Used to add HTML code before the headlines are displayed.	`$feed` - The feed object `$cat_view` - The category view `$qfh_ret` - Unknown	HTML code
`HOOK_QUERY_HEADLINES`	Used to alter listing previews as they are added to the display.	`$line` - The object containing that headline's content preview. `250` - Unknown (Character length?) `false` - Unknown	`$line`
`HOOK_ARTICLE_EXPORT_FEED`	Runs after HOOK_QUERY_HEADLINES but only for public feeds.	`$line` - Array of lines of HTML code) `$feed` - Object with feed info and the array of articles (populates each article after this runs) `$is_cat` - Category	`$line`
Hook	Description	Inputs	Return
`HOOK_ARTICLE_LEFT_BUTTON`	Used to add buttons to the left of each individual article as it is displayed.	`$line` - Object of article data.	`$line["buttons_left"]`
`HOOK_ARTICLE_BUTTON`	Used to add buttons to the top of each individual article as it is displayed.	`$line` - Object of article data.	`$line["buttons"]`
`HOOK_RENDER_ARTICLE_CDM`	Used to alter article content or anything else in the displayed article.	`$line` - Object of article data.	`$line`
`HOOK_RENDER_ARTICLE`	Used to alter article content or anything else in the displayed article before everything has been placed into html. Note: This only runs on public feeds.	`$line` - Object of article data.	`$line`
`HOOK_FORMAT_ARTICLE`	Used to alter article content or anything else in the displayed article after everything has been placed into html (including buttons). Note: This only runs on public feeds.	`$rv` - The HTML to be returned for each article `$line` - Object of article data. `true` - Unknown	`$rv`
Hook	Description	Inputs	Return
`HOOK_FORMAT_ENCLOSURES`	Used to add content and replace default enclosures for media (url, content types, width, title, etc).	`$rv` - The HTML code for the enclosure `$result` - Lines of entries `$id` - Unknown `$always_display_enclosures` - Unknown `$article_content` - Content of the article `$hide_images` - Whether images are displayed	`$retval ([0] = $rv, [1] = $result)`
`HOOK_ENCLOSURE_ENTRY`	Used to alter each media item.	`$line` - The information on that item (url, width, title, etc)	`$line`
`HOOK_RENDER_ENCLOSURE`	Used to alter HTML as the media item is displayed.	`$entry` - The media item `$hide_images` - If hide images is on or off	HTML code placed in the IMG tag
Hook	Description	Inputs	Return
`HOOK_SUBSCRIBE_FEED`	Used to alto feed content as a feed is subscribed to, right after the data is pulled.	`$contents` - Contents of the feed after first pull `$url` - URL of the feed `$auth_login` - Auth user if requred `$auth_pass` - Auth password if requred	`$content`
`HOOK_UNSUBSCRIBE_FEED`	Used to run code when a feed is unsubscribed.	`$id` - The feed id `$owner_uid` - The owner of the feed	Boolean for success
`HOOK_SEARCH`	Used to alter search results.	`$search` - The search object	The search list
`HOOK_AUTH_USER`	Used to add authentication methods.	`$login` - Username `$password` - Password	`$user_id`
Hook	Description	Inputs	Return
`HOOK_HOTKEY_INFO`	Used to alter the information returned about hotkeys.	`$hotkeys` - Object of hotkey info	`$hotkeys`
`HOOK_HOTKEY_MAP`	Used to add/alter hotkeys.	`$hotkeys` - Array of hotkeys	`$hotkeys`
`HOOK_PREFS_EDIT_FEED`	Used to alter a feed when the settings screen for a feed is displayed.	`$feed_id` - The feed's id	None
`HOOK_PREFS_SAVE_FEED`	Used to execute commands when a feed is saved (before commit).	`$feed_id` - The feed's id	None
`HOOK_PREFS_TAB_SECTION`	Used to run code when preferences tabs are loaded.	No inputs	None
`HOOK_PREFS_TAB`	Used to run code inside a preference tab.	No inputs	None
`HOOK_PREFS_TABS`	Used to add HTML tabs to the top of preferences.	No inputs	None
Hook	Description	Inputs	Return
`HOOK_SANITIZE`	Runs whenever content is sanitized.	`$doc` - Unknown `$site_url` - Unknown `$allowed_elements` - HTML ellements allowed in fields `$disallowed_attributes` - HTML elements not allowed in fields `$article_id` - The current article id	`$retval ([0] = $doc, [1] = $allowed_elements, [2] = $disallowed_attributes)`
`HOOK_SEND_LOCAL_FILE`	Runs when a local file is sent to a client (such as proxied media).	`$filename` - The file being sent	Boolean for success (not used)
`HOOK_SEND_MAIL`	Used to execute an action when email is sent.	`$this` - The current object `$params` - See https://gitlab.com/gothfox/tt-rss/blob/master/classes/mailer.php#L9	`$rc` (See https://gitlab.com/gothfox/tt-rss/blob/master/classes/mailer.php#L24)
`HOOK_UPDATE_TASK`	Unknown	No inputs	None