Action & Filters

Pharox uses the same hook system as WordPress. A hook is basicly an event that fires when you reach a certain point in code. Hooks are for Plugin Development only. You need those hooks in order to expand the functionality of pharox.

There are two types of hooks: Actions and Filters. An example for an action would be: "programStarted", "cssFileLoad". Now you can hook into that event and append a custom callback function that fires when that point in code get reached.

Action	Filter
HOOK.do_action(name, ...args)	HOOK.apply_filter(name, value, ...args)
HOOK.add_action(name, callback, priority?)	HOOK.add_filter(name, callback, priority?)

import { HOOK } from './hook.js';

generateFileXY()
{
    //  the event gets executed
    HOOK.do_action( 'myHookName', myVar );

    ...

}

//  append additional behaviour via callback
HOOK.add_action('myHookName', ( myVar ) => { console.log( myVar ); })

The only difference between an Action and a Filter is that a filter needs to return a value in its callback function to manipulate the original result, while an action does not need to return a value.

const content = HOOK.apply_filter("myFile", fs.readFileSync(file, 'utf8'));

...

HOOK.add_filter("myFile", ( file ) => { return file..replaceAll('a','x'); })

But why using the hooksystem at all? When adding a new feature to pharox it is highly recommended to write a new plugin using the hooksystem instead of bloating core files in order to keep the codebase nice and clean. By using hooks we can manipulate the flow of the program from the outside without messing around with the core files.

buildHTMLBefore

type	action
param	—

Fires before the HTML output folder is created and pages are rendered.

buildPageBefore

type	action
param	`pageName` string

Fires before a single page starts rendering.

buildSitemapAfter

type	action
param	—

Fires after sitemap.xml has been saved.

buildSitemapBefore

type	action
param	—

Fires before the sitemap update loop begins.

parseHeaderFileAfter

type	action
param	`filePath` string

Fires after a header file has been fully parsed.

parseHeaderFileBefore

type	action
param	`filePath` string

Fires before a header file is read and parsed.

customCss

type	filter
param	`css` string, `pageName` string, `md` MDExtract
return	string

Fires after the custom CSS file is loaded, before it is wrapped in a style tag.

getClassFileName

type	filter
param	`fileName` string
return	string

getClassMarkdown

type	filter
param	`content` string, `cls` object, `instance` MDExtract
return	string

Fires after a class markdown is generated, before it is written. Cross-links are already injected at this point.

getClassMarkdownPath

type	filter
param	`filePath` string
return	string

Fires before a class markdown file is written. Use to remap the output path.

getClassName

type	filter
param	`className` string
return	string

getClassParents

type	filter
param	`parents` string[]
return	string[]

getConfig

type	filter
param	`config` object
return	config object

Fires after the user config got loaded in.

getDefFileName

type	filter
param	`fileName` string
return	string

getDefLine

type	filter
param	`line` number or string
return	number or string

getDefName

type	filter
param	`name` string
return	string

getDefShortName

type	filter
param	`short` string
return	string

getDTOFileName

type	filter
param	`fileName` string
return	string

getDTOMembers

type	filter
param	`members` object[]
return	object[]

getDTOName

type	filter
param	`name` string
return	string

getEnumFileName

type	filter
param	`fileName` string
return	string

getEnumMarkdown

type	filter
param	`content` string
return	string

Fires after enums.md is generated, before it is written.

getEnumMembers

type	filter
param	`members` object[]
return	object[]

getEnumName

type	filter
param	`enumName` string
return	string

getFunctionFileName

type	filter
param	`fileName` string
return	string

getFunctionMarkdown

type	filter
param	`content` string
return	string

Fires after functions.md or macros.md is generated, before it is written.

getFunctionName

type	filter
param	`functionName` string
return	string

getFunctionScope

type	filter
param	`scope` string
return	string

getFunctionScopeKind

type	filter
param	`scopeKind` string
return	string

getHeaderFileContent

type	filter
param	`content` string
return	string

Fires after the header file is read, before it is parsed.

getHeaderFilePath

type	filter
param	`filePath` string
return	string

Fires for each discovered c++ file before it enters the file list.

getInlineScript

type	filter
param	`js` string
return	string

Fires after the inline JS file is loaded, before it is wrapped in a script tag.

getNavbarHTML

type	filter
param	`html` string
return	string

Fires after the navbar markdown is converted to HTML by pandoc.

getNavbarMarkdown

type	filter
param	`content` string
return	string

Fires after navbar.md is generated, before it is written.

getNavigationBar

type	filter
param	`content` string
return	string

Fires after the navbar file is loaded, before it is used.

getPageHTML

type	filter
param	`html` string
return	string

Fires after the page markdown is converted to HTML by pandoc.

getPageKeywords

type	filter
param	`keywords` string
return	string

Fires before the keyword string is injected into the meta template.

getPageLayout

type	filter
param	`html` string
return	string

Fires after the layout template file is loaded, before %PLACEHOLDER% substitution.

getPageMetaHTML

type	filter
param	`html` string
return	string

Fires after the meta template file is loaded, before %PLACEHOLDER% substitution.

getPageName

type	filter
param	`name` string
return	string

Fires for each entry in the page list before rendering begins. Use to rename or skip pages.

getPageTitle

type	filter
param	`title` string
return	string

Fires before the page title is injected into the layout.

getPlugins

type	filter
param	`plugins` Plugin[]
return	Plugin[]

Fires after the plugin list is loaded in from config.

getRobotsContent

type	filter
param	`content` string
return	string

Fires after ./robots.txt is loaded and %SITEMAP_URL% is replaced with the full sitemap URL (domain + path + /sitemap.xml), before the file is written to the HTML output directory.

getSitemapContent

type	filter
param	`content` string
return	string

Fires after all entries are injected into the sitemap XML, before the file is saved.

getSitemapDate

type	filter
param	`date` string
return	string

Fires before the date is written into each sitemap entry. Format: YYYY-MM-DD.

getSitemapEntry

type	filter
param	`entry` string
return	string

Fires after a <url> block is assembled, before it is pushed to the entries list.

getSitemapFrequency

type	filter
param	`frequency` string
return	string

Default value: monthly.

getSitemapPriority

type	filter
param	`priority` string
return	string

Default value: 0.9.

getStructFileName

type	filter
param	`fileName` string
return	string

getStructMarkdown

type	filter
param	`content` string
return	string

Fires after structs.md is generated, before it is written.

getStructMembers

type	filter
param	`members` object[]
return	object[]

getStructName

type	filter
param	`structName` string
return	string

getStructParents

type	filter
param	`parents` string[]
return	string[]

getVarFileName

type	filter
param	`fileName` string
return	string

getVarLine

type	filter
param	`line` number or string
return	number or string

getVarMarkdown

type	filter
param	`content` string
return	string

Fires after variables.md is generated, before it is written.

getVarName

type	filter
param	`name` string
return	string

getVarShortName

type	filter
param	`short` string
return	string

getTypeAttr

Comment block types (for example \class, \enum) are listed in Commands.

Filter names follow get<Type><Attr>: put the block type in place of <Type> (the word after the backslash, with normal capitalization—e.g. \class → Class, \enum → Enum).

Put the field attr in place of <Attr>. Common attributes (\brief, \details, …) are described in Commands; the attribute name is capitalized for the hook (e.g. Brief, Details).

get<Type><Attr>

Examples: getClassBrief, getFunctionDetails, getEnumSee.