glFusion Wiki

Site Tools


glfusion:development:api:plugin:functions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

glfusion:development:api:plugin:functions [2010/02/01 20:12]
glfusion:development:api:plugin:functions [2016/07/16 19:40] (current)
Line 1: Line 1:
 +~~NOTOC~~
 +====== Plugin Integration Functions ======
  
 +These functions can be implemented by a plugin.
 +
 +**This document is work in progress and is not yet finished**
 +
 +
 +====== plugin_autotags_{plugin_name} ======
 +
 +(glFusion v1.0.0)
 +
 +| ''​string plugin_autotags_{plugin_name}( string $op, [string $content = %%''​%%],​ [string $autotag = %%''​%%] )''​ |
 +
 +This hook allows plugins to implement auto tag support. Auto Tags provide a method to integrate content from plugins into other aspects of the site.
 +
 +Auto tags take the form of <​nowiki>​[autotagname:​parm1 parm2]</​nowiki>​
 +
 +**Parameters**
 +
 +|string ​ |**$op** ​ |Operation to perform. ​ Valid options are **tagname** and **parse** ​ |
 +|string ​ |**$content** ​ |Full content of the item being displayed, including the auto tags  |
 +|array ​  ​|**$autotag** ​ |array of auto tag attributes ​ \\ parm1 = first parameter after colon  \\    |
 +
 +**Return**
 +
 +If **$op** == tagname - return an array of valid auto tags for the plugin
 +
 +If **$op** == parse - parse the auto tag and return the content with the auto tag expanded.
 +
 +**Example**
 +
 +This example implements 2 auto tags: **staticpage** and **staticpage_content**
 +
 +<​code>​
 +function plugin_autotags_staticpages($op,​ $content = '',​ $autotag = ''​)
 +{
 +    global $_CONF, $_TABLES;
 +
 +    static $recursive = array();
 +
 +    if ($op == '​tagname'​ ) {
 +        return array('​staticpage',​ '​staticpage_content'​);​
 +    } else if ($op == '​parse'​) {
 +        if ($autotag['​tag'​] == '​staticpage'​ ) {
 +            $sp_id = COM_applyFilter($autotag['​parm1'​]);​
 +            if (! empty($sp_id)) {
 +                $url = COM_buildUrl($_CONF['​site_url'​]
 +                                    . '/​staticpages/​index.php?​page='​ . $sp_id);
 +                if (empty($autotag['​parm2'​])) {
 +                    $linktext = DB_getItem ($_TABLES['​staticpage'​],​
 +                                             '​sp_title',​ "sp_id = '"​.addslashes($sp_id)."'"​);​
 +                } else {
 +                    $linktext = $autotag['​parm2'​];​
 +                }
 +                $link = COM_createLink($linktext,​ $url);
 +                $content = str_replace($autotag['​tagstr'​],​ $link, $content);
 +            }
 +        } else if ($autotag['​tag'​] == '​staticpage_content'​) {
 +            $sp_id = COM_applyFilter($autotag['​parm1'​]);​
 +            if (! empty($sp_id)) {
 +                if (isset($recursive[$sp_id])) {
 +                    $content = '';​
 +                } else {
 +                    $recursive[$sp_id] = true;
 +                    $sp_content = SP_returnStaticpage($sp_id,​ '​autotag'​);​
 +                    $content = str_replace($autotag['​tagstr'​],​ $sp_content,​
 +                                           ​$content);​
 +                }
 +            }
 +        }
 +
 +        return $content;
 +    }
 +}
 +</​code>​
 +
 +**Notes**
 +
 +Keep in mind this code is called each time an item that supports auto tags is displayed, so be resource friendly.
 +
 +
 +====== plugin_autouninstall_{pluginname} ======
 +(glFusion v1.0.0)
 +
 +| ''​array plugin_autouninstall_{plugin_name}( ​ )''​ |
 +
 +Uninstalls a plugin from the glFusion CMS.  This functions provides the necessary information to the glFusion uninstaller to automatically remove the plugin'​s database tables, group, and feature entries.
 +
 +**Return**
 +
 +An array containing the following elements:
 +
 +  * tables => array of tables to remove
 +  * groups => array of groups to remove
 +  * features => array of features to remove
 +  * php_blocks => array of php blocks to remove
 +  * vars => array of gl_var entries to remove
 +
 +**Example**
 +
 +<​code>​
 +function plugin_autouninstall_mediagallery ()
 +{
 +    $out = array (
 +        /* give the name of the tables, without $_TABLES[] */
 +        '​tables'​ => array('​mg_albums','​mg_media','​mg_media_albums','​mg_usage_tracking','​mg_config',​ '​mg_mediaqueue',​ '​mg_media_album_queue','​mg_playback_options','​mg_userprefs','​mg_exif_tags',​ '​mg_watermarks',​ '​mg_category',​ '​mg_sessions',​ '​mg_session_items',​ '​mg_session_items2','​mg_session_log',​ '​mg_sort',​ '​mg_postcard','​mg_rating'​),​
 +        /* give the full name of the group, as in the db */
 +        '​groups'​ => array('​mediagallery Admin'​),​
 +        /* give the full name of the feature, as in the db */
 +        '​features'​ => array('​mediagallery.admin',​ '​mediagallery.config'​),​
 +        /* give the full name of the block, including '​phpblock_',​ etc */
 +        '​php_blocks'​ => array('​phpblock_mg_randommedia','​phpblock_mg_maenroll'​),​
 +        /* give all vars with their name */
 +        '​vars'​=>​ array()
 +    );
 +    return $out;
 +}
 +</​code>​
 +
 +
 +====== plugin_cclabel_{pluginname} ======
 +(glFusion v1.0.0)
 +
 +| ''​array plugin_cclabel_{plugin_name}( ​ )''​ |
 +
 +Returns the Command & Control screen icon and link for the plugin.
 +
 +**Return**
 +
 +An array containing the text name, URL, and icon URL
 +
 +
 +**Example**
 +
 +<​code>​
 +function plugin_cclabel_mediagallery() {
 +    global $_CONF, $_MG_CONF, $LANG_MG00;
 +
 +    if (SEC_hasRights('​mediagallery.config'​) ) {
 +        return array($LANG_MG00['​plugin'​],​
 +            $_MG_CONF['​admin_url'​] . '​index.php',​
 +            MG_getImageFile('​mediagallery.png'​));​
 +    } else {
 +        return '';​
 +    }
 +}
 +</​code>​
 +
 +**Notes**
 +
 +The plugin should validate that the user has the necessary permissions to see the link. The Command & Control screen will be displayed for any user that has administrative rights to **any** glFusion feature or plugin. ​ For example, a user with the Story.Admin privilege will be able to access the C&C screen.
 +====== plugin_centerblock_{pluginname} ======
 +(glFusion v1.0.0)
 +
 +| ''​string plugin_centerblock_{pluginname}( [int $where = 1], [int $page = 1], [string $topic = %%''​%%])''​ |
 +
 +Allows the plugin to display content as a centerblock on the main index page.
 +
 +**Parameters**
 +
 +|int     ​|**$where** ​ |where 1 = top, 2 = after featured story, 3 = bottom of page, 0 = entire page|
 +|int     ​|**$page** ​  |page number (1, ...)|
 +|string ​ |**$topic** ​ |topic ID or empty string == front page  |
 +
 +
 +**Return**
 +
 +Formatted center block content
 +
 +**Notes**
 +
 +The plugin should have the following configuration options to allow the site admin to select; **if** the plugin should display a centerblock;​ **where** to put the centerblock;​
 +
 +There are 3 options on where to display the centerblock:​
 +
 +  * Top of Page - This will display the centerblock before any other content
 +  * After Featured Story - This will display after the featured story. ​ If there is no featured story, the centerblock will be displayed **before** any other stories.
 +  * Bottom of Page - This will display the centerblock below any other content at the bottom of the page
 +
 +This function allows a plugin to **take over** or replace the main index page.  If **$where** is 0, this allows the plugin to completely replace the main page.
 +
 +Plugin may want to consider using the Instance Caching feature of glFusion to cache the contents of the centerblock.
 +
 +**Example**
 +
 +<​code>​
 +function plugin_centerblock_forum ($where = 1, $page = 1, $topic = ''​)
 +{
 +    global $_CONF, $_USER, $_TABLES, $LANG_GF01,​$CONF_FORUM;​
 +
 +    if ( (!isset($_USER['​uid'​]) || $_USER['​uid'​] < 2) && ​
 +      $CONF_FORUM['​registration_required'​] == 1 )  {
 +        return;
 +    }
 +    ​
 +    /*
 +     * plugin_centerblock_forum will get called 3 times, once for
 +     * each locaton (top of page, after featured story, bottom of page)
 +     * Check to see if the $where is what the forum is configured to 
 +     * display, if not return.
 +     */
 +
 +    if ( $CONF_FORUM['​centerblock_where'​] != $where ) {
 +        return;
 +    }
 +
 +    $retval = '';​
 +
 +    $cb_enable ​     = $CONF_FORUM['​show_centerblock'​];​
 +    $cb_homepage ​   = $CONF_FORUM['​centerblock_homepage'​];​
 +    $cb_where ​      = $CONF_FORUM['​centerblock_where'​];​
 +
 +    // If enabled only for homepage and this is not page 1 or a topic page,
 +    // then set disable flag
 +    ​
 +    if ($cb_homepage == 1 AND ($page > 1 OR !empty ($topic))) {
 +        $cb_enable = 0;
 +    } elseif ($cb_homepage == 0 and $page > 1) {
 +        $cb_where = 1;      // Top of Page
 +    }
 +
 +    if ($cb_enable AND ($cb_where == $where)) {
 +        // build the center content and return
 +        ​
 +        $retval .= '​center content goes here';
 +    }
 +    ​
 +    return $retval;
 +}
 +</​code>​
 +====== plugin_checkforSpam_{pluginname} ======
 +(glFusion v1.0.0)
 +
 +| ''​int plugin_checkforSpam( string $content, [int $action = -1])''​ |
 +
 +Allows plugins and Core glFusion Components to filter out spam.
 +
 +**Parameters**
 +
 +|string ​ |**$content** ​ |Text to be filtered or checked for spam|
 +|int     ​|**$action** ​  |what to do if spam found|
 +
 +
 +**Return**
 +
 +False if no spam detected ​ - True if spam is detected
 +
 +
 +**Notes**
 +
 +
 +**Example**
 +<​code>​
 +
 +</​code>​
 +
 +====== plugin_chkVersion_{pluginname} ======
 +(glFusion v1.0.0)
 +
 +plugin_chkVersion_{plugin_name}() - Return the current version of the plugin code
 +
 +**Description**
 +
 +This API allows a plugin to return the version of the currently installed code.
 +
 +**Return Value**
 +
 +Returns the version number.
 +
 +**Notes**
 +
 +
 +**Example**
 +
 +<​code>​
 +function plugin_chkVersion_forum() {
 +    global $_FF_CONF;
 +
 +    return $_FF_CONF['​pi_version'​] ;
 +}
 +</​code>​
 +====== plugin_commentPreSave_{pluginname} ======
 +(glFusion v1.0.0)
 +
 +| ''​mixed plugin_commentPreSave_{pluginname}( int $uid, string &​$title,​ string &​$comment,​ string $sid, int $pid, string $type, string &​$postmode)''​ |
 +
 +Allows plugins a chance to handle a comment before glFusion does.
 +
 +**Parameters**
 +
 +|int  |**$uid** ​ |User ID|
 +|string ​ |**&​$title** ​ |Comment title|
 +|string ​ |**&​$comment** ​ |Comment text|
 +|string ​ |**$sid** ​ |Story ID (not always a story, remember!)|
 +|int  |**$pid** ​ |Parent comment ID|
 +|string ​ |**$type** ​ |Type of comment|
 +|string ​ |**&​$postmode** ​ |HTML or text|
 +
 +
 +**Return**
 +
 +an error otherwise false if no errors were encountered
 +
 +
 +**Notes**
 +
 +
 +**Example**
 +
 +<​code>​
 +function plugin_commentPreSave_captcha($uid,​ $title, $comment, $sid, $pid, $type, $postmode) {
 +    global $_CP_CONF, $_USER;
 +
 +    // check to see if we should process a comment
 +
 +    if ( $_CP_CONF['​enable_comment'​] != 1 ) {
 +        return 0;
 +    }
 +
 +    // set $uid 
 +
 +    if (COM_isAnonUser() ) {
 +        $uid = 1;
 +    } else {
 +        $uid = $_USER['​uid'​];​
 +    }
 +
 +    // if configured to handle anonymous only and the $uid is < 2 then process...
 +
 +    if ( ($_CP_CONF['​anonymous_only'​] && $uid < 2) || $_CP_CONF['​anonymous_only'​] == 0 
 +            || ($_CP_CONF['​remoteusers'​] == 1 && SEC_inGroup("​Remote Users"​) ) ) {
 +        $str = COM_applyFilter($_POST['​captcha'​]);​
 +        list( $rc, $msg )  = CAPTCHA_checkInput( '​comment',​$str );
 +        if ( $rc == 1 )
 +            return 0;  // all good
 +        else
 +            return 1;  // check failed
 +    }
 +    return 0;
 +}
 +</​code>​
 +
 +====== plugin_deletecomment_{pluginname} ======
 +(glFusion v1.0.0)
 +
 +| ''​mixed plugin_deletecomment_{pluginname}( string $type, int $cid, string $id)''​ |
 +
 +Plugin handles a comment delete.
 +
 +**Parameters**
 +
 +|string ​ |**$type** ​ |Plugin to delete comment|
 +|int  |**$cid** ​ |Comment to be deleted|
 +|string ​ |**$id** ​ |Item id to which $cid belongs|
 +
 +**Return**
 +
 +false for failure, HTML string (redirect?) for success
 +
 +
 +**Notes**
 +
 +For plugins, glFusion does not actually delete the record from the comment table. Instead, plugins must perform the full deletion process.
 +
 +**See Also**
 +
 +CMT_deleteComment
 +
 +**Example**
 +
 +<​code>​
 +function plugin_deletecomment_mediagallery($cid,​$id) {
 +    global $_CONF, $_MG_CONF, $_TABLES;
 +
 +    // find the album that holds this peice of media
 +
 +    $sql = "​SELECT * FROM {$_TABLES['​mg_media_albums'​]} WHERE media_id='"​ . addslashes($id) . "'";​
 +    $result = DB_query($sql);​
 +    $nRows ​ = DB_numRows($result);​
 +    if ( $nRows > 0 ) {
 +        $row = DB_fetchArray($result);​
 +        $sql = "​SELECT group_id,​perm_owner,​perm_group,​perm_members,​perm_anon FROM {$_TABLES['​mg_albums'​]} WHERE album_id='"​ . $row['​album_id'​] ."'";​
 +        $result = DB_query($sql);​
 +        $nRows = DB_numRows($result);​
 +        if ( $nRows > 0 ) {
 +            $row = DB_fetchArray($result);​
 +            $access = SEC_hasAccess ($row['​owner_id'​],​
 +                        $row['​group_id'​],​
 +                        $row['​perm_owner'​],​
 +                        $row['​perm_group'​],​
 +                        $row['​perm_members'​],​
 +                        $row['​perm_anon'​]);​
 +        } else {
 +            $access = 0;
 +        }
 +    } else {
 +        $access = 0;
 +    }
 +
 +    if ($access == 3 || SEC_hasRights('​mediagallery.admin'​)){
 +        if (CMT_deleteComment($cid,​ $id, '​mediagallery'​) == 0) {
 +            //reduce count in media table
 +            $comments = DB_count ($_TABLES['​comments'​],​ array('​sid','​type'​),​ array(addslashes($id),​ '​mediagallery'​));​
 +            DB_change($_TABLES['​mg_media'​],'​media_comments',​ $comments, '​media_id',​ addslashes($id));​
 +            // Now redirect the program flow to the view of the file and its comments
 +            return (COM_refresh($_MG_CONF['​site_url'​] . "/​media.php?​s=$id"​));​
 +
 +        } else {
 +            return false;
 +        }
 +    } else {
 +        return false;
 +    }
 +}
 +</​code>​
 +
 +
 +
 +====== plugin_getglobaljs_{pluginname} ======
 +(glFusion v1.1.0)
 +
 +| ''​array plugin_getglobaljs_{pluginname}( )''​ |
 +
 +This API allows a plugin to return any global JavaScript variable declarations.
 +
 +
 +**Return**
 +
 +The return is an array containing the name/value pair, for example, a return of:
 +
 +    $globalJS['​mgBaseURL'​] = '​http://​www.glfusion.org';​
 +
 +would result in the following JavaScript declaration:​
 +
 +    var mgBaseURL = '​http://​www.glfusion.org';​
 +
 +
 +**Notes**
 +
 +
 +
 +**See Also**
 +
 +[[glfusion:​development:​api:​plugin:​functions#​plugin_getheadercode_pluginname|plugin_getheadercode_{pluginname)]]
 +
 +
 +
 +====== plugin_getheadercss_{pluginname} ======
 +(glFusion v1.1.0)
 +
 +| ''​array plugin_getheadercss_{pluginname}( )''​ |
 +
 +Allows a plugin to specify CSS files to load.
 +
 +
 +**Return**
 +
 +This function must return an array with the full path (not URL) to the CSS files.
 +
 +
 +**Notes**
 +
 +
 +
 +**See Also**
 +
 +[[glfusion:​development:​api:​plugin:​functions#​plugin_getheadercode_pluginname|plugin_getheadercode_{pluginname)]]
 +
 +**Example**
 +
 +<​code>​
 +function plugin_getheadercss_mediagallery() {
 +    global $_CONF, $_MG_CONF, $mgLightBox,​ $glversion,​$swfjsinclude,​$themeStyle;​
 +
 +    $styles = array();
 +
 +    if ( $_MG_CONF['​template_path'​] == $_CONF['​path'​] . '​plugins/​mediagallery/​templates'​ ) {
 +     $styleFile = $_MG_CONF['​path_html'​] . '​style.css';​
 + } else {
 + $styleFile = $_CONF['​layout_path'​] . '/​mediagallery/​style.css';​
 + }
 + $styles[] = $styleFile;
 +
 +    // check for random skin css
 +    $cacheInstance = '​mgrs'​ . $_MG_CONF['​random_skin'​] . '​__'​ . $_CONF['​theme'​];​
 +    $retval = CACHE_check_instance($cacheInstance,​ 0);
 +    if ( $retval ) {
 +        $styles[] = CACHE_instance_filename($cacheInstance,​0);​
 +    } else {
 +        require_once($_MG_CONF['​path_html'​] . '​classFrame.php'​);​
 +        $nFrame = new mgFrame();
 +        $nFrame->​constructor( $_MG_CONF['​random_skin'​] );
 +        $fCSS= $nFrame->​getCSS();​
 +        CACHE_create_instance($cacheInstance,​ $fCSS, 0);
 +        $styles[] = CACHE_instance_filename($cacheInstance,​0);​
 +    }
 +
 + return ($styles);
 +}
 +</​code>​
 +
 +This example also demonstrates how to return **dynamic** CSS.  By leveraging **instance caching**, Media Gallery dynamically creates the //Random Image Frame CSS// and stores it in an instance cache file.  It then returns the actual cache file name in the $styles array.
 +
 +
 +
 +====== plugin_getheaderjs_{pluginname} ======
 +(glFusion v1.1.0)
 +
 +| ''​array plugin_getheaderjs_{pluginname}( )''​ |
 +
 +Allows a plugin to specify JavaScript files to load.
 +
 +
 +**Return**
 +
 +This function must return an array with the full path (not URL) to the JavaScript files.
 +
 +
 +**Notes**
 +
 +
 +
 +**See Also**
 +
 +[[glfusion:​development:​api:​plugin:​functions#​plugin_getheadercode_pluginname|plugin_getheadercode_{pluginname)]]
 +
 +**Example**
 +
 +<​code>​
 +function plugin_getheaderjs_mediagallery() {
 +    global $_CONF, $_MG_CONF, $mgLightBox;​
 +
 +    $js = array();
 +
 +    $js[] = $_MG_CONF['​path_html'​] . '​js/​swfobject.js';​
 +    $js[] = $_MG_CONF['​path_html'​] . '​js/​mediagallery.js';​
 +    if ( $_MG_CONF['​disable_lightbox'​] != true ) {
 +        $js[] = $_MG_CONF['​path_html'​] . '​js/​slimbox.js';​
 +    }
 +    $js[] = $_MG_CONF['​path_html'​] . '​js/​rating.js';​
 +    $js[] = $_MG_CONF['​path_html'​] . '​js/​slideshow.js';​
 +
 +    return ($js);
 +}
 +</​code>​
 +====== THEME_themeJS ======
 +(glFusion v1.1.0)
 +
 +| ''​array THEME_themeJS( )''​ |
 +
 +Allows a theme'​s custom functions.php to specify JavaScript files to load.
 +
 +
 +**Return**
 +
 +This function must return an array with the full path (not URL) to the JavaScript files.
 +
 +
 +**Notes**
 +
 +
 +
 +**See Also**
 +
 +[[glfusion:​development:​api:​plugin:​functions#​plugin_getheadercode_pluginname|plugin_getheadercode_{pluginname)]]
 +
 +**Example**
 +
 +<​code>​
 +function theme_themeJS() {
 +    global $_CONF;
 +
 +    $js = array();
 +    $js[] = $_CONF['​path_html'​] ​
 +            .'​javascript/​mootools/​gl_moochronometer.js';​
 +    $js[] = $_CONF['​path_layout'​] .'​js/​gltips.js';​
 +
 +    return($js);​
 +}
 +</​code>​