Docs For Class Plugin

Methods

Constructor Plugin [line 306]

Plugin Plugin(
)

Constructor.

You should not use a constructor with your plugin, but the Plugin::PluginInit() method instead!

[ Top ]

AdminAfterMenuInit [line 669]

void AdminAfterMenuInit(
)

Event handler: Gets invoked in /admin.php for every backoffice page after the menu structure is built. You could use the $AdminUI object to modify it.

This is the hook to register menu entries. See register_menu_entry().

Redefined in descendants as:

[ Top ]

AdminAfterNavbarInit [line 657]

void AdminAfterNavbarInit(
)

Event handler: Gets invoked in /toolbar.inc.php after the menu structure is built.

Redefined in descendants as:

test_plugin::AdminAfterNavbarInit()

[ Top ]

AdminAfterPageFooter [line 694]

boolean AdminAfterPageFooter(
array
&$params 
)

Event handler: Called right after displaying the admin page footer.

Parameters:

array

&$params:

Associative array of parameters

API Tags:

Return:

did we do something?

Redefined in descendants as:

test_plugin::AdminAfterPageFooter()

[ Top ]

AdminBeforeItemEditCreate [line 1314]

void AdminBeforeItemEditCreate(
array
&$params 
)

Event handler: Called before a new item gets created (in the backoffice).

You could add a message of category "error" here, to prevent the comment from being inserted.

Parameters:

array

&$params:

Associative array of parameters

'Item': the Item which gets created (by reference)

Redefined in descendants as:

test_plugin::AdminBeforeItemEditCreate()

[ Top ]

AdminBeforeItemEditDelete [line 1300]

void AdminBeforeItemEditDelete(
array
&$params 
)

Event handler: Called before an item gets deleted (in the backoffice).

You could add a message of category "error" here, to prevent the comment from being deleted.

Parameters:

array

&$params:

Associative array of parameters 'Item': the Item which gets created (by reference)

Information Tags:

Since:

2.0

[ Top ]

AdminBeforeItemEditUpdate [line 1328]

void AdminBeforeItemEditUpdate(
array
&$params 
)

Event handler: Called before an existing item gets updated (in the backoffice).

You could add a message of category "error" here, to prevent the comment from being inserted.

Parameters:

array

&$params:

Associative array of parameters 'Item': the Item which gets updated (by reference)

Redefined in descendants as:

test_plugin::AdminBeforeItemEditUpdate()

[ Top ]

AdminBeginPayload [line 816]

void AdminBeginPayload(
)

Event handler: Gets invoked before the main payload in the backoffice.

Redefined in descendants as:

test_plugin::AdminBeginPayload()

[ Top ]

AdminDispCommentFormField [line 1440]

boolean AdminDispCommentFormField(
array
&$params 
)

Event handler: Called at the end of the "Edit comment" form.

Parameters:

array

&$params:

Associative array of parameters

'Form': the Form object (by reference)
'Comment': the Comment which gets edited (by reference)
'edit_layout': only NULL currently, as there's only one layout

API Tags:

Return:

did we display something?

Redefined in descendants as:

[ Top ]

AdminDisplayCommentToolbar [line 1425]

boolean AdminDisplayCommentToolbar(
array
&$params 
)

Event handler: Called when displaying comment editor toolbars in admin.

Parameters:

array

&$params:

Associative array of parameters

API Tags:

Return:

did we display a toolbar?

Redefined in descendants as:

[ Top ]

AdminDisplayEditorButton [line 715]

boolean AdminDisplayEditorButton(
array
$params 
)

Event handler: Called when displaying editor buttons.

This method, if implemented, should output the buttons (probably as html INPUT elements) and return true, if button(s) have been displayed.

You should provide an unique html ID with your button.

Parameters:

array

$params:

Associative array of parameters.

'target_type': either 'Comment' or 'Item'.
'edit_layout': "simple", "expert", etc. (users, plugins, etc. may create their own layouts in addition to these)

NOTE: "simple" mode for writing is gone but 'edit_layout' is still here because I'm lazy :)

API Tags:

Return:

did we display a button?

Redefined in descendants as:

[ Top ]

AdminDisplayFieldsetAbove [line 1252]

boolean AdminDisplayFieldsetAbove(
array
&$params 
)

Event handler: Called when displaying item form fieldsets above the post textarea.

Parameters:

array

&$params:

Associative array of parameters

'Form': the Form object (by reference)
'Item': the Item which gets edited (by reference)
'edit_layout': "simple", "expert", etc. (users, plugins, etc. may create their own layouts in addition to these)

NOTE: "simple" mode for writing is gone but 'edit_layout' is still here because I'm lazy :)

API Tags:

Return:

did we display something?

Redefined in descendants as:

test_plugin::AdminDisplayFieldsetAbove()

[ Top ]

AdminDisplayFieldsetBelow [line 1268]

boolean AdminDisplayFieldsetBelow(
array
&$params 
)

Event handler: Called when displaying item form fieldsets below the post textarea.

Parameters:

array

&$params:

Associative array of parameters

'Form': the Form object (by reference)
'Item': the Item which gets edited (by reference)
'edit_layout': "simple", "expert", etc. (users, plugins, etc. may create their own layouts in addition to these)

NOTE: "simple" mode for writing is gone but 'edit_layout' is still here because I'm lazy :)

API Tags:

Return:

did we display something?

Redefined in descendants as:

test_plugin::AdminDisplayFieldsetBelow()

[ Top ]

AdminDisplayFieldsetSidebar [line 1284]

boolean AdminDisplayFieldsetSidebar(
array
&$params 
)

Event handler: Called when displaying item form fieldsets at the top of the sidebar.

Parameters:

array

&$params:

Associative array of parameters

'Form': the Form object (by reference)
'Item': the Item which gets edited (by reference)
'edit_layout': "simple", "expert", etc. (users, hackers, plugins, etc. may create their own layouts in addition to these)

NOTE: "simple" mode for writing is gone but 'edit_layout' is still here because I'm lazy :)

API Tags:

Return:

did we display something?

Redefined in descendants as:

[ Top ]

AdminDisplayToolbarAbove [line 730]

boolean AdminDisplayToolbarAbove(
array
&$params 
)

Event handler: Called when displaying editor toolbars above the post textarea.

Parameters:

array

&$params:

Associative array of parameters

'target_type': either 'Comment' or 'Item'.
'edit_layout': "simple", "expert", etc. (users, plugins, etc. may create their own layouts in addition to these)

NOTE: "simple" mode for writing is gone but 'edit_layout' is still here because I'm lazy :)

API Tags:

Return:

did we display a toolbar?

Redefined in descendants as:

[ Top ]

AdminDisplayToolbarBelow [line 745]

boolean AdminDisplayToolbarBelow(
array
&$params 
)

Event handler: Called when displaying editor toolbars below the post textarea.

Parameters:

array

&$params:

Associative array of parameters

'target_type': either 'Comment' or 'Item'.
'edit_layout': "simple", "expert", etc. (users, plugins, etc. may create their own layouts in addition to these)

NOTE: "simple" mode for writing is gone but 'edit_layout' is still here because I'm lazy :)

API Tags:

Return:

did we display a toolbar?

Redefined in descendants as:

[ Top ]

AdminDisplayToolbarSidebar [line 760]

boolean AdminDisplayToolbarSidebar(
array
&$params 
)

Event handler: Called when displaying editor toolbars at the top of the sidebar.

Parameters:

array

&$params:

Associative array of parameters

'target_type': either 'Comment' or 'Item'.
'edit_layout': "simple", "expert", etc. (users, plugins, etc. may create their own layouts in addition to these)

NOTE: "simple" mode for writing is gone but 'edit_layout' is still here because I'm lazy :)

API Tags:

Return:

did we display a toolbar?

Redefined in descendants as:

[ Top ]

AdminEndHtmlHead [line 682]

boolean AdminEndHtmlHead(
array
&$params 
)

Event handler: Called when ending the admin html head section.

Parameters:

array

&$params:

Associative array of parameters

API Tags:

Return:

did we do something?

Redefined in descendants as:

[ Top ]

AdminTabAction [line 795]

void AdminTabAction(
)

Event handler: Method that gets invoked when our tab is selected.

You should catch (your own) params (using param()) here and do actions (but no output!).

Use msg() to add messages for the user.

Redefined in descendants as:

[ Top ]

AdminTabPayload [line 807]

boolean AdminTabPayload(
)

Event handler: Gets invoked when our tab is selected and should get displayed.

Do your output here.

API Tags:

Return:

did we display something?

Redefined in descendants as:

[ Top ]

AdminToolAction [line 771]

void AdminToolAction(
)

Event handler: Called when handling actions for the "Tools" menu.

Use msg() to add messages for the user.

Redefined in descendants as:

test_plugin::AdminToolAction()

[ Top ]

AdminToolPayload [line 781]

boolean AdminToolPayload(
)

Event handler: Called when displaying the block in the "Tools -> misc" menu.

API Tags:

Return:

did we display something?

Redefined in descendants as:

test_plugin::AdminToolPayload()

[ Top ]

AfterCommentDelete [line 1592]

void AfterCommentDelete(
array
&$params 
)

Event handler: called at the end of deleting a comment from the database.

Parameters:

array

&$params:

Associative array of parameters

'Comment': the related Comment (by reference)

[ Top ]

AfterCommentFormInsert [line 1530]

void AfterCommentFormInsert(
array
&$params 
)

Event handler: Called when a comment form has been processed and the comment got inserted into DB.

Parameters:

array

&$params:

Associative array of parameters

'Comment': the Comment (by reference)
'original_comment': this is the unstripped and unformated posted comment

Redefined in descendants as:

captcha_img_plugin::AfterCommentFormInsert()

[ Top ]

AfterCommentInsert [line 1580]

void AfterCommentInsert(
array
&$params 
)

Event handler: called at the end of inserting a comment into the database, which means it has been created.

Parameters:

array

&$params:

Associative array of parameters

'Comment': the related Comment (by reference)
'dbchanges': array with DB changes; a copy of Comment::dbchanges(), before they got applied (since 1.9)

[ Top ]

AfterCommentUpdate [line 1566]

void AfterCommentUpdate(
array
&$params 
)

Event handler: called at the end of updating a comment in the database.

Parameters:

array

&$params:

Associative array of parameters

'Comment': the related Comment (by reference)
'dbchanges': array with DB changes; a copy of Comment::dbchanges(), before they got applied (since 1.9)

[ Top ]

AfterFileSave [line 2376]

void AfterFileSave(
array
&$params 
)

Event handler: Called after an uploaded file gets saved on server.

Parameters:

array

&$params:

Associative array of parameters

'newFile': The new "File" object (by reference).

[ Top ]

AfterFileUpload [line 2364]

boolean AfterFileUpload(
array
&$params 
)

Event handler: Called before an uploaded file gets saved on server.

Parameters:

array

&$params:

Associative array of parameters

'File': The "File" object (by reference).
'name': file name (by reference).
'type': file mimetype (by reference).
'tmp_name': file location (by reference).
'size': file size in bytes (by reference).

API Tags:

Return:

'false' to abort file upload, otherwise return 'true'

[ Top ]

AfterInstall [line 928]

void AfterInstall(
)

Event handler: Called after the plugin has been installed.

Redefined in descendants as:

[ Top ]

AfterItemDelete [line 1215]

void AfterItemDelete(
array
&$params 
)

Event handler: called at the end of deleting an item/post from the database.

Parameters:

array

&$params:

Associative array of parameters

'Item': the related Item (by reference)

[ Top ]

AfterItemInsert [line 1203]

void AfterItemInsert(
array
&$params 
)

Event handler: called at the end of inserting a item/post into the database, which means it has been created.

Parameters:

array

&$params:

Associative array of parameters

'Item': the related Item (by reference)
'dbchanges': array with DB changes; a copy of Item::dbchanges(), before they got applied (since 1.9)

[ Top ]

AfterItemUpdate [line 1174]

void AfterItemUpdate(
array
&$params 
)

Event handler: called at the end of updating an item/post in the database.

Parameters:

array

&$params:

Associative array of parameters

'Item': the related Item (by reference)
'dbchanges': array with DB changes; a copy of Item::dbchanges(), before they got applied (since 1.9)

[ Top ]

AfterLoginAnonymousUser [line 1975]

void AfterLoginAnonymousUser(

&$params 
)

Event handler: Called at the end of the login procedure, if the user is anonymous ($current_User NOT set).

Use this for example to read some cookie and define further handling of this visitor or force them to login, by adding a message of class "login_error", which will trigger the login screen.

Parameters:

&$params:

[ Top ]

AfterLoginRegisteredUser [line 1993]

void AfterLoginRegisteredUser(

&$params 
)

Event handler: Called at the end of the login procedure, if the $current_User is set and the user is therefor registered.

Use this for example to re-act on specific Plugin::$UserSettings, e.g., call Plugin::forget_events() to de-activate the plugin for the current request.

You can also add a message of class "login_error" to prevent the user from accessing the site and triggering the login screen.

Parameters:

&$params:

[ Top ]

AfterSendMessage [line 1750]

void AfterSendMessage(
)

Event handler: Called after a message has been sent through the public email form.

This is meant to cleanup generated data.

Redefined in descendants as:

captcha_img_plugin::AfterSendMessage()

[ Top ]

AfterTrackbackInsert [line 1625]

void AfterTrackbackInsert(
array
&$params 
)

Event handler: Gets called after a trackback has been recorded.

Parameters:

array

&$params:

Associative array of parameters

"blog_name" => "author"
"url" => "author_url"
"title"/"excerpt" => "comment"

[ Top ]

AfterUserDelete [line 2221]

void AfterUserDelete(
array
&$params 
)

Event handler: called at the end of deleting an user from the database.

Parameters:

array

&$params:

Associative array of parameters

'User': the related User (by reference)

Information Tags:

Since:

1.8.1

[ Top ]

AfterUserInsert [line 2208]

void AfterUserInsert(
array
&$params 
)

Event handler: called at the end of inserting an user account into the database, which means it has been created.

Parameters:

array

&$params:

Associative array of parameters

'User': the related User (by reference)

Information Tags:

Since:

1.8.1

[ Top ]

AfterUserRegistration [line 2028]

void AfterUserRegistration(
array
&$params 
)

Event handler: Called when a new user has registered and got created.

Note: if you want to modify a new user, use Plugin::AppendUserRegistrTransact() instead!

Parameters:

array

&$params:

Associative array of parameters

'User': the user object (as reference).

Redefined in descendants as:

[ Top ]

AfterUserUpdate [line 2195]

void AfterUserUpdate(
array
&$params 
)

Event handler: called at the end of updating an user account in the database, which means that it has been changed.

Parameters:

array

&$params:

Associative array of parameters

'User': the related User (by reference)

Information Tags:

Since:

1.8.1

[ Top ]

AlternateAuthentication [line 2182]

boolean AlternateAuthentication(

&$params 
)

Event handler: called at the end of the login process, if the user did not try to login (by sending "login" and "pwd"), the session has no user attached or only "login" is given.

This hook is meant to automagically login/authenticate an user by his/her IP address, special cookie, etc..

If you can authenticate the user, you'll have to attach him to the $Session, either through Session::set_user_ID() or Session::set_User().

Parameters:

&$params:

API Tags:

Return:	True, if the user has been authentificated (set in $Session)
See:	Plugin::Logout()
See:	Plugin::LoginAttempt()

Redefined in descendants as:

test_plugin::AlternateAuthentication()

[ Top ]

AppendHitLog [line 2346]

boolean AppendHitLog(
array
&$params 
)

Event handler: Called when a hit gets logged, but before it gets recorded.

Parameters:

array

&$params:

Associative array of parameters

'Hit': The "Hit" object (by reference).

API Tags:

Return:

True if you've handled the recording of the hit, false otherwise.

Redefined in descendants as:

basic_antispam_plugin::AppendHitLog()

[ Top ]

AppendItemPreviewTransact [line 1226]

void AppendItemPreviewTransact(
array
&$params 
)

Event handler: called when instantiating an Item for preview.

Parameters:

array

&$params:

Associative array of parameters

'Item': the related Item (by reference)

[ Top ]

AppendUserRegistrTransact [line 2013]

boolean AppendUserRegistrTransact(
array
&$params 
)

Event handler: Called when a new user has registered, at the end of the DB transaction that created this user.

If you want to modify the about-to-be-created user (if the transaction gets committed), you'll have to call User::dbupdate() on it, because he got already inserted (but the transaction is not yet committed).

Note: if you want to re-act on a new user, use Plugin::AfterUserRegistration() instead!

Parameters:

array

&$params:

Associative array of parameters

'User': the user object (as reference).

API Tags:

Return:

false if the whole transaction should get rolled back (the user does not get created).

[ Top ]

are_events_available [line 2712]

boolean are_events_available(
array|string
$events, [boolean
$by_one_plugin = false] 
)

Check if the requested list of events is provided by any or one plugin.

Parameters:

array\|string	$events:	A single event or a list thereof
boolean	$by_one_plugin:	Make sure there's at least one plugin that provides them all? This is useful for event pairs like "CaptchaPayload" and "CaptchaValidated", which should be served by the same plugin.

[ Top ]

BeforeBlogDisplay [line 828]

void BeforeBlogDisplay(

&$params 
)

Event handler: Called before a blog gets displayed (in _blog_main.inc.php).

Parameters:

&$params:

[ Top ]

BeforeCommentFormInsert [line 1517]

void BeforeCommentFormInsert(
array
&$params 
)

Event handler: Called before a comment gets inserted through the public comment form.

Use this, to validate a comment: you could add a message of category "error" here, to prevent the comment from being inserted.

Parameters:

array

&$params:

Associative array of parameters

'Comment': the Comment (by reference)
'original_comment': this is the unstripped and unformated posted comment
'action': "save" or "preview" (by reference) (since 1.10)
'is_preview': is this a request for previewing the comment? (boolean)

API Tags:

See:

Plugin::DisplayCommentFormFieldset()

Redefined in descendants as:

[ Top ]

BeforeDisable [line 999]

void BeforeDisable(
)

Event handler: Your plugin gets notified here, just before it gets disabled.

You cannot prevent this, but only clean up stuff, if you have to.

[ Top ]

BeforeEnable [line 987]

true|string BeforeEnable(
)

Event handler: Called when the admin tries to enable the plugin, changes its configuration/settings and after installation.

Use this, if your plugin needs configuration before it can be used.

API Tags:

Return:

True, if the plugin can be enabled/activated, a string with an error/note otherwise.

Redefined in descendants as:

basic_antispam_plugin::BeforeEnable()
captcha_img_plugin::BeforeEnable()
generic_ping_plugin::BeforeEnable() : Check ping service URL and plugin code.
turingtest_plugin::BeforeEnable()
twitter_plugin::BeforeEnable()

[ Top ]

BeforeInstall [line 919]

true|string BeforeInstall(
)

Event handler: Called before the plugin is going to be installed.

This is the hook to create any DB tables or the like.

If you just want to add a note, use Plugin::msg() (and return true).

API Tags:

Return:

True, if the plugin can be enabled/activated, a string with an error/note otherwise.

Redefined in descendants as:

test_plugin::BeforeInstall()

[ Top ]

BeforeSendMessage [line 1723]

void BeforeSendMessage(
array
&$params 
)

Event handler: Called when a message form has been submitted.

Add messages of category "error" to prevent the message from being sent.

You can also alter the "message" or "message_footer" that gets sent here.

Parameters:

array

&$params:

Associative array of parameters

'recipient_ID': ID of the user (if any)
'item_ID': ID of the item where the user clicked the msgform icon (if any)
'comment_ID': ID of the comment where the user clicked the msgform icon (if any)
'sender_name': The name of the sender (by reference) (since 1.10.0)
'sender_email': The email address of the sender (by reference) (since 1.10.0)
'subject': The subject of the message to be sent (by reference) (since 1.10.0)
'message': The message to be sent (by reference)
'message_footer': The footer of the message (by reference)
'Blog': The blog, depending on the context (may be null) (by reference) (since 1.10.0)

Redefined in descendants as:

[ Top ]

BeforeSessionsDelete [line 2332]

array BeforeSessionsDelete(
array
&$params 
)

Event handler: Called before pruning sessions. The plugin can prevent deletion of particular sessions, by returning their IDs.

Note: There can be hundreds of thousands of sessions about to be deleted. Any plugin making use of this may have serious performance/memory issues.

fp> TODO: maybe we should pass the prune cut off date instead. What's a use case for this?

Parameters:

array

&$params:

Associative array of parameters

'IDs': list of session IDs that are about to get deleted (WARNING: potentially huge)

API Tags:

Return:

List of IDs that should not get deleted

Redefined in descendants as:

test_plugin::BeforeSessionsDelete()

[ Top ]

BeforeThumbCreate [line 1819]

void BeforeThumbCreate(
array
&$params 
)

This gets called before an image thumbnail gets created.

This is useful to post-process the thumbnail image (add a watermark or change colors).

Parameters:

array

&$params:

Associative array of parameters

'File': the related File (by reference)
'imh': image resource (by reference)
'size': size name (by reference)
'mimetype': mimetype of thumbnail (by reference)
'quality': JPEG image quality [0-100] (by reference)

[ Top ]

BeforeTrackbackInsert [line 1611]

void BeforeTrackbackInsert(
array
&$params 
)

Event handler: called before a trackback gets recorded.

Use this, to validate a trackback: you could add a message of category "error" here, to prevent the trackback from being accepted.

Parameters:

array

&$params:

Associative array of parameters

"blog_name" => "author"
"url" => "author_url"
"title"/"excerpt" => "comment"

Redefined in descendants as:

[ Top ]

BeforeUninstall [line 955]

boolean|NULL BeforeUninstall(
array
&$params 
)

Event handler: Called before the plugin is going to be un-installed.

This is the hook to remove any files or the like - tables with canonical names (see Plugin::get_sql_table(), are handled internally.

See BeforeUninstallPayload() for the corresponding payload handler, which you can request to invoke by returning NULL here.

Note: this method gets called again, if the uninstallation has to be confirmed, either because you've requested a call to BeforeUninstallPayload() or there are tables to be dropped (what the admin user has to confirm).

Parameters:

array

&$params:

Associative array of parameters. 'unattended': true if Uninstall is unattended (e.g., the /install action "deletedb" uses it). This should cleanup everything without confirmation!

API Tags:

Return:

true when it's ok to uninstall, false on failure (the plugin won't get uninstalled then). You should add the reason for it through Plugin::msg(). NULL requests to execute the BeforeUninstallPayload() method.

Redefined in descendants as:

test_plugin::BeforeUninstall()

[ Top ]

BeforeUninstallPayload [line 973]

void BeforeUninstallPayload(
array
&$params 
)

Event handler: Gets invoked to display the payload before uninstalling the plugin.

You have to request a call to this during the plugin uninstall procedure by returning NULL in BeforeUninstall().

Parameters:

array

&$params:

Associative array of parameters. 'Form': The Form that asks the user for confirmation (by reference). If your plugin uses canonical table names (see Plugin::get_sql_table()), there will be already a list of those tables included in it. Do not end the form, just add own inputs or hidden keys to it.

[ Top ]

CacheIsCollectingContent [line 1803]

boolean CacheIsCollectingContent(
)

Event handler: gets asked for if we are generating cached content.

This is useful to not generate a list of online users or the like.

API Tags:

See:

Plugin::CachePageContent()

[ Top ]

CacheObjects [line 1768]

boolean CacheObjects(
array
&$params 
)

Event handler: called to cache object data.

Parameters:

array

&$params:

Associative array of parameters

'action': 'delete', 'set', 'get'
'key': The key to refer to 'data'
'data': The actual data. This must be set by the plugin.

API Tags:

Return:

True if action was successful, false otherwise.

[ Top ]

CachePageContent [line 1790]

boolean CachePageContent(
array
&$params 
)

Event handler: called to cache page content (get cached content or request caching).

This method must build a unique key for the requested page (including cookie/session info) and start an output buffer, to get the content to cache.

Note, that there are special occassions when this event does not get called, because we want really fresh content always:

we're generating static pages
there gets a "dynamic object", such as "Messages" or "core.preview_Comment" transported in the session

Parameters:

array

&$params:

Associative array of parameters

'data': this must get set to the page content on cache hit

API Tags:

Return:	True if we handled the request (either returned caching data or started buffering), false if we do not want to cache this page.
See:	Plugin::CacheIsCollectingContent()

[ Top ]

CaptchaPayload [line 2245]

boolean CaptchaPayload(
array
&$params 
)

Event handler: general event to inject payload for a captcha test.

This does not get called by Quam Plures itself, but provides an interface to other plugins. E.g., the dnsbl_antispam_plugin uses this event optionally to whitelist a user.

Parameters:

array

&$params:

Associative array of parameters

'Form': the form where payload should get added (by reference, OPTIONALLY!) If it's not given as param, you have to create an own form, if you need one.
'form_use_fieldset': if a "Form" param is given and we use it, should we add an own fieldset? (boolean, default "true", OPTIONALLY!)
'key': A key that is associated to the caller of the event (string, OPTIONALLY!)

API Tags:

Return:

True, if you have provided payload for a captcha test

Redefined in descendants as:

captcha_img_plugin::CaptchaPayload()

[ Top ]

CaptchaValidated [line 2268]

boolean CaptchaValidated(
array
&$params 
)

Event handler: general event to validate a captcha which payload was added through CaptchaPayload().

This does not get called by Quam Plures itself, but provides an interface to other plugins. E.g., the dnsbl_antispam_plugin uses this event optionally to whitelist a user.

NOTE: if the action is verified/completed in total, you HAVE to call CaptchaValidatedCleanup(), so that the plugin can cleanup its data and is not vulnerable against multiple usage of the same captcha!

Parameters:

array

&$params:

Associative array of parameters

'validate_error': you can optionally set this, if you want to give a reason of the failure. This is optionally and meant to be used by other plugins that trigger this event.

API Tags:

Return:

true if the catcha could be validated

Redefined in descendants as:

captcha_img_plugin::CaptchaValidated()

[ Top ]

CaptchaValidatedCleanup [line 2283]

void CaptchaValidatedCleanup(

&$params 
)

Event handler: general event to be called after an action has been taken, which involved CaptchaPayload() and CaptchaValidated().

This is meant to cleanup generated data for the Captcha test.

This does not get called by Quam Plures itself, but provides an interface to other plugins. E.g., the dnsbl_antispam_plugin uses this event optionally to whitelist a user.

Parameters:

&$params:

Redefined in descendants as:

captcha_img_plugin::CaptchaValidatedCleanup()

[ Top ]

CommentFormSent [line 1498]

void CommentFormSent(
array
&$params 
)

Event handler: Called before at the beginning, if a comment form gets sent (and received).

Use this to filter input, e.g. the OpenID uses this to provide alternate authentication.

Parameters:

array

&$params:

Associative array of parameters

'comment_post_ID': ID of the item the comment is for
'comment': the comment text (by reference)
'original_comment': the original, unfiltered comment text - you should not modify it here, this is meant e.g. for the OpenID plugin to re-inject it after redirection (by reference)
'comment_autobr': is the Auto-BR checkbox checked (by reference)
'action': "save" or "preview" (by reference)
'User': User, if logged in or null (by reference)
'anon_name': Name of the anonymous commenter (by reference)
'anon_email': E-Mail of the anonymous commenter (by reference)
'anon_url': URL of the anonymous commenter (by reference)
'anon_allow_msgform': "Allow msgform" preference of the anonymous commenter (by reference)
'anon_cookies': "Remember me" preference of the anonymous commenter (by reference)
'redirect_to': URL where to redirect to in the end of comment posting (by reference)

API Tags:

See:

Plugin::DisplayCommentFormFieldset()

Information Tags:

Since:

1.10.0

Redefined in descendants as:

code_highlight_plugin::CommentFormSent()

[ Top ]

debug_log [line 2595]

void debug_log(
string
$msg, [array
$add_cats = array()] 
)

Log a debug message.

This gets added to the global Debuglog with the category '[plugin_classname]_[plugin_ID]'.

NOTE: if debugging is not enabled (see $debug), $Debuglog is of class Log_noop, which means it does not accept nor display messages.

Parameters:

string	$msg:	Message to log.
array	$add_cats:	Optional list of additional categories.

[ Top ]

disable_event [line 2844]

boolean disable_event(

$event 
)

Disable an event.

This removes it from the events table.

Parameters:

$event:

API Tags:

Return:

True, if status has changed; false if it was disabled already

[ Top ]

DisplayCommentFormButton [line 1471]

void DisplayCommentFormButton(
array
&$params 
)

Event handler: Called in the submit button section of the frontend comment form.

Parameters:

array

&$params:

Associative array of parameters

'Form': the comment form generating object
'Item': the Item for which the comment is meant

[ Top ]

DisplayCommentFormFieldset [line 1458]

void DisplayCommentFormFieldset(
array
&$params 
)

Event handler: Called at the end of the frontend comment form.

You might want to use this to inject antispam payload to use in in GetSpamKarmaForComment() or modify the Comment according to it in BeforeCommentFormInsert().

Parameters:

array

&$params:

Associative array of parameters

'Form': the comment form generating object
'Item': the Item for which the comment is meant

API Tags:

See:

Plugin::BeforeCommentFormInsert(), Plugin::AfterCommentFormInsert()

Redefined in descendants as:

[ Top ]

DisplayCommentToolbar [line 1413]

boolean DisplayCommentToolbar(
array
&$params 
)

Event handler: Called when displaying comment editor toolbars.

Parameters:

array

&$params:

Associative array of parameters

API Tags:

Return:

did we display a toolbar?

Redefined in descendants as:

[ Top ]

DisplayItemAsHtml [line 1104]

boolean DisplayItemAsHtml(
array
&$params 
)

Event handler: Called when displaying an item/post's content as HTML.

This is different from RenderItemAsHtml(), because it gets called on every display (while rendering gets cached).

Parameters:

array

&$params:

Associative array of parameters

'data': the data (by reference). You probably want to modify this.
'format': see format_to_output().
'Item': The Item that gets displayed (by reference).
'preview': Is this only a preview?
'dispmore': Does this include the "more" text (if available), which means "full post"?

API Tags:

Return:

Have we changed something?

Redefined in descendants as:

[ Top ]

DisplayItemAsText [line 1144]

boolean DisplayItemAsText(
array
&$params 
)

Event handler: Called when displaying an item/post's content as text.

This is different from RenderItemAsText(), because it gets called on every display (while rendering gets cached).

Parameters:

array

&$params:

Associative array of parameters

'data': the data (by reference). You probably want to modify this.
'format': see format_to_output(). Only 'text' will arrive here.
'Item': The Item that gets displayed (by reference).
'preview': Is this only a preview?
'dispmore': Does this include the "more" text (if available), which means "full post"?

API Tags:

Return:

Have we changed something?

Redefined in descendants as:

test_plugin::DisplayItemAsText()

[ Top ]

DisplayItemAsXml [line 1124]

boolean DisplayItemAsXml(
array
&$params 
)

Event handler: Called when displaying an item/post's content as XML.

This is different from RenderItemAsXml(), because it gets called on every display (while rendering gets cached).

Parameters:

array

&$params:

Associative array of parameters

'data': the data (by reference). You probably want to modify this.
'format': see format_to_output().
'Item': The Item that gets displayed (by reference).
'preview': Is this only a preview?
'dispmore': Does this include the "more" text (if available), which means "full post"?

API Tags:

Return:

Have we changed something?

Redefined in descendants as:

[ Top ]

DisplayLoginFormFieldset [line 2074]

void DisplayLoginFormFieldset(
array
&$params 
)

Event handler: Called at the end of the "Login" form.

You might want to use this to inject payload to use in LoginAttempt().

Parameters:

array

&$params:

Associative array of parameters

'Form': the comment form generating object (by reference)

Redefined in descendants as:

test_plugin::DisplayLoginFormFieldset()

[ Top ]

DisplayMessageFormButton [line 1700]

void DisplayMessageFormButton(
array
&$params 
)

Event handler: Called in the submit button section of the frontend message form.

Parameters:

array

&$params:

Associative array of parameters

'Form': the comment form generating object
'recipient_ID': ID of the user (if any)
'item_ID': ID of the item where the user clicked the msgform icon (if any)
'comment_ID': ID of the comment where the user clicked the msgform icon (if any)

[ Top ]

DisplayMessageFormFieldset [line 1685]

void DisplayMessageFormFieldset(
array
&$params 
)

Event handler: Called at the end of the frontend message form, which allows to send an email to a user/commentator.

You might want to use this to inject antispam payload to use in in MessageFormSent().

Parameters:

array

&$params:

Associative array of parameters

'Form': the comment form generating object
'recipient_ID': ID of the user (if any)
'item_ID': ID of the item where the user clicked the msgform icon (if any)
'comment_ID': ID of the comment where the user clicked the msgform icon (if any)

Redefined in descendants as:

[ Top ]

DisplayRegisterFormFieldset [line 2042]

void DisplayRegisterFormFieldset(
array
&$params 
)

Event handler: Called at the end of the "Register as new user" form.

You might want to use this to inject antispam payload to use in Plugin::RegisterFormSent().

Parameters:

array

&$params:

Associative array of parameters

'Form': the comment form generating object (by reference)

Redefined in descendants as:

[ Top ]

DisplayTemplate [line 900]

void DisplayTemplate(
array
&$params 
)

Event handler: Display a template. Use Plugin::GetProvidedTemplates() to return a list of names that you register.

Parameters:

array

&$params:

Associative array of parameters

'template': name of template to be displayed (from the list of Plugin::GetProvidedTemplates()). If your Plugin only registers one template, you can ignore it.

[ Top ]

DisplayTrackbackAddr [line 1383]

void DisplayTrackbackAddr(
array
&$params 
)

Event handler: called to display the URL that accepts trackbacks for an item.

Parameters:

array

&$params:

Associative array of parameters

'Item': the Item object (by reference)
'template': the template to display the URL (%url%)

Redefined in descendants as:

captcha_img_plugin::DisplayTrackbackAddr()

[ Top ]

DisplayValidateAccountFormFieldset [line 2151]

void DisplayValidateAccountFormFieldset(
array
&$params 
)

Event handler: Called at the end of the "Validate user account" form, which gets invoked if newusers_mustvalidate is enabled and the user has not been validated yet.

The corresponding action event is Plugin::ValidateAccountFormSent().

Parameters:

array

&$params:

Associative array of parameters

'Form': the comment form generating object (by reference)

Redefined in descendants as:

test_plugin::DisplayValidateAccountFormFieldset()

[ Top ]

enable_event [line 2858]

boolean enable_event(

$event 
)

Enable an event.

This adds it to the events table.

Parameters:

$event:

API Tags:

Return:

True, if status has changed; false if it was enabled already

[ Top ]

ExecCronJob [line 640]

array ExecCronJob(
array
&$params 
)

Execute/handle a cron job, which has been scheduled by the admin out of the list that the Plugin provides (see GetCronJobs()).

Parameters:

array

&$params:

Associative array of parameters

'ctrl': The "ctrl" name as defined in GetCronJobs()
'params': The "params" value as defined in GetCronJobs(), plus "ctsk_ID" which holds the cron task ID.

API Tags:

Return:

with keys "code" (integer, 1 is ok), "message" (gets logged)

Redefined in descendants as:

[ Top ]

FilterCommentAuthor [line 1637]

void FilterCommentAuthor(
array
&$params 
)

Event handler: called to filter the comment's author name (blog name for trackbacks)

Parameters:

array

&$params:

Associative array of parameters

'data': the name of the author/blog (by reference)
'makelink': true, if the "data" contains a link
'Comment': the Comment object

Redefined in descendants as:

basic_antispam_plugin::FilterCommentAuthor()

[ Top ]

FilterCommentAuthorUrl [line 1651]

void FilterCommentAuthorUrl(
array
&$params 
)

Event handler: called to filter the comment's author URL.

This may be either the URL only or a full link (A tag).

Parameters:

array

&$params:

Associative array of parameters

'data': the URL of the author/blog (by reference)
'makelink': true, if the "data" contains a link (HTML A tag)
'Comment': the Comment object

Redefined in descendants as:

basic_antispam_plugin::FilterCommentAuthorUrl()

[ Top ]

FilterCommentContent [line 1663]

void FilterCommentContent(
array
&$params 
)

Event handler: called to filter the comment's content

Parameters:

array

&$params:

Associative array of parameters

'data': the name of the author/blog (by reference)
'Comment': the Comment object

Redefined in descendants as:

[ Top ]

FilterIpAddress [line 2299]

boolean FilterIpAddress(
array
&$params 
)

Event handler: Called when an IP address gets displayed, typically in a protected area or for a privileged user, e.g. in the backoffice statistics menu.

Parameters:

array

&$params:

Associative array of parameters

'data': the data (by reference). You probably want to modify this.
'format': see format_to_output().

API Tags:

Return:

Have we changed something?

Redefined in descendants as:

test_plugin::FilterIpAddress()

[ Top ]

forget_events [line 2830]

void forget_events(
)

Call this to unregister all your events for the current request.

[ Top ]

GetCronJobs [line 625]

array GetCronJobs(

&$params 
)

This method gets asked for a list of cronjobs that the plugin provides.

If a user installs a cron job out of this list, the Plugin::ExecCronJob() of the plugin gets called.

Parameters:

&$params:

API Tags:

Return:

Array of arrays with keys "name", "ctrl" and "params". "name" gets used for display. "ctrl" (string) and "params" (array) get passed to the Plugin::ExecCronJob() method when the cronjob gets executed.

Redefined in descendants as:

[ Top ]

GetDbLayout [line 563]

void GetDbLayout(
)

This method should return your DB schema, consisting of a list of CREATE TABLE queries.

The DB gets changed accordingly on installing or enabling your Plugin.

If you want to change your DB layout in a new version of your Plugin, simply adjust the queries here and increase Plugin::$version, because this will request to check the current DB layout against the one you require.

For restrictions see db_delta().

Redefined in descendants as:

[ Top ]

GetDefaultBlogSettings [line 500]

array GetDefaultBlogSettings(
array
&$params 
)

Define here default collection/blog settings that are to be made available in the backoffice.

Parameters:

array

&$params:

Associative array of parameters. 'for_editing': true, if the settings get queried for editing; false, if they get queried for instantiating Plugin::$UserSettings.

API Tags:

Return:	See Plugin::GetDefaultSettings().
See:	Plugin::GetDefaultSettings()

Redefined in descendants as:

[ Top ]

GetDefaultSettings [line 459]

array GetDefaultSettings(
array
&$params 
)

Define default settings here.

Those can then be edited in the backoffice.

You can access them in the plugin through the member object Plugin::$Settings, e.g.:

$this->Settings->get( 'my_param' );

fp> this is unclear: You probably don't need to set or change values (other than the defaultvalues), but if you know what you're doing, see PluginSettings, where Plugin::$Settings gets derived from.

NOTE: this method gets called by b2evo when instantiating the plugin settings and when the settings get displayed for editing in the backoffice. In the second case, $params['for_editing'] will be true.

Parameters:

array

&$params:

Associative array of parameters (since 1.9). 'for_editing': true, if the settings get queried for editing; false, if they get queried for instantiating Plugin::$Settings.

API Tags:

Return:

The array to be returned should define the names of the settings as keys (max length is 30 chars) and assign an array with the following keys to them (only 'label' is required):

'label': Name/Title of the param, gets displayed as label for the input field, or as "legend" tag with types "array" and "fieldset". 'defaultvalue': Default value for the setting, defaults to '' (empty string) 'type', which can be: 'info': not an input - just a label followed by information (text, link, image - whatever) 'info': if type is info then use info to supply the actual information 'text' (default): a simple string 'password': like text, but hidden during input 'html_input' : like text, but allows html 'checkbox': either 0 or 1 'integer': a number (no float, can have leading "+" or "-") (like 'text' for input, but gets validated when submitting) 'float': a floating number (can have leading "+" or "-", e.g. "+1", "-0.05") (like 'text' for input, but gets validated when submitting) 'textarea': several lines of input. The following can be set for this type: 'rows': number of rows 'cols': number of columns 'html_textarea': like textarea, but allows html 'select': a drop down field; you must set 'options' for it: 'options': an array of options ('value' => 'description'), see Form::select_input_array(). 'select_blog': a drop down field, providing all existing blogs (Blog ID is the value or "" if "allow_none" is true) (WARNING: does not scale - not recommended) 'select_group': a drop down field, providing all existing groups (Group ID is the value or "" if "allow_none" is true) 'select_user': a drop down field, providing all existing groups (User ID is the value or "" if "allow_none" is true) (WARNING: does not scale - not recommended) 'array': a subset of settings. The value gets automagically (un)serialized through get() and set(). The following keys apply to this type: 'entries': an array with meta information about sub-settings (which can be everything from the top-level, except: "valid_pattern", "valid_range"). Note: currently there's no type forcing or checking for sub-entries involved (e.g., if you have an entry of type "integer", you could get a non-numeric string there). fp> TODO: !!!! very unsafe 'key': defines the key to use for each entry. This may be a text input for example (with label, note etc). (optional, default is numeric keys, which are not editable) 'max_count': maximum count of sets (optional, default is no restriction) 'min_count': minimum count of sets (optional, default is no restriction) 'note' (gets displayed as a note to the param field), 'size': Size of the HTML input field (applies to types 'text', 'password' and 'integer'; defaults to 15) 'maxlength': maxlength attribute for the input field (See 'size' above; defaults to no limit) 'disabled': if true, it adds a 'disabled="disabled"' html attribute to the element and the value cannot be changed 'no_edit': if true, the setting is not editable. This is useful for internal settings. 'allow_none': set this to true to have "None" in the options list for types 'select_group' and 'select_user'. 'valid_pattern': A regular expression pattern that the value must match. This is either just a regexp pattern as string or an array with the keys 'pattern' and 'error' to define a custom error message. 'valid_range': An array with keys 'min', 'max' and (optionally) 'error' to define a custom error message. At least "min" or "max" must be given. 'help': can be: '#anchor': anchor that gets appended to $help_url true: the settings name/key gets transformed to an html ID and gets used as anchor to $help_url. 'http://example.com/uri': a full URL (starting with http:// or https://) 'layout': Use this to visually group your settings. Either 'begin_fieldset', 'end_fieldset' or 'separator'. You can use 'label' for 'begin_fieldset'. 'multiple': This allows to select multiple values in a SELECT (including select_*) (boolean) 'id', 'onchange', 'onclick', 'onfocus', 'onkeyup', 'onkeydown', 'onreset', 'onselect', 'cols', 'rows', 'maxlength': get passed through as attributes to the form/input element.

e.g.:

return array(
'my_param' => array(
'label' => $this->T_('My Param'),
'defaultvalue' => '10',
'note' => $this->T_('Quite cool, eh?'),
'valid_pattern' => array( 'pattern' => '[1-9]\d+', $this->T_('The value must be >= 10.') ),
),
'another_param' => array( // this one has no 'note'
'label' => $this->T_('My checkbox'),
'defaultvalue' => '1',
'type' => 'checkbox',
),
array( 'layout' => 'separator' ),
'my_select' => array(
'label' => $this->T_('Selector'),
'defaultvalue' => 'one',
'type' => 'select',
'options' => array( 'sun' => $this->T_('Sunday'), 'mon' => $this->T_('Monday') ),
) );

Information Tags:

Todo:	3.0 fp> 1) This is not an event: RENAME to lowercase (in b2evo 3.0) dh> Not only events are CamelCase, but "interactions" with the Plugins(_admin) class, too! Maybe it should get prefixed with "Plugin"?! The intention is: all interfacing methods are camel-cased. That makes a lot of sense, given the provided helpers (get_plugin_url etc). This applies to the other todos below, too.
Todo:	3.0 fp> 2) This defines more than Default values :: confusing name
Todo:	name tentative get_general_param_definitions()

Redefined in descendants as:

[ Top ]

GetDefaultUserSettings [line 485]

array GetDefaultUserSettings(
array
&$params 
)

Define here default user settings that are then available in the backoffice.

You can access them in the plugin through the member object $UserSettings, e.g.:

$this->UserSettings->get( 'my_param' );

This method behaves exactly like Plugin::GetDefaultSettings(), except that it defines user specific settings instead of global settings.

Parameters:

array

&$params:

Associative array of parameters. 'for_editing': true, if the settings get queried for editing; false, if they get queried for instantiating Plugin::$UserSettings.

API Tags:

Return:	See Plugin::GetDefaultSettings().
See:	Plugin::GetDefaultSettings()

Information Tags:

Todo:	3.0 fp> 1) This is not an event: RENAME to lowercase (in b2evo 3.0)
Todo:	3.0 fp> 2) This defines more than Default values :: confusing name
Todo:	name tentative get_user_param_definitions()

Redefined in descendants as:

[ Top ]

GetDefaultWidgetSettings [line 512]

void GetDefaultWidgetSettings(
local
$params 
)

Get definitions for widget specific editable params

Parameters:

local

$params:

params like 'for_editing' => true

API Tags:

See:

Plugin::GetDefaultSettings()

Redefined in descendants as:

[ Top ]

GetDependencies [line 545]

array GetDependencies(
)

Get the list of dependencies that the plugin has.

This gets checked on install or uninstall of a plugin.

There are two classes of dependencies:

'recommends': This is just a recommendation. If it cannot get fulfilled there will just be a note added on install.
'requires': A plugin cannot be installed if the dependencies cannot get fulfilled. Also, a plugin cannot get uninstalled, if another plugin depends on it.

Each class of dependency can have the following types:

'events_by_one': A list of eventlists that have to be provided by a single plugin, e.g.,
1. array( array('CaptchaPayload', 'CaptchaValidated') )
to look for a plugin that provides both events.
'plugins': A list of plugins, either just the plugin's classname or an array with classname and minimum version of the plugin (see Plugin::$version). E.g.:
1. array( 'test_plugin', '1' )
to require at least version "1" of the test plugin.
'app_min': Minimum application (QP) version, e.g. "1.0". This way you can make sure that the hooks you need are implemented in the core.

API Tags:

See:

test_plugin::GetDependencies()

Redefined in descendants as:

[ Top ]

GetExtraEvents [line 585]

NULL|array GetExtraEvents(
)

This method gets asked when plugins get installed and allows you to return a list of extra events, which your plugin triggers itself (e.g. through $Plugins->trigger_event()).

NOTE: PLEASE use a distinct prefix for the event name, e.g. "$this->classname".

NOTE: The length of event names is limited to 40 chars.

NOTE: Please comment the params and the return value here with the list that you return. Only informal as comment, but makes it easier for others.

API Tags:

Return:	"event_name" => "description"
See:	test_plugin::GetExtraEvents()

Redefined in descendants as:

[ Top ]

GetProvidedTemplates [line 886]

array GetProvidedTemplates(
)

Event handler: Gets asked about a list of template names that the plugin handles.

If one of the templates returned gets called through the "template=X" URL param, the Plugin::DisplayTemplate() method of your plugin gets called.

API Tags:

Usedby:

template_provided_by_plugin()

[ Top ]

GetSpamKarmaForComment [line 1551]

integer|NULL GetSpamKarmaForComment(
array
&$params 
)

Event handler: Called to ask the plugin for the spam karma of a comment/trackback.

This gets called just before the comment gets stored.

Parameters:

array

&$params:

Associative array of parameters

'Comment': the Comment object (by reference)

'cur_karma': current karma value (cur_karma_abs/cur_karma_divider or NULL)
'cur_karma_abs': current karma absolute value or NULL (if no Plugin returned karma before)
'cur_karma_divider': current divider (sum of weights)
'cur_count_plugins': number of Plugins that have already been asked

API Tags:

Return:

Spam probability (-100 - 100). -100 means "absolutely no spam", 100 means "absolutely spam". Only if you return a numeric value, it gets considered (e.g., "", NULL or false get ignored).

Redefined in descendants as:

basic_antispam_plugin::GetSpamKarmaForComment()

[ Top ]

GetSrvcMethods [line 608]

array GetSrvcMethods(
)

Override this method to define methods/functions that you want to make accessible through /qp_srvc/call_plugin.php, which allows you to call those methods by HTTP request.

This is useful for things like AJAX or displaying an <iframe> element, where the content should get provided by the plugin itself.

E.g., the image captcha plugin uses this method to serve a generated image.

NOTE: the Plugin's method must be prefixed with "srvc_", but in this list (and the URL) it is not. E.g., to have a method "disp_image" that should be callable through this method return

array('disp_image')

here and implement it as

function srvc_disp_image( $params )

in your plugin. This is used to distinguish those methods from others, but keep URLs nice.

API Tags:

See:

Plugin::get_srvc_url()

Redefined in descendants as:

[ Top ]

get_class_id [line 2484]

string get_class_id(
[string
$append = ''] 
)

Get a string, unqiue for the plugin, usable in HTML form elements.

Parameters:

string

$append:

Optional text to append (gets prefixed with "_").

[ Top ]

get_coll_setting [line 3067]

void get_coll_setting(
string
$parname, Blog
&$Blog 
)

Get a template specific param value from current Blog

Parameters:

string	$parname:
Blog	&$Blog:	collection

[ Top ]

get_edit_settings_link [line 3001]

false|string get_edit_settings_link(
)

Get a link to edit the Plugin's settings (if the user has permission).

[ Top ]

get_help_file [line 2960]

false|string get_help_file(
)

Get the help file for a Plugin ID. README.LOCALE.html will take precedence above the general (english) README.html.

Information Tags:

Todo:

Handle encoding of files (to $io_charset)

[ Top ]

get_help_link [line 2885]

string get_help_link(
[string
$target = ''] 
)

Get a link to a help page (with icon).

Parameters:

string

$target:

Target; one of the following:

anchor to $help_url ("#anchor")
absolute link to some URL, e.g. "http://example.com/example.php"
'$help_url' or empty for $help_url, then also the "www" icon gets used
'$readme' to link to the plugin's README.html file (if available)

API Tags:

Return:

The html A tag, linking to the help (or empty in case of $readme, if there is none).

[ Top ]

get_help_url [line 2939]

string get_help_url(
)

Get the plugin's external help/website URL.

If Plugin::$help_url is empty, it defaults to the manual wiki.

[ Top ]

get_plugin_url [line 2560]

string get_plugin_url(
[string
$abs = false] 
)

Get the absolute URL to the plugin's directory (where the plugins classfile is).

Trailing slash included.

Parameters:

string

$abs:

Get absolute URL? (or make it relative to $ReqHost)

[ Top ]

get_sql_table [line 2751]

string get_sql_table(
string
$name 
)

Get canonical name for database tables a plugin uses, by adding an unique prefix for your plugin instance.

You should use this when refering to your SQL table names.

E.g., for the "test_plugin" with ID 7 and the default $app_db_tableprefix of "evo_" it would generate: "evo_plugin_test_7_log" for a requested name "log".

Parameters:

string

$name:

Your name, which gets returned with the unique prefix.

[ Top ]

get_srvc_url [line 2633]

string get_srvc_url(
string
$method, [array
$params = array()], [string
$glue = '&amp;'], [string
$abs = false] 
)

Get the URL to call a plugin method through http. This links to the /qp_srvc/call_plugin.php file.

It uses either $srvc_url or $srvc_url_sensitive (if $ReqHost is on https).

NOTE: AJAX callbacks are required to be on the same domain/protocol, so if you're using absolute blog URLs on different domains you must set $srvc_url dynamically, to use the same domain!

Parameters:

string	$method:	Method to call. This must be listed in GetSrvcMethods().
array	$params:	Array of optional parameters passed to the method.
string	$glue:	Glue for additional GET params used internally.
string	$abs:	Get absolute URL? (or cut off $ReqHost at the beginning)

API Tags:

Return:

The URL

Information Tags:

Todo:

dh> we might want to provide whitelisting of methods through $Session here and check for it in the srvc handler.

[ Top ]

get_tools_tab_url [line 2696]

void get_tools_tab_url(
)

Get URL for the tools tab for this plugin.

The tools tab must be provided with AdminTabPayload()

[ Top ]

IsValidFilteredEmail [line 2463]

boolean IsValidFilteredEmail(
array
$params 
)

Event handler: Called when checking if an email address that looks syntactically correct is in fact valid.

Parameters:

array

$params:

Associative array of parameters

'email': The email address to validate.
'format': How should the address be validated? 'simple' or 'rfc'. The latter should lead to strictly RFC-compliant checking; the former may allow for simple validation.

API Tags:

Return:	True if the email address is valid, false if not.
See:	is_email()
See:	Plugin::IsValidRawEmail()

Redefined in descendants as:

basic_antispam_plugin::IsValidFilteredEmail()

[ Top ]

IsValidRawEmail [line 2442]

integer IsValidRawEmail(
array
$params 
)

Event handler: Called when checking if an unprocessed email address as supplied by the user is valid.

Parameters:

array

$params:

Associative array of parameters

'email': The email address to validate.
'format': How should the address be validated? 'simple' or 'rfc'. The latter should lead to strictly RFC-compliant checking; the former may allow for simple validation.

API Tags:

Return:	self::EmailNotSure, self::EmailInvalid, self::EmailValid or self::EmailValidSyntax.
See:	Plugin::IsValidFilteredEmail()
See:	is_email()
See:	self::EmailValidSyntax
See:	self::EmailValid
See:	self::EmailInvalid
See:	self::EmailNotSure

[ Top ]

ItemApplyAsRenderer [line 1398]

boolean|NULL ItemApplyAsRenderer(

&$params 
)

Event handler: Does your Plugin want to apply as a renderer for the item?

NOTE: this is especially useful for lazy Plugins, which would look at the content and decide, if they apply.

Parameters:

&$params:

API Tags:

Return:

If true, the Plugin gets added as a renderer, false removes it as a renderer (if existing) and NULL does not change the renderer setting regarding your Plugin.

[ Top ]

ItemCanComment [line 1344]

boolean|string ItemCanComment(
array
&$params 
)

Event handler: the plugin gets asked if an item can receive feedback/comments.

Parameters:

array

&$params:

Associative array of parameters 'Item': the Item

API Tags:

Return:

true, if the Item can receive feedback false/string, if the Item cannot receive feedback. If you return a string this gets displayed as an error/explanation. NULL, if you do not want to say "yes" or "no".

Redefined in descendants as:

basic_antispam_plugin::ItemCanComment()

[ Top ]

ItemInsertFileJavascript [line 1354]

array ItemInsertFileJavascript(
)

Event handler: allows an editor plugin to write custom tags when inserting a file, usually an image.

API Tags:

Return:

Tags used to wrap files (usually images)

Redefined in descendants as:

tinymce_plugin::ItemInsertFileJavascript()

[ Top ]

ItemSendPing [line 1370]

boolean ItemSendPing(
array
&$params 
)

Event handler: send a ping about a new item.

Parameters:

array

&$params:

Associative array of parameters 'Item': the Item (by reference) 'xmlrpcresp': Set this to the xmlrpcresp object, if the plugin uses XMLRPC. 'display': Should results get displayed? (normally you should not need to care about this, especially if you can set 'xmlrpcresp')

API Tags:

Return:

Was the ping successful?

Redefined in descendants as:

[ Top ]

ItemViewsIncreased [line 1237]

void ItemViewsIncreased(
array
&$params 
)

Event handler: Called when the view counter of an item got increased.

Parameters:

array

&$params:

Associative array of parameters

'Item': the Item object (by reference)

[ Top ]

LoginAttempt [line 2106]

void LoginAttempt(
array
&$params 
)

Event handler: called when a user attemps to login.

You can prevent the user from logging in by adding a message of type "login_error".

Otherwise, this hook is meant to authenticate a user against some external database (e.g. LDAP) and generate a new user.

To check, if a user already exists in QP with that login/password, you might want to use

user_pass_ok( $login, $pass_md5, true )

NOTE: if 'pass_hashed' is not empty, you won't receive the password in clear-type. It has been hashed using client-side Javascript. SHA1( MD5($params['pass']).$params['pass_salt'] ) should result in $params['pass_hashed']! If you need the raw password, see LoginAttemptNeedsRawPassword().

Parameters:

array

&$params:

Associative array of parameters

'login': user's login (by reference since 1.10.0)
'pass': user's password (by reference since 1.10.0)
'pass_md5': user's md5 password (by reference since 1.10.0)
'pass_salt': the salt used in "pass_hashed" (by reference) (since EVO_NEXT_VERSION)
'pass_hashed': if non-empty this is the users passwords hashed. See note above. (by reference) (since EVO_NEXT_VERSION)
'pass_ok': is the password ok for 'login'? (by reference) (since 1.10.0)

API Tags:

See:	Plugin::Logout()
See:	Plugin::AlternateAuthentication()

Redefined in descendants as:

test_plugin::LoginAttempt()

[ Top ]

LoginAttemptNeedsRawPassword [line 2119]

boolean LoginAttemptNeedsRawPassword(
)

Event handler: your Plugin should return true here, if it needs a raw (un-hashed) password for the Plugin::LoginAttempt() event. If any Plugin returns true for this event, client-side hashing of the password is not used.

NOTE: this causes passwords to travel un-encrypted, unless SSL/HTTPS get used.

API Tags:

Return:

True, if you need the raw password.

Redefined in descendants as:

test_plugin::LoginAttemptNeedsRawPassword()

[ Top ]

Logout [line 2136]

void Logout(
array
$params 
)

Event handler: called when a user logs out.

This is meant to cleanup data, e.g. if you use the Plugin::AlternateAuthentication() hook.

Parameters:

array

$params:

Associative array of parameters

'User': the user object

API Tags:

See:	Plugin::Logout()
See:	Plugin::AlternateAuthentication()

[ Top ]

ModifySendMessage [line 1740]

void ModifySendMessage(
array
&$params 
)

Event handler: Called after preparing but before sending a message.

Replaces the core's use of php's mail() function. Your plugin must return 'true' if successful!

Parameters:

array

&$params:

Associative array of parameters

'to': comma separated list of emails, or email+name if only one recipient
'subject': the subject of the message
'message': the message text
'headerstring': the header components as a string
'debug': value of $debug

[ Top ]

msg [line 2662]

void msg(
string
$msg, [string|array
$category = 'note'] 
)

A simple wrapper around the $Messages object with a default catgory of 'note'.

Parameters:

string	$msg:	Message
string\|array	$category:	category ('note', 'error', 'success'; default: 'note')

[ Top ]

PluginInit [line 329]

boolean PluginInit(
array
&$params 
)

Init the Plugin after it has been registered/instantiated.

Should set name, short description, and long description in a localizable fashion.

This gets called on every instantiated plugin, also if it's just for discovering the list of available plugins in the backoffice.

Use this to validate Settings/requirements and/or cache them into class properties.

Parameters:

array

&$params:

Associative array of parameters. 'is_installed': true, if the plugin is installed; false if not (probably it got discovered then) 'db_row': an array with the columns of the plugin DB entry (in T_plugins). This is empty, if the plugin is not installed! E.g., 'plug_version' might be interesting to compare again "$this->version".

API Tags:

Return:

If this method returns false, the Plugin gets unregistered (for the current request only).

Redefined in descendants as:

[ Top ]

PluginSettingsEditAction [line 1871]

void PluginSettingsEditAction(
)

Event handler: Called as action before displaying the "Edit plugin" form, which includes the display of the Plugin::$Settings.

You may want to use this to check existing settings or display notes about something.

[ Top ]

PluginSettingsEditDisplayAfter [line 1886]

void PluginSettingsEditDisplayAfter(
array
&$params 
)

Event handler: Called after the form to edit the Plugin::$Settings has been displayed.

Use this to add custom input fields (and catch them in PluginSettingsUpdateAction()) or display custom output (e.g. a test link).

Parameters:

array

&$params:

Associative array of parameters

'Form': the Form, where an fieldset has been opened already (by reference)

Redefined in descendants as:

[ Top ]

PluginSettingsUpdateAction [line 1859]

false|NULL PluginSettingsUpdateAction(
)

Event handler: Called as action just before updating the Plugin::$Settings.

The "regular" settings from GetDefaultSettings() have been set into Plugin::$Settings, but get saved into DB after this method has been called.

Use this to catch custom input fields from PluginSettingsEditDisplayAfter() or add notes/errors through Plugin::msg().

If you want to modify plugin events (see Plugin::enable_event() and Plugin::disable_event()), you should use Plugin::BeforeEnable(), because Plugin events get saved (according to the edit settings screen) after this event.

API Tags:

Return:

Return false to prevent the settings from being updated to DB.

[ Top ]

PluginSettingsValidateSet [line 1839]

string|NULL PluginSettingsValidateSet(
array
&$params 
)

Event handler: Called before displaying or setting a plugin's setting in the backoffice.

Parameters:

array

&$params:

Associative array of parameters

'name': name of the setting
'value': value of the setting (by reference)
'meta': meta data of the setting (as given in GetDefaultSettings())
'action': 'display' or 'set' (since b2evo EVO_NEXT_VERSION)

API Tags:

Return:	Return a string with an error to prevent the setting from being set and/or a message added to the settings field.
See:	Plugin::GetDefaultSettings()

Redefined in descendants as:

captcha_img_plugin::PluginSettingsValidateSet()
generic_ping_plugin::PluginSettingsValidateSet() : Check ping service URL.

[ Top ]

PluginUserSettingsEditAction [line 1942]

void PluginUserSettingsEditAction(
array
&$params 
)

Event handler: Called as action before displaying the "Edit user" form, which includes the display of the Plugin::$UserSettings.

You may want to use this to check existing settings or display notes about something.

Parameters:

array

&$params:

Associative array of parameters

'User': the User for which the settings are being displayed/edited

[ Top ]

PluginUserSettingsEditDisplayAfter [line 1958]

void PluginUserSettingsEditDisplayAfter(
array
&$params 
)

Event handler: Called after the form to edit the Plugin::$UserSettings has been displayed.

Use this to add custom input fields (and catch them in PluginUserSettingsUpdateAction()) or display custom output (e.g. a test link).

Parameters:

array

&$params:

Associative array of parameters

'Form': the Form, where an fieldset has been opened already (by reference)
'User': the User whose settings get displayed for editing (since 1.10.0)

[ Top ]

PluginUserSettingsUpdateAction [line 1927]

false|NULL PluginUserSettingsUpdateAction(
array
&$params 
)

Event handler: Called as action just before updating the Plugin::$UserSettings.

The "regular" settings from GetDefaultUserSettings() have been set into Plugin::$UserSettings, but get saved into DB after this method has been called.

Use this to catch custom input fields from PluginUserSettingsEditDisplayAfter() or add notes/errors through Plugin::msg().

Parameters:

array

&$params:

Associative array of parameters

'User': the User for which the settings get updated
'action': "save", "reset"

API Tags:

Return:

Return false to prevent the settings from being updated to DB.

Redefined in descendants as:

test_plugin::PluginUserSettingsUpdateAction()

[ Top ]

PluginUserSettingsValidateSet [line 1907]

string|NULL PluginUserSettingsValidateSet(
array
&$params 
)

Event handler: Called before displaying or setting a plugin's user setting in the backoffice.

Parameters:

array

&$params:

Associative array of parameters

'name': name of the setting
'value': value of the setting (by reference)
'meta': meta data of the setting (as given in GetDefaultUserSettings())
'User': the User for which the setting is
'action': 'display' or 'set' (since b2evo EVO_NEXT_VERSION)

API Tags:

Return:	Return a string with an error to prevent the setting from being set and/or a message added to the settings field.
See:	Plugin::GetDefaultUserSettings()

[ Top ]

PluginVersionChanged [line 1016]

boolean PluginVersionChanged(
array
&$params 
)

Event handler: Called when we detect a version change (in Plugins::register()).

Use this for your upgrade needs.

Parameters:

array

&$params:

Associative array of parameters. 'old_version': The old version of your plugin as stored in DB. 'db_row': an array with the columns of the plugin DB entry (in T_plugins). The key 'plug_version' is the same as the 'old_version' key.

API Tags:

Return:

If this method returns false, the Plugin's status gets changed to "needs_config" and it gets unregistered for the current request.

Redefined in descendants as:

basic_antispam_plugin::PluginVersionChanged() : A little housekeeping.
captcha_img_plugin::PluginVersionChanged()

[ Top ]

PrependItemInsertTransact [line 1189]

void PrependItemInsertTransact(
array
&$params 
)

Event handler: called at the beginning of inserting an item/post in the database.

Use this to manipulate the Item, e.g. adding a renderer code through Item::add_renderer().

Parameters:

array

&$params:

Associative array of parameters

'Item': the related Item (by reference)

[ Top ]

PrependItemUpdateTransact [line 1160]

void PrependItemUpdateTransact(
array
&$params 
)

Event handler: called at the beginning of updating an item/post in the database.

Use this to manipulate the Item, e.g. adding a renderer code through Item::add_renderer().

Parameters:

array

&$params:

Associative array of parameters

'Item': the related Item (by reference)

[ Top ]

RegisterFormSent [line 2060]

void RegisterFormSent(
array
&$params 
)

Event handler: Called when a "Register as new user" form has been submitted.

You can cancel the registration process by adding a message of type "error".

Parameters:

array

&$params:

Associative array of parameters

'login': Login name (by reference) (since 1.10.0)
'email': E-Mail value (by reference) (since 1.10.0)
'locale': Locale value (by reference) (since 1.10.0)
'pass1': Password (by reference) (since 1.10.0)
'pass2': Confirmed password (by reference) (since 1.10.0)

Redefined in descendants as:

[ Top ]

register_menu_entry [line 2677]

void register_menu_entry(
string
$text, [string|array
$path = 'tools'], [array
$menu_entry_props = array()] 
)

Register a tab (sub-menu) for the backoffice Tools menus.

Parameters:

string	$text:	Text for the tab.
string\|array	$path:	Path to add the menu entry into. See AdminUI::add_menu_entries(). Default: 'tools' for the Tools menu.
array	$menu_entry_props:	Optional params. See AdminUI::add_menu_entries().

[ Top ]

RenderItemAsHtml [line 1040]

boolean RenderItemAsHtml(
array
&$params 
)

Event handler: Called when rendering item/post contents as HTML. (CACHED)

The rendered content will be *cached* and the cached content will be reused on subsequent displays. Use DisplayItemAsHtml() instead if you want to do rendering at display time.

Note: You have to change $params['data'] (which gets passed by reference).

Parameters:

array

&$params:

Associative array of parameters

'data': the data (by reference). You probably want to modify this.
'format': see format_to_output(). Only 'htmlbody' and 'entityencoded' will arrive here.
'Item': the Item object which gets rendered.

API Tags:

Return:

Have we changed something?

Redefined in descendants as:

[ Top ]

RenderItemAsText [line 1084]

boolean RenderItemAsText(
array
0 
)

Event handler: Called when rendering item/post contents other than XML or HTML.

Note: return value is ignored. You have to change $params['data'].

Parameters:

array

Associative array of parameters

'data': the data (by reference). You probably want to modify this.
'format': see format_to_output(). Only 'text' will arrive here.
'Item': the Item object which gets rendered.

API Tags:

Return:

Have we changed something?

Redefined in descendants as:

test_plugin::RenderItemAsText()

[ Top ]

RenderItemAsXml [line 1067]

boolean RenderItemAsXml(
array
&$params 
)

Event handler: Called when rendering item/post contents as XML.

Should this plugin apply to XML? It should actually only apply when:

it generates some content that is visible without HTML tags
it removes some dirty markup when generating the tags (which will get stripped afterwards)

Note: htmlentityencoded is not considered as XML here.

Note: You have to change $params['data'] (which gets passed by reference).

Parameters:

array

&$params:

Associative array of parameters

'data': the data (by reference). You probably want to modify this.
'format': see format_to_output(). Only 'xml' will arrive here.
'Item': the Item object which gets rendered.

API Tags:

Return:

Have we changed something?

Redefined in descendants as:

[ Top ]

SessionLoaded [line 2313]

void SessionLoaded(
)

Event handler: Called after initializing plugins, DB, Settings, Hit, .. but quite early.

This is meant to be a good point for Antispam plugins to cancel the request.

API Tags:

See:

dnsbl_antispam_plugin

[ Top ]

session_delete [line 2819]

void session_delete(
string
$name 
)

Delete a value from the session data, using a unique prefix to the Plugin.

Parameters:

string

$name:

Name of the data's key (gets prefixed with 'plugIDX_' internally).

[ Top ]

session_get [line 2806]

mixed session_get(
string
$name, [mixed
$default = NULL] 
)

Get a data value for the session, using a unique prefix to the Plugin.

This checks for the data to be expired and unsets it then.

Parameters:

string	$name:	Name of the data's key (gets prefixed with 'plugIDX_' internally).
mixed	$default:	Default value to use if key is not set or has expired. (since 1.10.0)

API Tags:

Return:

The value, if set; otherwise $default

[ Top ]

session_set [line 2785]

void session_set(
string
$name, mixed
$value, integer
$timeout, [boolean
$save_immediately = false] 
)

Set a data value for the session.

NOTE: the session data is limited to about 64kb, so do not use it for huge data! Please consider using an own database table (see Plugin::GetDbLayout()).

Parameters:

string	$name:	Name of the data's key (gets prefixed with 'plugIDX_' internally).
mixed	$value:	The value
integer	$timeout:	Time in seconds for data to expire (0 to disable).
boolean	$save_immediately:	Should the data get saved immediately? (otherwise it gets saved on script shutdown)

[ Top ]

set_coll_setting [line 3096]

void set_coll_setting(
string
$parname, mixed
$parvalue 
)

Set a template specific param value for current Blog

Parameters:

string	$parname:	parameter name
mixed	$parvalue:	parameter value

[ Top ]

set_status [line 2726]

boolean set_status(
string
$status 
)

Set the status of the plugin.

Parameters:

string

$status:

'enabled', 'disabled' or 'needs_config'

[ Top ]

stop_propagation [line 2767]

void stop_propagation(
)

Stop propagation of the event to next plugins (with lower priority) in events that get triggered for a batch of Plugins.

API Tags:

See:	Plugins::stop_propagation()
See:	Plugins::trigger_event()

[ Top ]

TemplateBeginHtmlBody [line 849]

void TemplateBeginHtmlBody(
)

Event handler: Called at the beginning of the template's HTML BODY section.

Use this to add any HTML snippet at the beginning of the generated page.

[ Top ]

TemplateBeginHtmlHead [line 839]

void TemplateBeginHtmlHead(

&$params 
)

Event handler: Called at the beginning of the template's HTML HEAD section.

Use this to add any HTML HEAD lines (like CSS styles or links to resource files (CSS, JavaScript, ..)).

Parameters:

&$params:

Redefined in descendants as:

[ Top ]

TemplateEndHtmlBody [line 860]

void TemplateEndHtmlBody(

&$params 
)

Event handler: Called at the end of the template's HTML BODY section.

Use this to add any HTML snippet at the end of the generated page.

Parameters:

&$params:

[ Top ]

TemplateTag [line 874]

void TemplateTag(
array
&$params 
)

Called when a plugin gets called by its @{link $code}.

If you provide this event, Quam Plures will assume your plugin provides a widget and list it in the "Available widgets" list.

Parameters:

array

&$params:

The array passed to @{link Plugins::call_by_code()}.

API Tags:

See:	Plugins::call_by_code()
See:	Plugin::$code

Redefined in descendants as:

archives_plugin::TemplateTag() : Event handler: TemplateTag
calendar_plugin::TemplateTag() : Event handler: TemplateTag (widget)
whosonline_plugin::TemplateTag() : Event handler: TemplateTag (widget)

[ Top ]

TS_ [line 2547]

string TS_(
string
$string, [string
$req_locale = ''] 
)

Translate and escape single quotes.

This is to be used mainly for Javascript strings.

Parameters:

string	$string:	String to translate
string	$req_locale:	Locale to use

API Tags:

Return:	The translated and escaped string.
Uses:	Plugin::T_()

Information Tags:

Since:

2.5.0

[ Top ]

T_ [line 2503]

string T_(
string
$string, [string
$req_locale = ''] 
)

Translate a given string, in the Plugin's context.

This means, that the translation is obtained from the Plugin's "po/php" folder.

Parameters:

string	$string:	The string (english), that should be translated
string	$req_locale:	Requested locale ($current_locale gets used by default)

API Tags:

Return:	The translated string.
Usedby:	Plugin::T_()
Uses:	Plugin::T_()
Usedby:	Plugin::TS_()

Information Tags:

Link:

It uses the global/regular function as a fallback.

[ Top ]

ValidateAccountFormSent [line 2162]

void ValidateAccountFormSent(

&$params 
)

Event handler: Called when a "Validate user account" form has been submitted.

You can cancel the registration process by adding a message of type "error".

Parameters:

&$params:

[ Top ]

__get [line 3022]

Reference &__get(

$nm 
)

PHP5 overloading of get method to lazy-load (User)Settings, when they get accessed.

With PHP4, settings get instantiated in Plugins::init_settings right away.

Parameters:

$nm:

API Tags:

Return:

to the object or null

[ Top ]

	plugins

[ class tree: plugins ] [ index: plugins ] [ all elements ]

Class: Plugin

Class Plugin