GeeklogWiki - User contributions [en]

Scripts Class

2013-04-21T13:58:14Z

LWC: /* Setting a JavaScript Library */ Fixed line

== Introduction ==

As of version 1.8.0, Geeklog introduced the Scripts class. The Scripts Class has been designed to allow themes and plugins to easily add JavaScript, JavaScript files and CSS files to the header and/or footer of a page. It also allows plugins and themes to enable the use of jQuery and the jQuery UI plugin. By default Geeklog will place all JavaScript in the footer unless told otherwise.

In previous versions of Geeklog, JavaScript and the CSS files were handled solely by the plugin usually by including the functions plugin_getheadercode_foo or plugin_getfootercode_foo.

The advantages of using the Scripts class over having a plugin or theme manage things are many. You have easy access to jQuery and the jQuery UI plugin, no more inline scripting, and you can setup things to have files only load when needed. Plus, in the future it will automatically support caching and compression of the CSS and JavaScript files.

== Usage ==

The Scripts class is set near the beginning of lib-common.php as $_SCRIPTS. It uses the template variable plg_headercode (which is set in the function COM_SiteHeader) to put information in the header and the template variable plg_footercode (which is set in the function COM_SiteFooter) to put JavaScript in the footer. All of your JavaScript code and CSS files for the header needs to be set in the class before COM_SiteHeader is run or, for plugins, in your plugin_getheadercode_xxxx function, and themes, in the functions.php file. All JavaScript for the footer must be set by the time you call COM_SiteFooter (this shouldn't be a problem since this is one of the last functions you should be calling anyways on a page).

All JavaScript in the footer will also have access to the GeeklogConfig object. This object contains commonly used attributes taken right from Geeklogs configuration array ($_CONF) and uses the same keys.

=== Setting a CSS File ===

To set a CSS file for your plugin you would point the Scripts class to the file like so:

<pre>global $_SCRIPTS;

$_SCRIPTS->setCSSFile('polls', '/polls/style.css');</pre>

This tells the Scripts class to include the style sheet called polls. It is also telling the class that you plan to always include this CSS file. The reason you want to tell Geeklog that you plan to always include this CSS file is that it will then be marked for caching and compressing (future feature). If you plan to only include this CSS file on pages that the plugin displays you may want to include an extra parameter in the call to the class:

<pre>global $_SCRIPTS;

$_SCRIPTS->setCSSFile('polls', '/polls/style.css', false);</pre>

As stated before this needs to be done before you run the function COM_SiteHeader or in your plugins plugin_getheadercode_foo function. If your plugin has a block or uses Autotags that need the CSS file then you should always make sure it is included since Geeklog has no way of knowing if a block or Autotag will be displayed before the header is written.

=== Setting JavaScript ===

To set JavaScript for your plugin or theme you would do the following:

<pre>global $_SCRIPTS;

$js = 'some JavaScript';
$_SCRIPTS->setJavaScript($js, true);</pre>

This will automatically wrap the code in the html script tag. If you want to include your own script tag then just remove the "true" from the function call. There are several other attributes to this function that you may need to use from time to time (i.e. specifying the JavaScript to appear in the header and if it is constant). For more information on these take a look at the Scripts class found in the "/system/classes/" directory of your Geeklog install.

=== Setting a JavaScript File ===

To set a JavaScript file for your plugin or theme you would do the following:

<pre>global $_SCRIPTS;

$_SCRIPTS->setJavaScriptFile('pluginname', '/pluginname/javascript/yourfile.js');</pre>

The first attribute of the function is the internal name of the file. Make sure this is unique as you can overwrite previous entries. To standardize this, the name should be your plugin name (for themes use "theme.themename"). If you have more than one JavaScript file then you could use a name like "pluginname.subname". The second attribute of the function is obviously the location and file name of your JavaScript file. The backslash needs to be included at the beginning of this and you only include the part of the path after the public_html directory.

=== Setting a JavaScript Library ===

To load the jQuery libray included with Geeklog all you need to do is add the following code:

<pre>global $_SCRIPTS;
$_SCRIPTS->setJavaScriptLibrary('jquery');</pre>

To load a jQuery UI widget all you need to do add the following code:

<pre>global $_SCRIPTS;
$_SCRIPTS->setJavaScriptLibrary('jquery.ui.tabs');</pre>

To load a jQuery UI effect all you need to do add the following code:

<pre>global $_SCRIPTS;
$_SCRIPTS->setJavaScriptLibrary('jquery.ui.effects-highlight');</pre>

When loading an effect or widget you do not need to load the jQuery library first. When loading an effect or widget all the required files will be automatically set to load.

If a jQuery file is missing then the Google CDN-hosted copy will be substituted. There is also an option in the Geeklog Configuration under the Site tab to always use a CDN-hosted version of jQuery.

When loading one of the widgets or effects for jQuery UI you need to make sure to set it before COM_SiteHeader is executed or in your plugins plugin_getheadercode_foo function. The reason for this is the css files are set in COM_SiteHeader and we need to make sure that the CSS files for the UI plugin get set.

Stories

2011-01-04T20:25:45Z

LWC: /* Adding Images */ Sub-categories

== What Is A Story? ==

A Story is a dated entry which is added to your website. The stories are sorted by date, and have many features associated with them. There are two main components to a story: the topic and the actual story.

[[Topics]] allow you to categorize your stories and virtually create sections within your website. The default installation of Geeklog includes the topics "General News" and "Geeklog". These topics can be renamed or deleted, and new ones can be added.

Stories are the main way you can add new content to your Geeklog-powered website. Traditionally, they are used much like news-articles and are used to provide new and ongoing information to visitors of a Geeklog-powered website. Please read the [[Administration]] section for other content options.

The following instructions are for administrators' use with the [http://www.geeklog.net/article.php?story=advanced-editor Advanced Editor] which comes with Geeklog 1.4 and is integrated into the Professional theme. You must be a member of Root or Story Admin to be able to add a story this way.

=== Adding A Story ===

# Log into your site.
# In the [[Admins Block|Admins Only]] section on the left, click the "Stories" link.
# Click the "Create New" link near the top of the page.
# Wait for the page to load the toolbar for editing.
# Complete the "Title" field
# Select a Topic.
# You may change the text in the "ID" field if desired (it defaults to the date and time).
# By default (i.e. unless you have changed the setting in the [[ConfigFile14|configuration file]]) the "Show Topic" icon is selected. Change this if you do not want the topic icon to show.
# Select the "Draft" box if you are creating a draft only.
# Complete the "Intro Text" and "Body Text" fields. The text in the "Intro Text" field will show on your main page. The text in the "Body Text" field will show with the intro text after someone clicks on the "read more" link under a story.
# If you are using the advanced editor and want to preview your story, you must click the "Preview" button at the bottom to save a temporary copy of the story on the server, then click the "Preview" button at the top to view the preview.
# When you are happy with your changes, click the "Save" button.

=== Publishing Options ===

When editing your story, you can access the publishing options by clicking the "Publishing Options" link at the top of the screen. Your options are to change:
* the publishing date (future-dated stories will not be published until that date)
* whether the story is "featured" (the default is "not featured"; a featured story will show at the top of the list of stories, even if a newer story is added, until another story is flagged as "featured")
* whether the story will show on the "front page" (i.e. home page) of your site, or whether it will only show in the topic subsection
* whether comments are allowed
* whether trackbacks are allowed (this is defaulted to "disabled"; [http://en.wikipedia.org/wiki/Trackback trackbacks] are links to sites which link to yours; use trackbacks with caution, because much trackback is now found to be spam)

=== Adding Images ===

====Internally====
Click on the "Images" link at the top of the story editor screen. Use the "Browse" buttons to look for the images on your computer for uploading. The "Images" section of the story editor has more notes on how to integrate the images in your post. You will need to insert the [image1] etc tags into the story manually.
=====Extra images=====
* To increase the number of images you can upload (available only if you have access to uploading files directly to the webserver):
*# log out of your site
*# open your config.php file in a text editor
*# search for <i>$_CONF['maximagesperarticle']</i>
*# change the number "5" to the maximum number of images you want to be allowed for a story
*# save your changes
*# upload the changed config.php file (overwrite the existing file) onto your web server

====Externally====
# Stay in the "Editor" screen (if you have left it, simply click the "Editor" link at the top of the screen).
# Click the arrow button in your editor toolbar [[image:expand-arrow.jpg]]. This will open the editor in a new window.
# Click on the image icon [[image:image.jpg]]. A new window will open.
# Click on the "Browse Server" button. The window will change to the Resource Browser window.
# To upload a new photo:
#* click the "Browse" button at the bottom
#* find the image on your computer, and double-click it to select the image
#* click the "Upload" button and wait for the upload to complete
#* if the window goes blank, right-click in the window and select "Reload" or "Refresh" to update the list of photos.
# If you have already uploaded your photo, you can click on it to select the photo.
# Other options (changes will show in the preview area):
#* Type a number in the "Border" field if you want a border (0=no border; 1=thin border; 2 and up correspond with the thickness of the border)
#* HSpace is the space on the left and right of the image
#* VSpace is the space above and below the image
#* The Alternate Text is what will show if you "hover" your mouse above the image, or if your visitor's web browser is set to block images
#* The "Link" tab allows you to make the image a link. You can either type the web address in the "URL" or click the "Browse Server" button to activate the Resource Browser window (this works the same way as it does in the "To upload a new photo" instructions above). The "Target" drop-down allows you to change the target window of the link.
#* Advanced Features - ? (please edit this page and add info on the Advanced Features tab if you have used it)
# When you are happy with your changes, click the "OK" button. This will close the small window.
# You can continue to edit your story here, or return to the main editing window. To close the large editing window, click the arrow button [[image:minimize-arrow.jpg]]

=== Archive Options ===

The archive options allow you to set whether the story will be [[Archive Topic|archived]] or deleted on a particular date. The default is for no archiving or deleting. To change the setting, click on the "Archive Options" link and make the desired changes.

=== Permissions ===

Permissions indicate who is allowed to read and edit the story. The default is that anyone can read the story, and only the owner can edit it.

The possible permission options are:
* Anonymous visitors (not logged-in) - read-access on or off
* Members (logged-in) - read-access on or off
* Group members (must be logged-in) - read-access on or off; edit-access on or off
* Owner (must be logged-in) - read-access on or off; edit-access on or off

To allow only members to read the story, de-select the check-box under "Anonymous". Members must log into the site before they can read the article.

To prevent members from reading the story (e.g. if you have a story about creating a user-account and don't want it to show once they have logged in), de-select the check-box under "Members".

Geeklog also has permissions set by groups. By default, the Admin account and any account with Root access is a member of all groups except Remote Users. Members can also be assigned selectively to individual groups (e.g. "Story Admin"). By changing the group showing in the drop-down box and selecting the check-box "E" under "Groups", you will allow anyone in the selected group to be able to edit the story.

You will want to retain read- and edit-access to your story. De-selecting those options does not seem to remove your read- and edit-access, but you are advised against changing that because you may lock yourself out of the story.

=== Show All ===

The "Show All" link allows you to see and edit the story, publish options, images, archive options and permissions on one page.

Submitting Patches

2010-04-05T10:32:34Z

LWC: Added title and fixed typo

If you want to submit a patch for Geeklog, please check out the current development version from our [[Using Mercurial|Mercurial]] repository. You can also submit patches against released versions by checking out that version's code using the <tt>..._stable</tt> [[Tags and Branches|tag]].

==Checklist==
* check out the source code
* make the necessary changes to the source
* commit changes into your local repository
* Exporting:
** export the changeset using <tt>hg export REV</tt> where <tt>REV</tt> is the revision number of the changeset
*** to export the latest changeset from your repository, simply use <pre>hg export tip</pre>
*** The TortoiseHg GUI equivalence is: '''Hg Repository Explorer=>choose Changeset=>Export Patch'''
* if your patch consists of more than one changeset, please export them individually into separate files with consecutive numbers so we know in which order they need to be applied (Note: while <tt>hg export</tt> can export multiple changesets into one file, the equivalent <tt>hg import</tt> currently only accepts one changeset per file, so we're asking for separate files.)
* Diff files:
** if you are '''not''' using <tt>hg export</tt> please send ''unified'' diff files and make sure you list the files in the correct order, i.e. <pre>diff -u original-file modified-file > patch.diff</pre>
** The TortoiseHg GUI equivalence is: '''Hg Commit=>Diff''' ''(?)''
* add the patch (or zipped/gzipped set of patches) as an attachment to the bug or feature request in question on our [http://project.geeklog.net/tracking/ bugtracker]
** if there is no bug or feature request for your patch, send the patch (with an explanation) to the [http://eight.pairlist.net/mailman/admindb/geeklog-devel geeklog-devel] mailing list (if the patch is really huge, you may want to upload it somewhere and only send the URL)

Thank you!

== diff vs. hg export ==

You may be wondering why we're asking you to use <tt>hg export</tt> instead of the more common <tt>diff</tt> files. That is because export files
* include the checkin comment
* give proper attribution to the person who created the patch (i.e. '''you''')

[[Category:Development]]

Submitting Patches

2010-04-05T10:31:54Z

LWC: GUI equivalence

If you want to submit a patch for Geeklog, please check out the current development version from our [[Using Mercurial|Mercurial]] repository. You can also submit patches against released versions by checking out that version's code using the <tt>..._stable</tt> [[Tags and Branches|tag]].

* check out the source code
* make the necessary changes to the source
* commit changes into your local repository
* Exporting:
** export the changeset using <tt>hg export REV</tt> where <tt>REV</tt> is the revision number of the changeset
*** to export the latest changeset from your repository, simply use <pre>hg export tip</pre>
*** The TortoiseHg GUI equivalence is: '''Hd Repository Explorer=>choose Changeset=>Export Patch'''
* if your patch consists of more than one changeset, please export them individually into separate files with consecutive numbers so we know in which order they need to be applied (Note: while <tt>hg export</tt> can export multiple changesets into one file, the equivalent <tt>hg import</tt> currently only accepts one changeset per file, so we're asking for separate files.)
* Diff files:
** if you are '''not''' using <tt>hg export</tt> please send ''unified'' diff files and make sure you list the files in the correct order, i.e. <pre>diff -u original-file modified-file > patch.diff</pre>
** The TortoiseHg GUI equivalence is: '''Hg Commit=>Diff''' ''(?)''
* add the patch (or zipped/gzipped set of patches) as an attachment to the bug or feature request in question on our [http://project.geeklog.net/tracking/ bugtracker]
** if there is no bug or feature request for your patch, send the patch (with an explanation) to the [http://eight.pairlist.net/mailman/admindb/geeklog-devel geeklog-devel] mailing list (if the patch is really huge, you may want to upload it somewhere and only send the URL)

Thank you!

== diff vs. hg export ==

You may be wondering why we're asking you to use <tt>hg export</tt> instead of the more common <tt>diff</tt> files. That is because export files
* include the checkin comment
* give proper attribution to the person who created the patch (i.e. '''you''')

[[Category:Development]]

InstallFaq

2010-03-25T20:39:32Z

LWC: /* What are the System Requirments for Geeklog? */ LightTPD

'''Note:''' You may also want to check [http://www.geeklog.net/faqman/ the FAQs on geeklog.net] as some of the information here may be out of date or incomplete.

== Configuring Email (Geeklog 1.3.9 and newer versions) ==

Starting with version 1.3.9, Geeklog uses the PEAR::Mail class to send all emails, offering you the following methods to send emails:
*'smtp', i.e. using an SMTP server
*'mail', i.e. using PHP's built-in mail function
*'sendmail', i.e. using the Unix sendmail application

All the following settings can be found in your config.php.

=== SMTP ===

To configure Geeklog to send all emails using an SMTP server, set 'backend' to 'smtp' and enter the information to contact your SMTP server as follows:

:'host' => 'name of your smtp server',
:'port' => '25',
:'auth' => false,
:'username' => 'your smtp username',
:'password' => 'your smtp password'

You should have gotten these settings from your ISP. The name of the smtp server is usually something like 'smtp.your-domain.com' but in some cases it's simply 'localhost'. The port number is usually 25. The 'auth' option tells Geeklog whether to use authentication or not (set to true for authentication).

=== mail ===

When setting 'backend' to 'mail' (which is also the default) Geeklog will use PHP's built-in mail() function. None of the other $_CONF['mail_settings'] options have to be changed for this.

This is almost like what Geeklog used in versions prior to 1.3.9. There is, however, a difference in how PEAR::Mail implements this option so that 'mail' can not be used when safe_mode is activate on your webserver. You will have to use one of the other options if that is the case for you.

=== sendmail ===

On most setups, there isn't any benefit in using this option - it's mainly provided for completeness. You can set the path to the sendmail binary ('sendmail_path') and pass additional arguments to sendmail by setting 'sendmail_args' accordingly.

=== Which method should I use? ===

If you can, SMTP is probably the best method to use. It ensures that the email is sent through your SMTP server which reduces the chances that emails are regarded as spam by some of the more strict mail filters.

'mail' is the second-best option but, as noted above, won't work when safe_mode is on.

=== A fourth option ===

If none of the above methods work for you, there is a fourth option: You can implement your own function to send email. This may be necessary on some free hosting services that disable PHP's mail function.

The function must be called CUSTOM_mail. A sample implementation is included in the lib-custom.php file that ships with Geeklog. This sample code is a re-implementation of the way Geeklog sent emails prior to 1.3.9. It also uses PHP's mail function, but in such a way that it will work when safe_mode is on.

Please note that the function is commented out by default - you will have to remove the comments around the function before it will be used.

== Geeklog on PHP 5 ==

Here are some initial observations, a few days after the official release of PHP 5.0.0:

*The links to plugins don't show up properly in the Admin and User Functions blocks, as well as in the "Command and Control" block. The problem is in lib-plugins.php and a fix (for Geeklog 1.3.9sr1) is available from CVS.
*Make sure you have register_long_arrays = On in your php.ini. For compatibility with old versions of PHP 4, Geeklog relies on the "old-style" input arrays, $HTTP_POST_VARS and $HTTP_GET_VARS.
*Don't forget to switch register_globals = On

== How can I upgrade from a version of Geeklog older than 1.2.5-1? ==

If you are running a version of Geeklog older than 1.2.5-1 you will need to upgrade your database from your current version to 1.2.5-1 using the SQL scripts in the sql/updates directory. Once you have the database upgraded to 1.2.5-1 you can run the installation script to upgrade to the current version.

== How do I find out my paths? ==

Just call up the install script <b><nowiki>http://yourgeeklogsite/admin/install/install.php</nowiki></b>. At the bottom of the page, it will give you a hint what the complete path to the install script is and, depending on your configuration, it may also tell you what you need to set as your "path to geeklog". You should be able to figure the paths out from these hints.

If you have shell access to your webserver, another way to find out the proper paths is to change to the directories in question (e.g. the one where the config.php resides) and enter the Unix pwd command, which will print out the current path.

== How do I setup PHP mail for Windows? ==

Geeklog prior to version 1.3.9 uses the built-in mail function in PHP. In your php.ini file find the following section header: [mail function]

Setup the smtp directive to either you local server or your ISP. Also setup the sendmail_from directive. That should do it.

[mail function]
; For Win32 only.
SMTP = mail.mw.centurytel.net

; For Win32 only.
sendmail_from = admim@somegeeklogsite.com

; For Unix only. You may supply arguments as well (default: "sendmail -t -i").
;sendmail_path =

Starting with Geeklog 1.3.9, you can make those settings in Geeklog's config.php instead. See this FAQ for details.

== Migrating a Geeklog Site ==

Sooner or later, you'll be facing the problem of having to move your Geeklog site from one server to another, e.g. when changing hosting services. Here are a few tips to successfully make that transition:

#Create a '''backup''' of your Geeklog database on your old server
#Make backups of the story images in the images/articles and the userphotos in the images/userphoto directories
#Make a backup of your config.php for reference
#Make a backup of your theme

We'd suggest that you start with a fresh install on your new site. Moving your site is also the perfect opportunity to upgrade if you haven't been running the latest version of Geeklog anyway (use the "GL Version Test" link on your old site to check if you are running the current version).

Once you have Geeklog up and running on the new server, you can drop the database, create an empty database again, and then import the database backup from your old site (see Restoring a database backup).

*If you had any plugins installed (besides the Static Pages plugin), you should now upload their files on the new server as well (don't run any install scripts for those plugins, though).
*Upload your story images and userphotos into their new locations.
*If you're upgrading to a new Geeklog version in the process, then don't upload your theme just yet. New Geeklog versions usually include changes in the theme files and you should use one of the included default themes until you can be sure your migrated site works properly.
*If you're upgrading your Geeklog site, run the install script in upgrade mode now.
*If you've updated any of your plugins, run their upgrade scripts now, if necessary (please refer to the documentation of your plugins to see if that is necessary).
*Make sure everything works properly. See if you can edit stories, for example.
*Update your theme, if necessary. Refer to Geeklog's theme documentation for a list of changes in the themes.

That's it. You've successfully migrated your Geeklog site.

=== Common problems ===

*Make sure register_globals=on on your new server.
: You can check this by creating a file (in a text editor) with the following line:
<pre><?php phpinfo(); ?></pre>
: Save this file somewhere on your server as "phpinfo.php" and load it up in your browser. This will generate a nice table with all the current settings of your php installation. If register_globals is OFF, [[#Will Geeklog work with register_globals off?|see the tip below]].

*If the URL of your site changed, then the URLs to any uploaded images in your stories will still point to your old site. There is, unfortunately, no easy solution for this yet, so you'll have to edit those image URLs in the database directly (using phpMyAdmin). This is currently listed as a bug and will be addressed in a future version of Geeklog.

== What are the System Requirments for Geeklog? ==

Geeklog requires [http://www.php.net PHP], [http://www.mysql.com MySQL] and a webserver that works with these.

'''PHP''': The minimum PHP version required is '''PHP 4.0.4'''. However, that version is very much out of date (and has security issues), so we suggest you use PHP 4.1.2 at the very least. Or, better yet, use the most up to date version available at the time you're reading this.

At the time of this writing, PHP 5 is still in Beta. As one of the main goals of PHP 5 development was to keep compatibility with PHP 4, we do not expect any serious problems with PHP 5. We plan to be fully compatible with PHP 5 when it is released.

'''MS SQL''': Microsoft SQL Server 2000 or above.

'''MySQL''': While we try to be compatible with MySQL down to version 3.22, we recommend using the most up to date version of the 3.23 or 4.0 variety available at the time you're reading this.

Please note that because of possible SQL injection problems, we do not recommend using Geeklog on MySQL 4.1 (which is still in Alpha state at the time of this writing). We plan to resolve any outstanding issues with the release of Geeklog 1.3.9 in early 2004.

'''Webserver''': Geeklog is known to work with the Apache, Zeus, Microsoft IIS and LightTPD webservers. As with the other components, it is suggested to use the most up to date version available at the time you're reading this.

A note about Apache 2 compatibility: At the time of this writing, there was still no official word from the PHP developers regarding compatibility of PHP 4 and Apache 2. There are, however, several sites running without any problems on this combination. Again, it is suggested to use the most up to date version of both Apache and PHP.

== Where Do I enter the mail server configuration? ==

For Geeklog 1.3.9 and newer versions, please see [[#Configuring_Email_(Geeklog_1.3.9_and_newer_versions)|this FAQ entry]].

Older Geeklog versions simply use PHP's mail() function to send all email. To make that function work, you will need to edit your php.ini file.

The [http://www.php.net/manual/en/ref.mail.php PHP manual] has all the information you need.

In case your site is running on Windows, [[#How do I setup PHP mail for Windows?|this FAQ entry]] has additional information.

== Will you install Geeklog for me? ==

Sure. The people listed in [http://www.geeklog.net/article.php?story=20030818224145271 this story] will be more than willing to install it for you.

== Will Geeklog work with register_globals off? ==

Only Geeklog 1.4.0 and later versions will work with <code>register_globals = off</code>. Older versions as well as some plugins and other add-ons still require it to be "on".

[[#Common problems|How to tell if it's on or off]]

If you can't set <code>register_globals = on</code> in <tt>php.ini</tt> (e.g. because you don't have access to it) you can try to create a <tt>.htaccess</tt> file in your document root that has this line in it:

<pre>php_flag register_globals on</pre>

This will only work when your webserver is Apache (does a similar option exist for IIS?) and when it's configured such that it lets you override the <code>register_globals</code> setting.

See also: Isn't it a security risk to have register_globals=on?

InstallFaq

2010-03-25T20:38:35Z

LWC: /* What are the System Requirments for Geeklog? */ MS SQL is supported too

'''Note:''' You may also want to check [http://www.geeklog.net/faqman/ the FAQs on geeklog.net] as some of the information here may be out of date or incomplete.

== Configuring Email (Geeklog 1.3.9 and newer versions) ==

Starting with version 1.3.9, Geeklog uses the PEAR::Mail class to send all emails, offering you the following methods to send emails:
*'smtp', i.e. using an SMTP server
*'mail', i.e. using PHP's built-in mail function
*'sendmail', i.e. using the Unix sendmail application

All the following settings can be found in your config.php.

=== SMTP ===

To configure Geeklog to send all emails using an SMTP server, set 'backend' to 'smtp' and enter the information to contact your SMTP server as follows:

:'host' => 'name of your smtp server',
:'port' => '25',
:'auth' => false,
:'username' => 'your smtp username',
:'password' => 'your smtp password'

You should have gotten these settings from your ISP. The name of the smtp server is usually something like 'smtp.your-domain.com' but in some cases it's simply 'localhost'. The port number is usually 25. The 'auth' option tells Geeklog whether to use authentication or not (set to true for authentication).

=== mail ===

When setting 'backend' to 'mail' (which is also the default) Geeklog will use PHP's built-in mail() function. None of the other $_CONF['mail_settings'] options have to be changed for this.

This is almost like what Geeklog used in versions prior to 1.3.9. There is, however, a difference in how PEAR::Mail implements this option so that 'mail' can not be used when safe_mode is activate on your webserver. You will have to use one of the other options if that is the case for you.

=== sendmail ===

On most setups, there isn't any benefit in using this option - it's mainly provided for completeness. You can set the path to the sendmail binary ('sendmail_path') and pass additional arguments to sendmail by setting 'sendmail_args' accordingly.

=== Which method should I use? ===

If you can, SMTP is probably the best method to use. It ensures that the email is sent through your SMTP server which reduces the chances that emails are regarded as spam by some of the more strict mail filters.

'mail' is the second-best option but, as noted above, won't work when safe_mode is on.

=== A fourth option ===

If none of the above methods work for you, there is a fourth option: You can implement your own function to send email. This may be necessary on some free hosting services that disable PHP's mail function.

The function must be called CUSTOM_mail. A sample implementation is included in the lib-custom.php file that ships with Geeklog. This sample code is a re-implementation of the way Geeklog sent emails prior to 1.3.9. It also uses PHP's mail function, but in such a way that it will work when safe_mode is on.

Please note that the function is commented out by default - you will have to remove the comments around the function before it will be used.

== Geeklog on PHP 5 ==

Here are some initial observations, a few days after the official release of PHP 5.0.0:

*The links to plugins don't show up properly in the Admin and User Functions blocks, as well as in the "Command and Control" block. The problem is in lib-plugins.php and a fix (for Geeklog 1.3.9sr1) is available from CVS.
*Make sure you have register_long_arrays = On in your php.ini. For compatibility with old versions of PHP 4, Geeklog relies on the "old-style" input arrays, $HTTP_POST_VARS and $HTTP_GET_VARS.
*Don't forget to switch register_globals = On

== How can I upgrade from a version of Geeklog older than 1.2.5-1? ==

If you are running a version of Geeklog older than 1.2.5-1 you will need to upgrade your database from your current version to 1.2.5-1 using the SQL scripts in the sql/updates directory. Once you have the database upgraded to 1.2.5-1 you can run the installation script to upgrade to the current version.

== How do I find out my paths? ==

Just call up the install script <b><nowiki>http://yourgeeklogsite/admin/install/install.php</nowiki></b>. At the bottom of the page, it will give you a hint what the complete path to the install script is and, depending on your configuration, it may also tell you what you need to set as your "path to geeklog". You should be able to figure the paths out from these hints.

If you have shell access to your webserver, another way to find out the proper paths is to change to the directories in question (e.g. the one where the config.php resides) and enter the Unix pwd command, which will print out the current path.

== How do I setup PHP mail for Windows? ==

Geeklog prior to version 1.3.9 uses the built-in mail function in PHP. In your php.ini file find the following section header: [mail function]

Setup the smtp directive to either you local server or your ISP. Also setup the sendmail_from directive. That should do it.

[mail function]
; For Win32 only.
SMTP = mail.mw.centurytel.net

; For Win32 only.
sendmail_from = admim@somegeeklogsite.com

; For Unix only. You may supply arguments as well (default: "sendmail -t -i").
;sendmail_path =

Starting with Geeklog 1.3.9, you can make those settings in Geeklog's config.php instead. See this FAQ for details.

== Migrating a Geeklog Site ==

Sooner or later, you'll be facing the problem of having to move your Geeklog site from one server to another, e.g. when changing hosting services. Here are a few tips to successfully make that transition:

#Create a '''backup''' of your Geeklog database on your old server
#Make backups of the story images in the images/articles and the userphotos in the images/userphoto directories
#Make a backup of your config.php for reference
#Make a backup of your theme

We'd suggest that you start with a fresh install on your new site. Moving your site is also the perfect opportunity to upgrade if you haven't been running the latest version of Geeklog anyway (use the "GL Version Test" link on your old site to check if you are running the current version).

Once you have Geeklog up and running on the new server, you can drop the database, create an empty database again, and then import the database backup from your old site (see Restoring a database backup).

*If you had any plugins installed (besides the Static Pages plugin), you should now upload their files on the new server as well (don't run any install scripts for those plugins, though).
*Upload your story images and userphotos into their new locations.
*If you're upgrading to a new Geeklog version in the process, then don't upload your theme just yet. New Geeklog versions usually include changes in the theme files and you should use one of the included default themes until you can be sure your migrated site works properly.
*If you're upgrading your Geeklog site, run the install script in upgrade mode now.
*If you've updated any of your plugins, run their upgrade scripts now, if necessary (please refer to the documentation of your plugins to see if that is necessary).
*Make sure everything works properly. See if you can edit stories, for example.
*Update your theme, if necessary. Refer to Geeklog's theme documentation for a list of changes in the themes.

That's it. You've successfully migrated your Geeklog site.

=== Common problems ===

*Make sure register_globals=on on your new server.
: You can check this by creating a file (in a text editor) with the following line:
<pre><?php phpinfo(); ?></pre>
: Save this file somewhere on your server as "phpinfo.php" and load it up in your browser. This will generate a nice table with all the current settings of your php installation. If register_globals is OFF, [[#Will Geeklog work with register_globals off?|see the tip below]].

*If the URL of your site changed, then the URLs to any uploaded images in your stories will still point to your old site. There is, unfortunately, no easy solution for this yet, so you'll have to edit those image URLs in the database directly (using phpMyAdmin). This is currently listed as a bug and will be addressed in a future version of Geeklog.

== What are the System Requirments for Geeklog? ==

Geeklog requires [http://www.php.net PHP], [http://www.mysql.com MySQL] and a webserver that works with these.

'''PHP''': The minimum PHP version required is '''PHP 4.0.4'''. However, that version is very much out of date (and has security issues), so we suggest you use PHP 4.1.2 at the very least. Or, better yet, use the most up to date version available at the time you're reading this.

At the time of this writing, PHP 5 is still in Beta. As one of the main goals of PHP 5 development was to keep compatibility with PHP 4, we do not expect any serious problems with PHP 5. We plan to be fully compatible with PHP 5 when it is released.

'''MS SQL''': Microsoft SQL Server 2000 or above.

'''MySQL''': While we try to be compatible with MySQL down to version 3.22, we recommend using the most up to date version of the 3.23 or 4.0 variety available at the time you're reading this.

Please note that because of possible SQL injection problems, we do not recommend using Geeklog on MySQL 4.1 (which is still in Alpha state at the time of this writing). We plan to resolve any outstanding issues with the release of Geeklog 1.3.9 in early 2004.

'''Webserver''': Geeklog is known to work with the Apache, Zeus, and Microsoft IIS webservers. As with the other components, it is suggested to use the most up to date version available at the time you're reading this.

A note about Apache 2 compatibility: At the time of this writing, there was still no official word from the PHP developers regarding compatibility of PHP 4 and Apache 2. There are, however, several sites running without any problems on this combination. Again, it is suggested to use the most up to date version of both Apache and PHP.

== Where Do I enter the mail server configuration? ==

For Geeklog 1.3.9 and newer versions, please see [[#Configuring_Email_(Geeklog_1.3.9_and_newer_versions)|this FAQ entry]].

Older Geeklog versions simply use PHP's mail() function to send all email. To make that function work, you will need to edit your php.ini file.

The [http://www.php.net/manual/en/ref.mail.php PHP manual] has all the information you need.

In case your site is running on Windows, [[#How do I setup PHP mail for Windows?|this FAQ entry]] has additional information.

== Will you install Geeklog for me? ==

Sure. The people listed in [http://www.geeklog.net/article.php?story=20030818224145271 this story] will be more than willing to install it for you.

== Will Geeklog work with register_globals off? ==

Only Geeklog 1.4.0 and later versions will work with <code>register_globals = off</code>. Older versions as well as some plugins and other add-ons still require it to be "on".

[[#Common problems|How to tell if it's on or off]]

If you can't set <code>register_globals = on</code> in <tt>php.ini</tt> (e.g. because you don't have access to it) you can try to create a <tt>.htaccess</tt> file in your document root that has this line in it:

<pre>php_flag register_globals on</pre>

This will only work when your webserver is Apache (does a similar option exist for IIS?) and when it's configured such that it lets you override the <code>register_globals</code> setting.

See also: Isn't it a security risk to have register_globals=on?

User talk:LWC

2010-03-07T19:10:14Z

LWC: /* Templates */

==Templates==
LWC, I'm not sure if your use of templates for links really improves things. IMHO, it only makes things harder to read. As in "... we will be adopting jQuery as our ...". What's wrong with having "jQuery" as a link? I can guess where the link goes to and if I don't want to follow it, I can easily ignore it. But with your template, it now reads "... jQuery (Wikipedia entry) as our ...", which is much harder to read and clutters the sentence with information that I don't need. -- [[User:Dirk|Dirk]] 19:06, 7 March 2010 (UTC)
: Actually, that one is not a template but just a regular wiki-link. As for the templates, you can just change them to look like what you want. But the bottom line is that I think users deserve to know where they'll be going before clicking external links. This full disclosure is a matter of taste, I guess. If it was Wikipedia, we could do a vote. :-) -[[User:LWC|LWC]] 19:10, 7 March 2010 (UTC)

SoC improve configuration gui

2010-03-07T18:53:32Z

LWC: Improved links

<center>(This is an idea page for the [[Google Summer of Code]])</center>

== Incentive ==

This is a continuation of the [[SoC config.php GUI|2007 GSoC project]] that resulted in the current Configuration GUI. This follow-up project is aimed at implementing some of the ideas that didn't make it into the initial version. This is also a good opportunity to do a reality check of the existing GUI and see what's missing and what could be improved.

== Details ==

=== More Fine Grained Access Control ===

Currently, only users in Geeklog's "Root" group have access to the Configuration. The idea has always been, however, to make this more fine grained so that, for example, Story Admins could - optionally - have access to configuration options related to stories and story submissions.

==== Define Config Groups ====

As a first step, the existing config options will have to be reviewed and grouped to get an idea which options belong together and to which access can be granted. There will certainly be options for which Root access is still required. Plugins should also be allowed to control access to their config options.

==== Access Control ====

Access control should be implemented on a per-option basis. There are various ways how this could be implemented. One obvious solution could be to introduce <tt>config.*</tt> permissions, e.g. having <tt>config.story</tt> permissions would give access to config options related to stories (actually, that's probably too broad and should be more fine grained). But there may be other (better) ways to implement this.

Options for which the current user does not have access should not be displayed. Root users should have access to everything, as usual.

=== JavaScript ===

==== jQuery ====
The current GUI uses some custom JavaScript code to operate. For future versions of Geeklog, we will be adopting jQuery ([[wikipedia:en:jQuery|Wikipedia entry]]) as our standard JavaScript library. This would be a good opportunity to use jQuery for some non-trivial application, i.e. rewrite the existing JavaScript code for jQuery.

==== UI improvements ====

Other areas where JavaScript could help improve the UI:
* Some config options depend on each other (e.g. 'language_files' and 'languages'). Some JavaScript code could help prevent setting these options to illegal states that could prevent the site from working properly.
* Real-time bounds checks: Some config options are displayed as free-form input fields but really only accept numerical values or a certain range of values.

=== Search ===

With over 200 configuration options for the Geeklog core alone, it is sometimes hard to find the config option you're looking for. Being able to search for an option would come in handy.

While this could be implemented as a "traditional" search, something more interactive could make this a really useful feature. This would also be another case that could benefit from the adoption of jQuery.

=== New UI Elements ===

Currently, the Configuration GUI supports dropdowns, input fields (one-line and multi-line) and array-type fields.

Many of the dropdowns, however, only offer true/false options and may be better represented as radio buttons or checkboxes. Review the existing options and implement support for the additional types where required.

There may be other new UI elements that we may want to implement to better represent some of the available options. A pair of fresh eyes (belonging to someone who doesn't know about the $_CONF heritage of the Configuration) could help identify those ...

=== Miscellaneous ===

And then there are a couple of minor details that should be looked into, e.g.

* re-grouping / re-arranging / re-wording options
* provide direct links to config sections, e.g. {{forum|89704|for plugins}}

== Level of Difficulty ==

''medium''

This project involves understanding the existing code and learning how to modify and extend it. Knowledge of JavaScript is required.

== Further Reading ==

* [[Configuration Class|Implementation details of the Configuration Class]]
* {{tracker|950|Feature Request #0000950}}: Only root admins can see and use Site Configuration

[[Category:Summer of Code]] [[Category:Development]]

Template:Tracker

2010-03-07T18:52:24Z

LWC: New page: <includeonly>'''{{{2}}}''' ([http://project.geeklog.net/tracking/view.php?id={{{1}}} tracker link])</includeonly><noinclude>Supply tracker parameters and get a link. ==Usage== <pre><nowik...

<includeonly>'''{{{2}}}''' ([http://project.geeklog.net/tracking/view.php?id={{{1}}} tracker link])</includeonly><noinclude>Supply tracker parameters and get a link.

==Usage==
<pre><nowiki>{{tracker|ticketID|Title}}</nowiki></pre>

For example, <nowiki>{{tracker|200|Test}}</nowiki> would display as:

{{tracker|200|Test}}
</noinclude>

Themes and XHTML

2010-01-24T23:00:47Z

LWC: /* XHTML Constant */ Fixed spelling

Since version 1.5.0, Geeklog supports [http://en.wikipedia.org/wiki/XHTML XHTML] compliant themes. This means that Geeklog will automatically create XHTML compliant tags when required.

== Switching to XHTML ==

Whether Geeklog will switch to XHTML compliant mode or not depends on the definition of an <tt>XHTML</tt> variable in the PHP code. This variable can either be defined by the theme (in the theme's <tt>functions.php</tt> file) or by selecting an XHTML DOCTYPE from the Configuation (since Geeklog 1.6.0):

: Configuration > Geeklog > Theme > Theme > [http://www.geeklog.net/docs/english/config.html#desc_doctype DOCTYPE Declaration]

Selecting an XHTML DOCTYPE will automatically set the <tt>XHTML</tt> constant properly (any definition made by the theme still takes precedence, though, so make sure the two don't conflict).

== XHTML Constant ==

For an XHTML compliant theme, the <tt>XHTML</tt> constant should be defined like so:

<pre>define('XHTML', ' /');</pre>

Otherwise, the constant will be defined as an empty string:

<pre>define('XHTML', '');</pre>

Plugins can simply use the <tt>XHTML</tt> constant - Geeklog will take care that is always defined. The same is true for code in <tt>lib-custom.php</tt>, with the exception of code that is not located in a function (since <tt>lib-custom.php</tt> will be included before the theme, and any global code in <tt>lib-custom.php</tt> would therefore be executed before the constant is defined).

== Template Variables ==

The definition of the <tt>XHTML</tt> constant is also available as a <tt>{xhtml}</tt> template variable in all template files used by Geeklog. This way, it is possible to create themes that will work both as XHTML and "plain" HTML by using the template variable for tags that have to be closed in XHTML, e.g.

<pre><br{xhtml}>
<input type="submit" name="test"{xhtml}>
<img src="image.png" alt=""{xhtml}></pre>

=== Other Template Variables ===

Themes that are written to be both valid HTML and XHTML (as described above) should use the <tt>{doctype}</tt> variable as the first line in <tt>header.thtml</tt> instead of hard-coding the DOCTYPE.

In XHTML mode, Geeklog will also provide a <tt>{xmlns}</tt> variable that will contain the <tt>xmlns</tt> attribute for the <tt>html</tt> element.

Putting it all together, the first 3 lines of your theme's <tt>header.thtml</tt> should look like this:

<pre>{doctype}
<html{lang_attribute}{xmlns}>
<head></pre>

The <tt>{lang_attribute}</tt> will set a <tt>lang</tt> attribute in [[Multilingual Support|multi-language setups]].

The Professional theme that ships with Geeklog uses the <tt>{doctype}</tt> template variable and is both HTML and XHTML compliant, depending on the DOCTYPE selected in the Configuration.

[[Category:Themes]]

Dynamic Blocks

2010-01-24T15:42:31Z

LWC: /* Dynamic Block API */ Fixed spelling

== Dynamic Block Plugin API in Geeklog 1.4 ==

The dynamic block plugin API is a new feature of Geeklog 1.4. This new API function allows plugin developers to create left and right blocks in Geeklog on the fly without adding a block to the blocks table. This is accomplished by inserting the block data directly into the array of blocks that is created from a SQL call to the blocks table before it is used to create what is displayed. What follows is an description of the API call and its use in a plugin.

=== Dynamic Block API ===

This section will describe and document how to enable your plugin to use the Geeklog dynamic block API. This will be a useful feature of plugin functionality for many developers and it has been designed to be easy to integrate into your plugin. We have done our best to make this straightforward.

<b>NOTE:</b> You will need to be using Geeklog version 1.4 or later to successfully use the Dynamic Block API. This plugin API is only available in Geeklog 1.4 and is not present in previous versions of Geeklog.

There is only one plugin function that is required to support dynamic blocks in a plugin. The example function that is included in this explanation are very complete. You should only need to edit them for your plugin name name. The following table summarizes the functions:

<div align="center">
<table cellpadding="2" width="100%" border="1"
style="border-collapse: collapse" bordercolor="#111111"
cellspacing="0">
<tr>
<th vAlign="top" width="4%"> </th>
<th vAlign="top" width="31%">Function</th>
<th vAlign="top" width="95%">Description of Function</th>

</tr>
<tr>
<td class="codeheader" valign="top" width="5%" align="center"><font
size="2">1</font></td>
<td class="codeheader" valign="top" width="10%"><font
size="2">plugin_getBlocks_<plugin name></font></td>
<td class="code" valign="top" width="85%"><font size="2">This
function expects two parameters: side and topic. This function is called when a left and right blocks are created with COM_showBlocks in lib-common.php. It is up to the plugin to make sure that the requesting user has sufficient permissions to view any blocks that are returned. It should return an array of block data containing the dynamically generated blocks that you wish the user to see.</font></td>
</tr>
</table>
</div>

=== Function Details and Examples ===

Examples provided here have been provided from an initial example created by the developer of the Dynamic Block API for a plugin currently in development

This function expects two parameters: side and topic. This function is called when a left and right blocks are created with COM_showBlocks in lib-common.php. It is up to the plugin to make sure that the requesting user has sufficient permissions to view any blocks that are returned. It should return an array of block data containing the dynamically generated blocks that you wish the user to see.

<div style="white-space:pre; border: solid; border-color: black;
border-width: 1; background-color: #DDDDDD; padding: 6px 6px 6px 6px;
font-size: x-small">
<pre>
/**
* Returns blocks for this plugin that should appear when COM_showBlocks is run
*
* NOTE: this MUST return the label/value pairs in the following format
* $items[] = array('label1' => 'value', 'label2' => 'value')
* Basic available labels are..
* name Name of block (BLOCK_ID)
* type Must always be set 'dynamic' unless you use advanced API labels
* Advanced API means you set all fields that COM_showBlocks
* expects to see from the blocks table. All labels are column names
* title Title of block
* blockorder Block order number
* content Body of the block (the html output)
* help Optional url to a help page
*
* You must only return left or right blocks based on $side and
* you must also do your own security checks. Everything you send
* will show up on a page load
*
*
*
*/
function plugin_getBlocks_glcommerce($side, $topic='' )
{
global $_CONF, $_USER, $HTTP_SERVER_VARS, $REQUEST_URI, $sess, $db;
// only show on a page in the plugin's dir
If (in_string('glcommerce', $REQUEST_URI))
{
// generate left blocks
if ($side=='left')
{

$display1 = glc_makemenu();
$display2 = glc_latestprod();

$items[] = array('name' => 'glcommerce_1',
'type' => 'dynamic',
'onleft' => 1,
'title' => 'Shop Menu',
'blockorder' => 1,
'content' => $display1,
'help' => '/glcommerce/help.html');

$items[] = array('name' => 'glcommerce_2',
'type' => 'dynamic',
'onleft' => 1,
'title' => 'Latest Products ',
'blockorder' => 1,
'content' => $display2,
'help' => '/glcommerce/help.html');

} else {
// else generate right blocks
$display3 = glc_featuredprod()'
$display4 = glc_minicart();

$items[] = array('name' => 'glcommerce_3',
'type' => 'dynamic',
'onleft' => 0,
'title' => 'Featured Stuff',
'blockorder' => 1,
'content' => $display3,
'help' => '/glcommerce/help.html');

$items[] = array('name' => 'glcommerce_4',
'type' => 'dynamic',
'onleft' => 0,
'title' => 'My Cart',
'blockorder' => 1,
'content' => $display4,
'help' => '/glcommerce/help.html');

}

}
return $items;
}
</pre>
</div>

=== Function PLG_getBlocks() for reference ===

<div style="white-space:pre; border: solid; border-color: black;
border-width: 1; background-color: #DDDDDD; padding: 6px 6px 6px 6px;
font-size: x-small">
<pre>
/**
* gets Geeklog blocks from plugin's
*
* Returns data for blocks on a given side and, potentially, for
* a given topic.
*
* @param string $side Side to get blocks for (right or left for now)
* @param string $topic Only get blocks for this topic
* @return array of block data
*
*/
function PLG_getBlocks( $side, $topic='')
{
global $_PLUGINS;

$ret = array();
foreach ($_PLUGINS as $pi_name)
{
$function = 'plugin_getBlocks_' . $pi_name;
if (function_exists($function))
{
$items = $function($side, $topic='');
if (is_array ($items))
{
$ret = array_merge ($ret, $items);
}
}
}

// future code to do a lib-custom function
/*
if (function_exists('CUSTOM_getBlocks')) {
$cust_items .= CUSTOM_getBlocks($side, $topic='');
if (is_array ($cust_items)) {
$ret = array_merge ($ret, $cust_items)
}
}
*/
return $ret;
}
</pre>
</div>

[[Geeklog Documentation|Main Table of Contents]]<br/>
[[Complete Table of Contents]]

[[Category:Development]] [[Category:Plugin Development]] [[Category:Blocks]]

Multilingual Support

2009-12-15T16:19:09Z

LWC: /* Blocks */ Stressed what's disabled

== Background ==

The Geeklog language files have been translated into more than 25 languages - but that only means that you can have the user interface in one of those languages. For the actual site content (articles, static pages, ...), there was no support for multiple languages, which means that you either had to have everything in one language only or you ended up with all the different language versions of, e.g. an article, being displayed to anyone.

Euan McKay then came up with a [http://heatherengineering.com/staticpages/index.php/multilingual-en first multilingual hack], which was later [http://www.geeklog.net/forum/viewtopic.php?showtopic=61999 built upon and generalized] by LWC.

The multilingual support in Geeklog (as of version 1.4.1) is based on this earlier work by Euan and LWC.

== How it works ==

The basic idea behind the multilingual support is to encode the language of an object into its ID. For example, for a story to encode it into the story ID, like so:

<pre>http://www.example.com/article.php/introduction_en -- English version
http://www.example.com/article.php/introduction_de -- German version</pre>

Now there is a way to identify the language of an object (article, topic, static page, ...) and it can be displayed (or not), based on the user's language preferences. It's also possible then to switch between the various languages in which an object exists in the database.

== Setting it up ==

=== Geeklog 1.4.1 ===

In config.php, there is a new section to enable multilingual support and to define the list of supported languages:

<pre>// Multilingual support
// (note that this section is commented out - remove the '/*' and '*/' lines
// below to activate it and make sure you understand what it does)
/*

// IMPORTANT!
// 1) Both the $_CONF['language_files'] and the $_CONF['languages'] arrays
// (see below) must have the same number of elements.
// 2) The shortcuts used must be the same in both arrays.
// 3) All shortcuts must have the same length, e.g. 2 characters.

// The shortcuts are to be used in IDs of objects that are multilingual
// aware, e.g. /article.php/introduction_en and /article.php/introduction_de
// for the English and German version of an introductory article.

// Supported languages
// Maps a shortcut to a Geeklog language file (without the '.php' extension)
$_CONF['language_files'] = array (
'en' => 'english',
'de' => 'german_formal'
);

// Display names of supported languages
// Maps the same shortcuts as above to a language name. The language names
// are used to let users switch languages, e.g. in a drop-down menu.
$_CONF['languages'] = array (
'en' => 'English',
'de' => 'Deutsch'
);

*/</pre>

To enable multilingual support, the two arrays $_CONF['language_files'] and $_CONF['languages'] have to be defined. In the default config.php, they are commented out and, therefore, not defined.

=== Geeklog 1.5.0 and later ===

As of Geeklog 1.5.0, the <tt>config.php</tt> file has been replaced with a web-based configuration that can be found under "Configuration" in the Admin's block. Under the "Languages and Locale" heading, you'll find two options:
* Language Files
* Languages
These two options are the equivalents of the <code>$_CONF['language_files']</code> and <code>$_CONF['languages']</code> arrays, as explained above. To use the multilingual feature, '''both''' of these options have to be enabled. Other than that, the two options work as described above.

Note that in Geeklog 1.5.0, you can not easily disable multilingual support again (for a workaround, see [http://www.geeklog.net/forum/viewtopic.php?showtopic=83327 here]). As of Geeklog 1.5.1, there is a litte <tt>(X)</tt> next to the options (once they're enabled). Click on the <tt>(X)</tt> to disable the options again (remember that you need to disable both of them).

=== The shortcuts ===

For each of the languages you intend to support, you will have to define a shortcut that will then be used in the IDs of the multilingual objects, as explained above.

You can freely define these shortcuts, but it would make sense to set them in some relation to the language which they represent. From Geeklog's point of view, though, it doesn't matter whether the English language is represented by a shortcut 'en' or by 'peter'.

Please note:
* All the shortcuts in both of the arrays have to be of the same length.
* The shortcut must be appended to the ''end'' of an object's ID and it must be preceded by an underscore '_' character.
* It's recommended that you use a language's ISO abbreviation ('en' for English, 'de' for German, etc.), either with or without the country appendix ('en-US'), as Geeklog will also try to determine a user's preferred language from their browser setting.

=== The language files ===

The $_CONF['language_files'] array defines which language files should represent which language. Note that Geeklog also uses the language file name for a user's language setting (in their preferences).

It's recommended that you remove all the other language files, i.e. those for which you do not intend to have content in that particular language on your site.

'''Note:''' Be careful when mixing languages that use different character sets (e.g. Russian and Japanese). You may want to switch to the UTF-8 versions of ''all'' language files for such a setup.

=== The language names ===

The $_CONF['languages'] array defines a set of display names for the supported languages. These names are used to let the user switch between the supported languages, e.g. from a drop-down menu.

Most of the time, you'll want to use the native names of the languages, e.g. "Deutsch" instead of "German", but that's only a convention.

== Blocks ==

Multilingual blocks are only supported as of Geeklog 1.5.1. The setup differs slightly from the setup for stories, topics, etc.

Let's assume you want to create a multilingual "about this site" block and that your site is configured for two languages (say, English and German). For this setup you would then need ''three''(!) blocks. The block name serves as the ID and you would create blocks with the following names:
* about_en (disabled)
* about_de (disabled)
* about
The first two blocks would simply contain your content in English and German, respectively. Both blocks should be ''disabled''. The third block then serves as a placeholder for the actual block for the current language. Therefore, only this block ("about", in our example) should be enabled. When the multilingual support is enabled, you will never see the contents of that block, as it will be replaced with the proper block for the current language, e.g. "about_en" for English.

== Switching languages ==

Registered users can always switch their preferred language by selecting another language in their preferences.

To make things more convenient (and also allow anonymous users to switch the language), you can put a PHP block on your site. Geeklog provides a function phpblock_switch_language that will display a drop-down menu of all available languages (if you only have two languages defined, it will display a simple link to the other language instead).

This function can also be called from the header.thtml template file of your theme, so that you can put it into your site's menu:
<pre><?php print phpblock_switch_language(); ?></pre>

Technically, switching the language will set a cookie (with the selected language) and also update a user's language preference, if they're registered with the site.

== Detecting the language ==

When a user comes to a multilingual enabled site, Geeklog will check for the user's preference setting first (if it's a registered user), then for the language cookie, and if that couldn't be found, it tries to get the language from the browser's 'Accept-Language' header (which only works if you chose to use the ISO shortcuts, as explained above). If all else fails, content will be presented in the site's default language, i.e. $_CONF['language'].

== Supporting multiple languages ==

Developers of plugins and other add-ons don't have to do much to support multiple languages. Mainly, the objects under your plugin's control will have to have an editable, non-numerical ID (like Geeklog's stories have), so that the language shortcut can be appended to the ID.

If you have a list of objects under your plugin's control and only want to show the objects in the current language, you can use the COM_getLangSQL() function when building your SQL request. It will provide the part of an SQL request to only return the objects in the current language (see the function's description in lib-common.php for details).

COM_getLangSQL() will return an empty string when multilingual support is disabled, so you don't need to check for that yourself.

Most of the time, that should be all that you need to know about supporting multiple languages in a plugin. In some scenarios, the following functions may also come in handy:
* COM_getLanguageId returns the shortcut of the current user's language
* COM_getLanguage returns the full name of the current user's language, i.e. the name of the Geeklog language file (without the .php extension)

== Switching locale settings ==

Switching the language will often also require different formatting of the date, time, and other locale settings. For this, you can define alternative settings for each language in your site's config.php.

For example, the default date formatting in Geeklog's config.php is
<pre>$_CONF['date'] = '%A, %B %d %Y @ %I:%M %p %Z';</pre>
which, amongst other things, includes a time format using am/pm. If your site switches between, say, English and German, then your typical German visitor will expect the time to use a 24-hour format, e.g.
<pre>$_CONF['date'] = '%A, %d. %B %Y, %R Uhr';</pre>

If you're using the ISO abbreviation 'de' for German, then you could have the following in your site's config.php:
<pre>$_CONF['date'] = '%A, %B %d %Y @ %I:%M %p %Z';
$_CONF['date_de'] = '%A, %d. %B %Y, %R Uhr';</pre>
With these two lines, Geeklog would use the 'date_de' formatting when displaying content in German, and the 'date' formatting for all the other languages.

Actually, for this to work properly, you will also have to set <code>$_CONF['locale']</code> and <code>$_CONF['locale_de']</code> accordingly, since some of the date formatting (localized day and month names) requires the correct locale to be set:
<pre>$_CONF['locale'] = 'en_GB';
$_CONF['locale_de'] = 'de_DE';</pre>

You can switch all of the following [http://www.geeklog.net/docs/english/config.html#languages_locale locale settings] as described above:
* <code>$_CONF['locale']</code>
* <code>$_CONF['date']</code>
* <code>$_CONF['daytime']</code>
* <code>$_CONF['shortdate']</code>
* <code>$_CONF['dateonly']</code>
* <code>$_CONF['timeonly']</code>
* <code>$_CONF['week_start']</code>
* <code>$_CONF['hour_mode']</code>
* <code>$_CONF['thousand_separator']</code>
* <code>$_CONF['decimal_separator']</code>

'''Note:''' In Geeklog 1.5.0 and later, you will have to add the language-specific entries ($_CONF['date_de'], etc.) to the <tt>siteconfig.php</tt> file. The settings for the default language can be found in the Configuration admin panel:

: Configuration > Geeklog > Languages and Locale

== Notes and ideas ==

* To make things nicer for the user, the language could be hidden from the ID when editing objects. Instead, the user could be presented with a drop-down menu of the available languages. The shortcut could then be silently added to the ID when the object is saved.
* [[SoC improve multilingual feature|More ideas]]

Timezone Support

2009-11-02T09:23:14Z

LWC: /* Prerequisites */ Used template

By default, Geeklog uses the timezone that is configured for your webserver. To change the timezone for your website, you need to enable timezone support in the Configuration. Go to

: Configuration > Geeklog > Languages and Locale > Locale

and enable the "Timezone" option. It will display a dropdown of the available timezones (in Geeklog versions prior to 1.6.1, you'll see a text entry field, i.e. you have to type in the timezone to use).

== Prerequisites ==

For timezone support to work, one of the following requirements must be met, i.e. you need either

* PHP 5.1.0 (or later) ''or''
* an Apache webserver and PHP with "safe_mode" turned off

The latter option is known as the {{forum|21232|Timezone Hack}} and has been integrated into Geeklog since version 1.3.10. Geeklog 1.6.1 added the former option (requirement for PHP 5.1.0), which usually works more smoothly.

== User Timezone ==

As of Geeklog 1.6.1, users can change their timezone, if the timezone support has been enabled for the site. Go to

: My Account > Layout & Language > Misc Settings

and select your preferred timezone from the dropdown.

Note: This dropdown has been present in earlier Geeklog versions but wasn't used.

=== Timezone Cookie ===

Selecting a timezone for the account will also set a timezone cookie. Please note that this cookie is also used when you are not logged into the site. The same is true for the theme cookie, so that you can see the site with your preferred theme and timezone, even when you are not logged in.

Template:Forum

2009-11-02T09:22:27Z

LWC: Improved description

<includeonly>'''{{{2}}}''' ([http://www.geeklog.net/forum/viewtopic.php?showtopic={{{1}}} forum link])</includeonly><noinclude>Supply forum parameters and get a link.

==Usage==
<pre><nowiki>{{forum|forumID|Title}}</nowiki></pre>

For example, <nowiki>{{forum|9778|Test}}</nowiki> would display as:

{{forum|9778|Test}}
</noinclude>

Template:Forum

2009-11-02T09:21:31Z

LWC: Added title

<includeonly>'''{{{2}}}''' ([http://www.geeklog.net/forum/viewtopic.php?showtopic={{{1}}} forum link])</includeonly><noinclude>Supply an forum ID from the main site and get a link for it.

==Usage==
<pre><nowiki>{{forum|forumID|Title}}</nowiki></pre>

For example, <nowiki>{{forum|9778|Test}}</nowiki> would display as:

{{forum|9778|Test}}
</noinclude>

Language Tips And Tricks

2009-10-31T00:33:42Z

LWC: /* How to convert your complete Geeklog to Unicode/UTF-8 in 11 steps. */ Fixed English

== General Things ==

When you switch to another language in Geeklog, not only the menu text changes, but also the character set might change. This means that certain international characters might not be readable anymore. So if your site has German, Japanese or eastern European content, switching the language might turn your complete content unreadable.

== Multilingual Sites ==

If you plan to run a site where the content will be [[Multilingual Support|in several languages]], it is better to stick to languages that support UTF-8. Since they all use the same code, you will be able to display German Umlaut next to Japanese Characters for example. Otherwise, readers will always see unreadable characters next to readables, and will have to switch languages in order to read everything. Read below how to convert your favorite language to UTF-8.

Further, to support proper search and other functions, you should enable --with-mb_string functions in your PHP. In Linux, this might mean that you have to recompile linux! If you do this remember also to set your php.ini to have "mbstring.func_overload = 7". This makes php use multibyte-functions by default whenever a single-byte function is called.

== Unwanted Languages ==

You can remove unwanted languages by simply deleting the unwanted files from the <tt>/language/</tt> directory. Or you might want to create a subfolder there and move the unwanted files into it. Like this you can avoid that users choose Languages with character sets that will turn content unreadable.

== How to convert Language file Character Sets ==

First check in the download section of geeklog.net if nobody already converted the language file after the last release of Geeklog!

If you have Windows & MS Word, there is a very easy way to convert your language files to UTF-8 or other formats: Simply open the language-file with Word (rename it .doc and double-click for example). Then you will be asked what Character set the Source has. Choose the one that allows you to read the characters properly in the preview. Then save the file again as "Text Only"-Format. You will be asked again what Character Set you want to use. Choose your preferred ("Unicode UTF-8" for example). Make sure you also correct the line 32 of the file so that it represents the format you want:

<pre>$LANG_CHARSET = "utf-8";</pre>

Then, rename the file to "language_utf-8.php".

If you have done so, you might want to publish the file also on the geeklog.net website.

== How to convert your complete Geeklog to Unicode/UTF-8 in 11 steps. ==

If you started your server with one language, and want to move to a multilingual system later on, it can be quite difficult if you need different character sets for the different languages. With UTF-8 you can display all languages and letters at the same time in the same page without any problems. The best solution therefore would be to convert your ''complete'' data into Unicode in one go. You don't want to go through each story and comment and edit letters by hand after you switched the encoding of the page.

For this procedure to work you need (1) a text editor like notepad that can save raw text data while choosing the encoding (Notepad unter windows for example), (2) direct access to you MySQL executable (Windows cmd or Linux Shell) and (3) a NON-Unicode-Capable Editor (!) such as PHPEdit (or linux shell editors AFAIK). You can find out which editor cannot handle Unicode by saving a small text containing a "xxöxx" or similar with notepad as UTF-8 (See step 3) and opening it with the other editor. If you the letter "ö" appears now as "Ã¶" you have the right one.

Now let's start.

# Make a Backup of your database using the Geeklog Backup function.
# Download the created file from your server, zip it, burn it on a CD and send it to your lawyer. He should keep it as a backup in case you need it later to go back to step one.
# Open the file in Notepad/unicode-able editor (Notepad.exe). If your database is large, this will take some time, but its worth waiting for. Save the file again under a different (!) filename. Before you press the save-button, you have a field called "Encoding" below the field where you entered the filename. Choose "UTF-8".
# Now open the file in the non-Unicode-capable editor. You will see three strange letters "ï»¿" in the beginning of the file. Remove them. They cause error messages in the SQL later. Save the file again.
# Upload the file to your server. You might want to zip it first (also before downloading) to reduce transfer time.
# Create a new database if you can. If not delete all tables from your old one (call your lawyer to have your backup ready in an envelope).
# Write the data back into the database. Do this by typing <pre>mysql --user=root --password databasename file.txt</pre> replace "databasename" with the name of the newly created or empty database, and file.txt with the name of the file that you saved with notepad. The file has to be in the same directory as you are, if not move the file there. In Windows, it has to be in the /Mysql/bin-directory, where your MySQL.exe resides. If you do not want to move the files, prepend the path to the mysql.exe and/or the filename path.<br>If you do not have root access to the database, exchange "root" with the username that you use to access your MySQL server.
# Hit enter. You will be prompted for the user's password. Enter it, and press return again. Now the database will be parsed back into the server.
# If you created a second database, edit your Geeklog's config.php so that it accesses the new one.
# Switch your Geeklog language to one of the _UTF-8 sets. If you want to reduce hassle with your users that have been using non-UTF-8 languages, convert all the language-files you have to UTF-8 with notepad (You don't need to remove the first three letter there) and change the encoding string in each file (Line 30) to <pre>$LANG_CHARSET = "utf-8";</pre>
# Change config.php so that the standard language file will be one of the UTF-8 sets also (somehwere line 239), <pre>$_CONF['language'] = "english_utf-8";</pre>
# You might want to delete all non-UTF-8 languages from your language folders.

That's all. Good luck <tt>:-)</tt>

== Switching back to one language (1.3.9sr1 and before) ==

If you set your config.php so that you use only one language, you might run into trouble if you have users that already registered and selected another language. These users will continue to use their pre-set language. Even if you set their language manually to the standard or NULL (with a tool such as [http://www.phpmyadmin.net/ phpMyAdmin]), the cookies on the user's computers will still call up the old one.

== Links and Further Reading ==

* [http://lists.geeklog.net/mailman/listinfo/geeklog-translations geeklog-translations mailing list]
* [[Multilingual Support]] (as of Geeklog 1.4.1)

Building a View

2009-10-31T00:33:00Z

LWC: /* Why Flexy? */ Fixed English

== Building a View ==

Views are the visual components shown to your users. They often display information from one or more models. It is important to note that your views are to contain no business logic. It just displays a page to a user. The Geeklog 2 Framework has consciously chose to use [http://pear.php.net/package/HTML_Template_Flexy Flexy] for a variety of reasons but know now that you can very quickly retrofit any of what you see to use any other templating engine (such as [http://smarty.php.net/ Smarty]).

== Why Flexy? ==

One of the more annoying questions I get from PHP developers is why Flexy? Why Flexy? Why Flexy? First, keep in mind the Geeklog 2 Framework has been around in various forms since 2003 and back then one of the more annoying things about other template engines out there is their blatant desire to allow rendering of HTML and JavaScript by default. Flexy, rightfully so, hates these things and will always escape them unless you explicitly tell it to allow them. After that, Flexy is full of the sorts of features you'd like to see from a modern PHP template eninge. Things like compiling of templates, support for control structures (IF's, FOR loops, etc), object-oriented design and out-of-the-box multilingual support via [http://pear.php.net/package/Translation2 PEAR::Translation2].

Are there other good alternatives out there? Absolutely, and let me remind you that just because the Geeklog 2 Framework uses Flexy that doesn't mean you couldn't retrofit your projects to use another engine. That's the beauty of object-oriented code.

== Your First View ==

OK, enough talk...let's see an MVCnPHP view first hand. Every view is comprised of two parts. The first part is the MVCnPHP view which is responsible for pulling all data needed to be displayed on the page. The second part is the Flexy template. Let's first build the Flexy template by creating a page called Home.thtml. Note that Geeklog 2 Coding Standards require that all HTML templates use the .thtml extension.

<code><pre>
<html>
<head>
<title>{pageTitle}</title>
</head>
<body>
<p>
This is a page created using the Geeklog 2 Framework. You are viewing this page on {getDateTime()}.
</p>
</body>
</html>
</pre></code>

As you would expect from a PHP template engine, the template file itself is mostly HTML. The template above excercises a couple tasks such as showing data in a variable and calling a method. Those familir with other template engines might notice the variable and method call noted by {} above. In the TITLE tag, there is the pageTitle variable and in the body there is a method call to getDateTime(). Where does that variable and method exist? On the MVCnPHP view!

<code><pre>
/**
* MVCnPHP Abstract BaseView object
*/
require 'Geeklog/MVCnPHP/BaseView.php';

/**
* PEAR::HTML_Template_Flexy
*/
require 'Flexy.php';

class SAMPLE_HomeView extend MVCnPHP_BaseView {
/**
* Handle to instance of a flexy object
*
* @access protected
* @var object
*/
protected $flexyHandle = null;

/**
* Page title
* @var string
* @access protected
*/
protected $pageTitle = null;

/**
* Constructor
*
* @access public
*/
public function __construct()
{
$this->pageTitle = 'Your first MVCnPHP View';
$this->initializeFlexy();
}

/**
* Instantiates Flexy
*
* @access protected
*
*/
protected function initializeFlexy()
{
$options = array(
'templateDir' => '/path/to/templates',
'compileDir' => '/path/to/templates/compiled_templates',
'forceCompile' => 0,
'debug' => 0,
'locale' => 'en'
);

$this->flexyHandle = new FARMS_HTML_Template_Flexy($options);
}

/**
* Gets current date and time
*
* @access public
* @return string Current date and time
*
*/
public function getDateTime()
{
return strftime('%D %T');
}

/**
* Shows the page.
*
* @access public
*/
public function getView() {

$this->setPageTitle('Your first MVCnPHP View');
$this->flexyHandle->compile('Home.thtml');
$this->flexyHandle->outputObject($this);
}
}
</pre></code>

So how does all the above work? Let's run down the notable bits of code. First of all, if you go back and look at the Flexy template we created, we had a variable called pageTitle. It is no mistake that on our MVCnPHP view we have a public class member called pageTitle. Similarly, the Flexy template had a call to a method getDateTime() which can be seen above as a public method on our MVCnPHP view. The magic to all this is in the getView() method:

<code><pre>
$this->flexyHandle->compile('Home.thtml');
$this->flexyHandle->outputObject($this);
</pre></code>

The first line above compiles our Flexy template Home.thtml into executable PHP code. It's worth noting that Flexy is smart enough to only compile the template if the template hasn't be compiled yet or if the template itself has changed since the last compile. This works exactly like JSP's in the Java world.

The outputObject() call tell Flexy to now run the compiled template and that it should use our MVCnPHP view ($this) as the class that holds all the data and methods needed to render the page.

Now you may be wondering how the getView() method even gets called. That is done by the MVCnPHP Controller and it knows how to call our view based on it's [[MVCnPHPConfig|configuration file]].

== Note on Namespacing ==

PHP5 has no notion of namespaces. Thus if you have a class called User and you are trying to integrate your code with third party code that also has a class called User then you will be in trouble because of the name conflict. Your only option is ensure the class names are entirely different. The Geeklog 2 Framework, uses the [http://pear.php.net PEAR] approach to solving this by qualifying each class name with a prefix. That prefix is typically the package name you'd like to give the class had you had namespace support. If you agree this is all messy, feel free to follow the history of attempts made at getting namespace support in PHP5 [http://phpnamespaces.org/wiki/ here]. In the meantime, if you notice class names with prefixs like SAMPLE_ or GEEKLOG_ or MVCnPHP_ you know why.

ConfigFile14

2009-10-31T00:31:55Z

LWC: Fixed link

<h1>GeekLog Configuration File</h1>
<h2>Setting up config.php</h2>
<p>The Geeklog Configuration file (along with the languages file) is the place to make changes to system-wide settings such as the name of the site, user settings, and more.<br>
<br>
Tip: Make changes to a copy of your file so you can always revert back to a configuration file that you know works.<br>
<br>
Tip: Until you are familiar with what is going on, make a single change then upload it to see what happened. Once you get the hang of it you can make more substantial edits at a time.<br>
</p>
<p>Most of Geeklog's "static" settings (i.e. those that you aren't
going to change often) are set in a text file called <tt>config.php</tt>. It is
necessary to edit this file to get your system running as well as configuring it
to your preferences. This file contains a set of variables as defined below:</p>
<ul>
<li><a href="http://www.geeklog.net/docs/config.html#database">Database
Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#server">Server Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#site">Site Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#locale">Locale Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#session">Session Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#cookie">Cookie Names</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#desc_mail_settings">E-Mail
Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#login">Login Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#submission">Submission
Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#trackback">Trackback,
Pingback, and Ping Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#misc">Topic, What's New,
and Daily Digest Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#story">Story Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#comment">Comment Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#image">Image Settings</a>
<ul>
<li><a href="http://www.geeklog.net/docs/config.html#userphoto">User photo</a></li>
</ul>
</li>
<li><a href="http://www.geeklog.net/docs/config.html#rdf">Syndication Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#content">Content Control
Settings</a></li>
<li><a href="http://www.geeklog.net/docs/config.html#url-rewrite">URL
Rewriting</a></li>
</ul>
<h3><a name="database">Database Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top">_DB_dbms</td>
<td valign="top">mysql</td>
<td valign="top">This option tells Geeklog which type of database it's
running on. Can be either <code>'mysql'</code> (for MySQL) or <code>'mssql'</code>
(for Microsoft SQL Server).</td>
</tr>
<tr>
<td valign="top">_DB_host</td>
<td valign="top">localhost</td>
<td valign="top">Database Server (to be entered in the form: <i>hostname:port:unixsocket</i>).
In most cases you won't need to change the default value.</td>
</tr>
<tr>
<td valign="top">_DB_name</td>
<td valign="top">geeklog</td>
<td valign="top">Database Name</td>
</tr>
<tr>
<td valign="top">_DB_user</td>
<td valign="top">root</td>
<td valign="top">Database User Account</td>
</tr>
<tr>
<td valign="top">_DB_pass</td>
<td valign="top">null</td>
<td valign="top">Database User Password</td>
</tr>
<tr>
<td valign="top">_DB_table_prefix</td>
<td valign="top">gl_</td>
<td valign="top">Prefix to put in front of all of Geeklog's table names
(to avoid name collisions with tables used by other applications)</td>
</tr>
<tr>
<td valign="top">_DB_mysqldump_path</td>
<td valign="top">/usr/bin/mysqldump</td>
<td valign="top">Complete path to the <a href="http://www.mysql.com/doc/en/mysqldump.html">mysqldump</a>
utility (part of MySQL) for making backups of your Geeklog database.<br>
<i>(only used when running on a MySQL database)</i></td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_mysqldump">allow_mysqldump</a></td>
<td valign="top">1</td>
<td valign="top">Enable or disable the backup functionality (1 = on, 0 =
off).<br>
<i>(only used when running on a MySQL database)</i></td>
</tr>
<tr>
<td valign="top"><a name="desc_mysqldump_options">mysqldump_options</a></td>
<td valign="top">-Q</td>
<td valign="top">Here you can include additional options for the <a href="http://www.mysql.com/doc/en/mysqldump.html">mysqldump</a>
call that Geeklog uses to create a backup from your database.<br>
<i>(only used when running on a MySQL database)</i></td>
</tr>
</tbody>
</table>
<h3><a name="server">Server Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_path">path</a></td>
<td valign="top">/path/to/geeklog/</td>
<td valign="top">Base file system path for your site (trailing slash
necessary)</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_system">path_system</a></td>
<td valign="top">/path/to/geeklog/system/</td>
<td valign="top">Path to your system directory for your site (trailing
slash necessary). This directory holds the code libraries used
throughout Geeklog</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_html">path_html</a></td>
<td valign="top">/path/to/geeklog/public_html/</td>
<td valign="top">Path to your web tree directory for your site (trailing
slash necessary). This directory holds all the web pages used by
Geeklog.</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_images">path_images</a></td>
<td valign="top">/path/to/geeklog/public_html/images/</td>
<td valign="top">Path where Geeklog expects to find its images, including
user photos and images for stories.</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_log">path_log</a></td>
<td valign="top">/path/to/geeklog/logs/</td>
<td valign="top">File system path for the log files</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_language">path_language</a></td>
<td valign="top">/path/to/geeklog/language/</td>
<td valign="top">location of the Geeklog language files</td>
</tr>
<tr>
<td valign="top"><a name="desc_backup_path">backup_path</a></td>
<td valign="top">/path/to/geeklog/backups/</td>
<td valign="top">location where mysqldump (see above) will store database
backups</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_data">path_data</a></td>
<td valign="top">/path/to/geeklog/data/</td>
<td valign="top">File system path for the data directory, used e.g. for
the user batch add feature</td>
</tr>
<tr>
<td valign="top"><a name="desc_have_pear">have_pear</a></td>
<td valign="top"><code>false</code></td>
<td valign="top">Whether you have <a href="http://pear.php.net/">PEAR</a>
installed on your server (<code>= true</code>) or not (<code>= false</code>).
When set to <code>false</code>, Geeklog will use the PEAR packages
installed in <code>$_CONF['path_pear']</code> (see below)</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_pear">path_pear</a></td>
<td valign="top"><tt>/path/to/geeklog/system/pear/</tt></td>
<td valign="top">When <code>$_CONF['have_pear']</code> (see above) is set
to <code>false</code>, this is the path where Geeklog expects to find
the <a href="http://pear.php.net/">PEAR</a> packages it requires (e.g.
PEAR::Mail for sending emails).</td>
</tr>
</tbody>
</table>
<h3><a name="site">Site Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_site_name">site_name</a></td>
<td valign="top">GeekLog Site</td>
<td valign="top">Name of your site</td>
</tr>
<tr>
<td valign="top"><a name="desc_site_slogan">site_slogan</a></td>
<td valign="top">Another Nifty GeekLog Site</td>
<td valign="top">Slogan for your site. This is added to the HTML title
field.</td>
</tr>
<tr>
<td valign="top"><a name="desc_site_mail">site_mail</a></td>
<td valign="top">admin@example.com</td>
<td valign="top">E-mail address for all admin mail</td>
</tr>
<tr>
<td valign="top"><a name="desc_site_url">site_url</a></td>
<td valign="top">http://www.example.com</td>
<td valign="top">Base URL for your site (no trailing slash)</td>
</tr>
<tr>
<td valign="top"><a name="desc_site_admin_url">site_admin_url</a></td>
<td valign="top">http://www.example.com/admin</td>
<td valign="top">Base URL of the admin area of your site (no trailing
slash). You won't have to change this normally, but some hosting
services use a predefined "admin" directory for other
purposes. In this case, you can rename Geeklog's <tt>admin</tt>
directory and adjust the URL accordingly to avoid conflicts.</td>
</tr>
<tr>
<td valign="top"><a name="desc_theme">theme</a></td>
<td valign="top">professional</td>
<td valign="top">Default theme to use on the site</td>
</tr>
<tr>
<td valign="top"><a name="desc_layout_url">layout_url</a></td>
<td valign="top">Site URL path, with layout dir and default layout</td>
<td valign="top">Location of the default layout</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_themes">path_themes</a></td>
<td valign="top">/path/to/geeklog/public_html/layout/</td>
<td valign="top">Directory where all themes reside</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_layout">path_layout</a></td>
<td valign="top">/path/to/geeklog/public_html/layout/professional/</td>
<td valign="top">Path to current theme directory</td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_user_themes">allow_user_themes</a></td>
<td valign="top">Can be 1 or 0</td>
<td valign="top">If set to 1, users can set their own theme that the site
uses</td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_user_language">allow_user_language</a></td>
<td valign="top">Can be 1 or 0</td>
<td valign="top">If set to 1, users can select the language for the site
navigation</td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_user_photo">allow_user_photo</a></td>
<td valign="top">Can be 1 or 0</td>
<td valign="top">If set to 1, users can upload a photo to their profile</td>
</tr>
<tr>
<td valign="top"><a name="desc_hide_author_exclusion">hide_author_exclusion</a></td>
<td valign="top">Can be 1 or 0</td>
<td valign="top">If set to 1, the option to to exclude certain authors
from being seen is hidden from the user's preferences.</td>
</tr>
<tr>
<td valign="top"><a name="desc_show_fullname">show_fullname</a></td>
<td valign="top">0</td>
<td valign="top">Whether to display a user's full name (= 1) or only their
username (= 0). For users that haven't entered their full name, Geeklog
will always display the username.</td>
</tr>
<tr>
<td valign="top"><a name="desc_remoteauthentication">remoteauthentication</a></td>
<td valign="top">false</td>
<td valign="top">Allow (when set to <tt>true</tt>) users who already have
an account with some other service to log into your Geeklog site with
the login for that service. Currently supported: Blogger and LiveJournal.<br>
Please note that to enable login for a specific service, you need an
authorization class in <tt>system/classes/authentication</tt>. If you
only want to allow Blogger but not LiveJournal users (or vice versa),
simply remove the class file for the unwanted service(s).</td>
</tr>
<tr>
<td valign="top"><a name="desc_show_servicename">show_servicename</a></td>
<td valign="top">true</td>
<td valign="top">If you allow users to log in with accounts on remote
services (like Blogger or LiveJournal), this option will at the
service's name to the username to avoid confusion with local users of
the same name. Set to <tt>false</tt> to disable.</td>
</tr>
<tr>
<td valign="top"><a name="desc_site_enabled">site_enabled</a></td>
<td valign="top">true</td>
<td valign="top">A Geeklog site can be disabled quickly (e.g. for
maintenance) by setting this to 'false'.</td>
</tr>
<tr>
<td valign="top"><a name="desc_site_disabled_msg">site_disabled_msg</a></td>
<td valign="top">'Geeklog Site is down. Please come back soon.'</td>
<td valign="top">This contains the message to display when a Geeklog site
is disabled. If the text begins with "http:" then visitors are
redirected to that URL.</td>
</tr>
<tr>
<td valign="top"><a name="desc_sort_admin">sort_admin</a></td>
<td valign="top">false</td>
<td valign="top">If set to <tt>true</tt> will sort the entries in the
Admin's block and the icons on the Submissions page (<tt>moderation.php</tt>)
alphabetically.</td>
</tr>
<tr>
<td valign="top"><a name="desc_link_documentation">link_documentation</a></td>
<td valign="top">1</td>
<td valign="top">Add a link to Geeklog's documentation to the Admin block.
Set this to 0 if you don't want that link to show up.</td>
</tr>
<tr>
<td valign="top"><a name="desc_menu_elements">menu_elements</a></td>
<td valign="top"><code>array('contribute', 'calendar', 'search', 'stats',
'directory', 'plugins')</code></td>
<td valign="top">Specifies which entries are displayed in the site's menu
bar (if your theme uses the <code>{menu_elements}</code> variable to
display the menu bar). Can be any combination of <tt>'home'</tt>, <tt>'contribute'</tt>,
<tt>'calendar'</tt>, <tt>'search'</tt>, <tt>'directory'</tt>, <tt>'prefs'</tt>,
<tt>'plugins'</tt>, and <tt>'custom'</tt> where <tt>'plugins'</tt> is
the same as the <code>{plg_menu_elements}</code> variable, i.e. a list
of the menu entries provided by plugins, and <tt>'custom'</tt> displays
the entries returned by a custom function <code>CUSTOM_menuEntries</code>
(see <tt>lib-custom.php</tt> for details).</td>
</tr>
<tr>
<td valign="top"><a name="desc_custom_registration">custom_registration</a></td>
<td valign="top"><code>false</code></td>
<td valign="top">When set to <code>true</code>, Geeklog will let you use
your own signup form for new user registrations. Please see the file <tt>lib-custom.php</tt>
that ships with Geeklog for an example.</td>
</tr>
<tr>
<td valign="top"><a name="desc_spamx">spamx</a></td>
<td valign="top">128</td>
<td valign="top">Tells Geeklog's <a href="http://www.geeklog.net/docs/spamx.html" rel="nofollow">Spam-X</a>
plugin what to do when a spam post has been detected. The value is the
sum of all values that uniquely identify the Spam-X modules that should
be executed. E.g. the "delete" action module uses 128, the
"email admin" module uses 8, so if both modules should be
executed, this option should be set to 128 + 8 = 136.</td>
</tr>
<tr>
<td valign="top"><a name="desc_rootdebug">rootdebug</a></td>
<td valign="top"><code>false</code></td>
<td valign="top">When a PHP error occurs, Geeklog's error handler will
only display the actual error message to members of the Root group (to
prevent leakage of possibly sensitive information). When set to <code>true</code>,
this information will be displayed to <em>all</em> users. <strong>Use
only for debugging purposes!</strong></td>
</tr>
<tr>
<td valign="top"><a name="desc_lastlogin">lastlogin</a></td>
<td valign="top"><code>true</code></td>
<td valign="top">Whether to keep track of when a user last logged in (<code>=
true</code>) or not (<code>= false</code>).</td>
</tr>
<tr>
<td valign="top"><a name="desc_cron_schedule_interval">cron_schedule_interval</a></td>
<td valign="top">86400</td>
<td valign="top">Geeklog can emulate a <a href="http://en.wikipedia.org/wiki/Cronjob">cronjob</a>,
i.e. trigger a certain action at a given time. The code to be executed
can be provided by a plugin or through the <code>CUSTOM_runScheduledTask</code>
function in your <tt>lib-custom.php</tt>. The value given is in seconds
and specifies the interval in which the code should be executed.<br>
Please note that to trigger this action, you will need to have someone
visit your site at around the specified time. On a site with few
visitors, the code may only be executed with considerable delay.<br>
Set to 0 to disable.</td>
</tr>
</tbody>
</table>
<h3><a name="locale">Locale Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_language">language</a></td>
<td valign="top">english</td>
<td valign="top">Name of your language file. Additional language files may
be available for download at <a href="http://www.geeklog.net/">http://www.geeklog.net</a>.
If you translate a language file, please send it to us. Also see <a href="http://www.geeklog.net/docs/config.html#Localization">Localization</a>
below.</td>
</tr>
<tr>
<td valign="top"><a name="desc_locale">locale</a></td>
<td valign="top">en_GB</td>
<td valign="top"><a href="http://en.wikipedia.org/wiki/Locale">Locale</a>
for the system. This defines both the language and the country that PHP
will use when deciding how to display localized information such as
dates (e.g. for the names of months).</td>
</tr>
<tr>
<td valign="top"><a name="desc_date">date</a></td>
<td valign="top">%A, %B %d %Y @ %I:%M %p %Z</td>
<td valign="top">Date format used for most of the site, including story
displays. See <a href="http://www.geeklog.net/docs/config.html#date_formats">date
formats</a> below.</td>
</tr>
<tr>
<td valign="top"><a name="desc_daytime">daytime</a></td>
<td valign="top">%m/%d %I:%M%p</td>
<td valign="top">Date format used when a shorter date is needed. See <a href="http://www.geeklog.net/docs/config.html#date_formats">date
formats</a> below.</td>
</tr>
<tr>
<td valign="top"><a name="desc_shortdate">shortdate</a></td>
<td valign="top">%x</td>
<td valign="top">Date format this is the shortest date. See <a href="http://www.geeklog.net/docs/config.html#date_formats">date
formats</a> below.</td>
</tr>
<tr>
<td valign="top"><a name="desc_dateonly">dateonly</a></td>
<td valign="top">%d-%b</td>
<td valign="top">Short date format (day and month only), to be used e.g.
in the Upcoming Events and Older Stories blocks. See <a href="http://www.geeklog.net/docs/config.html#date_formats">date
formats</a> below.</td>
</tr>
<tr>
<td valign="top"><a name="desc_timeonly">timeonly</a></td>
<td valign="top">%I:%M %p %Z</td>
<td valign="top">Format string for the time only, to be used e.g. on the
Event Details page. See <a href="http://www.geeklog.net/docs/config.html#date_formats">date
formats</a> below.</td>
</tr>
<tr>
<td valign="top"><a name="desc_week_start">week_start</a></td>
<td valign="top">Sun</td>
<td valign="top">First day of the week in the calendar. Can be either <tt>'Sun'</tt>
(Sunday) or <tt>'Mon'</tt> (Monday).</td>
</tr>
<tr>
<td valign="top"><a name="desc_hour_mode">hour_mode</a></td>
<td valign="top">12</td>
<td valign="top">Which format to use when submitting or editing an object
with a time setting (e.g. the publish time of a story). Can be 12 (for
the 12 hour am/pm format) or 24 (for the 24 hour format).</td>
</tr>
<tr>
<td valign="top"><a name="desc_default_charset">default_charset</a></td>
<td valign="top">iso-8859-1</td>
<td valign="top">Character encoding used by Geeklog when serving HTML
pages or sending email. Only used if the language file did not already
set another character encoding.<br>
For <a href="http://wiki.geeklog.net/wiki/index.php/Multilingual_Support">multilingualism</a>
setups, using <code>'utf-8'</code> as the default character set is
recommended.</td>
</tr>
<tr>
<td valign="top"><a name="desc_thousand_separator">thousand_separator</a></td>
<td valign="top"><code>,</code></td>
<td valign="top">Character to use between every group of thousands.</td>
</tr>
<tr>
<td valign="top"><a name="desc_decimal_separator">decimal_separator</a></td>
<td valign="top"><code>.</code></td>
<td valign="top">Character to use before decimals.</td>
</tr>
<tr>
<td valign="top"><a name="desc_decimal_count">decimal_count</a></td>
<td valign="top">2</td>
<td valign="top">How many decimal places to display.</td>
</tr>
<tr>
<td valign="top"><a name="desc_timezone">timezone</a></td>
<td valign="top"><i>(commented out)</i></td>
<td valign="top">If your server is located in a different timezone, use
this option to set your local (i.e. your own) timezone, so that the time
and date on the site match your own.<br>
This option is known as the "<a href="http://www.geeklog.net/forum/viewtopic.php?showtopic=21232">timezone
hack</a>" and may not work on some servers.</td>
</tr>
</tbody>
</table>
<h3><a name="session">Session Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_cookie_ip">cookie_ip</a></td>
<td valign="top">0</td>
<td valign="top">Session ID to contain IP address of user as well as
random number. This is more secure but will more than likely require
dialed up users to login each and every time. (0=no, 1=yes)</td>
</tr>
<tr>
<td valign="top"><a name="desc_default_perm_cookie_timeout">default_perm_cookie_timeout</a></td>
<td valign="top">28800</td>
<td valign="top">Permanent cookie timeout in seconds (28800 = 8 hours).</td>
</tr>
<tr>
<td valign="top"><a name="desc_session_cookie_timeout">session_cookie_timeout</a></td>
<td valign="top">7200</td>
<td valign="top">Session cookie timeout (in seconds).</td>
</tr>
<tr>
<td valign="top"><a name="desc_cookie_path">cookie_path</a></td>
<td valign="top">/</td>
<td valign="top">Cookie path (see the <a href="http://www.php.net/manual/en/function.setcookie.php">PHP
manual</a> for details).</td>
</tr>
<tr>
<td valign="top"><a name="desc_cookiedomain">cookiedomain</a></td>
<td valign="top"><i>(empty)</i></td>
<td valign="top">The domain that the cookie is available. Geeklog will
attempt to guess the correct value for this setting (based on the 'site_url'
variable). See the <a href="http://www.php.net/manual/en/function.setcookie.php">PHP
manual</a> for details.</td>
</tr>
<tr>
<td valign="top"><a name="desc_cookiesecure">cookiesecure</a></td>
<td valign="top">0</td>
<td valign="top">Only set to 1 if your site uses HTTPS (see the <a href="http://www.php.net/manual/en/function.setcookie.php">PHP
manual</a> for details).</td>
</tr>
</tbody>
</table>
<h3><a name="cookie">Cookie Names</a></h3>
<p>These variables define the names of all of Geeklog's cookies. They can easily
be changed in case there's a name collision with the cookies used by some other
software package that you may use on your site.</p>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_cookie_session">cookie_session</a></td>
<td valign="top">gl_session</td>
<td valign="top">Name of the cookie that stores the session ID.</td>
</tr>
<tr>
<td valign="top"><a name="desc_cookie_name">cookie_name</a></td>
<td valign="top">geeklog</td>
<td valign="top">Name of the permanent cookie.</td>
</tr>
<tr>
<td valign="top"><a name="desc_cookie_password">cookie_password</a></td>
<td valign="top">password</td>
<td valign="top">Name of the password cookie.</td>
</tr>
<tr>
<td valign="top"><a name="desc_cookie_theme">cookie_theme</a></td>
<td valign="top">theme</td>
<td valign="top">Name of the theme cookie.</td>
</tr>
<tr>
<td valign="top"><a name="desc_cookie_language">cookie_language</a></td>
<td valign="top">language</td>
<td valign="top">Name of the language cookie.</td>
</tr>
</tbody>
</table>
<h3><a name="desc_mail_settings">E-Mail Settings</a><a name="email"></a></h3>
<p>Starting with Geeklog 1.3.9, Geeklog uses the PEAR::Mail class to send all
emails. You can then select whether emails should be sent through SMTP, sendmail,
or PHP's <code>mail()</code> function.</p>
<p>Within <code>$_CONF['mail_settings']</code> you have the following options:</p>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_backend">backend</a></td>
<td valign="top">mail</td>
<td valign="top">Used to select how to send email. Can be one of 'smtp', 'sendmail',
or 'mail'.</td>
</tr>
<tr>
<td valign="top"><a name="desc_sendmail_path">sendmail_path</a></td>
<td valign="top"><tt>/usr/bin/sendmail</tt></td>
<td valign="top">If you chose 'sendmail' for the backend setting, this
specifies the complete path to the sendmail binary.</td>
</tr>
<tr>
<td valign="top"><a name="desc_sendmail_args">sendmail_args</a></td>
<td valign="top"><tt>''</tt> <i>(empty)</i></td>
<td valign="top">If you chose 'sendmail' for the backend setting, this
variable can be used to pass additional parameters to the sendmail
binary.</td>
</tr>
<tr>
<td valign="top"><a name="desc_host">host</a></td>
<td valign="top">smtp.example.com</td>
<td valign="top">If you chose 'smtp' for the backend setting, this is the
SMTP server to use.</td>
</tr>
<tr>
<td valign="top"><a name="desc_port">port</a></td>
<td valign="top">25</td>
<td valign="top">If you chose 'smtp' for the backend setting, this is the
port number to talk to on the SMTP server.</td>
</tr>
<tr>
<td valign="top"><a name="desc_auth">auth</a></td>
<td valign="top">false</td>
<td valign="top">If you chose 'smtp' for the backend setting, set this to <code>true</code>
if your SMTP server requires authorization, and <code>false</code> if it
doesn't.</td>
</tr>
<tr>
<td valign="top"><a name="desc_username">username</a></td>
<td valign="top">smtp-username</td>
<td valign="top">If you chose 'smtp' for the backend setting, this is the
name of your SMTP account.</td>
</tr>
<tr>
<td valign="top"><a name="desc_password">password</a></td>
<td valign="top">smtp-password</td>
<td valign="top">If you chose 'smtp' for the backend setting, this is the
password for your SMTP account.</td>
</tr>
</tbody>
</table>
<h3><a name="login">Login Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_loginrequired">loginrequired</a></td>
<td valign="top">0</td>
<td valign="top">Login is required to access <em>any</em> part of the
site. When set to 1, this overrides the following settings. When you
only want to block access to certain parts of the site, set this to 0
and select from the following settings.</td>
</tr>
<tr>
<td valign="top"><a name="desc_submitloginrequired">submitloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can submit stories
and items handled by plugins, e.g. links and events</td>
</tr>
<tr>
<td valign="top"><a name="desc_commentsloginrequired">commentsloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can submit comments</td>
</tr>
<tr>
<td valign="top"><a name="desc_calendarloginrequired">calendarloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can access the
calendar</td>
</tr>
<tr>
<td valign="top"><a name="desc_statsloginrequired">statsloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can access the site
stats</td>
</tr>
<tr>
<td valign="top"><a name="desc_searchloginrequired">searchloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can use the advanced
search. When set to 2, the simple search is blocked for anonymous users,
too.</td>
</tr>
<tr>
<td valign="top"><a name="desc_profileloginrequired">profileloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can view another
user's profile</td>
</tr>
<tr>
<td valign="top"><a name="desc_emailuserloginrequired">emailuserloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can use the email
submission form to send an email to another user</td>
</tr>
<tr>
<td valign="top"><a name="desc_emailstoryloginrequired">emailstoryloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can email stories</td>
</tr>
<tr>
<td valign="top"><a name="desc_directoryloginrequired">directoryloginrequired</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, only registered users can access the list
of past articles</td>
</tr>
</tbody>
</table>
<h3><a name="submission">Submission Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_storysubmission">storysubmission</a></td>
<td valign="top">1</td>
<td valign="top">Enable (1) or disable (0) the story submission queue</td>
</tr>
<tr>
<td valign="top"><a name="desc_usersubmission">usersubmission</a></td>
<td valign="top">0</td>
<td valign="top">Enable (1) or disable (0) the user submission queue (i.e.
new users must be approved before they receive their password)</td>
</tr>
<tr>
<td valign="top"><a name="desc_disable_new_user_registration">disable_new_user_registration</a></td>
<td valign="top">false</td>
<td valign="top">When set to <tt>true</tt> completely disables all options
to sign up as a new user.</td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_domains">allow_domains</a></td>
<td valign="top">''</td>
<td valign="top">When the user submission queue is enabled this can
contain a comma-separated list of domain names from which user
submissions will not be queued (but approved automatically). Regular
expressions are also allowed and interpreted.<br>
<strong>Example:</strong> <tt>'mycompany.com,myothercompany.com'</tt></td>
</tr>
<tr>
<td valign="top"><a name="desc_disallow_domains">disallow_domains</a></td>
<td valign="top">''</td>
<td valign="top">This is the opposite of <code>$_CONF['allow_domains']</code>
(see above): A list of domain names that are <em>not</em> allowed in
email addresses of new users. Note that this list is <em>always</em>
used, even when the user submission queue has been switched off. Again,
regular expression can be used.<br>
<strong>Example</strong> disallow email addresses with a certain domain
name and from any ".edu" domain: <tt>'somebaddomain.com,\.edu$'</tt></td>
</tr>
<tr>
<td valign="top"><a name="desc_notification">notification</a></td>
<td valign="top">array()</td>
<td valign="top">Send an email notification to <tt>$_CONF['site_email']</tt>
when a new story, comment, trackback or pingback has been submitted or a
new user has registered with the site. The <tt>array()</tt> can hold any
combination of the strings <tt>'story'</tt>, <tt>'comment'</tt>, <tt>'trackback'</tt>,
<tt>'pingback'</tt>, and <tt>'user'</tt> (separated by commas),
depending on which notification(s) you want.<br>
<strong>Example:</strong> <code>array('story','user');</code> would send
notifications when a new story has been submitted or a new user has
registered. No notifications would be sent, for example, for new
comments.</td>
</tr>
<tr>
<td valign="top"><a name="desc_listdraftstories">listdraftstories</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, this will display an additional block on
the submissions page (<tt>moderation.php</tt>) that lists all the
stories that have the 'draft' flag set.</td>
</tr>
<tr>
<td valign="top"><a name="desc_postmode">postmode</a></td>
<td valign="top">plaintext</td>
<td valign="top">Sets the default submission mode to 'html' or 'plaintext'</td>
</tr>
<tr>
<td valign="top"><a name="desc_speedlimit">speedlimit</a></td>
<td valign="top">45</td>
<td valign="top">Minimum delay between submissions in seconds. This helps
prevent Denial of Service (DOS) attacks</td>
</tr>
<tr>
<td valign="top"><a name="desc_skip_preview">skip_preview</a></td>
<td valign="top">0</td>
<td valign="top">If 1, allows submission of stories and comments without
previewing (i.e. the submission form will always have a Preview <em>and</em>
a Submit button).</td>
</tr>
<tr>
<td valign="top"><a name="desc_advanced_editor">advanced_editor</a></td>
<td valign="top">false</td>
<td valign="top">Enable (if set to <code>true</code>) a WYSIWYG editor for
story and comment submissions and static pages. Geeklog ships with <a href="http://www.fckeditor.net/">FCKeditor</a>.</td>
</tr>
</tbody>
</table>
<h3><a name="trackback">Trackback, Pingback, and Ping Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_trackback_enabled">trackback_enabled</a></td>
<td valign="top">true</td>
<td valign="top">Enable (true) or disable (true) <a href="http://en.wikipedia.org/wiki/Trackback">trackback</a>
comments. This applies to both sending and receiving trackback comments.</td>
</tr>
<tr>
<td valign="top"><a name="desc_pingback_enabled">pingback_enabled</a></td>
<td valign="top">true</td>
<td valign="top">Enable (true) or disable (true) <a href="http://en.wikipedia.org/wiki/Pingback">pingback</a>
support. This applies to both sending and receiving pingbacks.</td>
</tr>
<tr>
<td valign="top"><a name="desc_ping_enabled">ping_enabled</a></td>
<td valign="top">true</td>
<td valign="top">Enable (true) or disable (true) the ability to ping
weblog directory services like <a href="http://technorati.com/">Technorati</a>.</td>
</tr>
<tr>
<td valign="top"><a name="desc_trackback_code">trackback_code</a></td>
<td valign="top">0</td>
<td valign="top">Default value for new stories: Trackback enabled (0) or
disabled (-1)</td>
</tr>
<tr>
<td valign="top"><a name="desc_multiple_trackbacks">multiple_trackbacks</a></td>
<td valign="top">0</td>
<td valign="top">How to handle multiple trackbacks and pingbacks from the
same source: 0 = keep only the first, reject any further trackbacks /
pingbacks; 1 = overwrite, i.e. only keep the latest trackback / pingback;
2 = allow multiple trackbacks / pingbacks, i.e. list them all</td>
</tr>
<tr>
<td valign="top"><a name="desc_trackbackspeedlimit">trackbackspeedlimit</a></td>
<td valign="top">300</td>
<td valign="top">Number of seconds between two trackbacks / pingbacks from
the same IP address.</td>
</tr>
<tr>
<td valign="top"><a name="desc_check_trackback_link">check_trackback_link</a></td>
<td valign="top">2</td>
<td valign="top">This option can be used to check the validity of a
trackback. You can check if the URL in the trackback actually contains a
link back to your site (otherwise, it's probably spam). You can also
check if the trackback was sent from the proper IP address, i.e. the IP
of the site in the trackback URL (again, if they don't match, it's
probably spam). Note that you can <strong>add up the values</strong>
below to do more than one check (but using option 1 <em>and</em> 2
doesn't make sense and will be treated as if you requested option 2).<br>
Options are: 0 = don't perform any checks, 1 = check only for your
site's main URL (<code>$_CONF['site_url']</code>), 2 = check for the
exact URL of the entry (e.g. an article) on your site, 4 = check IP
address of the sender of the trackback against the site referred to in
the trackback URL.<br>
<b>Example:</b> <code>$_CONF['check_trackback_link'] = 6; // check for
the exact URL (2) and proper IP address (4)</code></td>
</tr>
<tr>
<td valign="top"><a name="desc_pingback_self">pingback_self</a></td>
<td valign="top">0</td>
<td valign="top">Pingbacks are sent out automatically to <em>all</em> the
URLs linked from a story - which includes stories on your own site that
you may have linked in the article. This option lets you specify how
these "self pingbacks" are to be handled: 0 = skip them, i.e.
don't send pingbacks to stories on your own site; 1 = allow them, but
obey the speed limit; 2 = allow them and ignore the speed limit.<br>
If your article contains more than one link to other stories on your
site, then option 1 is probably of limited use, as it would only
pingback the first linked story and run into the speed limit for the
others.</td>
</tr>
</tbody>
</table>
<h3><a name="misc">Topic, What's New, and E-mail Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_sortmethod">sortmethod</a></td>
<td valign="top">sortnum</td>
<td valign="top">alpha = Sort topics in topic list alphabetically<br>
sortnum = Sort topics in topic list by sort number</td>
</tr>
<tr>
<td valign="top"><a name="desc_showstorycount">showstorycount</a></td>
<td valign="top">1</td>
<td valign="top">Show the number of stories in a topic in the Sections
block (0=no, 1=yes)</td>
</tr>
<tr>
<td valign="top"><a name="desc_showsubmissioncount">showsubmissioncount</a></td>
<td valign="top">1</td>
<td valign="top">Show the number of story submissions for a topic in the
Sections block (0=no, 1=yes)</td>
</tr>
<tr>
<td valign="top"><a name="desc_hide_home_link">hide_home_link</a></td>
<td valign="top">0</td>
<td valign="top">Hide the "Home" link from the Sections block
(0=no, 1=yes)</td>
</tr>
<tr>
<td valign="top"><a name="desc_whosonline_threshold">whosonline_threshold</a></td>
<td valign="top">300</td>
<td valign="top">How long, in seconds, users can be idle before removing
them from the whosonline block</td>
</tr>
<tr>
<td valign="top"><a name="desc_whosonline_anonymous">whosonline_anonymous</a></td>
<td valign="top">0</td>
<td valign="top">If enabled (i.e. set to 1), anonymous users will only see
the number of registered users currently online in the Who's Online
block but not their names. Only logged-in users will see the names of
other users that are currently online.</td>
</tr>
<tr>
<td valign="top"><a name="desc_emailstories">emailstories</a></td>
<td valign="top">0</td>
<td valign="top">Let users get stories e-mailed to them (0=no, 1=yes), aka
Daily Digest. Please note that this requires cron and the use of PHP as
a shell script.</td>
</tr>
<tr>
<td valign="top"><a name="desc_emailstorieslength">emailstorieslength</a></td>
<td valign="top">1</td>
<td valign="top">When emailstories (above) is enabled, send only the title
and the link to the new stories (0), or send the entire introtext (1) or
send the first <i>n</i> characters from the introtext (where <i>n</i> =
any other number)</td>
</tr>
<tr>
<td valign="top"><a name="desc_emailstoriesperdefault">emailstoriesperdefault</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, new users will be subscribed to the daily
digest automatically when they register with the site.</td>
</tr>
<tr>
<td valign="top"><a name="desc_newstoriesinterval">newstoriesinterval</a></td>
<td valign="top">86400</td>
<td valign="top">Stories are "new" if they are this many seconds
old.</td>
</tr>
<tr>
<td valign="top"><a name="desc_newcommentsinterval">newcommentsinterval</a></td>
<td valign="top">172800</td>
<td valign="top">Comments are "new" if they are this many
seconds old.</td>
</tr>
<tr>
<td valign="top"><a name="desc_newtrackbackinterval">newtrackbackinterval</a></td>
<td valign="top">172800</td>
<td valign="top">Trackback comments are "new" if they are this
many seconds old.</td>
</tr>
<tr>
<td valign="top"><a name="desc_hidenewstories">hidenewstories</a></td>
<td valign="top">0</td>
<td valign="top">Set to 1 to hide new stories from the What's New block.</td>
</tr>
<tr>
<td valign="top"><a name="desc_hidenewcomments">hidenewcomments</a></td>
<td valign="top">0</td>
<td valign="top">Set to 1 to hide new comments from the What's New block.</td>
</tr>
<tr>
<td valign="top"><a name="desc_hidenewtrackbacks">hidenewtrackbacks</a></td>
<td valign="top">0</td>
<td valign="top">Set to 1 to hide new trackback comments from the What's
New block.</td>
</tr>
<tr>
<td valign="top"><a name="desc_hidenewplugins">hidenewplugins</a></td>
<td valign="top">0</td>
<td valign="top">Set to 1 to hide new entries by plugins from the What's
New block.</td>
</tr>
<tr>
<td valign="top"><a name="desc_title_trim_length">title_trim_length</a></td>
<td valign="top">20</td>
<td valign="top">Max. length of the title of items listed in the What's
New block.</td>
</tr>
<tr>
<td valign="top"><a name="desc_copyrightyear">copyrightyear</a></td>
<td valign="top"><i>(commented out)</i></td>
<td valign="top">Set this to the year you want to appear in the copyright
notice of your site's footer. If not set, Geeklog will use the current
year.</td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_username_change">allow_username_change</a></td>
<td valign="top">0</td>
<td valign="top">If set to 1, users will be allowed to change their
username (login name). Stories and comments posted under the old
username will automatically show the new username.</td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_account_delete">allow_account_delete</a></td>
<td valign="top">0</td>
<td valign="top">If set to 1, users will be allowed to delete their
accounts. Stories and comments posted under that account will be kept
and show up as being posted by "Anonymous".</td>
</tr>
<tr>
<td valign="top"><a name="desc_passwordspeedlimit">passwordspeedlimit</a></td>
<td valign="top">300</td>
<td valign="top">Minimum delay between two requests for a new password, in
seconds.</td>
</tr>
<tr>
<td valign="top"><a name="desc_login_attempts">login_attempts</a></td>
<td valign="top">3</td>
<td valign="top">Max. number of login attempts before the speedlimit (see
below) kicks in and further logins are blocked for the given amount of
time.</td>
</tr>
<tr>
<td valign="top"><a name="desc_login_speedlimit">login_speedlimit</a></td>
<td valign="top">300</td>
<td valign="top">How many seconds have to pass before another login
attempt can be made after <code>$_CONF['login_attempts']</code> (see
above) login attempts have failed.</td>
</tr>
<tr>
<td valign="top"><a name="desc_ip_lookup">ip_lookup</a></td>
<td valign="top"><i>not set</i></td>
<td valign="top">The IP addresses of comment posters are logged and
displayed for admin users. When this variable is set to point to a
service that can do IP address lookups, it's possible to lookup the
owner of an IP address by clicking on it, making it easier to report
abuse to ISPs, etc.<br>
<code>$_CONF['ip_lookup']</code> should hold the complete URL to the
lookup service, with a '<code>*</code>' marking the place where the IP
address should go. It's also possible to use Tom Willet's <a href="http://sourceforge.net/project/showfiles.php?group_id=68255&package_id=95743">NetTools</a>
package, in which case the correct setting would be <code>$_CONF['ip_lookup']
= $_CONF['site_url'] . '/nettools/whois.php?domain=*';</code></td>
</tr>
<tr>
<td valign="top"><a name="desc_num_search_results">num_search_results</a></td>
<td valign="top">10</td>
<td valign="top">Number of search results per page (and per type).</td>
</tr>
</tbody>
</table>
<h3><a name="story">Story Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_maximagesperarticle">maximagesperarticle</a></td>
<td valign="top">5</td>
<td valign="top">max. number of images you can have in a story</td>
</tr>
<tr>
<td valign="top"><a name="desc_limitnews">limitnews</a></td>
<td valign="top">10</td>
<td valign="top">Number of stories to limit the index page to, this same
number will appear in the older stuff block</td>
</tr>
<tr>
<td valign="top"><a name="desc_minnews">minnews</a></td>
<td valign="top">1</td>
<td valign="top">Minimum numbers of stories than can appear on a topic
page</td>
</tr>
<tr>
<td valign="top"><a name="desc_contributedbyline">contributedbyline</a></td>
<td valign="top">1</td>
<td valign="top">Show author username to public, and enable search by
username (0=no, 1=yes)</td>
</tr>
<tr>
<td valign="top"><a name="desc_hideviewscount">hideviewscount</a></td>
<td valign="top">0</td>
<td valign="top">Whether to show (= 0) or to hide (= 1) the number of
views a story has had.</td>
</tr>
<tr>
<td valign="top"><a name="desc_article_image_align">article_image_align</a></td>
<td valign="top">right</td>
<td valign="top">Which side of article the topic image should be shown
(right or left)</td>
</tr>
<tr>
<td valign="top"><a name="desc_show_topic_icon">show_topic_icon</a></td>
<td valign="top">1</td>
<td valign="top">Default setting for new stories and story submissions:
Whether to show the topic icon (1) or not (0).</td>
</tr>
<tr>
<td valign="top"><a name="desc_draft_flag">draft_flag</a></td>
<td valign="top">0</td>
<td valign="top">Default setting for new stories created by Story Admins:
Whether the story's draft flag should be set (1) or not (0).</td>
</tr>
<tr>
<td valign="top"><a name="desc_frontpage">frontpage</a></td>
<td valign="top">0</td>
<td valign="top">Default setting for new stories and story submissions:
Whether the story should appear on the site's frontpage (1) or only in
its topic's page (0). Please note that for stories submitted to the
archive topic, this setting will be ignored and the story will <em>not</em>
appear on the frontpage.</td>
</tr>
<tr>
<td valign="top"><a name="desc_onlyrootfeatures">onlyrootfeatures</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, this will only allow members of the Root
group to make a story "featured", i.e. the sticky top story on
the site.</td>
</tr>
<tr>
<td valign="top"><a name="desc_hideemailicon">hideemailicon</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, this will disable the ability to send a
story by email. It will also hide the email icon from stories and the
"Email Article To a Friend" from the Story Options block.</td>
</tr>
<tr>
<td valign="top"><a name="desc_hideprintericon">hideprintericon</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, this will disable display of a story in a
"printer friendly" format. It will also hide the printer icon
from stories and the "View Printable Version" from the Story
Options block.</td>
</tr>
<tr>
<td valign="top"><a name="desc_hide_no_news_msg">hide_no_news_msg</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, hide the "No News To Display"
message on the index page (e.g. when viewing a topic without any stories
in it)</td>
</tr>
<tr>
<td valign="top"><a name="desc_hide_main_page_navigation">hide_main_page_navigation</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, this option will hide the "Google
paging" navigation from index.php, i.e. from the site's frontpage
and all topic pages. This may come in handy for more advanced layouts
but will of course prevent people from easily reaching older articles.</td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_page_breaks">allow_page_breaks</a></td>
<td valign="top">1</td>
<td valign="top">Allow usage of the <code>[page_break]</code> tag in
stories (when set to 1), so that stories can spread over multiple pages.</td>
</tr>
<tr>
<td valign="top"><a name="desc_page_break_comments">page_break_comments</a></td>
<td valign="top">last</td>
<td valign="top">When the <code>[page_break]</code> tag is allowed in
stories (see above), where should the story's comments be displayed: <code>'last'</code>
= on the story's last page only, <code>'first'</code> = on the first
page only, <code>'all'</code> = on every page.</td>
</tr>
<tr>
<td valign="top"><a name="desc_show_right_blocks">show_right_blocks</a></td>
<td valign="top">false</td>
<td valign="top">If set to <tt>true</tt>, the right-side column of blocks
will be displayed on <em>all</em> pages (instead of only on the index
page).</td>
</tr>
<tr>
<td valign="top"><a name="desc_showfirstasfeatured">showfirstasfeatured</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, this will render the first story on <em>any</em>
page using the templates for a featured story, even if that story is not
featured. This will even be applied to the first story on page 2 of a
topic page, for example.</td>
</tr>
<tr>
<td valign="top"><a name="desc_showfirstasfeatured">onlyrootfeatures</a></td>
<td valign="top">0</td>
<td valign="top">This restricts the featuring of stories to root user(s).
If you have several story admins that can create content that is not
visible to other story admins, and such a content is featured, another
admin might think its ok to feature his own content. To prevent that two
admins unknowingly take features from each other away, only a user who
can see all content (= root) should be able to feature a story.</td>
</tr>
<tr>
<td valign="top"><a name="desc_left_blocks_in_footer">left_blocks_in_footer</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, this will make the <code>{left_blocks}</code>
variable available in <tt>footer.thtml</tt> (and disable it in <tt>header.thtml</tt>).
This is really only useful for two-column layouts where you want the
left column contain the stories and the right columni contain the
standard blocks.</td>
</tr>
</tbody>
</table>
<h3><a name="comment">Comment Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_commentspeedlimit">commentspeedlimit</a></td>
<td valign="top">45</td>
<td valign="top">Number of seconds between posting a comment for the user</td>
</tr>
<tr>
<td valign="top"><a name="desc_comment_limit">comment_limit</a></td>
<td valign="top">100</td>
<td valign="top">Most number of comments to show at any one time</td>
</tr>
<tr>
<td valign="top"><a name="desc_comment_mode">comment_mode</a></td>
<td valign="top">threaded</td>
<td valign="top">How to display comments (threaded, nested, flat or
nocomments)</td>
</tr>
<tr>
<td valign="top"><a name="desc_comment_code">comment_code</a></td>
<td valign="top">0</td>
<td valign="top">Default value for new stories: Comments enabled (0) or
disabled (-1)</td>
</tr>
</tbody>
</table>
<h3><a name="image">Image Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_image_lib">image_lib</a></td>
<td valign="top">'' <i>(empty string)</i></td>
<td valign="top">Set this to either 'imagemagick', 'netpbm', or 'gdlib' if
images should be resized during upload. Leave as '' if you don't want
images to be resized or if you don't have those packages available.</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_to_mogrify">path_to_mogrify</a></td>
<td valign="top"><i>(commented out)</i></td>
<td valign="top">If you chose 'imagemagick' for <code>$_CONF['image_lib']</code>
above, then this should hold the <strong>complete path</strong> to the
mogrify executable (from the ImageMagick package), e.g. '/usr/bin/mogrify'.<br>
You will need a fairly recent version of <a href="http://www.imagemagick.org/">ImageMagick</a>
for this to work (version 5.4.9 or newer is recommended).</td>
</tr>
<tr>
<td valign="top"><a name="desc_path_to_netpbm">path_to_netpbm</a></td>
<td valign="top"><i>(commented out)</i></td>
<td valign="top">If you chose 'netpbm' for <code>$_CONF['image_lib']</code>
above, then this should hold the complete path to the <em>directory</em>
where the binaries from the netpbm package are kept, e.g. <code>'/usr/bin/netpbm/'</code>.
Note that the path must end in a slash.<br>
Precompiled binaries of the netpbm package for various platforms can be
downloaded from the <a href="http://sourceforge.net/projects/gallery/">Homepage
of the Gallery project</a>.</td>
</tr>
<tr>
<td valign="top"><a name="desc_keep_unscaled_image">keep_unscaled_image</a></td>
<td valign="top">0</td>
<td valign="top">Set this to 1 if you want Geeklog to keep the original,
unscaled images after upload. The smaller image will then be used as a
thumbnail and will link to the original image. Note that this may use a
lot of disk space (depending on the size of your images).</td>
</tr>
<tr>
<td valign="top"><a name="desc_allow_user_scaling">allow_user_scaling</a></td>
<td valign="top">1</td>
<td valign="top">When unscaled images are kept (see above), this option
lets the user chose between using the scaled or unscaled image in the
story, i.e. enables the <code>[unscaled<i>X</i>]</code> image tag (in
addition to the <code>[image<i>X</i>]</code> tag).</td>
</tr>
<tr>
<td valign="top"><a name="desc_max_image_width">max_image_width</a></td>
<td valign="top">160</td>
<td valign="top">Max. width of an image in pixels. If it exceeds this, it
is either rejected or resized (depending on the setting of <code>$_CONF['image_lib']</code>
above).</td>
</tr>
<tr>
<td valign="top"><a name="desc_max_image_height">max_image_height</a></td>
<td valign="top">120</td>
<td valign="top">Max. height of an image in pixels. If it exceeds this, it
is either rejected or resized (depending on the setting of <code>$_CONF['image_lib']</code>
above).</td>
</tr>
<tr>
<td valign="top"><a name="desc_max_image_size">max_image_size</a></td>
<td valign="top">1048576 <i>(equals 1 MB)</i></td>
<td valign="top">Max. size of an image in bytes. If it exceeds this, it is
is rejected (even if you're using a graphics package to resize images).</td>
</tr>
<tr>
<td valign="top"><a name="desc_max_topicicon_width">max_topicicon_width</a></td>
<td valign="top">48</td>
<td valign="top">Max. width of a topic icon in pixels. If it exceeds this,
it is either rejected or resized (depending on the setting of <code>$_CONF['image_lib']</code>
above).</td>
</tr>
<tr>
<td valign="top"><a name="desc_max_topicicon_height">max_topicicon_height</a></td>
<td valign="top">48</td>
<td valign="top">Max. height of a topic icon in pixels. If it exceeds
this, it is either rejected or resized (depending on the setting of <code>$_CONF['image_lib']</code>
above).</td>
</tr>
<tr>
<td valign="top"><a name="desc_max_topicicon_size">max_topicicon_size</a></td>
<td valign="top">65536 <i>(equals 64 KB)</i></td>
<td valign="top">Max. size of a user photo in bytes. If it exceeds this,
it is rejected (even if you're using a graphics package to resize
images).</td>
</tr>
<tr>
<td valign="top"><a name="desc_debug_image_upload">debug_image_upload</a></td>
<td valign="top"><i>(commented out)</i></td>
<td valign="top">When not commented out(!) and set to <code>true</code>,
this option enables debugging output to be written into Geeklog's <tt>error.log</tt>
file during the upload of an image. This is useful to track down
problems with the image upload.</td>
</tr>
</tbody>
</table>
<h4><a name="userphoto">User photo</a></h4>
<p>Additional options for the user photo.</p>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_max_photo_width">max_photo_width</a></td>
<td valign="top">128</td>
<td valign="top">Max. width of a user photo in pixels. If it exceeds this,
it is either rejected or resized (depending on the setting of <code>$_CONF['image_lib']</code>
above).</td>
</tr>
<tr>
<td valign="top"><a name="desc_max_photo_height">max_photo_height</a></td>
<td valign="top">128</td>
<td valign="top">Max. height of a user photo in pixels. If it exceeds
this, it is either rejected or resized (depending on the setting of <code>$_CONF['image_lib']</code>
above).</td>
</tr>
<tr>
<td valign="top"><a name="desc_max_photo_size">max_photo_size</a></td>
<td valign="top">65536 <i>(equals 64 KB)</i></td>
<td valign="top">Max. size of a user photo in bytes. If it exceeds this,
it is rejected (even if you're using a graphics package to resize
images).</td>
</tr>
<tr>
<td valign="top"><a name="desc_use_gravatar">use_gravatar</a></td>
<td valign="top">false</td>
<td valign="top">If enabled (set to <tt>true</tt>), a user's avatar image
will be requested from <a href="http://gravatar.com/">gravatar.com</a>
if the user didn't upload a user photo (i.e. an uploaded photo always
takes priority).<br>
Please note that this option may slow down your site on pages that
display a lot of userphotos for different users (e.g. forum threads).</td>
</tr>
<tr>
<td valign="top"><a name="desc_gravatar_rating">gravatar_rating</a></td>
<td valign="top"><i>(commented out)</i></td>
<td valign="top">Avatars submitted to gravatar.com are <a href="http://gravatar.com/rating.php">rated</a>
with the rating system used for movies (in the U.S.), i.e. the letters
G, PG, R, or X. This option will let you chose the <em>maximum</em>
allowed rating for an avatar. For example, a max. rating of R will make
sure that no X-rated avatars will be displayed on your site (only G, PG,
and R).</td>
</tr>
<tr>
<td valign="top"><a name="desc_force_photo_width">force_photo_width</a></td>
<td valign="top"><i>(commented out)</i></td>
<td valign="top">This option, when enabled, will only apply when <em>displaying</em>
a user photo. The <code><img></code> tag for the user photo will
be emitted with a max. width, as specified by this option. This means
that the actual photo can still be larger, but will only be displayed
smaller. This is useful for cases where you don't want oddly shaped user
photos to break your page's layout (e.g. in a forum).</td>
</tr>
<tr>
<td valign="top"><a name="desc_default_photo">default_photo</a></td>
<td valign="top"><i>(commented out)</i></td>
<td valign="top">When enabled, this option should point to an image (full
URL required!) that should be displayed for users without a user photo.
When this option is not set and a user does not have a user photo (or an
avatar) then Geeklog will simply not display anything.</td>
</tr>
</tbody>
</table>
<h3><a name="rdf">Syndication Settings</a></h3>
<p>Geeklog can export its headlines to a news feed in various formats (RSS, RDF,
and Atom). This will let you share your news with other sites (Hint: Create a
Portal block from Geeklog's Block menu to import news feeds from other sites).</p>
<p>Starting with Geeklog 1.3.9, feeds can be created and configured from
Geeklog's Admin menu ("Content Syndication"). The following settings
will only be used as the <em>default settings</em> for any new feeds that you
create from the admin panel.</p>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_backend">backend</a></td>
<td valign="top">1</td>
<td valign="top">Create a feed file for the stories in rdf_file (0=no,
1=yes)</td>
</tr>
<tr>
<td valign="top"><a name="desc_rdf_file">rdf_file</a></td>
<td valign="top">HTML path with "/backend/geeklog.rss" suffix</td>
<td valign="top">File system path for the feed file. This file allows you
to share your site's headlines with others</td>
</tr>
<tr>
<td valign="top"><a name="desc_rdf_language">rdf_language</a></td>
<td valign="top">en-gb</td>
<td valign="top">Value for the feed's language tag. Depending on your
site's language and operating system, this may differ from the language
setting in the locale (see above).<br>
<strong>Example:</strong> The PHP locale setting for German is 'de_DE'
while the correct language setting for a German RSS feed would be
'de-DE' (note the dash instead of the underscore).</td>
</tr>
<tr>
<td valign="top"><a name="desc_rdf_limit">rdf_limit</a></td>
<td valign="top">10</td>
<td valign="top">Limit the number of stories to export to the news feed.
If the value for this setting is a number, the feed will hold this many
stories. If the number is followed by a lower-case 'h' (e.g. 24h) it
denotes the number of hours from which to chose the stories.</td>
</tr>
<tr>
<td valign="top"><a name="desc_rdf_storytext">rdf_storytext</a></td>
<td valign="top">0</td>
<td valign="top">If this value is 1, then the entire introtext of the
stories will be included in the news feed. Any number greater than 1
limits the introtext to that many characters (e.g. a value of 80 would
only include the first 80 characters from the introtext in the feed). If
set to 0, the introtext is not included in the feed.</td>
</tr>
<tr>
<td valign="top"><a name="desc_syndication_max_headlines">syndication_max_headlines</a></td>
<td valign="top">0</td>
<td valign="top">Upper limit for the max. number of headlines when <em>importing</em>
a feed (into a portal block). The limit can also be set for each
individual portal block in the block menu.<br>
When set to 0, all headlines are imported.</td>
</tr>
</tbody>
</table>
<h3><a name="content">Content Control Settings</a></h3>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_user_html">user_html</a></td>
<td valign="top"><p>, <b>, <i>, <a>, <em>,
<br>, <tt>, <hr>, <ol>, <ul>, <li>,
<code>, <pre></td>
<td valign="top">HTML tags and attributes that normal users are allowed to
use in story submissions and comments.</td>
</tr>
<tr>
<td valign="top"><a name="desc_admin_html">admin_html</a></td>
<td valign="top">additional HTML tags, e.g. for tables</td>
<td valign="top">HTML tags and attributes that admin users are allowed to
use (in addition to those from user_html). Redefining a tag with
additional attributes will overwrite the definition from user_html.</td>
</tr>
<tr>
<td valign="top"><a name="desc_allowed_protocols">allowed_protocols</a></td>
<td valign="top">array ('http', 'https', 'ftp');</td>
<td valign="top">Defines which protocols are allowed in links (i.e. HTML <code><a></code>
tags).</td>
</tr>
<tr>
<td valign="top"><a name="desc_skip_html_filter_for_root">skip_html_filter_for_root</a></td>
<td valign="top">0</td>
<td valign="top">When set to 1, this will allow members of the Root group
to use <em>all</em> HTML in their posts. <strong>Use at your own risk!</strong></td>
</tr>
<tr>
<td valign="top"><a name="desc_disable_autolinks">disable_autolinks</a></td>
<td valign="top">0</td>
<td valign="top">If set to 1, disables the autolinks. I.e. links using the
[story:] etc. syntax are not interpreted any more.</td>
</tr>
<tr>
<td valign="top"><a name="desc_censormode">censormode</a></td>
<td valign="top">1</td>
<td valign="top">Censor submissions and comments (0=no, 1=yes)</td>
</tr>
<tr>
<td valign="top"><a name="desc_censorreplace">censorreplace</a></td>
<td valign="top">*censored*</td>
<td valign="top">Text to replace a censored word with</td>
</tr>
<tr>
<td valign="top"><a name="desc_censorlist">censorlist</a></td>
<td valign="top">array(<i>a list of "bad" words goes here ...</i>)</td>
<td valign="top">An array of censored words</td>
</tr>
</tbody>
</table>
<h3><a name="url-rewrite">URL Rewriting</a></h3>
<p>Geeklog includes a simple but useful URL rewriting feature which can help
make your site more crawler friendly (i.e. the URLs of your site are more likely
to be picked up by the search engine's indexing bots). This feature is supported
for URLs to stories, static pages, the article directory, and links.</p>
<p>URL rewriting means that your URLs will look like this</p>
<p align="center"><tt>http://www.geeklog.net/article.php/20021022234959146</tt></p>
<p>instead of like this</p>
<p align="center"><tt>http://www.geeklog.net/article.php?story=20021022234959146</tt></p>
<p>While some search engines will pick up the second form, Google seems to
prefer the first format and completely ignores the second format.</p>
<p><strong>Note:</strong> This feature may not work with all web servers. It is
known to work with Apache (all versions) and known <em>not</em> to work with IIS
(at least some versions). Please try it out before you go public with your site.</p>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_url_rewrite">url_rewrite</a></td>
<td valign="top">false</td>
<td valign="top">Enable (true) or disable (false) URL rewriting.</td>
</tr>
</tbody>
</table>
<h3><a name="unused">Unused Settings</a></h3>
<p>This is a list of <tt>config.php</tt> options that are currently unused, e.g.
because the feature they were intended for has not been implemented yet.</p>
<table border="1" width="100%">
<tbody>
<tr>
<th width="8%">Variable</th>
<th width="29%">Default Value</th>
<th width="63%">Description</th>
</tr>
<tr>
<td valign="top"><a name="desc_ostype">ostype</a></td>
<td valign="top"><code>PHP_OS</code></td>
<td valign="top">Identifies the operating system running on your webserver.</td>
</tr>
<tr>
<td valign="top"><a name="desc_pdf_enabled">pdf_enabled</a></td>
<td valign="top">0</td>
<td valign="top">PDF conversion of stories has not been fully implemented
yet. Leave this option as is to prevent unfinished options from showing
up on your site.</td>
</tr>
</tbody>
</table>
<h2><a name="Localization">Localization</a></h2>
<p>Localizing GeekLog is fairly easy. All strings are contained in a language
file. The default file that ships with the tarball is english.php. People
interested in translating Geeklog to other languages are encouraged to join the <a href="http://lists.geeklog.net/listinfo/geeklog-translations">geeklog-translations</a>
mailing list. All important information concerning translating Geeklog will be
posted there.</p>
<h3><a name="date_formats">Locale and Date Formats</a></h3>
<p>You can set the locale and date format in the config.php file. To set the
locale, set the variable to the proper string or if you leave it blank it will
pull the default locale from the operating system. The date formats are handled
by your locale. Isn't that smart? Locale names are OS dependent. On most UNIX
hosts, you can find locale codes in the <i>/usr/share/locale/locale.alias</i>
file and on some systems the command <i>locale -a</i> will display all available
locales on a system. If a locale doesn't exist you can create it using the <i>localedef</i>
command.</p>
<p>More info on locale: <a href="http://www.opengroup.org/onlinepubs/7908799/xbd/locale.html">http://www.opengroup.org/onlinepubs/7908799/xbd/locale.html</a><br>
More info on localdef: <a href="http://www.opengroup.org/onlinepubs/7908799/xcu/localedef.html">http://www.opengroup.org/onlinepubs/7908799/xcu/localedef.html</a></p>
<h3>Date Format Syntax</h3>
<ul>
<li><tt>%a - abbreviated weekday name according to the current locale</tt></li>
<li><tt>%A - full weekday name according to the current locale</tt></li>
<li><tt>%b - abbreviated month name according to the current locale</tt></li>
<li><tt>%B - full month name according to the current locale</tt></li>
<li><tt>%c - preferred date and time representation for the current locale</tt></li>
<li><tt>%C - century number (the year divided by 100 and truncated to an
integer, range 00 to 99)</tt></li>
<li><tt>%d - day of the month as a decimal number (range 00 to 31)</tt></li>
<li><tt>%D - same as %m/%d/%y</tt></li>
<li><tt>%e - day of the month as a decimal number, a single digit is preceded
by a space (range ' 1' to '31')</tt></li>
<li><tt>%h - same as %b</tt></li>
<li><tt>%H - hour as a decimal number using a 24-hour clock (range 00 to 23)</tt></li>
<li><tt>%I - hour as a decimal number using a 12-hour clock (range 01 to 12)</tt></li>
<li><tt>%j - day of the year as a decimal number (range 001 to 366)</tt></li>
<li><tt>%m - month as a decimal number (range 1 to 12)</tt></li>
<li><tt>%M - minute as a decimal number</tt></li>
<li><tt>%n - newline character</tt></li>
<li><tt>%p - either `am' or `pm' according to the given time value, or the
corresponding strings for the current locale</tt></li>
<li><tt>%r - time in a.m. and p.m. notation</tt></li>
<li><tt>%R - time in 24 hour notation</tt></li>
<li><tt>%S - second as a decimal number</tt></li>
<li><tt>%t - tab character</tt></li>
<li><tt>%T - current time, equal to %H:%M:%S</tt></li>
<li><tt>%u - weekday as a decimal number [1,7], with 1 representing Monday</tt></li>
<li><tt>%U - week number of the current year as a decimal number, starting
with the first Sunday as the first day of the first week</tt></li>
<li><tt>%V - The ISO 8601:1988 week number of the current year as a decimal
number, range 01 to 53, where week 1 is the first week that has at least 4
days in the current year, and with Monday as the first day of the week.</tt></li>
<li><tt>%W - week number of the current year as a decimal number, starting
with the first Monday as the first day of the first week</tt></li>
<li><tt>%w - day of the week as a decimal, Sunday being 0</tt></li>
<li><tt>%x - preferred date representation for the current locale without the
time</tt></li>
<li><tt>%X - preferred time representation for the current locale without the
date</tt></li>
<li><tt>%y - year as a decimal number without a century (range 00 to 99)</tt></li>
<li><tt>%Y - year as a decimal number including the century</tt></li>
<li><tt>%Z - time zone or name or abbreviation</tt></li>
<li><tt>%% - a literal `%' character</tt></li>
</ul>

Multilingual Support

2009-10-31T00:28:40Z

LWC: Fixed English

== Background ==

The Geeklog language files have been translated into more than 25 languages - but that only means that you can have the user interface in one of those languages. For the actual site content (articles, static pages, ...), there was no support for multiple languages, which means that you either had to have everything in one language only or you ended up with all the different language versions of, e.g. an article, being displayed to anyone.

Euan McKay then came up with a [http://heatherengineering.com/staticpages/index.php/multilingual-en first multilingual hack], which was later [http://www.geeklog.net/forum/viewtopic.php?showtopic=61999 built upon and generalized] by LWC.

The multilingual support in Geeklog (as of version 1.4.1) is based on this earlier work by Euan and LWC.

== How it works ==

The basic idea behind the multilingual support is to encode the language of an object into its ID. For example, for a story to encode it into the story ID, like so:

<pre>http://www.example.com/article.php/introduction_en -- English version
http://www.example.com/article.php/introduction_de -- German version</pre>

Now there is a way to identify the language of an object (article, topic, static page, ...) and it can be displayed (or not), based on the user's language preferences. It's also possible then to switch between the various languages in which an object exists in the database.

== Setting it up ==

=== Geeklog 1.4.1 ===

In config.php, there is a new section to enable multilingual support and to define the list of supported languages:

<pre>// Multilingual support
// (note that this section is commented out - remove the '/*' and '*/' lines
// below to activate it and make sure you understand what it does)
/*

// IMPORTANT!
// 1) Both the $_CONF['language_files'] and the $_CONF['languages'] arrays
// (see below) must have the same number of elements.
// 2) The shortcuts used must be the same in both arrays.
// 3) All shortcuts must have the same length, e.g. 2 characters.

// The shortcuts are to be used in IDs of objects that are multilingual
// aware, e.g. /article.php/introduction_en and /article.php/introduction_de
// for the English and German version of an introductory article.

// Supported languages
// Maps a shortcut to a Geeklog language file (without the '.php' extension)
$_CONF['language_files'] = array (
'en' => 'english',
'de' => 'german_formal'
);

// Display names of supported languages
// Maps the same shortcuts as above to a language name. The language names
// are used to let users switch languages, e.g. in a drop-down menu.
$_CONF['languages'] = array (
'en' => 'English',
'de' => 'Deutsch'
);

*/</pre>

To enable multilingual support, the two arrays $_CONF['language_files'] and $_CONF['languages'] have to be defined. In the default config.php, they are commented out and, therefore, not defined.

=== Geeklog 1.5.0 and later ===

As of Geeklog 1.5.0, the <tt>config.php</tt> file has been replaced with a web-based configuration that can be found under "Configuration" in the Admin's block. Under the "Languages and Locale" heading, you'll find two options:
* Language Files
* Languages
These two options are the equivalents of the <code>$_CONF['language_files']</code> and <code>$_CONF['languages']</code> arrays, as explained above. To use the multilingual feature, '''both''' of these options have to be enabled. Other than that, the two options work as described above.

Note that in Geeklog 1.5.0, you can not easily disable multilingual support again (for a workaround, see [http://www.geeklog.net/forum/viewtopic.php?showtopic=83327 here]). As of Geeklog 1.5.1, there is a litte <tt>(X)</tt> next to the options (once they're enabled). Click on the <tt>(X)</tt> to disable the options again (remember that you need to disable both of them).

=== The shortcuts ===

For each of the languages you intend to support, you will have to define a shortcut that will then be used in the IDs of the multilingual objects, as explained above.

You can freely define these shortcuts, but it would make sense to set them in some relation to the language which they represent. From Geeklog's point of view, though, it doesn't matter whether the English language is represented by a shortcut 'en' or by 'peter'.

Please note:
* All the shortcuts in both of the arrays have to be of the same length.
* The shortcut must be appended to the ''end'' of an object's ID and it must be preceded by an underscore '_' character.
* It's recommended that you use a language's ISO abbreviation ('en' for English, 'de' for German, etc.), either with or without the country appendix ('en-US'), as Geeklog will also try to determine a user's preferred language from their browser setting.

=== The language files ===

The $_CONF['language_files'] array defines which language files should represent which language. Note that Geeklog also uses the language file name for a user's language setting (in their preferences).

It's recommended that you remove all the other language files, i.e. those for which you do not intend to have content in that particular language on your site.

'''Note:''' Be careful when mixing languages that use different character sets (e.g. Russian and Japanese). You may want to switch to the UTF-8 versions of ''all'' language files for such a setup.

=== The language names ===

The $_CONF['languages'] array defines a set of display names for the supported languages. These names are used to let the user switch between the supported languages, e.g. from a drop-down menu.

Most of the time, you'll want to use the native names of the languages, e.g. "Deutsch" instead of "German", but that's only a convention.

== Blocks ==

Multilingual blocks are only supported as of Geeklog 1.5.1. The setup differs slightly from the setup for stories, topics, etc.

Let's assume you want to create a multilingual "about this site" block and that your site is configured for two languages (say, English and German). For this setup you would then need ''three''(!) blocks. The block name serves as the ID and you would create blocks with the following names:
* about_en
* about_de
* about
The first two blocks would simply contain your content in English and German, respectively. Both blocks should be ''disabled''. The third block then serves as a placeholder for the actual block for the current language. Therefore, only this block ("about", in our example) should be enabled. When the multilingual support is enabled, you will never see the contents of that block, as it will be replaced with the proper block for the current language, e.g. "about_en" for English.

== Switching languages ==

Registered users can always switch their preferred language by selecting another language in their preferences.

To make things more convenient (and also allow anonymous users to switch the language), you can put a PHP block on your site. Geeklog provides a function phpblock_switch_language that will display a drop-down menu of all available languages (if you only have two languages defined, it will display a simple link to the other language instead).

This function can also be called from the header.thtml template file of your theme, so that you can put it into your site's menu:
<pre><?php print phpblock_switch_language(); ?></pre>

Technically, switching the language will set a cookie (with the selected language) and also update a user's language preference, if they're registered with the site.

== Detecting the language ==

When a user comes to a multilingual enabled site, Geeklog will check for the user's preference setting first (if it's a registered user), then for the language cookie, and if that couldn't be found, it tries to get the language from the browser's 'Accept-Language' header (which only works if you chose to use the ISO shortcuts, as explained above). If all else fails, content will be presented in the site's default language, i.e. $_CONF['language'].

== Supporting multiple languages ==

Developers of plugins and other add-ons don't have to do much to support multiple languages. Mainly, the objects under your plugin's control will have to have an editable, non-numerical ID (like Geeklog's stories have), so that the language shortcut can be appended to the ID.

If you have a list of objects under your plugin's control and only want to show the objects in the current language, you can use the COM_getLangSQL() function when building your SQL request. It will provide the part of an SQL request to only return the objects in the current language (see the function's description in lib-common.php for details).

COM_getLangSQL() will return an empty string when multilingual support is disabled, so you don't need to check for that yourself.

Most of the time, that should be all that you need to know about supporting multiple languages in a plugin. In some scenarios, the following functions may also come in handy:
* COM_getLanguageId returns the shortcut of the current user's language
* COM_getLanguage returns the full name of the current user's language, i.e. the name of the Geeklog language file (without the .php extension)

== Switching locale settings ==

Switching the language will often also require different formatting of the date, time, and other locale settings. For this, you can define alternative settings for each language in your site's config.php.

For example, the default date formatting in Geeklog's config.php is
<pre>$_CONF['date'] = '%A, %B %d %Y @ %I:%M %p %Z';</pre>
which, amongst other things, includes a time format using am/pm. If your site switches between, say, English and German, then your typical German visitor will expect the time to use a 24-hour format, e.g.
<pre>$_CONF['date'] = '%A, %d. %B %Y, %R Uhr';</pre>

If you're using the ISO abbreviation 'de' for German, then you could have the following in your site's config.php:
<pre>$_CONF['date'] = '%A, %B %d %Y @ %I:%M %p %Z';
$_CONF['date_de'] = '%A, %d. %B %Y, %R Uhr';</pre>
With these two lines, Geeklog would use the 'date_de' formatting when displaying content in German, and the 'date' formatting for all the other languages.

Actually, for this to work properly, you will also have to set <code>$_CONF['locale']</code> and <code>$_CONF['locale_de']</code> accordingly, since some of the date formatting (localized day and month names) requires the correct locale to be set:
<pre>$_CONF['locale'] = 'en_GB';
$_CONF['locale_de'] = 'de_DE';</pre>

You can switch all of the following [http://www.geeklog.net/docs/english/config.html#languages_locale locale settings] as described above:
* <code>$_CONF['locale']</code>
* <code>$_CONF['date']</code>
* <code>$_CONF['daytime']</code>
* <code>$_CONF['shortdate']</code>
* <code>$_CONF['dateonly']</code>
* <code>$_CONF['timeonly']</code>
* <code>$_CONF['week_start']</code>
* <code>$_CONF['hour_mode']</code>
* <code>$_CONF['thousand_separator']</code>
* <code>$_CONF['decimal_separator']</code>

'''Note:''' In Geeklog 1.5.0 and later, you will have to add the language-specific entries ($_CONF['date_de'], etc.) to the <tt>siteconfig.php</tt> file. The settings for the default language can be found in the Configuration admin panel:

: Configuration > Geeklog > Languages and Locale

== Notes and ideas ==

* To make things nicer for the user, the language could be hidden from the ID when editing objects. Instead, the user could be presented with a drop-down menu of the available languages. The shortcut could then be silently added to the ID when the object is saved.
* [[SoC improve multilingual feature|More ideas]]

Summer of Code 2008

2009-10-31T00:27:31Z

LWC: Fixed link

SoC improve multilingual feature

2009-10-31T00:26:26Z

LWC: SoC improve multi-language feature moved to SoC improve multilingual feature: Fixed English

<center>(Return to the main idea page for the [[Google Summer of Code]])</center>

== Incentive ==

While Geeklog's interface has been translated into more than 25 languages by now, actually having the site's content available in several languages was only added as an afterthought. So while multilingual support is there now and works most of the time, it is somewhat awkward to use in places.

In this project, we would like someone to look at all the problems with the current solution and see what can be done about them so that multilingual sites are easier to maintain.

== Details ==

These are the known issues with the multilingual support that we would like the student to look into:

=== Setting a Fallback Language ===

There is no concept of a "fallback language", i.e. for every piece of content there has to be a separate object in each of the supported languages. So if your site was set up to use English, German, and Spanish, you would need 3 copies of every story (one per language). You can not, say, publish a story in English only and have the English version show up automatically for the other languages.

A related problem is adding another language to the site later. For example, starting a site in English and German and only adding Spanish later. In that case, you currently have to copy all the existing content over to a Spanish version (otherwise, Spanish visitors may see a note about the article not being available to them instead of at least falling back to, say, the English version).

=== User Interface ===

Missing support in the user interface: Users have to make sure to add the proper suffix ('_en', '_de') to objects (story, topic, ...). There's no protection against typos, for example.

Adding a dropdown to select the language for an object would be a simple solution. There may be better ways, though.

=== Anonymous Visitors ===

For anonymous visitors (guests) of the site, switching the language requires a cookie to be set. Users that do not accept the cookie will not be able to switch the language. This includes bots (e.g. search engines), which won't be able to index the content in languages other than the default language. This can also lead to a mix of languages, e.g. when following a link to an article in English while the site's default language is German.

== Level of Difficulty ==

''medium to high''

We don't actually expect a lot of new code to be written for this project. This is more of a research project aimed at people who love tinkering with existing code. For compatibility reasons, there is only limited room for radical changes. The project will require a lot of testing and attention to details.

== Further reading ==

* [[Multilingual_Support]] in Geeklog
* Bug: [http://project.geeklog.net/tracking/view.php?id=712 Using the browser's back button can cause confusion in multilingual setups]

[[Category:Summer of Code]] [[Category:Development]]

SoC improve multi-language feature

2009-10-31T00:26:26Z

LWC: SoC improve multi-language feature moved to SoC improve multilingual feature: Fixed English

#REDIRECT [[SoC improve multilingual feature]]

SoC improve multilingual feature

2009-10-31T00:25:41Z

LWC: Fixed English

Language Tips And Tricks

2009-10-31T00:24:19Z

LWC: Fixed links

== General Things ==

When you switch to another language in Geeklog, not only the menu text changes, but also the character set might change. This means that certain international characters might not be readable anymore. So if your site has German, Japanese or eastern European content, switching the language might turn your complete content unreadable.

== Multilingual Sites ==

If you plan to run a site where the content will be [[Multilingual Support|in several languages]], it is better to stick to languages that support UTF-8. Since they all use the same code, you will be able to display German Umlaut next to Japanese Characters for example. Otherwise, readers will always see unreadable characters next to readables, and will have to switch languages in order to read everything. Read below how to convert your favorite language to UTF-8.

Further, to support proper search and other functions, you should enable --with-mb_string functions in your PHP. In Linux, this might mean that you have to recompile linux! If you do this remember also to set your php.ini to have "mbstring.func_overload = 7". This makes php use multibyte-functions by default whenever a single-byte function is called.

== Unwanted Languages ==

You can remove unwanted languages by simply deleting the unwanted files from the <tt>/language/</tt> directory. Or you might want to create a subfolder there and move the unwanted files into it. Like this you can avoid that users choose Languages with character sets that will turn content unreadable.

== How to convert Language file Character Sets ==

First check in the download section of geeklog.net if nobody already converted the language file after the last release of Geeklog!

If you have Windows & MS Word, there is a very easy way to convert your language files to UTF-8 or other formats: Simply open the language-file with Word (rename it .doc and double-click for example). Then you will be asked what Character set the Source has. Choose the one that allows you to read the characters properly in the preview. Then save the file again as "Text Only"-Format. You will be asked again what Character Set you want to use. Choose your preferred ("Unicode UTF-8" for example). Make sure you also correct the line 32 of the file so that it represents the format you want:

<pre>$LANG_CHARSET = "utf-8";</pre>

Then, rename the file to "language_utf-8.php".

If you have done so, you might want to publish the file also on the geeklog.net website.

== How to convert your complete Geeklog to Unicode/UTF-8 in 11 steps. ==

If you started your server with one language, and want to move to a multi-language system later on, it can be quite difficult if you need different character sets for the different languages. With UTF-8 you can display all languages and letters at the same time in the same page without any problems. The best solution therefore would be to convert your ''complete'' data into Unicode in one go. You don't want to go through each story and comment and edit letters by hand after you switched the encoding of the page.

For this procedure to work you need (1) a text editor like notepad that can save raw text data while choosing the encoding (Notepad unter windows for example), (2) direct access to you MySQL executable (Windows cmd or Linux Shell) and (3) a NON-Unicode-Capable Editor (!) such as PHPEdit (or linux shell editors AFAIK). You can find out which editor cannot handle Unicode by saving a small text containing a "xxöxx" or similar with notepad as UTF-8 (See step 3) and opening it with the other editor. If you the letter "ö" appears now as "Ã¶" you have the right one.

Now let's start.

# Make a Backup of your database using the Geeklog Backup function.
# Download the created file from your server, zip it, burn it on a CD and send it to your lawyer. He should keep it as a backup in case you need it later to go back to step one.
# Open the file in Notepad/unicode-able editor (Notepad.exe). If your database is large, this will take some time, but its worth waiting for. Save the file again under a different (!) filename. Before you press the save-button, you have a field called "Encoding" below the field where you entered the filename. Choose "UTF-8".
# Now open the file in the non-Unicode-capable editor. You will see three strange letters "ï»¿" in the beginning of the file. Remove them. They cause error messages in the SQL later. Save the file again.
# Upload the file to your server. You might want to zip it first (also before downloading) to reduce transfer time.
# Create a new database if you can. If not delete all tables from your old one (call your lawyer to have your backup ready in an envelope).
# Write the data back into the database. Do this by typing <pre>mysql --user=root --password databasename file.txt</pre> replace "databasename" with the name of the newly created or empty database, and file.txt with the name of the file that you saved with notepad. The file has to be in the same directory as you are, if not move the file there. In Windows, it has to be in the /Mysql/bin-directory, where your MySQL.exe resides. If you do not want to move the files, prepend the path to the mysql.exe and/or the filename path.<br>If you do not have root access to the database, exchange "root" with the username that you use to access your MySQL server.
# Hit enter. You will be prompted for the user's password. Enter it, and press return again. Now the database will be parsed back into the server.
# If you created a second database, edit your Geeklog's config.php so that it accesses the new one.
# Switch your Geeklog language to one of the _UTF-8 sets. If you want to reduce hassle with your users that have been using non-UTF-8 languages, convert all the language-files you have to UTF-8 with notepad (You don't need to remove the first three letter there) and change the encoding string in each file (Line 30) to <pre>$LANG_CHARSET = "utf-8";</pre>
# Change config.php so that the standard language file will be one of the UTF-8 sets also (somehwere line 239), <pre>$_CONF['language'] = "english_utf-8";</pre>
# You might want to delete all non-UTF-8 languages from your language folders.

That's all. Good luck <tt>:-)</tt>

== Switching back to one language (1.3.9sr1 and before) ==

If you set your config.php so that you use only one language, you might run into trouble if you have users that already registered and selected another language. These users will continue to use their pre-set language. Even if you set their language manually to the standard or NULL (with a tool such as [http://www.phpmyadmin.net/ phpMyAdmin]), the cookies on the user's computers will still call up the old one.

== Links and Further Reading ==

* [http://lists.geeklog.net/mailman/listinfo/geeklog-translations geeklog-translations mailing list]
* [[Multilingual Support]] (as of Geeklog 1.4.1)

Multi-Language Support

2009-10-31T00:23:17Z

LWC: Multi-Language Support moved to Multilingual Support: Fixed English

#REDIRECT [[Multilingual Support]]

Multilingual Support

2009-10-31T00:23:17Z

LWC: Multi-Language Support moved to Multilingual Support: Fixed English

== Background ==

The Geeklog language files have been translated into more than 25 languages - but that only means that you can have the user interface in one of those languages. For the actual site content (articles, static pages, ...), there was no support for multiple languages, which means that you either had to have everything in one language only or you ended up with all the different language versions of, e.g. an article, being displayed to anyone.

Euan McKay then came up with a [http://heatherengineering.com/staticpages/index.php/multilingual-en first multi-language hack], which was later [http://www.geeklog.net/forum/viewtopic.php?showtopic=61999 built upon and generalized] by LWC.

The multi-language support in Geeklog (as of version 1.4.1) is based on this earlier work by Euan and LWC.

== How it works ==

The basic idea behind the multi-language support is to encode the language of an object into its ID. For example, for a story to encode it into the story ID, like so:

<pre>http://www.example.com/article.php/introduction_en -- English version
http://www.example.com/article.php/introduction_de -- German version</pre>

Now there is a way to identify the language of an object (article, topic, static page, ...) and it can be displayed (or not), based on the user's language preferences. It's also possible then to switch between the various languages in which an object exists in the database.

== Setting it up ==

=== Geeklog 1.4.1 ===

In config.php, there is a new section to enable multi-language support and to define the list of supported languages:

<pre>// Multi-language support
// (note that this section is commented out - remove the '/*' and '*/' lines
// below to activate it and make sure you understand what it does)
/*

// IMPORTANT!
// 1) Both the $_CONF['language_files'] and the $_CONF['languages'] arrays
// (see below) must have the same number of elements.
// 2) The shortcuts used must be the same in both arrays.
// 3) All shortcuts must have the same length, e.g. 2 characters.

// The shortcuts are to be used in IDs of objects that are multi-language
// aware, e.g. /article.php/introduction_en and /article.php/introduction_de
// for the English and German version of an introductory article.

// Supported languages
// Maps a shortcut to a Geeklog language file (without the '.php' extension)
$_CONF['language_files'] = array (
'en' => 'english',
'de' => 'german_formal'
);

// Display names of supported languages
// Maps the same shortcuts as above to a language name. The language names
// are used to let users switch languages, e.g. in a drop-down menu.
$_CONF['languages'] = array (
'en' => 'English',
'de' => 'Deutsch'
);

*/</pre>

To enable multi-language support, the two arrays $_CONF['language_files'] and $_CONF['languages'] have to be defined. In the default config.php, they are commented out and, therefore, not defined.

=== Geeklog 1.5.0 and later ===

As of Geeklog 1.5.0, the <tt>config.php</tt> file has been replaced with a web-based configuration that can be found under "Configuration" in the Admin's block. Under the "Languages and Locale" heading, you'll find two options:
* Language Files
* Languages
These two options are the equivalents of the <code>$_CONF['language_files']</code> and <code>$_CONF['languages']</code> arrays, as explained above. To use the multi-language feature, '''both''' of these options have to be enabled. Other than that, the two options work as described above.

Note that in Geeklog 1.5.0, you can not easily disable multi-language support again (for a workaround, see [http://www.geeklog.net/forum/viewtopic.php?showtopic=83327 here]). As of Geeklog 1.5.1, there is a litte <tt>(X)</tt> next to the options (once they're enabled). Click on the <tt>(X)</tt> to disable the options again (remember that you need to disable both of them).

=== The shortcuts ===

For each of the languages you intend to support, you will have to define a shortcut that will then be used in the IDs of the multi-language objects, as explained above.

You can freely define these shortcuts, but it would make sense to set them in some relation to the language which they represent. From Geeklog's point of view, though, it doesn't matter whether the English language is represented by a shortcut 'en' or by 'peter'.

Please note:
* All the shortcuts in both of the arrays have to be of the same length.
* The shortcut must be appended to the ''end'' of an object's ID and it must be preceded by an underscore '_' character.
* It's recommended that you use a language's ISO abbreviation ('en' for English, 'de' for German, etc.), either with or without the country appendix ('en-US'), as Geeklog will also try to determine a user's preferred language from their browser setting.

=== The language files ===

The $_CONF['language_files'] array defines which language files should represent which language. Note that Geeklog also uses the language file name for a user's language setting (in their preferences).

It's recommended that you remove all the other language files, i.e. those for which you do not intend to have content in that particular language on your site.

'''Note:''' Be careful when mixing languages that use different character sets (e.g. Russian and Japanese). You may want to switch to the UTF-8 versions of ''all'' language files for such a setup.

=== The language names ===

The $_CONF['languages'] array defines a set of display names for the supported languages. These names are used to let the user switch between the supported languages, e.g. from a drop-down menu.

Most of the time, you'll want to use the native names of the languages, e.g. "Deutsch" instead of "German", but that's only a convention.

== Blocks ==

Multi-lingual blocks are only supported as of Geeklog 1.5.1. The setup differs slightly from the setup for stories, topics, etc.

Let's assume you want to create a multi-lingual "about this site" block and that your site is configured for two languages (say, English and German). For this setup you would then need ''three''(!) blocks. The block name serves as the ID and you would create blocks with the following names:
* about_en
* about_de
* about
The first two blocks would simply contain your content in English and German, respectively. Both blocks should be ''disabled''. The third block then serves as a placeholder for the actual block for the current language. Therefore, only this block ("about", in our example) should be enabled. When the multi-language support is enabled, you will never see the contents of that block, as it will be replaced with the proper block for the current language, e.g. "about_en" for English.

== Switching languages ==

Registered users can always switch their preferred language by selecting another language in their preferences.

To make things more convenient (and also allow anonymous users to switch the language), you can put a PHP block on your site. Geeklog provides a function phpblock_switch_language that will display a drop-down menu of all available languages (if you only have two languages defined, it will display a simple link to the other language instead).

This function can also be called from the header.thtml template file of your theme, so that you can put it into your site's menu:
<pre><?php print phpblock_switch_language(); ?></pre>

Technically, switching the language will set a cookie (with the selected language) and also update a user's language preference, if they're registered with the site.

== Detecting the language ==

When a user comes to a multi-language enabled site, Geeklog will check for the user's preference setting first (if it's a registered user), then for the language cookie, and if that couldn't be found, it tries to get the language from the browser's 'Accept-Language' header (which only works if you chose to use the ISO shortcuts, as explained above). If all else fails, content will be presented in the site's default language, i.e. $_CONF['language'].

== Supporting multiple languages ==

Developers of plugins and other add-ons don't have to do much to support multiple languages. Mainly, the objects under your plugin's control will have to have an editable, non-numerical ID (like Geeklog's stories have), so that the language shortcut can be appended to the ID.

If you have a list of objects under your plugin's control and only want to show the objects in the current language, you can use the COM_getLangSQL() function when building your SQL request. It will provide the part of an SQL request to only return the objects in the current language (see the function's description in lib-common.php for details).

COM_getLangSQL() will return an empty string when multi-language support is disabled, so you don't need to check for that yourself.

Most of the time, that should be all that you need to know about supporting multiple languages in a plugin. In some scenarios, the following functions may also come in handy:
* COM_getLanguageId returns the shortcut of the current user's language
* COM_getLanguage returns the full name of the current user's language, i.e. the name of the Geeklog language file (without the .php extension)

== Switching locale settings ==

Switching the language will often also require different formatting of the date, time, and other locale settings. For this, you can define alternative settings for each language in your site's config.php.

For example, the default date formatting in Geeklog's config.php is
<pre>$_CONF['date'] = '%A, %B %d %Y @ %I:%M %p %Z';</pre>
which, amongst other things, includes a time format using am/pm. If your site switches between, say, English and German, then your typical German visitor will expect the time to use a 24-hour format, e.g.
<pre>$_CONF['date'] = '%A, %d. %B %Y, %R Uhr';</pre>

If you're using the ISO abbreviation 'de' for German, then you could have the following in your site's config.php:
<pre>$_CONF['date'] = '%A, %B %d %Y @ %I:%M %p %Z';
$_CONF['date_de'] = '%A, %d. %B %Y, %R Uhr';</pre>
With these two lines, Geeklog would use the 'date_de' formatting when displaying content in German, and the 'date' formatting for all the other languages.

Actually, for this to work properly, you will also have to set <code>$_CONF['locale']</code> and <code>$_CONF['locale_de']</code> accordingly, since some of the date formatting (localized day and month names) requires the correct locale to be set:
<pre>$_CONF['locale'] = 'en_GB';
$_CONF['locale_de'] = 'de_DE';</pre>

You can switch all of the following [http://www.geeklog.net/docs/english/config.html#languages_locale locale settings] as described above:
* <code>$_CONF['locale']</code>
* <code>$_CONF['date']</code>
* <code>$_CONF['daytime']</code>
* <code>$_CONF['shortdate']</code>
* <code>$_CONF['dateonly']</code>
* <code>$_CONF['timeonly']</code>
* <code>$_CONF['week_start']</code>
* <code>$_CONF['hour_mode']</code>
* <code>$_CONF['thousand_separator']</code>
* <code>$_CONF['decimal_separator']</code>

'''Note:''' In Geeklog 1.5.0 and later, you will have to add the language-specific entries ($_CONF['date_de'], etc.) to the <tt>siteconfig.php</tt> file. The settings for the default language can be found in the Configuration admin panel:

: Configuration > Geeklog > Languages and Locale

== Notes and ideas ==

* To make things nicer for the user, the language could be hidden from the ID when editing objects. Instead, the user could be presented with a drop-down menu of the available languages. The shortcut could then be silently added to the ID when the object is saved.
* [[SoC improve multi-language feature|More ideas]]

Limit Portal Block Entry

2009-10-28T23:21:26Z

LWC: Fixed description

== Limiting Portal Block Entry ==

You can limit the number of entries in a [[Block_Types#Portal_Block|Portal Block]] for each individual portal block in the block menu. The default is specified in the value of <code>$_CONF['syndication_max_headlines']</code> (in <tt>Site: Syndication</tt> in the Configuration admin panel or in <tt>config.php</tt>, depending on the Geeklog version you're using).

In really old Geeklog versions, you can limit the number of entries by changing the value of <code>$maxheadlines</code> in <code>function COM_rdfImport($bid, $rdfurl)</code> to any number that you want.

== Reloading Portal Block ==

After changing the limit, the portal block will not be updated until the next RSS update which by default is set to 3600 seconds/1 hour (specified in lib-common.php's function COM_rdfCheck). If you want to see the portal block updated immediately, you can go back to Blocks under the Admins function, select the portal block that you want to reload and save the portal block again.

[[Category:Blocks]]

SoC improving comments 2008

2009-10-23T08:41:57Z

LWC: Fixed grammar

This project was implemented in [[Summer of Code 2008]]. The comment improvements are available as of Geeklog 1.6.0. This project outline is therefore only of historical interest and you can not apply for this project in future instances of the Google Summer of Code. Please see our [[Google Summer of Code|ideas page]] for a current list of GSoC project ideas.

== Incentive ==

Comments are a simple and natural way to ask your readers for feedback to a particular article. Geeklog's comment system was originally written at a time when spam and heated discussions on websites were rare. Even though some improvements have since been made (e.g. integration of spam protection, reporting of abusive comments, etc.), the comment system is showing its age and is in desperate need of some changes and additions, as outlined in this project proposal.

== Goals ==

The goal of this project is to make comments more useful and attractive again for both visitors (so they are motivated to leave comments) and site administrators (so they are motivated to allow comments, despite the fear of spam). We believe this could be accomplished by implementing the following features:

* a comment moderation queue
* "aging" of stories, i.e. automatically close a story for comments after a while
* make comments editable for users
* being able to actually see the comment or article you're replying to while writing a comment
* allow users to receive notifications about follow-up comments
* allow non-registered users to identify themselves

== Details ==

Note: Geeklog has hierarchical comments, i.e. you can reply to a specific comment and your comment will be displayed below the comment you replied to (indented, instead of at the end of the list of comments).

=== Moderation ===

Just like story submissions, comments should - optionally - be held back until approved by a moderator.

* Option to only hold back comments by anonymous users.
* Option to put already published comments back into the moderation queue for review (including comments that are replies to these comments).
* Option to auto-approve comments by certain users or user groups.

The auto-approve should be implemented as a Geeklog right (permission), e.g. "comment.submit", so that this right can be assigned to groups of users (consistent with the "story.submit" right for stories).

For auto-approving comments by individual users, it may be worth looking at other systems for inspiration. Wordpress, for example, auto-approves comments by users once their first comment has been approved by a moderator. This works by setting a cookie and therefore doesn't require registration of an account.

=== "Aging" ===

Once a story has been up on a site for a while, it is less likely that someone wants to comment on it. At the same time, spammers are known to prefer spamming older posts in the hope that it will go unnoticed. Consequentially, it would make sense to have an option to automatically close a story for commenting after a while.

* Option to automatically close the story for comments after a certain amount of time.
* Option to only keep the last <var>x</var> stories open for comments (e.g. set to the number of stories on the homepage so that stories dropping off the homepage are closed automatically).

The option to close a story for comments after some time should be on a per-story basis (with a global default). The option to only keep the latest stories open for comment should override (and disable) the time-based option.

Note: Manual closing of comments is not available in Geeklog 1.4.1 but has been implemented in CVS for the upcoming version 1.5.

=== Editable comments ===

Making comments editable isn't going to help prevent spam but is aimed at making the comment system more attractive so that posters can correct typos or rephrase their comment.

Things to consider:

* A comment should only be editable as long as there hasn't been a follow-up comment.
* There should be a time limit for how long the comment should be editable.
* Comments should always be editable for Admins.
* The user has to be identified somehow. So either this feature has to be restricted to registered users or a cookie has to be set to identify the original poster (also see [[SoC_improving_comments_2008#Moderation|auto-approve]] above).

In order to indicate that a comment has been edited, it may be advisable to automatically add a ''(last edited by ... at ...)'' note to the comment. However, this should be made an option and it could also be left to the discretion of the user whether they want to leave that note in.

=== Seeing what you're commenting on ===

This should be a pretty straightforward change in the user interface: Currently, the comment submission form takes over the entire page so that you can't see the comment or article you are replying to (unless you open a separate window or tab).

This will also have to work with plugins that support comments, though, which may make things slightly more complicated than it seems at first.

=== Notifications ===

Users who left a comment will usually be interested in any follow-up comment that is being made. Users should therefore have an option to receive an email when such a comment is posted.

Things to consider:

* This could lead to a lot of emails being sent and should therefore be a global option.
* Possible email options:
** immediate notification
** no further notification until the next visit
** inclusion of comment that was posted
** digest(?)
* Ability to unsubscribe needed (preferrably with a link in the email).
* Overview of a user's subscriptions (e.g. under "My Account").

'''Note:''' There is some overlap here with the proposal for a [[SoC_core_notification_support|Notification Service]]. Implementing the comment notifications using that service should make things much easier.

=== Less anonymous comments ===

Geeklog currently lumps all comments made by users who are not logged in together under a guest user account called ''Anonymous''. If anonymous comments are enabled, there should be an optional text entry field where the commenter can leave a name.

Internally, these comments would still end up in the "Anonymous" account, but the display of a name should at least let them appear less anonymous.

== Level of Difficulty ==

''medium''

This project will require some wrestling with legacy code when implementing the [[SoC_improving_comments_2008#Editable_comments|editable comments]], so that formatting and special characters will not get lost. [[SoC_improving_comments_2008#Moderation|Moderation]] will have to use Geeklog's plugin API for moderation and will depend on being able to edit the comments (due to the requirements of the API). These two tasks will probably require most of the time and work.

The amount of work required for the [[SoC_improving_comments_2008#Notifications|notifications]] will depend on whether or not the project for a [[SoC_core_notification_support|Notification Service]] will be picked up and implemented. This task should probably be implemented last so that it can be cut down or dropped entirely, if necessary.

== Further Reading ==

* [http://vinny.furiafamily.com/article.php?story=20041129154258296 Representing Hierarchical Data in a Database] - How the comments are stored

[[Category:Summer of Code]] [[Category:Development]]

SoC improving comments

2009-10-23T08:41:37Z

LWC: Fixed grammar

This project was eventually implemented as [[SoC improving comments 2008]]. The comment improvements are available as of Geeklog 1.6.0. This project outline is therefore only of historical interest and you can not apply for this project in future instances of the Google Summer of Code. Please see our [[Google Summer of Code|ideas page]] for a current list of GSoC project ideas.

== Incentive ==

Comments are important for blogs and community-driven sites to get feedback from visitors. However, due to the rise of comment spam, it's becoming increasingly hard to keep comments open for everyone.

In Geeklog, you can currently only open comments for everyone (including anonymous users) or for registered users only. While the latter reduces the number of spam comments, it also reduces the number of overall comments, as visitors are less likely to leave a comment if they have to register first.

== Goals ==

The goal of this project is to make comments more useful and attractive again by implementing:

* a comment moderation queue
* "aging" of stories, i.e. automatically close a story for comments after a while
* make comments editable for users

== Details ==

Note: Geeklog supports hierarchical comments, i.e. you can reply to a specific comment and your comment will be displayed below the comment you replied to (indented, instead of at the end of the list of comments).

=== Moderation ===

Just like story submissions, comments should - optionally - be held back until approved by a moderator.

* Option to only hold back comments by anonymous users.
* Option to put already posted comments back into the moderation queue (including comments that are replies to these comments).
* Option to auto-approve comments by certain users or user groups.
* Possibly: Option to report moderated comments as spam (via the Spam-X plugin). This may be unnecessary, though, since the comments already went through the spam filter when they were posted initially.

=== "Aging" ===

Once a story has been up on a site for a while, it is less likely that someone wants to comment on it. At the same time, spammers are known to prefer spamming older posts in the hope that it will go unnoticed. Consequentially, it would make sense to have an option to automatically close a story for commenting after a while.

* Option to close the story for comments after a certain amount of time,
* Option to close the story for comments once it drops off the homepage (i.e. after a certain amount of new stories have been posted).

Note: Manual closing of comments is not available in Geeklog 1.4.1 but has been implemented in CVS (i.e. the current development version).

=== Editable comments ===

Making comments editable isn't going to help prevent spam, of course, but is aimed at making the comment system more attractive so that posters can correct typos or rephrase their comment.

Things to consider:

* A comment should only be editable as long as there hasn't been a follow-up comment.
* There should probably be a time-limit for how long the comment should be editable.
* Comments should always be editable for Admins, though.
* The user has to be identified somehow. So either this feature has to be restricted to registered users or a cookie has to be set to identify the original poster.

=== More ideas ===

There are more ideas and feature requests that would also help to make comments more attractive and motivate visitors to leave a comment:

* Let anonymous users at least enter a name.
* Optionally send a notification email when a reply has been made to a user's comment (for registered users only).
* Being able to see the comment or original post while commenting on it.

These ideas are not strictly part of the SoC task, but may be easy enough to implement or at least have to be considered in the design.

[[Category:Summer of Code]] [[Category:Development]]

SoC improving comments 2008

2009-10-23T08:40:37Z

LWC: No longer future tense and added link

This project was implemented in [[Summer of Code 2008]]. The comment improvements is available as of Geeklog 1.6.0. This project outline is therefore only of historical interest and you can not apply for this project in future instances of the Google Summer of Code. Please see our [[Google Summer of Code|ideas page]] for a current list of GSoC project ideas.

== Incentive ==

Comments are a simple and natural way to ask your readers for feedback to a particular article. Geeklog's comment system was originally written at a time when spam and heated discussions on websites were rare. Even though some improvements have since been made (e.g. integration of spam protection, reporting of abusive comments, etc.), the comment system is showing its age and is in desperate need of some changes and additions, as outlined in this project proposal.

== Goals ==

The goal of this project is to make comments more useful and attractive again for both visitors (so they are motivated to leave comments) and site administrators (so they are motivated to allow comments, despite the fear of spam). We believe this could be accomplished by implementing the following features:

* a comment moderation queue
* "aging" of stories, i.e. automatically close a story for comments after a while
* make comments editable for users
* being able to actually see the comment or article you're replying to while writing a comment
* allow users to receive notifications about follow-up comments
* allow non-registered users to identify themselves

== Details ==

Note: Geeklog has hierarchical comments, i.e. you can reply to a specific comment and your comment will be displayed below the comment you replied to (indented, instead of at the end of the list of comments).

=== Moderation ===

Just like story submissions, comments should - optionally - be held back until approved by a moderator.

* Option to only hold back comments by anonymous users.
* Option to put already published comments back into the moderation queue for review (including comments that are replies to these comments).
* Option to auto-approve comments by certain users or user groups.

The auto-approve should be implemented as a Geeklog right (permission), e.g. "comment.submit", so that this right can be assigned to groups of users (consistent with the "story.submit" right for stories).

For auto-approving comments by individual users, it may be worth looking at other systems for inspiration. Wordpress, for example, auto-approves comments by users once their first comment has been approved by a moderator. This works by setting a cookie and therefore doesn't require registration of an account.

=== "Aging" ===

Once a story has been up on a site for a while, it is less likely that someone wants to comment on it. At the same time, spammers are known to prefer spamming older posts in the hope that it will go unnoticed. Consequentially, it would make sense to have an option to automatically close a story for commenting after a while.

* Option to automatically close the story for comments after a certain amount of time.
* Option to only keep the last <var>x</var> stories open for comments (e.g. set to the number of stories on the homepage so that stories dropping off the homepage are closed automatically).

The option to close a story for comments after some time should be on a per-story basis (with a global default). The option to only keep the latest stories open for comment should override (and disable) the time-based option.

Note: Manual closing of comments is not available in Geeklog 1.4.1 but has been implemented in CVS for the upcoming version 1.5.

=== Editable comments ===

Making comments editable isn't going to help prevent spam but is aimed at making the comment system more attractive so that posters can correct typos or rephrase their comment.

Things to consider:

* A comment should only be editable as long as there hasn't been a follow-up comment.
* There should be a time limit for how long the comment should be editable.
* Comments should always be editable for Admins.
* The user has to be identified somehow. So either this feature has to be restricted to registered users or a cookie has to be set to identify the original poster (also see [[SoC_improving_comments_2008#Moderation|auto-approve]] above).

In order to indicate that a comment has been edited, it may be advisable to automatically add a ''(last edited by ... at ...)'' note to the comment. However, this should be made an option and it could also be left to the discretion of the user whether they want to leave that note in.

=== Seeing what you're commenting on ===

This should be a pretty straightforward change in the user interface: Currently, the comment submission form takes over the entire page so that you can't see the comment or article you are replying to (unless you open a separate window or tab).

This will also have to work with plugins that support comments, though, which may make things slightly more complicated than it seems at first.

=== Notifications ===

Users who left a comment will usually be interested in any follow-up comment that is being made. Users should therefore have an option to receive an email when such a comment is posted.

Things to consider:

* This could lead to a lot of emails being sent and should therefore be a global option.
* Possible email options:
** immediate notification
** no further notification until the next visit
** inclusion of comment that was posted
** digest(?)
* Ability to unsubscribe needed (preferrably with a link in the email).
* Overview of a user's subscriptions (e.g. under "My Account").

'''Note:''' There is some overlap here with the proposal for a [[SoC_core_notification_support|Notification Service]]. Implementing the comment notifications using that service should make things much easier.

=== Less anonymous comments ===

Geeklog currently lumps all comments made by users who are not logged in together under a guest user account called ''Anonymous''. If anonymous comments are enabled, there should be an optional text entry field where the commenter can leave a name.

Internally, these comments would still end up in the "Anonymous" account, but the display of a name should at least let them appear less anonymous.

== Level of Difficulty ==

''medium''

This project will require some wrestling with legacy code when implementing the [[SoC_improving_comments_2008#Editable_comments|editable comments]], so that formatting and special characters will not get lost. [[SoC_improving_comments_2008#Moderation|Moderation]] will have to use Geeklog's plugin API for moderation and will depend on being able to edit the comments (due to the requirements of the API). These two tasks will probably require most of the time and work.

The amount of work required for the [[SoC_improving_comments_2008#Notifications|notifications]] will depend on whether or not the project for a [[SoC_core_notification_support|Notification Service]] will be picked up and implemented. This task should probably be implemented last so that it can be cut down or dropped entirely, if necessary.

== Further Reading ==

* [http://vinny.furiafamily.com/article.php?story=20041129154258296 Representing Hierarchical Data in a Database] - How the comments are stored

[[Category:Summer of Code]] [[Category:Development]]

SoC improving comments

2009-10-23T08:40:00Z

LWC: No longer future tense

This project was eventually implemented [[SoC improving comments 2008|in the 2008 Google Summer of Code]]. The comment improvements is available as of Geeklog 1.6.0. This project outline is therefore only of historical interest and you can not apply for this project in future instances of the Google Summer of Code. Please see our [[Google Summer of Code|ideas page]] for a current list of GSoC project ideas.

== Incentive ==

Comments are important for blogs and community-driven sites to get feedback from visitors. However, due to the rise of comment spam, it's becoming increasingly hard to keep comments open for everyone.

In Geeklog, you can currently only open comments for everyone (including anonymous users) or for registered users only. While the latter reduces the number of spam comments, it also reduces the number of overall comments, as visitors are less likely to leave a comment if they have to register first.

== Goals ==

The goal of this project is to make comments more useful and attractive again by implementing:

* a comment moderation queue
* "aging" of stories, i.e. automatically close a story for comments after a while
* make comments editable for users

== Details ==

Note: Geeklog supports hierarchical comments, i.e. you can reply to a specific comment and your comment will be displayed below the comment you replied to (indented, instead of at the end of the list of comments).

=== Moderation ===

Just like story submissions, comments should - optionally - be held back until approved by a moderator.

* Option to only hold back comments by anonymous users.
* Option to put already posted comments back into the moderation queue (including comments that are replies to these comments).
* Option to auto-approve comments by certain users or user groups.
* Possibly: Option to report moderated comments as spam (via the Spam-X plugin). This may be unnecessary, though, since the comments already went through the spam filter when they were posted initially.

=== "Aging" ===

Once a story has been up on a site for a while, it is less likely that someone wants to comment on it. At the same time, spammers are known to prefer spamming older posts in the hope that it will go unnoticed. Consequentially, it would make sense to have an option to automatically close a story for commenting after a while.

* Option to close the story for comments after a certain amount of time,
* Option to close the story for comments once it drops off the homepage (i.e. after a certain amount of new stories have been posted).

Note: Manual closing of comments is not available in Geeklog 1.4.1 but has been implemented in CVS (i.e. the current development version).

=== Editable comments ===

Making comments editable isn't going to help prevent spam, of course, but is aimed at making the comment system more attractive so that posters can correct typos or rephrase their comment.

Things to consider:

* A comment should only be editable as long as there hasn't been a follow-up comment.
* There should probably be a time-limit for how long the comment should be editable.
* Comments should always be editable for Admins, though.
* The user has to be identified somehow. So either this feature has to be restricted to registered users or a cookie has to be set to identify the original poster.

=== More ideas ===

There are more ideas and feature requests that would also help to make comments more attractive and motivate visitors to leave a comment:

* Let anonymous users at least enter a name.
* Optionally send a notification email when a reply has been made to a user's comment (for registered users only).
* Being able to see the comment or original post while commenting on it.

These ideas are not strictly part of the SoC task, but may be easy enough to implement or at least have to be considered in the design.

[[Category:Summer of Code]] [[Category:Development]]

CommentAlgorithm

2009-10-23T08:28:23Z

LWC: /* Representing Geeklog's Comments in the Database */ Added titles

=Representing Geeklog's Comments in the Database=

Since Geeklog 1.3.10, Geeklog's comments have been stored in the database with columns (''lft'', ''rht'') representing a (modified) pre-order traversal ordering. This method of storage was chosen to improve comment retrieval performance, especially when viewing a subset of the comments for a given story.

==Details==
The idea behind pre-order traversal ordering, is that each node is ordered (or visited) before any of its children. In the modified preorder traversal algorithm implemented by Geeklog, the ''lft'' value of a comment is always less than the ''lft'' and ''rht'' values of all of the children of that node. Likewise the ''rht'' value of a node is always greater that the ''lft'' and ''rht'' values of all of the children of that node. (And trivially for any node, ''lft'' is always less than ''rht''.) A node without any children has the property ''rht'' is exactly one more than ''lft''.

Example: Comment A is a top level comment to a story. Comments A-A and A-B are children of A and comments A-A-A, A-A-B, and A-A-C are children of A-A. The table below shows the values for each comment:

{| cellpadding="2" cellspacing="0" border="1"
! style="width:25%" |comment
! style="width:25%" |parent
! style="width:25%" |lft
! style="width:25%" |rht
|-
|A
|N/A
|1
|12
|-
|A-A
|A
|2
|9
|-
|A-B
|A
|10
|11
|-
|A-A-A
|A-A
|3
|4
|-
|A-A-B
|A-A
|5
|6
|-
|A-A-C
|A-A
|7
|8
|}

The resulting database structure has many advantages. Selecting a subtree from the database is as easy as specifying the ''lft'' and ''rht'' numbers of the root node of the subtree. For instance, to get the subtree with root comment "A-A":

<code>SELECT * FROM comments WHERE lft >= 2 AND rht <= 9</code>

Or selecting all the children of a give node:

<code>SELECT * FROM comments WHERE lft > 2 AND rht < 9</code>

To select comments ordered for display in a "nested" format:

<code>SELECT * FROM comments ORDER BY lft</code>

Storing the preorder traversal information also allows us to easily find the path to a node (i.e. a nodes parents, grandparents, etc).

<code>SELECT * FROM comments WHERE lft < 7 AND rht > 8</tt>

Counting the number of children of a comment is equally easy: <code>('rht' - 'lft' - 1)/2</code>

Previously these operations required a (very slow) recursive algorithm. The way Geeklog had implemented this algorithm required one database query for every comment in the result set. Another way would have been to do one query to fetch all comments, and then use a recursive function to choose the desired comments. Both methods were extremely inefficient and caused load problems on frequently viewed Geeklog sites.

The downside to this method is that inserting and deleting comments takes more work (three queries instead of one) and must be done in a single transaction (or a write lock on the table). Inserts:

<code>START TRANSACTION<br>
UPDATE comments SET rht = rht + 2 WHERE rht >= comment.rht<br>
UPDATE comments SET lft = lft + 2 WHERE lft >= comment.rht<br>
INSERT INTO comments SET lft = comment.rht, rht = comment.rht + 1<br>
COMMIT</code>

Deletions:

<code>START TRANSACTION<br>
UPDATE comments SET rht = rht - 2 WHERE rht > comment.rht<br>
UPDATE comments SET lft = lft - 2 WHERE lft > comment.rht<br>
DELETE FROM comments WHERE id = comment.id<br>
COMMIT</code>

However, since fetching (reading) comments is a much more frequent action then adding or deleting comments and the increase in efficiency for fetching comments is much greater than the loss of efficiency for adding and deleting comments, the trade off is worth while.

Please note that in the SQL examples above, parts of the query were left out to make the algorithm more clear. For more detail, see the Geeklog source code (specifically lib-comment.php).

==External related articles==
* [http://www.sitepoint.com/article/hierarchical-data-database/2/ Storing Hierarchical Data in a Database]
* [http://www.ibase.ru/devinfo/DBMSTrees/sqltrees.html Trees in SQL]
* [http://en.wikipedia.org/wiki/Tree_traversal Tree Traversal]
* [http://dev.mysql.com/tech-resources/articles/hierarchical-data.html Managing Hierarchical Data in MySQL]

PLG getItemInfo

2009-06-01T15:28:41Z

LWC: /* Additional properties */ =

= Introduction =

<code>PLG_getItemInfo</code> was introduced in Geeklog 1.4.0 and used internally as part of the implementation of Trackbacks and Pingbacks. The API was [[#Extended_API|extended]] in Geeklog 1.6.0 for use by the [[XMLSitemap Plugin]].

The basic idea for this function is to request information for an item that is under a plugin's control (where, in this case, the list of "plugins" also includes Geeklog's built-in articles).

= Original API =

The API, as implemented in Geeklog versions 1.4.0 - 1.5.2:

<pre>function PLG_getItemInfo($type, $id, $what)</pre>

* <code>$type</code> is the type of plugin we want to request information from. This is the internal name of the plugin, e.g. 'links' for the Links plugin. Additionally, 'article' can be used to request information for stories.
* <code>$id</code> is the ID of the item we are requesting information about, e.g. the story ID (sid), link ID (lid), etc.
* <code>$what</code> is a comma-separated list of keywords indicating the information we are requesting for the specified item. We will call these key/value pairs ''properties'' from now on.<br>Currently, the following properties are defined:
** 'url' - the complete URL of the item
** 'title' - the item's title or subject
** 'excerpt' - a short description of the item
** 'description' - the full description of the item, e.g. the article text

The function returns an array of strings of the requested information, in the order defined by the <code>$what</code> parameter, e.g. for
<pre>PLG_getItemInfo('article', 'welcome', 'url,title');</pre>
it would return information about the default story on a fresh install of Geeklog:
<pre>array('http://www.example.com/article.php/welcome', 'Welcome to Geeklog!');</pre>
For properties not supported by the plugin, an empty string will be returned.

= Extended API =

The idea behind this extended API (as of Geeklog 1.6.0) is to allow Geeklog and other plugins to request a list of items and information about those items at the same time. The extensions are designed to be backward-compatible, as outlined below.

<pre>function PLG_getItemInfo($type, $id, $what, $uid = 0, $options = array())</pre>

== Plugin type ($type) ==
This includes 'article' for stories.

== Item ID ($id) ==

When requesting information for more than one item, the <code>$id</code> parameter is not needed. In this case, it should be set to <tt>'*'</tt> (a single asterisk character). This indicates to the plugin, that information for more than one item is requested.

==Which properties ($what)==
A comma-separated list of item properties.

== User ID ($uid) ==

The original API did not allow for access control. All operations were performed with the access control of the current user. With the $uid parameter, it is now possible to request items that are only visible to a specific user.

* Default: <code>$uid == 0</code> - use the permissions of the current user. This is for backward-compatibility with the original API.
* For a <code>$uid > 0</code>, only items that are accessible to that user should be returned.

== Options ($options) ==

''reserved for future extensions''

== Return values ==

When returning more than one entry, the return value is supposed to be an array of arrays (even if it only contains one entry). The properties should be returned using PHP's associative arrays using key/value pairs instead of relying on the order of properties. Properties that are not supported or available will not be set in the returned arrays, e.g. for <code>$what = 'url,something-unknown,title'</code>:
<pre>array(
array(
'url' => 'http://www.example.com/article.php/welcome',
'title' => 'Welcome to Geeklog!'
),
array(
'url' => 'http://www.example.com/article.php/about',
'title' => 'About this site'
)
)</pre>

=== Additional properties ===

* 'id' - an item's ID. Obviously, when requesting information about more than one item, we also need the IDs of those items to tell them apart.
* 'date-created' - date when the item was created, as a Unix timestamp.
* 'date-modified' - date when the item was last modified, as a Unix timestamp.

'''Note:''' Plugins that only have one of either 'date-created' or 'date-modified' should only return that information (i.e. do not return a modified date when it's really the item's creation date). Plugins that do not keep any date information should, obviously, not return any either.

Unknown properties should be silently ignored. This will allow for future extensions as well as for using properties that are only supported by some plugins.

[[Category:Plugin Development]]

PLG getItemInfo

2009-06-01T15:28:07Z

LWC: Deleted linebreaks and fixed order and added others

= Introduction =

<code>PLG_getItemInfo</code> was introduced in Geeklog 1.4.0 and used internally as part of the implementation of Trackbacks and Pingbacks. The API was [[#Extended_API|extended]] in Geeklog 1.6.0 for use by the [[XMLSitemap Plugin]].

The basic idea for this function is to request information for an item that is under a plugin's control (where, in this case, the list of "plugins" also includes Geeklog's built-in articles).

= Original API =

The API, as implemented in Geeklog versions 1.4.0 - 1.5.2:

<pre>function PLG_getItemInfo($type, $id, $what)</pre>

* <code>$type</code> is the type of plugin we want to request information from. This is the internal name of the plugin, e.g. 'links' for the Links plugin. Additionally, 'article' can be used to request information for stories.
* <code>$id</code> is the ID of the item we are requesting information about, e.g. the story ID (sid), link ID (lid), etc.
* <code>$what</code> is a comma-separated list of keywords indicating the information we are requesting for the specified item. We will call these key/value pairs ''properties'' from now on.<br>Currently, the following properties are defined:
** 'url' - the complete URL of the item
** 'title' - the item's title or subject
** 'excerpt' - a short description of the item
** 'description' - the full description of the item, e.g. the article text

The function returns an array of strings of the requested information, in the order defined by the <code>$what</code> parameter, e.g. for
<pre>PLG_getItemInfo('article', 'welcome', 'url,title');</pre>
it would return information about the default story on a fresh install of Geeklog:
<pre>array('http://www.example.com/article.php/welcome', 'Welcome to Geeklog!');</pre>
For properties not supported by the plugin, an empty string will be returned.

= Extended API =

The idea behind this extended API (as of Geeklog 1.6.0) is to allow Geeklog and other plugins to request a list of items and information about those items at the same time. The extensions are designed to be backward-compatible, as outlined below.

<pre>function PLG_getItemInfo($type, $id, $what, $uid = 0, $options = array())</pre>

== Plugin type ($type) ==
This includes 'article' for stories.

== Item ID ($id) ==

When requesting information for more than one item, the <code>$id</code> parameter is not needed. In this case, it should be set to <tt>'*'</tt> (a single asterisk character). This indicates to the plugin, that information for more than one item is requested.

==Which properties ($what)==
A comma-separated list of item properties.

== User ID ($uid) ==

The original API did not allow for access control. All operations were performed with the access control of the current user. With the $uid parameter, it is now possible to request items that are only visible to a specific user.

* Default: <code>$uid == 0</code> - use the permissions of the current user. This is for backward-compatibility with the original API.
* For a <code>$uid > 0</code>, only items that are accessible to that user should be returned.

== Options ($options) ==

''reserved for future extensions''

== Return values ==

When returning more than one entry, the return value is supposed to be an array of arrays (even if it only contains one entry). The properties should be returned using PHP's associative arrays using key/value pairs instead of relying on the order of properties. Properties that are not supported or available will not be set in the returned arrays, e.g. for <code>$what = 'url,something-unknown,title'</code>:
<pre>array(
array(
'url' => 'http://www.example.com/article.php/welcome',
'title' => 'Welcome to Geeklog!'
),
array(
'url' => 'http://www.example.com/article.php/about',
'title' => 'About this site'
)
)</pre>

== Additional properties ==

* 'id' - an item's ID. Obviously, when requesting information about more than one item, we also need the IDs of those items to tell them apart.
* 'date-created' - date when the item was created, as a Unix timestamp.
* 'date-modified' - date when the item was last modified, as a Unix timestamp.

'''Note:''' Plugins that only have one of either 'date-created' or 'date-modified' should only return that information (i.e. do not return a modified date when it's really the item's creation date). Plugins that do not keep any date information should, obviously, not return any either.

Unknown properties should be silently ignored. This will allow for future extensions as well as for using properties that are only supported by some plugins.

[[Category:Plugin Development]]

Adding Moderation Capability

2009-05-30T09:42:19Z

LWC: /* The functions */ Spaces

This section will describe and document how to enable your plugin to use the Geeklog moderation engine.

==Note==
This set of functions is optional when creating your plugin, but should be used when your plugin has functionality that includes submitting of an item that needs to be reviewed by a site admin or plugin admin before posting to the site. The Geeklog (GL) developers have made the implementation of this API very straight forward and enabled the API calls into the moderation related
core programs.

===Version note===
You will need to be using Geeklog version 1.3.7 or apply the
changes noted in the appendix to successfully use the Moderation API's, though some functionality may work with previous versions of Geeklog. The changes with 1.3.7 release include the following programs: moderation.php, submit.php, plugin.class.php and lib-plugins.php.
Refer to the appendix if you have a previous release and want to review the needed changes.

==The functions==
There are six (6) plugin functions that are required for the moderation plugin and two (2) optional functions. The example functions that are provided can be used as guide, but they will required some changes to make them work for your plugin.

The following table summarizes the functions:

{|cellPadding="2" width="100%" border="1"
!width=4%|
!Function
!Description of Function
|-
|1
|[[#plugin_ismoderator_<plugin name>|plugin_ismoderator_<plugin name>]]
|Checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise.

|-
|2
|[[#plugin_submissioncount_<plugin name>|plugin_submissioncount_<plugin name>]]
|Calculates the current number of submissions awaiting moderation and returns that number.

|-
|3
|[[#plugin_savesubmission_<plugin name>|plugin_savesubmission_<plugin name>]]
|Takes the data input by the plugin submission form and populates the <plugin name> submission table with that data.

|-
|4
|[[#plugin_moderationvalues_<plugin name>|plugin_moderationvalues_<plugin name>]]
|Returns a list of important moderation values. The list contains (in order): the row 'id' label, the main plugin table name, comma separated string of moderation fields, and the plugin submission table name.

|-
|5
|[[#plugin_itemlist_<plugin name>|plugin_itemlist_<plugin name>]]
|Uses the plugin class to return data required by moderation.php to list plugin objects that need to be moderated.

|-
|6
|[[#plugin_submit_<plugin name>|plugin_submit_<plugin name>]]
|Returns a string containing the HTML to display the plugin submission form.

|-
|7
|[[#plugin_moderationapprove_<plugin name>|plugin_moderationapprove_<plugin name>]]
|This optional function supplements moderation.php. While moderation.php actually moves data from the <plugin name> submission table to the main <plugin name> table, this function executes all other submission approval tasks including any other database updates required by your plugin.

|-
|8
|[[#plugin_moderationdelete_<plugin name>|plugin_moderationdelete_<plugin name>]]
|This optional function supplements moderation.php. While moderation.php actually removes data from the <plugin name> submission table, this function executes all other submission removal tasks including any other database updates required by your plugin.
|}

=== How to call the Moderation Engine ===

After you implement the moderation functions in your plugin, you will need to call the Geeklog moderation engine or program to create or moderate the submission. This can be done by adding a link or button which redirects the user to submit.php or moderate.php with the necessary parameters from your plugin.

The example below was used by the Mailing Lists plugin to link to the 'submit new mailing list' page. The link to submit.php needs to be passed with the parameter '''type''' to indicate which plugin's submission form should be displayed. The variable $retval is assigned the formatted link which will be displayed as a link in the plugin display.

<pre>$retval = "<a href='" . $_CONF['site_url'] . "/submit.php?type=lists'>" . $LANG_LISTS['SUBMITLIST'] . "</a>";</pre>

'''Admin interaction with the Moderation Engine:''' Once all the moderation
functions are implemented, the 'Submissions' link in the admin block will include a list of all submissions to be moderated (they can be approved, removed or edited). You must write your own submission edit function located in $_CONF['site_admin_url'] . '/plugins/<plugin name>/<plugin name>.php. It will be passed the http variables id=<item id> and mode=editsubmission.

=== Plugin database changes ===

The table <plugin name> submission must be the name of your submission
table. This table can only contain a proper subset of the columns from the main <plugin name> table. This allows the moderation.php script to
automatically copy those columns from the submission to the main table upon
approval. All data in columns of the submission table that are not in the main table will be lost.

=== Function details and examples ===

This explanation of the plugin moderation API functions will use the Mailing Lists plugin for examples and give a detailed description of each function.

====plugin_ismoderator_<plugin name>====
<pre>
function plugin_ismoderator_lists()
{
global $_USER, $_TABLES;

return SEC_hasRights('lists.admin');
}
</pre>

====plugin_submissioncount_<plugin name>====
The '''''plugin_ismoderator''''' function simply returns TRUE if
the current user has moderation privileges for the plugin. In the example
to the right, The mailing lists plugin simply uses the security function
SEC_hasRights to determine if a user has the required rights. The lists.admin permission was installed with the plugin. You could use your own SQL query or some other criteria to determine access rights.

<pre>
function plugin_submissioncount_lists()
{
global $_TABLES;

return DB_count($_TABLES['listssubmission']);
}
</pre>

====plugin_savesubmission_<plugin name>====
The '''''plugin_submissioncount''''' function returns the number of
submissions for this plugin that are awaiting moderation. This value is used to indicate the number of waiting submissions in the admin block. A DB_count() on the plugin submission table is usually sufficient for this.

<pre>
function plugin_savesubmission_lists($A)
{
global $_TABLES, $_USER, $_CONF;

// check for missing fields
if (empty($A['ml_name']) || empty($A['ml_descr'])) {
return false;
}

if (empty($_USER['uid'])) {
$owner_id = 1;
} else {
$owner_id = $_USER['uid'];
}

if (SEC_hasRights('links.admin')) {
$result = DB_getItem($_TABLES['groups'], '*', "grp_name = 'lists Admin'");
if ($_CONF['listsarchive'] == 'optional') {
$archive = $_CONF['listsarchivedefault'];
} elseif ($_CONF['listsarchive'] == 'no') {
$archive = 0;
} else { // $_CONF['listsarchive'] == 'yes'
$archive = 1;
}
DB_save($_TABLES['lists'], 'ml_id, ml_name, ml_descr, html, archive, owner_id, group_id',
"'" . COM_makeSid() . "', '" . $A['ml_name'] . "', '" . $A['ml_descr']
. "', " . $_CONF['listshtml'] . ", $archive, $owner_id, " . $result['grp_id']);
} elseif ($_CONF['listssubmission'] == 1) {
DB_save($_TABLES['listssubmission'],
'ml_id, ml_name, ml_descr',
"'" . COM_makeSid() . "', '" . $A['ml_name'] . "', '"
. $A['ml_descr'] . "'");
} else {
return false;
}

if (DB_error()) {
return false;
}

return true;
}
</pre>

====plugin_moderationvalues_<plugin name>====
The '''''plugin_savesubmission''''' function takes data entered into
the submission form and saves it to the submission table. Optionally, this function can use different logic for an admin or power user as seen in the Mailing Lists Plugin.
In addition to saving the information to the plugin's submission table, it must also check data entered for validity. Upon failure the function should return false or redirect to the submission form. If successful, the function should redirect to a relevant page, or return true. In Geeklog 1.3.7 the plugin API expects the function to do a redirect (COM_refresh()). If it does not, a successful return from the function
will redirect the user back to the Geeklog home page.

<pre>
function plugin_moderationvalues_lists()
{
global $_TABLES;

return array('ml_id', $_TABLES['lists'], 'ml_id, ml_name, ml_descr', $_TABLES['listssubmission']);
}
</pre>

====plugin_itemlist_<plugin name>====
The '''''plugin_moderationvalues''''' function returns important information used by the Plugin API to handle plugin submissions. It must return an array consisting of the main column id (ml_id), the main table name ($_TABLES['lists']), a comma separated list of columns that will be copied from the plugin submission table to the main table (ml_id, ml_name, ml_descr), and the name of the submission table ($_TABLE['listssubmission']). This information is used to automatically
copy information from the plugin submission table to the plugin main table when a submission is approved.

<pre>
function plugin_itemlist_lists()
{
global $_TABLES;

if (plugin_ismoderator_lists()) {
$plugin = new Plugin();
$plugin->submissionlabel = 'Mailing List Submissions';
$plugin->getsubmissionssql = SELECT ml_id as id, ml_name, ml_descr FROM
. $_TABLES['listssubmission'];
$plugin->addSubmissionHeading('List Name');
$plugin->addSubmissionHeading('List Description');

return $plugin;
}
}
</pre>

====plugin_submit_<plugin name>====
The function '''''plugin_itemlist''''' returns a Plugin() class containing information that will displayed on the moderation.php page. The following member variables of the Plugin class must be filled out:

* '''submissionlabel:''' The title that indicate the plugin submission section.
* '''getsubmissionsql:''' An SQL query that will select all the data that will be displayed in the plugin submission section. NOTE: one item (the unique id column) must be labeled id ('as id').
* '''addSubmissionHeading():''' This function must be called once for every field besides the one labeled id. The parameter passed should be the column name to be displayed.

<pre>
function plugin_submit_lists()
{
global $_CONF, $LANG12;

if ($_CONF['listssubmission'] == 0 && !SEC_hasRights('lists.admin')) {
return "Submission queue disabled for mailing lists";
}

if ($_POST['mode'] == $LANG12[32]) { // preview
$A = $_POST;
$ml_id = $A['ml_id'];
} else {
$ml_id = COM_makesid();
}

$template = new Template($_CONF['path'] . "plugins/lists/templates/public");
$template->set_file(array('form' => 'submit_form.thtml'));
$template->set_var('site_url', $_CONF['site_url']);
$template->set_var('lang_name', 'List Name');
$template->set_var('ml_name', $A['ml_name']);
$template->set_var('lang_descr', 'Description');
$template->set_var('ml_descr', $A['ml_descr']);
$template->set_var('ml_id', $ml_id);
$template->set_var('lang_preview', $LANG12[32]);
$template->set_var('lang_save', $LANG12[8]);

return $template->parse('output', 'form');
}
</pre>

====plugin_moderationapprove_<plugin name> ====
The function '''''plugin_submit''''' creates HTML that contains the submission form for the plugin. It is recommended to use the Geeklog template functionality as shown here to create the form. See the section of this manual [[Using Templates and Language Files|on templates]] for more information. When creating the form, be sure to include fields for each variable you would like the user to fill along with preview and submit buttons.

<pre>
function plugin_moderationapprove_lists($id)
{
global $_TABLES, $_USER, $_CONF;

$result = DB_query("SELECT * FROM " . $_TABLES['groups']
. " WHERE grp_name = 'lists Admin'");
$group = DB_fetchArray($result);
if ($_CONF['listsarchive'] == 'optional') {
$archive = $_CONF['listsarchivedefault'];
} elseif ($_CONF['listsarchive'] == 'no') {
$archive = 0;
} else { // $_CONF['listsarchive'] == 'yes'
$archive = 1;
}
$sql = "UPDATE " . $_TABLES['lists'] . " SET owner_id = " . $_USER['uid']
. ", group_id = " . $group['grp_id'] . ", html = " . $_CONF['listshtml']
. ", archive = $archive WHERE ml_id = '$id'";
$result = DB_query($sql);

if (DB_error()) {
return 'Error';
}
return '';
}
</pre>

====plugin_moderationdelete_<plugin name>====
Although the moderation.php script takes care of the work of actually moving data from the plugin submission table to the main plugin table, often times a plugin requires more to be done to the plugin tables or for other information to be updated. Geeklog provides the function '''''plugin_moderationapprove''''' for these tasks. In the case of the lists plugin, the main plugin table is updated with additional data that it is not desirable for a user to enter. Instead this function takes care of placing that information into the table. As of now the return value for this function is ignored.

<pre>
function plugin_moderationdelete_lists($id)
{
global $_TABLES;

// these tables should not contain any rows with ml_id = $id
// this is done 'just in case'
DB_delete($_TABLES['listsubscriptions'], 'ml_id', $id);
DB_delete($_TABLES['listarchive'], 'ml_id', $id);
DB_delete($_TABLES['listpermissions'], 'ml_id', $id);
}
</pre>

Although the moderation.php script takes care of the work of actually removing data from the plugin submission table for a submission deletion, often times a plugin requires more to be done to the plugin tables or for other information to be updated. Geeklog provides the function '''''plugin_moderationdelete''''' for these tasks. In the case of the lists plugin, tables are checked for extraneous data (that should not exist in most cases) and that data is removed if found. As of now the return value for this function is ignored.

[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Adding Moderation Capability

2009-05-30T09:41:36Z

LWC: /* The functions */ Space

This section will describe and document how to enable your plugin to use the Geeklog moderation engine.

==Note==
This set of functions is optional when creating your plugin, but should be used when your plugin has functionality that includes submitting of an item that needs to be reviewed by a site admin or plugin admin before posting to the site. The Geeklog (GL) developers have made the implementation of this API very straight forward and enabled the API calls into the moderation related
core programs.

===Version note===
You will need to be using Geeklog version 1.3.7 or apply the
changes noted in the appendix to successfully use the Moderation API's, though some functionality may work with previous versions of Geeklog. The changes with 1.3.7 release include the following programs: moderation.php, submit.php, plugin.class.php and lib-plugins.php.
Refer to the appendix if you have a previous release and want to review the needed changes.

==The functions==
There are six (6) plugin functions that are required for the moderation plugin and two (2) optional functions. The example functions that are provided can be used as guide, but they will required some changes to make them work for your plugin.

The following table summarizes the functions:

{|cellPadding="2" width="100%" border="1"
!width=4%|
!Function
!Description of Function
|-
|1
|[[#plugin_ismoderator_<plugin name>|plugin_ismoderator_<plugin name>]]
|Checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise.

|-
|2
|[[#plugin_submissioncount_<plugin name>|plugin_submissioncount_<plugin name>]]
|Calculates the current number of submissions awaiting moderation and returns that number.

|-
|3
|[[#plugin_savesubmission_<plugin name>|plugin_savesubmission_<plugin name>]]
|Takes the data input by the plugin submission form and populates the <plugin name> submission table with that data.

|-
|4
|[[#plugin_moderationvalues_<plugin name>|plugin_moderationvalues_<plugin name>]]
|Returns a list of important moderation values. The list contains (in order): the row 'id' label, the main plugin table name, comma separated string of moderation fields, and the plugin submission table name.

|-
|5
|[[#plugin_itemlist_<plugin name>|plugin_itemlist_<plugin name>]]
|Uses the plugin class to return data required by moderation.php to list plugin objects that need to be moderated.

|-
|6
|[[#plugin_submit_<plugin name>|plugin_submit_<plugin name>]]
|Returns a string containing the HTML to display the plugin submission form.

|-
|7
|[[#plugin_moderationapprove_<plugin name>|plugin_moderationapprove_<plugin name>]]
|This optional function supplements moderation.php. While moderation.php actually moves data from the <plugin name>submission table to the main <plugin name> table, this function executes all other submission approval tasks including any other database updates required by your plugin.

|-
|8
|[[#plugin_moderationdelete_<plugin name>|plugin_moderationdelete_<plugin name>]]
|This optional function supplements moderation.php. While moderation.php actually removes data from the <plugin name>submission table, this function executes all other submission removal tasks including any other database updates required by your plugin.
|}

=== How to call the Moderation Engine ===

After you implement the moderation functions in your plugin, you will need to call the Geeklog moderation engine or program to create or moderate the submission. This can be done by adding a link or button which redirects the user to submit.php or moderate.php with the necessary parameters from your plugin.

The example below was used by the Mailing Lists plugin to link to the 'submit new mailing list' page. The link to submit.php needs to be passed with the parameter '''type''' to indicate which plugin's submission form should be displayed. The variable $retval is assigned the formatted link which will be displayed as a link in the plugin display.

<pre>$retval = "<a href='" . $_CONF['site_url'] . "/submit.php?type=lists'>" . $LANG_LISTS['SUBMITLIST'] . "</a>";</pre>

'''Admin interaction with the Moderation Engine:''' Once all the moderation
functions are implemented, the 'Submissions' link in the admin block will include a list of all submissions to be moderated (they can be approved, removed or edited). You must write your own submission edit function located in $_CONF['site_admin_url'] . '/plugins/<plugin name>/<plugin name>.php. It will be passed the http variables id=<item id> and mode=editsubmission.

=== Plugin database changes ===

The table <plugin name>submission must be the name of your submission
table. This table can only contain a proper subset of the columns from the main <plugin name> table. This allows the moderation.php script to
automatically copy those columns from the submission to the main table upon
approval. All data in columns of the submission table that are not in the main table will be lost.

=== Function details and examples ===

This explanation of the plugin moderation API functions will use the Mailing Lists plugin for examples and give a detailed description of each function.

====plugin_ismoderator_<plugin name>====
<pre>
function plugin_ismoderator_lists()
{
global $_USER, $_TABLES;

return SEC_hasRights('lists.admin');
}
</pre>

====plugin_submissioncount_<plugin name>====
The '''''plugin_ismoderator''''' function simply returns TRUE if
the current user has moderation privileges for the plugin. In the example
to the right, The mailing lists plugin simply uses the security function
SEC_hasRights to determine if a user has the required rights. The lists.admin permission was installed with the plugin. You could use your own SQL query or some other criteria to determine access rights.

<pre>
function plugin_submissioncount_lists()
{
global $_TABLES;

return DB_count($_TABLES['listssubmission']);
}
</pre>

====plugin_savesubmission_<plugin name>====
The '''''plugin_submissioncount''''' function returns the number of
submissions for this plugin that are awaiting moderation. This value is used to indicate the number of waiting submissions in the admin block. A DB_count() on the plugin submission table is usually sufficient for this.

<pre>
function plugin_savesubmission_lists($A)
{
global $_TABLES, $_USER, $_CONF;

// check for missing fields
if (empty($A['ml_name']) || empty($A['ml_descr'])) {
return false;
}

if (empty($_USER['uid'])) {
$owner_id = 1;
} else {
$owner_id = $_USER['uid'];
}

if (SEC_hasRights('links.admin')) {
$result = DB_getItem($_TABLES['groups'], '*', "grp_name = 'lists Admin'");
if ($_CONF['listsarchive'] == 'optional') {
$archive = $_CONF['listsarchivedefault'];
} elseif ($_CONF['listsarchive'] == 'no') {
$archive = 0;
} else { // $_CONF['listsarchive'] == 'yes'
$archive = 1;
}
DB_save($_TABLES['lists'], 'ml_id, ml_name, ml_descr, html, archive, owner_id, group_id',
"'" . COM_makeSid() . "', '" . $A['ml_name'] . "', '" . $A['ml_descr']
. "', " . $_CONF['listshtml'] . ", $archive, $owner_id, " . $result['grp_id']);
} elseif ($_CONF['listssubmission'] == 1) {
DB_save($_TABLES['listssubmission'],
'ml_id, ml_name, ml_descr',
"'" . COM_makeSid() . "', '" . $A['ml_name'] . "', '"
. $A['ml_descr'] . "'");
} else {
return false;
}

if (DB_error()) {
return false;
}

return true;
}
</pre>

====plugin_moderationvalues_<plugin name>====
The '''''plugin_savesubmission''''' function takes data entered into
the submission form and saves it to the submission table. Optionally, this function can use different logic for an admin or power user as seen in the Mailing Lists Plugin.
In addition to saving the information to the plugin's submission table, it must also check data entered for validity. Upon failure the function should return false or redirect to the submission form. If successful, the function should redirect to a relevant page, or return true. In Geeklog 1.3.7 the plugin API expects the function to do a redirect (COM_refresh()). If it does not, a successful return from the function
will redirect the user back to the Geeklog home page.

<pre>
function plugin_moderationvalues_lists()
{
global $_TABLES;

return array('ml_id', $_TABLES['lists'], 'ml_id, ml_name, ml_descr', $_TABLES['listssubmission']);
}
</pre>

====plugin_itemlist_<plugin name>====
The '''''plugin_moderationvalues''''' function returns important information used by the Plugin API to handle plugin submissions. It must return an array consisting of the main column id (ml_id), the main table name ($_TABLES['lists']), a comma separated list of columns that will be copied from the plugin submission table to the main table (ml_id, ml_name, ml_descr), and the name of the submission table ($_TABLE['listssubmission']). This information is used to automatically
copy information from the plugin submission table to the plugin main table when a submission is approved.

<pre>
function plugin_itemlist_lists()
{
global $_TABLES;

if (plugin_ismoderator_lists()) {
$plugin = new Plugin();
$plugin->submissionlabel = 'Mailing List Submissions';
$plugin->getsubmissionssql = SELECT ml_id as id, ml_name, ml_descr FROM
. $_TABLES['listssubmission'];
$plugin->addSubmissionHeading('List Name');
$plugin->addSubmissionHeading('List Description');

return $plugin;
}
}
</pre>

====plugin_submit_<plugin name>====
The function '''''plugin_itemlist''''' returns a Plugin() class containing information that will displayed on the moderation.php page. The following member variables of the Plugin class must be filled out:

* '''submissionlabel:''' The title that indicate the plugin submission section.
* '''getsubmissionsql:''' An SQL query that will select all the data that will be displayed in the plugin submission section. NOTE: one item (the unique id column) must be labeled id ('as id').
* '''addSubmissionHeading():''' This function must be called once for every field besides the one labeled id. The parameter passed should be the column name to be displayed.

<pre>
function plugin_submit_lists()
{
global $_CONF, $LANG12;

if ($_CONF['listssubmission'] == 0 && !SEC_hasRights('lists.admin')) {
return "Submission queue disabled for mailing lists";
}

if ($_POST['mode'] == $LANG12[32]) { // preview
$A = $_POST;
$ml_id = $A['ml_id'];
} else {
$ml_id = COM_makesid();
}

$template = new Template($_CONF['path'] . "plugins/lists/templates/public");
$template->set_file(array('form' => 'submit_form.thtml'));
$template->set_var('site_url', $_CONF['site_url']);
$template->set_var('lang_name', 'List Name');
$template->set_var('ml_name', $A['ml_name']);
$template->set_var('lang_descr', 'Description');
$template->set_var('ml_descr', $A['ml_descr']);
$template->set_var('ml_id', $ml_id);
$template->set_var('lang_preview', $LANG12[32]);
$template->set_var('lang_save', $LANG12[8]);

return $template->parse('output', 'form');
}
</pre>

====plugin_moderationapprove_<plugin name> ====
The function '''''plugin_submit''''' creates HTML that contains the submission form for the plugin. It is recommended to use the Geeklog template functionality as shown here to create the form. See the section of this manual [[Using Templates and Language Files|on templates]] for more information. When creating the form, be sure to include fields for each variable you would like the user to fill along with preview and submit buttons.

<pre>
function plugin_moderationapprove_lists($id)
{
global $_TABLES, $_USER, $_CONF;

$result = DB_query("SELECT * FROM " . $_TABLES['groups']
. " WHERE grp_name = 'lists Admin'");
$group = DB_fetchArray($result);
if ($_CONF['listsarchive'] == 'optional') {
$archive = $_CONF['listsarchivedefault'];
} elseif ($_CONF['listsarchive'] == 'no') {
$archive = 0;
} else { // $_CONF['listsarchive'] == 'yes'
$archive = 1;
}
$sql = "UPDATE " . $_TABLES['lists'] . " SET owner_id = " . $_USER['uid']
. ", group_id = " . $group['grp_id'] . ", html = " . $_CONF['listshtml']
. ", archive = $archive WHERE ml_id = '$id'";
$result = DB_query($sql);

if (DB_error()) {
return 'Error';
}
return '';
}
</pre>

====plugin_moderationdelete_<plugin name>====
Although the moderation.php script takes care of the work of actually moving data from the plugin submission table to the main plugin table, often times a plugin requires more to be done to the plugin tables or for other information to be updated. Geeklog provides the function '''''plugin_moderationapprove''''' for these tasks. In the case of the lists plugin, the main plugin table is updated with additional data that it is not desirable for a user to enter. Instead this function takes care of placing that information into the table. As of now the return value for this function is ignored.

<pre>
function plugin_moderationdelete_lists($id)
{
global $_TABLES;

// these tables should not contain any rows with ml_id = $id
// this is done 'just in case'
DB_delete($_TABLES['listsubscriptions'], 'ml_id', $id);
DB_delete($_TABLES['listarchive'], 'ml_id', $id);
DB_delete($_TABLES['listpermissions'], 'ml_id', $id);
}
</pre>

Although the moderation.php script takes care of the work of actually removing data from the plugin submission table for a submission deletion, often times a plugin requires more to be done to the plugin tables or for other information to be updated. Geeklog provides the function '''''plugin_moderationdelete''''' for these tasks. In the case of the lists plugin, tables are checked for extraneous data (that should not exist in most cases) and that data is removed if found. As of now the return value for this function is ignored.

[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Adding Moderation Capability

2009-05-30T09:40:32Z

LWC: Formatted and fixed

This section will describe and document how to enable your plugin to use the Geeklog moderation engine.

==Note==
This set of functions is optional when creating your plugin, but should be used when your plugin has functionality that includes submitting of an item that needs to be reviewed by a site admin or plugin admin before posting to the site. The Geeklog (GL) developers have made the implementation of this API very straight forward and enabled the API calls into the moderation related
core programs.

===Version note===
You will need to be using Geeklog version 1.3.7 or apply the
changes noted in the appendix to successfully use the Moderation API's, though some functionality may work with previous versions of Geeklog. The changes with 1.3.7 release include the following programs: moderation.php, submit.php, plugin.class.php and lib-plugins.php.
Refer to the appendix if you have a previous release and want to review the needed changes.

==The functions==
There are six (6) plugin functions that are required for the moderation plugin and two (2) optional functions. The example functions that are provided can be used as guide, but they will required some changes to make them work for your plugin.

The following table summarizes the functions:

{|cellPadding="2" width="100%" border="1"
!width=4%|
!Function
!Description of Function
|-
|1
|[[#plugin_ismoderator_<plugin name>|plugin_ismoderator_<plugin name>]]
|Checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise.

|-
|2
|[[#plugin_submissioncount_<plugin name>|plugin_submissioncount_<plugin name>]]
|Calculates the current number of submissions awaiting moderation and returns that number.

|-
|3
|[[#plugin_savesubmission_<plugin name>|plugin_savesubmission_<plugin name>]]
|Takes the data input by the plugin submission form and populates the <plugin name>submission table with that data.

|-
|4
|[[#plugin_moderationvalues_<plugin name>|plugin_moderationvalues_<plugin name>]]
|Returns a list of important moderation values. The list contains (in order): the row 'id' label, the main plugin table name, comma separated string of moderation fields, and the plugin submission table name.

|-
|5
|[[#plugin_itemlist_<plugin name>|plugin_itemlist_<plugin name>]]
|Uses the plugin class to return data required by moderation.php to list plugin objects that need to be moderated.

|-
|6
|[[#plugin_submit_<plugin name>|plugin_submit_<plugin name>]]
|Returns a string containing the HTML to display the plugin submission form.

|-
|7
|[[#plugin_moderationapprove_<plugin name>|plugin_moderationapprove_<plugin name>]]
|This optional function supplements moderation.php. While moderation.php actually moves data from the <plugin name>submission table to the main <plugin name> table, this function executes all other submission approval tasks including any other database updates required by your plugin.

|-
|8
|[[#plugin_moderationdelete_<plugin name>|plugin_moderationdelete_<plugin name>]]
|This optional function supplements moderation.php. While moderation.php actually removes data from the <plugin name>submission table, this function executes all other submission removal tasks including any other database updates required by your plugin.
|}

=== How to call the Moderation Engine ===

After you implement the moderation functions in your plugin, you will need to call the Geeklog moderation engine or program to create or moderate the submission. This can be done by adding a link or button which redirects the user to submit.php or moderate.php with the necessary parameters from your plugin.

The example below was used by the Mailing Lists plugin to link to the 'submit new mailing list' page. The link to submit.php needs to be passed with the parameter '''type''' to indicate which plugin's submission form should be displayed. The variable $retval is assigned the formatted link which will be displayed as a link in the plugin display.

<pre>$retval = "<a href='" . $_CONF['site_url'] . "/submit.php?type=lists'>" . $LANG_LISTS['SUBMITLIST'] . "</a>";</pre>

'''Admin interaction with the Moderation Engine:''' Once all the moderation
functions are implemented, the 'Submissions' link in the admin block will include a list of all submissions to be moderated (they can be approved, removed or edited). You must write your own submission edit function located in $_CONF['site_admin_url'] . '/plugins/<plugin name>/<plugin name>.php. It will be passed the http variables id=<item id> and mode=editsubmission.

=== Plugin database changes ===

The table <plugin name>submission must be the name of your submission
table. This table can only contain a proper subset of the columns from the main <plugin name> table. This allows the moderation.php script to
automatically copy those columns from the submission to the main table upon
approval. All data in columns of the submission table that are not in the main table will be lost.

=== Function details and examples ===

This explanation of the plugin moderation API functions will use the Mailing Lists plugin for examples and give a detailed description of each function.

====plugin_ismoderator_<plugin name>====
<pre>
function plugin_ismoderator_lists()
{
global $_USER, $_TABLES;

return SEC_hasRights('lists.admin');
}
</pre>

====plugin_submissioncount_<plugin name>====
The '''''plugin_ismoderator''''' function simply returns TRUE if
the current user has moderation privileges for the plugin. In the example
to the right, The mailing lists plugin simply uses the security function
SEC_hasRights to determine if a user has the required rights. The lists.admin permission was installed with the plugin. You could use your own SQL query or some other criteria to determine access rights.

<pre>
function plugin_submissioncount_lists()
{
global $_TABLES;

return DB_count($_TABLES['listssubmission']);
}
</pre>

====plugin_savesubmission_<plugin name>====
The '''''plugin_submissioncount''''' function returns the number of
submissions for this plugin that are awaiting moderation. This value is used to indicate the number of waiting submissions in the admin block. A DB_count() on the plugin submission table is usually sufficient for this.

<pre>
function plugin_savesubmission_lists($A)
{
global $_TABLES, $_USER, $_CONF;

// check for missing fields
if (empty($A['ml_name']) || empty($A['ml_descr'])) {
return false;
}

if (empty($_USER['uid'])) {
$owner_id = 1;
} else {
$owner_id = $_USER['uid'];
}

if (SEC_hasRights('links.admin')) {
$result = DB_getItem($_TABLES['groups'], '*', "grp_name = 'lists Admin'");
if ($_CONF['listsarchive'] == 'optional') {
$archive = $_CONF['listsarchivedefault'];
} elseif ($_CONF['listsarchive'] == 'no') {
$archive = 0;
} else { // $_CONF['listsarchive'] == 'yes'
$archive = 1;
}
DB_save($_TABLES['lists'], 'ml_id, ml_name, ml_descr, html, archive, owner_id, group_id',
"'" . COM_makeSid() . "', '" . $A['ml_name'] . "', '" . $A['ml_descr']
. "', " . $_CONF['listshtml'] . ", $archive, $owner_id, " . $result['grp_id']);
} elseif ($_CONF['listssubmission'] == 1) {
DB_save($_TABLES['listssubmission'],
'ml_id, ml_name, ml_descr',
"'" . COM_makeSid() . "', '" . $A['ml_name'] . "', '"
. $A['ml_descr'] . "'");
} else {
return false;
}

if (DB_error()) {
return false;
}

return true;
}
</pre>

====plugin_moderationvalues_<plugin name>====
The '''''plugin_savesubmission''''' function takes data entered into
the submission form and saves it to the submission table. Optionally, this function can use different logic for an admin or power user as seen in the Mailing Lists Plugin.
In addition to saving the information to the plugin's submission table, it must also check data entered for validity. Upon failure the function should return false or redirect to the submission form. If successful, the function should redirect to a relevant page, or return true. In Geeklog 1.3.7 the plugin API expects the function to do a redirect (COM_refresh()). If it does not, a successful return from the function
will redirect the user back to the Geeklog home page.

<pre>
function plugin_moderationvalues_lists()
{
global $_TABLES;

return array('ml_id', $_TABLES['lists'], 'ml_id, ml_name, ml_descr', $_TABLES['listssubmission']);
}
</pre>

====plugin_itemlist_<plugin name>====
The '''''plugin_moderationvalues''''' function returns important information used by the Plugin API to handle plugin submissions. It must return an array consisting of the main column id (ml_id), the main table name ($_TABLES['lists']), a comma separated list of columns that will be copied from the plugin submission table to the main table (ml_id, ml_name, ml_descr), and the name of the submission table ($_TABLE['listssubmission']). This information is used to automatically
copy information from the plugin submission table to the plugin main table when a submission is approved.

<pre>
function plugin_itemlist_lists()
{
global $_TABLES;

if (plugin_ismoderator_lists()) {
$plugin = new Plugin();
$plugin->submissionlabel = 'Mailing List Submissions';
$plugin->getsubmissionssql = SELECT ml_id as id, ml_name, ml_descr FROM
. $_TABLES['listssubmission'];
$plugin->addSubmissionHeading('List Name');
$plugin->addSubmissionHeading('List Description');

return $plugin;
}
}
</pre>

====plugin_submit_<plugin name>====
The function '''''plugin_itemlist''''' returns a Plugin() class containing information that will displayed on the moderation.php page. The following member variables of the Plugin class must be filled out:

* '''submissionlabel:''' The title that indicate the plugin submission section.
* '''getsubmissionsql:''' An SQL query that will select all the data that will be displayed in the plugin submission section. NOTE: one item (the unique id column) must be labeled id ('as id').
* '''addSubmissionHeading():''' This function must be called once for every field besides the one labeled id. The parameter passed should be the column name to be displayed.

<pre>
function plugin_submit_lists()
{
global $_CONF, $LANG12;

if ($_CONF['listssubmission'] == 0 && !SEC_hasRights('lists.admin')) {
return "Submission queue disabled for mailing lists";
}

if ($_POST['mode'] == $LANG12[32]) { // preview
$A = $_POST;
$ml_id = $A['ml_id'];
} else {
$ml_id = COM_makesid();
}

$template = new Template($_CONF['path'] . "plugins/lists/templates/public");
$template->set_file(array('form' => 'submit_form.thtml'));
$template->set_var('site_url', $_CONF['site_url']);
$template->set_var('lang_name', 'List Name');
$template->set_var('ml_name', $A['ml_name']);
$template->set_var('lang_descr', 'Description');
$template->set_var('ml_descr', $A['ml_descr']);
$template->set_var('ml_id', $ml_id);
$template->set_var('lang_preview', $LANG12[32]);
$template->set_var('lang_save', $LANG12[8]);

return $template->parse('output', 'form');
}
</pre>

====plugin_moderationapprove_<plugin name> ====
The function '''''plugin_submit''''' creates HTML that contains the submission form for the plugin. It is recommended to use the Geeklog template functionality as shown here to create the form. See the section of this manual [[Using Templates and Language Files|on templates]] for more information. When creating the form, be sure to include fields for each variable you would like the user to fill along with preview and submit buttons.

<pre>
function plugin_moderationapprove_lists($id)
{
global $_TABLES, $_USER, $_CONF;

$result = DB_query("SELECT * FROM " . $_TABLES['groups']
. " WHERE grp_name = 'lists Admin'");
$group = DB_fetchArray($result);
if ($_CONF['listsarchive'] == 'optional') {
$archive = $_CONF['listsarchivedefault'];
} elseif ($_CONF['listsarchive'] == 'no') {
$archive = 0;
} else { // $_CONF['listsarchive'] == 'yes'
$archive = 1;
}
$sql = "UPDATE " . $_TABLES['lists'] . " SET owner_id = " . $_USER['uid']
. ", group_id = " . $group['grp_id'] . ", html = " . $_CONF['listshtml']
. ", archive = $archive WHERE ml_id = '$id'";
$result = DB_query($sql);

if (DB_error()) {
return 'Error';
}
return '';
}
</pre>

====plugin_moderationdelete_<plugin name>====
Although the moderation.php script takes care of the work of actually moving data from the plugin submission table to the main plugin table, often times a plugin requires more to be done to the plugin tables or for other information to be updated. Geeklog provides the function '''''plugin_moderationapprove''''' for these tasks. In the case of the lists plugin, the main plugin table is updated with additional data that it is not desirable for a user to enter. Instead this function takes care of placing that information into the table. As of now the return value for this function is ignored.

<pre>
function plugin_moderationdelete_lists($id)
{
global $_TABLES;

// these tables should not contain any rows with ml_id = $id
// this is done 'just in case'
DB_delete($_TABLES['listsubscriptions'], 'ml_id', $id);
DB_delete($_TABLES['listarchive'], 'ml_id', $id);
DB_delete($_TABLES['listpermissions'], 'ml_id', $id);
}
</pre>

Although the moderation.php script takes care of the work of actually removing data from the plugin submission table for a submission deletion, often times a plugin requires more to be done to the plugin tables or for other information to be updated. Geeklog provides the function '''''plugin_moderationdelete''''' for these tasks. In the case of the lists plugin, tables are checked for extraneous data (that should not exist in most cases) and that data is removed if found. As of now the return value for this function is ignored.

[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Using Geeklog's Improved Search Engine

2009-05-26T15:28:39Z

LWC: /* Standard SQL Query */ Fixed

==Plugins' compatibility with old Geeklog versions==
If you want to make your plugin compatible with Geeklog v1.5 and below, you must also implement [[Using Geeklog's Search Engine]].

==The functions==
Tying your plugin into Geeklogs search API is rather easy. Easy, that is, if you know how to search
your plugins data already. The Geeklog search API provides a way for you to return the SQL query back to Geeklog which will be executed in the core and the results included in its search page.

For the data in your plugin to be searched by Geeklog's search functions, there are two functions that you need to implement in your plugins function.inc:

*plugin_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
*plugin_dopluginsearch_{plugin_name}() returns the search SQL query back to Geeklog.

Let's look at each of them in turn:

=== plugin_searchtypes_{plugin_name}() ===

This function takes no parameters and returns an associative array of the search type. The normal code for this
function will make it all clear. Normally the function looks like this:

<pre>function plugin_searchtypes_{plugin_name}()
{
global $LANG_PL00;
$tmp['{plugin_name}']= $LANG_PL00['searchtype'];
return $tmp;
}</pre>
<sup>(don't forget to replace {plugin_name} with the actual name).</sup>

Naturally all occurrences of plugin would be replaced with the name of your
plugin and the LANGUAGE varible $LANG_PL00 is just an example. Your Plugin needs
to use a unique variable name so replace PL00.

The return array is of the format array['searchtype'] = 'Search Description', where searchtype
is returned to your plugin search routine and Description is displayed in the
Search Page Drop Down box.

You can have multiple search types and descriptions.

=== plugin_dopluginsearch_{plugin_name}() ===
This section will outline the method used to search a plugin's data.

==== Input Parameters ====
The parameters that are passed to this function are as follows:
*$query -- a string containing the search term.
*$datestart -- starting date to begin search.
*$dateend -- ending date to end search.
*$topic -- topic item is assigned to.
*$type -- no longer used, deprecated.
*$author -- the user id of the author.
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$page -- no longer used, deprecated.
*$perpage -- no longer used, deprecated.

Depending on your plugin, some of these criteria may be meaningless and thus ignored. The function should then perform two basic operations:
#Build search SQL string using the input parameters.
#Return the query along with some plugin information.

==== Returned Values ====
The search API requires the following information to be returned by the plugin_dopluginsearch_{plugin_name}() function:

===== Plugin Name =====
* A name to display to the user, i.e. 'My Plugin' (singular preferred)
* A name used locally to identify the plugin, i.e. 'myplugin'

===== A Search Rank =====
* An integer between 1 and 5 based on how many result to extract from the query.
As all the results have been combined into a single list, the core needs to prioritise important plugins to non important ones. The higher the ranking the more results will be displayed to the user. A rank of 1 will show fewer results, where as a rank of 5 shows the most amount of results from the plugin. The rank is optional, if it's not provided it will default to 3.
Here is an example of Geeklog setup with three plugins, the different rank values will allow varying results from each plugin. The results page is set to display a total of 50 results.
plugin rank results
---------------------------
stories 5 23
forums 4 18
comments 2 9

===== Standard SQL Query =====
* A string containing a single query.
* OR An array of two queries for both MSSQL and MySQL DBMS.
All SQL queries returned should be without the LIMIT and ORDER BY clauses. The SQL query must have the following column names and look like:
<pre>SELECT id, title, description, date, uid, hits, url FROM ... WHERE ...{space}</pre>
If a column does not exist in the table then another value should be substituted, for example: '0' AS hits, ...

======url======
The url is where to take the user when they have clicked a result. It should start with a single slash if the target is within the current domain. Otherwise the result with be printed, as is, in the href attribute of the link. For example this url belongs to the Geeklog site
<pre>CONCAT('/staticpages/index.php?page=', sp.sp_id) AS url</pre>
However the Links plugin needs to direct users to external sites when clicked, so providing the url from the database will suffice.

===== Full-Text SQL Query (optional) =====
* An array of two queries for both MSSQL and MySQL DBMS using the Full-Text search method.
This search method will take advantage of Full-Text indexes which will reduce search times. This should only be returned if the columns being searched have been properly indexed. The Full-Text SQL Query will only be executed if Full-Text searches have been enabled by the admin during the installation or upgrading process, otherwise the core will always fall back to the Standard SQL Query.

==== The SearchCriteria() Class ====
The process of returning the values is done by initializing a SearchCriteria() object, setting the parameters for the search then returning the object. Here is an example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setFTSQL($ftsql);
$search->setRank(4);</pre>
This indicates that the 'myplugin' plugin supports Full-Text searches and will have a ranking of 4.

===== buildSearchSQL() Function =====
As a lot of the plugins will be processing the same or similar SQL queries the buildSearchSQL() function has been provided to simplify things. This function will take four parameters then build the searching part of the SQL query. It will also return the Full-Text query strings should they be required. The parameters are:
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$query -- the query string.
*$columns -- the column names to search.
*$sql -- the sql query to append to. (optional)
And an example of how it can be put to use:
<pre>
$sql = 'SELECT ... FROM ... WHERE ... ';
$columns = array('title','bodytext');
list($sql,$ftsql) = buildSearchSQL('any', 'my geeklog', $columns, $sql);

// $sql => SELECT ... FROM ... WHERE ... AND ((title LIKE '%my%' OR bodytext LIKE '%my%') OR (title LIKE '%geeklog%' OR bodytext LIKE '%geeklog%'))
// $ftsql[mysql] => SELECT ... FROM ... WHERE ... AND MATCH(title,bodytext) AGAINST ('my geeklog' IN BOOLEAN MODE)
// $ftsql[mssql] => SELECT ... FROM ... WHERE ... AND CONTAINS((title,bodytext), '"my" OR "geeklog"')
</pre>
A proper example of its use is at the bottom of the page.

===== Enabling URL Rewrite =====
If the plugin requires the URL to be passed through the COM_buildUrl() function then it should set the setURLRewrite() function to true. For example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setURLRewrite(true);</pre>

===== Returning Multiple Objects =====
In some cases a plugin may be required to search across two or more tables that have no relation with one another. To accommodate this they may return an array of SearchCriteria() objects, each with a different SQL query. To allow the user to differentiate between the results an array of names can be passed, each name will be a separate sub group and will be appended to one another using the separator from the configuration.
The following example shows how this works:
<pre>
// Search the main table
// These results will be labelled 'My Plugin > Main'
$search_main = new SearchCriteria('myplugin', array('My Plugin', 'Main'));
$plugin_main->setSQL($sql_main);
$plugin_main->setFTSQL($ftsql_main);
$plugin_main->setRank(4);

// Search a sub tables
// These results will be labelled 'My Plugin > Sub'
$search_sub = new SearchCriteria('myplugin', array('My Plugin', 'Sub'));
$search_sub->setSQL($sql_sub);
$search_sub->setFTSQL($ftsql_sub);
$search_sub->setRank(4);

// Return both objects
return array($search_main, $search_sub);
</pre>
Note: The plugin identifier needs to stay the same across all objects, in this case 'myplugin'.

==== A Working Example ====
This example searches the Stories. Although it's not a plugin, it puts to use everything discussed here so it's a good example of how to implement the API in your plugin.
<pre>function plugin_dopluginsearch_searchStories($query, $datestart, $dateend, $topic, $type, $author, $keyType, $page, $perpage)
{
global $_TABLES, $_DB_dbms, $LANG09;

// Make sure the query is SQL safe
$query = trim(addslashes($query));

// Build the first part of the query
$sql = "SELECT
s.sid AS id,
s.title AS title,
s.introtext AS description,
UNIX_TIMESTAMP(s.date) AS date,
s.uid AS uid,
s.hits AS hits,
CONCAT('/article.php?story=',s.sid) AS url ";
$sql .= "FROM {$_TABLES['stories']} AS s, {$_TABLES['users']} AS u ";
$sql .= "WHERE (draft_flag = 0) AND (date <= NOW()) AND (u.uid = s.uid) ";
$sql .= COM_getPermSQL('AND') . COM_getTopicSQL('AND') . COM_getLangSQL('sid', 'AND') . ' ';

// If we are searching by date add that too
if (!empty($datestart) && !empty($dateend)) {
$delim = substr($datestart, 4, 1);
if (!empty($delim)) {
$DS = explode($delim, $datestart);
$DE = explode($delim, $dateend);
$startdate = mktime(0,0,0,$DS[1],$DS[2],$DS[0]);
$enddate = mktime(23,59,59,$DE[1],$DE[2],$DE[0]);
$sql .= "AND (UNIX_TIMESTAMP(date) BETWEEN '$startdate' AND '$enddate') ";
}
}
if (!empty($topic)) {
$sql .= "AND (s.tid = '$topic') ";
}
if (!empty($author)) {
$sql .= "AND (s.uid = '$author') ";
}

// Create a SearchCriteria instance with the name of the plugin
$search = new SearchCriteria('stories', $LANG09[65]);

// These are the columns in the table that need searching
$columns = array('introtext','bodytext','title');

// Get back the completed SQL query
list($sql,$ftsql) = $search->buildSearchSQL($keyType, $query, $columns, $sql);

// Set the Std. SQL Query
$search->setSQL($sql);

// Set the Full-Text Query, remember the columns _MUST_ be indexed first. If they are not then don't set this.
$search->setFTSQL($ftsql);

// Finally set a high ranking, enable URLRewrite and return the object.
$search->setRank(5);
$search->setURLRewrite(true);
return $search;
}</pre>

For more examples, there's a forum post ({{forum|87624}}) with updated search functions for the [[FAQ Manager Plugin|FAQ Manager]], [[Forum Plugin|Forum]], and [[File Management Plugin|File Management]] plugins.

[[Category:Plugin Development]]

Using Geeklog's Improved Search Engine

2009-05-26T12:33:16Z

LWC: /* Plugins' compatibility with old Geeklog versions */

==Plugins' compatibility with old Geeklog versions==
If you want to make your plugin compatible with Geeklog v1.5 and below, you must also implement [[Using Geeklog's Search Engine]].

==The functions==
Tying your plugin into Geeklogs search API is rather easy. Easy, that is, if you know how to search
your plugins data already. The Geeklog search API provides a way for you to return the SQL query back to Geeklog which will be executed in the core and the results included in its search page.

For the data in your plugin to be searched by Geeklog's search functions, there are two functions that you need to implement in your plugins function.inc:

*plugin_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
*plugin_dopluginsearch_{plugin_name}() returns the search SQL query back to Geeklog.

Let's look at each of them in turn:

=== plugin_searchtypes_{plugin_name}() ===

This function takes no parameters and returns an associative array of the search type. The normal code for this
function will make it all clear. Normally the function looks like this:

<pre>function plugin_searchtypes_{plugin_name}()
{
global $LANG_PL00;
$tmp['{plugin_name}']= $LANG_PL00['searchtype'];
return $tmp;
}</pre>
<sup>(don't forget to replace {plugin_name} with the actual name).</sup>

Naturally all occurrences of plugin would be replaced with the name of your
plugin and the LANGUAGE varible $LANG_PL00 is just an example. Your Plugin needs
to use a unique variable name so replace PL00.

The return array is of the format array['searchtype'] = 'Search Description', where searchtype
is returned to your plugin search routine and Description is displayed in the
Search Page Drop Down box.

You can have multiple search types and descriptions.

=== plugin_dopluginsearch_{plugin_name}() ===
This section will outline the method used to search a plugin's data.

==== Input Parameters ====
The parameters that are passed to this function are as follows:
*$query -- a string containing the search term.
*$datestart -- starting date to begin search.
*$dateend -- ending date to end search.
*$topic -- topic item is assigned to.
*$type -- no longer used, deprecated.
*$author -- the user id of the author.
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$page -- no longer used, deprecated.
*$perpage -- no longer used, deprecated.

Depending on your plugin, some of these criteria may be meaningless and thus ignored. The function should then perform two basic operations:
#Build search SQL string using the input parameters.
#Return the query along with some plugin information.

==== Returned Values ====
The search API requires the following information to be returned by the plugin_dopluginsearch_{plugin_name}() function:

===== Plugin Name =====
* A name to display to the user, i.e. 'My Plugin' (singular preferred)
* A name used locally to identify the plugin, i.e. 'myplugin'

===== A Search Rank =====
* An integer between 1 and 5 based on how many result to extract from the query.
As all the results have been combined into a single list, the core needs to prioritise important plugins to non important ones. The higher the ranking the more results will be displayed to the user. A rank of 1 will show fewer results, where as a rank of 5 shows the most amount of results from the plugin. The rank is optional, if it's not provided it will default to 3.
Here is an example of Geeklog setup with three plugins, the different rank values will allow varying results from each plugin. The results page is set to display a total of 50 results.
plugin rank results
---------------------------
stories 5 23
forums 4 18
comments 2 9

===== Standard SQL Query =====
* A string containing a single query.
* OR An array of two queries for both MSSQL and MySQL DBMS.
All SQL queries returned should be without the LIMIT and ORDER BY clauses. The SQL query must have the following column names and look like:
<pre>SELECT id, title, description, date, user, hits, url FROM ... WHERE ...</pre>
If a column does not exist in the table then another value should be substituted, for example: '0' AS hits, ...

The url is where to take the user when they have clicked a result. It should start with a single slash if the target is within the current domain. Otherwise the result with be printed, as is, in the href attribute of the link. For example this url belongs to the Geeklog site
<pre>CONCAT('/staticpages/index.php?page=', sp.sp_id) AS url</pre>
However the Links plugin needs to direct users to external sites when clicked, so providing the url from the database will suffice.

===== Full-Text SQL Query (optional) =====
* An array of two queries for both MSSQL and MySQL DBMS using the Full-Text search method.
This search method will take advantage of Full-Text indexes which will reduce search times. This should only be returned if the columns being searched have been properly indexed. The Full-Text SQL Query will only be executed if Full-Text searches have been enabled by the admin during the installation or upgrading process, otherwise the core will always fall back to the Standard SQL Query.

==== The SearchCriteria() Class ====
The process of returning the values is done by initializing a SearchCriteria() object, setting the parameters for the search then returning the object. Here is an example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setFTSQL($ftsql);
$search->setRank(4);</pre>
This indicates that the 'myplugin' plugin supports Full-Text searches and will have a ranking of 4.

===== buildSearchSQL() Function =====
As a lot of the plugins will be processing the same or similar SQL queries the buildSearchSQL() function has been provided to simplify things. This function will take four parameters then build the searching part of the SQL query. It will also return the Full-Text query strings should they be required. The parameters are:
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$query -- the query string.
*$columns -- the column names to search.
*$sql -- the sql query to append to. (optional)
And an example of how it can be put to use:
<pre>
$sql = 'SELECT ... FROM ... WHERE ... ';
$columns = array('title','bodytext');
list($sql,$ftsql) = buildSearchSQL('any', 'my geeklog', $columns, $sql);

// $sql => SELECT ... FROM ... WHERE ... AND ((title LIKE '%my%' OR bodytext LIKE '%my%') OR (title LIKE '%geeklog%' OR bodytext LIKE '%geeklog%'))
// $ftsql[mysql] => SELECT ... FROM ... WHERE ... AND MATCH(title,bodytext) AGAINST ('my geeklog' IN BOOLEAN MODE)
// $ftsql[mssql] => SELECT ... FROM ... WHERE ... AND CONTAINS((title,bodytext), '"my" OR "geeklog"')
</pre>
A proper example of its use is at the bottom of the page.

===== Enabling URL Rewrite =====
If the plugin requires the URL to be passed through the COM_buildUrl() function then it should set the setURLRewrite() function to true. For example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setURLRewrite(true);</pre>

===== Returning Multiple Objects =====
In some cases a plugin may be required to search across two or more tables that have no relation with one another. To accommodate this they may return an array of SearchCriteria() objects, each with a different SQL query. To allow the user to differentiate between the results an array of names can be passed, each name will be a separate sub group and will be appended to one another using the separator from the configuration.
The following example shows how this works:
<pre>
// Search the main table
// These results will be labelled 'My Plugin > Main'
$search_main = new SearchCriteria('myplugin', array('My Plugin', 'Main'));
$plugin_main->setSQL($sql_main);
$plugin_main->setFTSQL($ftsql_main);
$plugin_main->setRank(4);

// Search a sub tables
// These results will be labelled 'My Plugin > Sub'
$search_sub = new SearchCriteria('myplugin', array('My Plugin', 'Sub'));
$search_sub->setSQL($sql_sub);
$search_sub->setFTSQL($ftsql_sub);
$search_sub->setRank(4);

// Return both objects
return array($search_main, $search_sub);
</pre>
Note: The plugin identifier needs to stay the same across all objects, in this case 'myplugin'.

==== A Working Example ====
This example searches the Stories. Although it's not a plugin, it puts to use everything discussed here so it's a good example of how to implement the API in your plugin.
<pre>function plugin_dopluginsearch_searchStories($query, $datestart, $dateend, $topic, $type, $author, $keyType, $page, $perpage)
{
global $_TABLES, $_DB_dbms, $LANG09;

// Make sure the query is SQL safe
$query = trim(addslashes($query));

// Build the first part of the query
$sql = "SELECT
s.sid AS id,
s.title AS title,
s.introtext AS description,
UNIX_TIMESTAMP(s.date) AS date,
s.uid AS uid,
s.hits AS hits,
CONCAT('/article.php?story=',s.sid) AS url ";
$sql .= "FROM {$_TABLES['stories']} AS s, {$_TABLES['users']} AS u ";
$sql .= "WHERE (draft_flag = 0) AND (date <= NOW()) AND (u.uid = s.uid) ";
$sql .= COM_getPermSQL('AND') . COM_getTopicSQL('AND') . COM_getLangSQL('sid', 'AND') . ' ';

// If we are searching by date add that too
if (!empty($datestart) && !empty($dateend)) {
$delim = substr($datestart, 4, 1);
if (!empty($delim)) {
$DS = explode($delim, $datestart);
$DE = explode($delim, $dateend);
$startdate = mktime(0,0,0,$DS[1],$DS[2],$DS[0]);
$enddate = mktime(23,59,59,$DE[1],$DE[2],$DE[0]);
$sql .= "AND (UNIX_TIMESTAMP(date) BETWEEN '$startdate' AND '$enddate') ";
}
}
if (!empty($topic)) {
$sql .= "AND (s.tid = '$topic') ";
}
if (!empty($author)) {
$sql .= "AND (s.uid = '$author') ";
}

// Create a SearchCriteria instance with the name of the plugin
$search = new SearchCriteria('stories', $LANG09[65]);

// These are the columns in the table that need searching
$columns = array('introtext','bodytext','title');

// Get back the completed SQL query
list($sql,$ftsql) = $search->buildSearchSQL($keyType, $query, $columns, $sql);

// Set the Std. SQL Query
$search->setSQL($sql);

// Set the Full-Text Query, remember the columns _MUST_ be indexed first. If they are not then don't set this.
$search->setFTSQL($ftsql);

// Finally set a high ranking, enable URLRewrite and return the object.
$search->setRank(5);
$search->setURLRewrite(true);
return $search;
}</pre>

For more examples, there's a forum post ({{forum|87624}}) with updated search functions for the [[FAQ Manager Plugin|FAQ Manager]], [[Forum Plugin|Forum]], and [[File Management Plugin|File Management]] plugins.

[[Category:Plugin Development]]

Template:Forum

2009-05-26T12:32:45Z

LWC: /* Usage */

<includeonly>http://www.geeklog.net/forum/viewtopic.php?showtopic={{{1}}}</includeonly><noinclude>Supply an forum ID from the main site and get a link for it.

==Usage==
<pre><nowiki>{{forum|forumID}}</nowiki></pre>

For example, <nowiki>{{forum|9778}}</nowiki> would display as:

{{forum|9778}}
</noinclude>

Using Geeklog's Search Engine

2009-05-26T12:26:37Z

LWC: /* New method */

==Old method==
This method is meant for Geeklog v1.5 and below.

===The functions===
Tying your plugin into Geeklogs search API is rather easy. Easy, that is, if you know how search your plugins data already. The Geeklog search API provides a way for you to return your search results back to Geeklog to be included in its search results page.

For the data in your plugin to be searched by Geeklogs search functions, there are two functions that you need to implement in your plugins function.inc:

* plugin_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
* plugin_dopluginsearch_{plugin_name}() returns the actual results to Geeklog.

Let's look at each of them in turn:

==== plugin_searchtypes_{plugin_name}() ====

This function takes no parameters and returns an associative array of the search type. The normal code for this
function will make it all clear. Normally the function looks like this:

<pre>
function plugin_searchtypes_{plugin_name}() {
global $LANG_PL00;
$tmp['{plugin_name}']= $LANG_PL00['searchtype'];
return $tmp;
}
</pre>
<sup>(don't forget to replace {plugin_name} with the actual name).</sup>

Naturally all occurrences of plugin would be replaced with the name of your plugin and the LANGUAGE varible $LANG_PL00 is just an example. Your Plugin needs to use a unique variable name so replace PL00.

The return array is of the format array['searchtype'] = 'Search Description', where searchtype is returned to your plugin search routine and Description is displayed in the Search Page Drop Down box.

You can have multiple search types and descriptions.

==== plugin_dopluginsearch_{plugin_name}() ====

This function is where the search is actually done. It is passed a number of parameters that can be used in your search. They are:

* $query -- the actual items being searched for.
* $datestart -- starting date to begin search.
* $dateend -- ending date to end search.
* $topic -- topic item is assigned to.
* $type -- type of item (see searchtypes above).
* $author -- author of item.

Depending on your plugin, some of these criteria may be meaningless and thus ignored. Here is a brief overview of what your function should do.

# Initialize plugin object
# Check to see if type is appropriate for this plugin -- if not, bail out.
# Get a list of all your items to search.
# Create Search object and Build search results header.
# Search each of your items in turn.
# If a match then add item to the results.
# When done set number of results and return search object

Looking at the example code should make all of this clear. The search results are returned in a object of type Plugin. You initialize the object by setting the Label and then setting the names of the columns you want returned. This is done in typical object fashion with this construct: $plugin->addSearch Heading.

The headings will vary according to what your plugin does, but should include a link to the item found. After searching each of your items in turn; you add your search results to an array having the same number of items as the labels you set earlier.

Note: your search should be case insensitive to be compatible with Geeklogs search. This array will correspond to the column headings entered above. In the example below, the array consists of the Title of the page, the url to the page (a link) and the number of hits. This array is then added to the Plugin object as a row.

The following construct is used: $plugin->addSearchResult.
When you are done searching you set the number of rows found and the number searched to the plugin object and return it. The example below is from the External Pages Plugin.

<pre>
function plugin_dopluginsearch_external($query,$datestart,$dateend,$topic,$type,$author)
{
global $_TABLES, $_CONF, $LANG_EX00;

if (empty($type)) {
$type = 'all';
}

// Bail if we aren't supppose to do our search
if ($type <> 'all' AND $type <> 'external') {
$plugin_results = new Plugin();
$plugin_results->plugin_name = 'external';
$plugin_results->searchlabel = $LANG_EX00['externpages'] . $LANG_EX00['results'];
return $plugin_results;
}

// Build search SQL - Modified to exclude static PHP pages from search.
$sql = "SELECT * from " . $_TABLES['external'];
$result = DB_query($sql);

// OK, now create new plugin object and insert table header labels
require_once($_CONF['path_system'] . 'classes/plugin.class.php');
$plugin_results = new Plugin();
$plugin_results->plugin_name = 'external';
$plugin_results->searchlabel = $LANG_EX00['externpages'] . $LANG_EX00['results'];
$plugin_results->addSearchHeading($LANG_EX00['titlemsg']);
$plugin_results->addSearchHeading($LANG_EX00['urlmsg']);
$plugin_results->addSearchHeading($LANG_EX00['hitsmsg']);
$mycount = DB_numRows($result);
// NOTE if any of your data items need to be links then add them here!
// make sure data elements are in an array and in the same order as your
// headings above!
for ($i = 1; $i <= $mycount; $i++) {
$A = DB_fetchArray($result);

if(SEC_hasAccess($A[owner_id],$A[group_id],$A[perm_owner],$A[perm_group],$A[perm_members],$A[perm_anon])){
if (preg_match("/^(http:\/\/)/i",$A['url']) == 1) {
$pth = $A['url'];
$url = $A['url'];
} else {
$pth = $_CONF['path_html'] . $A['url'];
$url = $_CONF['site_url'] . '/' . $A['url'];
}
$cnts = implode('',file($pth));
if (stristr($cnts,$query) != '') {
$rcnt++;
$A['title'] = stripslashes($A['title']);
$row = array($A['title'],
'<a href="' . $url . '">' . $A['url'] . "</a>",
$A['hits']);
$plugin_results->addSearchResult($row);
}
}

}
$plugin_results->num_searchresults = $rcnt;
$plugin_results->num_itemssearched = DB_count($_TABLES['external']);

return $plugin_results;
}
</pre>

==New method==
This method only works in Geeklog v1.6 and above.

There is an updated API which makes use of the new and improved '''SearchCriteria()''' class. See [[Using Geeklog's Improved Search Engine]].

[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Using Geeklog's Improved Search Engine

2009-05-26T12:22:26Z

LWC: Formatted

==Plugins' compatibility with old Geeklog versions==
If you want to make your plugin compatible with Geeklog v1.5 and below, you must also implement [[Using Geeklog's Search Engine?]].

==The functions==
Tying your plugin into Geeklogs search API is rather easy. Easy, that is, if you know how to search
your plugins data already. The Geeklog search API provides a way for you to return the SQL query back to Geeklog which will be executed in the core and the results included in its search page.

For the data in your plugin to be searched by Geeklog's search functions, there are two functions that you need to implement in your plugins function.inc:

*plugin_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
*plugin_dopluginsearch_{plugin_name}() returns the search SQL query back to Geeklog.

Let's look at each of them in turn:

=== plugin_searchtypes_{plugin_name}() ===

This function takes no parameters and returns an associative array of the search type. The normal code for this
function will make it all clear. Normally the function looks like this:

<pre>function plugin_searchtypes_{plugin_name}()
{
global $LANG_PL00;
$tmp['{plugin_name}']= $LANG_PL00['searchtype'];
return $tmp;
}</pre>
<sup>(don't forget to replace {plugin_name} with the actual name).</sup>

Naturally all occurrences of plugin would be replaced with the name of your
plugin and the LANGUAGE varible $LANG_PL00 is just an example. Your Plugin needs
to use a unique variable name so replace PL00.

The return array is of the format array['searchtype'] = 'Search Description', where searchtype
is returned to your plugin search routine and Description is displayed in the
Search Page Drop Down box.

You can have multiple search types and descriptions.

=== plugin_dopluginsearch_{plugin_name}() ===
This section will outline the method used to search a plugin's data.

==== Input Parameters ====
The parameters that are passed to this function are as follows:
*$query -- a string containing the search term.
*$datestart -- starting date to begin search.
*$dateend -- ending date to end search.
*$topic -- topic item is assigned to.
*$type -- no longer used, deprecated.
*$author -- the user id of the author.
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$page -- no longer used, deprecated.
*$perpage -- no longer used, deprecated.

Depending on your plugin, some of these criteria may be meaningless and thus ignored. The function should then perform two basic operations:
#Build search SQL string using the input parameters.
#Return the query along with some plugin information.

==== Returned Values ====
The search API requires the following information to be returned by the plugin_dopluginsearch_{plugin_name}() function:

===== Plugin Name =====
* A name to display to the user, i.e. 'My Plugin' (singular preferred)
* A name used locally to identify the plugin, i.e. 'myplugin'

===== A Search Rank =====
* An integer between 1 and 5 based on how many result to extract from the query.
As all the results have been combined into a single list, the core needs to prioritise important plugins to non important ones. The higher the ranking the more results will be displayed to the user. A rank of 1 will show fewer results, where as a rank of 5 shows the most amount of results from the plugin. The rank is optional, if it's not provided it will default to 3.
Here is an example of Geeklog setup with three plugins, the different rank values will allow varying results from each plugin. The results page is set to display a total of 50 results.
plugin rank results
---------------------------
stories 5 23
forums 4 18
comments 2 9

===== Standard SQL Query =====
* A string containing a single query.
* OR An array of two queries for both MSSQL and MySQL DBMS.
All SQL queries returned should be without the LIMIT and ORDER BY clauses. The SQL query must have the following column names and look like:
<pre>SELECT id, title, description, date, user, hits, url FROM ... WHERE ...</pre>
If a column does not exist in the table then another value should be substituted, for example: '0' AS hits, ...

The url is where to take the user when they have clicked a result. It should start with a single slash if the target is within the current domain. Otherwise the result with be printed, as is, in the href attribute of the link. For example this url belongs to the Geeklog site
<pre>CONCAT('/staticpages/index.php?page=', sp.sp_id) AS url</pre>
However the Links plugin needs to direct users to external sites when clicked, so providing the url from the database will suffice.

===== Full-Text SQL Query (optional) =====
* An array of two queries for both MSSQL and MySQL DBMS using the Full-Text search method.
This search method will take advantage of Full-Text indexes which will reduce search times. This should only be returned if the columns being searched have been properly indexed. The Full-Text SQL Query will only be executed if Full-Text searches have been enabled by the admin during the installation or upgrading process, otherwise the core will always fall back to the Standard SQL Query.

==== The SearchCriteria() Class ====
The process of returning the values is done by initializing a SearchCriteria() object, setting the parameters for the search then returning the object. Here is an example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setFTSQL($ftsql);
$search->setRank(4);</pre>
This indicates that the 'myplugin' plugin supports Full-Text searches and will have a ranking of 4.

===== buildSearchSQL() Function =====
As a lot of the plugins will be processing the same or similar SQL queries the buildSearchSQL() function has been provided to simplify things. This function will take four parameters then build the searching part of the SQL query. It will also return the Full-Text query strings should they be required. The parameters are:
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$query -- the query string.
*$columns -- the column names to search.
*$sql -- the sql query to append to. (optional)
And an example of how it can be put to use:
<pre>
$sql = 'SELECT ... FROM ... WHERE ... ';
$columns = array('title','bodytext');
list($sql,$ftsql) = buildSearchSQL('any', 'my geeklog', $columns, $sql);

// $sql => SELECT ... FROM ... WHERE ... AND ((title LIKE '%my%' OR bodytext LIKE '%my%') OR (title LIKE '%geeklog%' OR bodytext LIKE '%geeklog%'))
// $ftsql[mysql] => SELECT ... FROM ... WHERE ... AND MATCH(title,bodytext) AGAINST ('my geeklog' IN BOOLEAN MODE)
// $ftsql[mssql] => SELECT ... FROM ... WHERE ... AND CONTAINS((title,bodytext), '"my" OR "geeklog"')
</pre>
A proper example of its use is at the bottom of the page.

===== Enabling URL Rewrite =====
If the plugin requires the URL to be passed through the COM_buildUrl() function then it should set the setURLRewrite() function to true. For example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setURLRewrite(true);</pre>

===== Returning Multiple Objects =====
In some cases a plugin may be required to search across two or more tables that have no relation with one another. To accommodate this they may return an array of SearchCriteria() objects, each with a different SQL query. To allow the user to differentiate between the results an array of names can be passed, each name will be a separate sub group and will be appended to one another using the separator from the configuration.
The following example shows how this works:
<pre>
// Search the main table
// These results will be labelled 'My Plugin > Main'
$search_main = new SearchCriteria('myplugin', array('My Plugin', 'Main'));
$plugin_main->setSQL($sql_main);
$plugin_main->setFTSQL($ftsql_main);
$plugin_main->setRank(4);

// Search a sub tables
// These results will be labelled 'My Plugin > Sub'
$search_sub = new SearchCriteria('myplugin', array('My Plugin', 'Sub'));
$search_sub->setSQL($sql_sub);
$search_sub->setFTSQL($ftsql_sub);
$search_sub->setRank(4);

// Return both objects
return array($search_main, $search_sub);
</pre>
Note: The plugin identifier needs to stay the same across all objects, in this case 'myplugin'.

==== A Working Example ====
This example searches the Stories. Although it's not a plugin, it puts to use everything discussed here so it's a good example of how to implement the API in your plugin.
<pre>function plugin_dopluginsearch_searchStories($query, $datestart, $dateend, $topic, $type, $author, $keyType, $page, $perpage)
{
global $_TABLES, $_DB_dbms, $LANG09;

// Make sure the query is SQL safe
$query = trim(addslashes($query));

// Build the first part of the query
$sql = "SELECT
s.sid AS id,
s.title AS title,
s.introtext AS description,
UNIX_TIMESTAMP(s.date) AS date,
s.uid AS uid,
s.hits AS hits,
CONCAT('/article.php?story=',s.sid) AS url ";
$sql .= "FROM {$_TABLES['stories']} AS s, {$_TABLES['users']} AS u ";
$sql .= "WHERE (draft_flag = 0) AND (date <= NOW()) AND (u.uid = s.uid) ";
$sql .= COM_getPermSQL('AND') . COM_getTopicSQL('AND') . COM_getLangSQL('sid', 'AND') . ' ';

// If we are searching by date add that too
if (!empty($datestart) && !empty($dateend)) {
$delim = substr($datestart, 4, 1);
if (!empty($delim)) {
$DS = explode($delim, $datestart);
$DE = explode($delim, $dateend);
$startdate = mktime(0,0,0,$DS[1],$DS[2],$DS[0]);
$enddate = mktime(23,59,59,$DE[1],$DE[2],$DE[0]);
$sql .= "AND (UNIX_TIMESTAMP(date) BETWEEN '$startdate' AND '$enddate') ";
}
}
if (!empty($topic)) {
$sql .= "AND (s.tid = '$topic') ";
}
if (!empty($author)) {
$sql .= "AND (s.uid = '$author') ";
}

// Create a SearchCriteria instance with the name of the plugin
$search = new SearchCriteria('stories', $LANG09[65]);

// These are the columns in the table that need searching
$columns = array('introtext','bodytext','title');

// Get back the completed SQL query
list($sql,$ftsql) = $search->buildSearchSQL($keyType, $query, $columns, $sql);

// Set the Std. SQL Query
$search->setSQL($sql);

// Set the Full-Text Query, remember the columns _MUST_ be indexed first. If they are not then don't set this.
$search->setFTSQL($ftsql);

// Finally set a high ranking, enable URLRewrite and return the object.
$search->setRank(5);
$search->setURLRewrite(true);
return $search;
}</pre>

For more examples, there's a forum post ({{forum|87624}}) with updated search functions for the [[FAQ Manager Plugin|FAQ Manager]], [[Forum Plugin|Forum]], and [[File Management Plugin|File Management]] plugins.

[[Category:Plugin Development]]

Using Geeklog's Improved Search Engine

2009-05-26T12:17:07Z

LWC: /* plugin_searchtypes_{plugin_name}() */ Fixed

Tying your plugin into Geeklogs search API is rather easy. Easy, that is, if you know how to search
your plugins data already. The Geeklog search API provides a way for you to return the SQL query back to Geeklog which will be executed in the core and the results included in its search page.

For the data in your plugin to be searched by Geeklog's search functions, there are two functions that you need to implement in your plugins function.inc:

*plugin_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
*plugin_dopluginsearch_{plugin_name}() returns the search SQL query back to Geeklog.

Let's look at each of them in turn:

== plugin_searchtypes_{plugin_name}() ==

This function takes no parameters and returns an associative array of the search type. The normal code for this
function will make it all clear. Normally the function looks like this:

<pre>function plugin_searchtypes_{plugin_name}()
{
global $LANG_PL00;
$tmp['{plugin_name}']= $LANG_PL00['searchtype'];
return $tmp;
}</pre>
<sup>(don't forget to replace {plugin_name} with the actual name).</sup>

Naturally all occurrences of plugin would be replaced with the name of your
plugin and the LANGUAGE varible $LANG_PL00 is just an example. Your Plugin needs
to use a unique variable name so replace PL00.

The return array is of the format array['searchtype'] = 'Search Description', where searchtype
is returned to your plugin search routine and Description is displayed in the
Search Page Drop Down box.

You can have multiple search types and descriptions.

== plugin_dopluginsearch_{plugin_name}() ==
This section will outline the method used to search a plugin's data.

=== Input Parameters ===
The parameters that are passed to this function are as follows:
*$query -- a string containing the search term.
*$datestart -- starting date to begin search.
*$dateend -- ending date to end search.
*$topic -- topic item is assigned to.
*$type -- no longer used, deprecated.
*$author -- the user id of the author.
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$page -- no longer used, deprecated.
*$perpage -- no longer used, deprecated.

Depending on your plugin, some of these criteria may be meaningless and thus ignored. The function should then perform two basic operations:
#Build search SQL string using the input parameters.
#Return the query along with some plugin information.

=== Returned Values ===
The search API requires the following information to be returned by the plugin_dopluginsearch_{plugin_name}() function:

==== Plugin Name ====
* A name to display to the user, i.e. 'My Plugin' (singular preferred)
* A name used locally to identify the plugin, i.e. 'myplugin'

==== A Search Rank ====
* An integer between 1 and 5 based on how many result to extract from the query.
As all the results have been combined into a single list, the core needs to prioritise important plugins to non important ones. The higher the ranking the more results will be displayed to the user. A rank of 1 will show fewer results, where as a rank of 5 shows the most amount of results from the plugin. The rank is optional, if it's not provided it will default to 3.
Here is an example of Geeklog setup with three plugins, the different rank values will allow varying results from each plugin. The results page is set to display a total of 50 results.
plugin rank results
---------------------------
stories 5 23
forums 4 18
comments 2 9

==== Standard SQL Query ====
* A string containing a single query.
* OR An array of two queries for both MSSQL and MySQL DBMS.
All SQL queries returned should be without the LIMIT and ORDER BY clauses. The SQL query must have the following column names and look like:
<pre>SELECT id, title, description, date, user, hits, url FROM ... WHERE ...</pre>
If a column does not exist in the table then another value should be substituted, for example: '0' AS hits, ...

The url is where to take the user when they have clicked a result. It should start with a single slash if the target is within the current domain. Otherwise the result with be printed, as is, in the href attribute of the link. For example this url belongs to the Geeklog site
<pre>CONCAT('/staticpages/index.php?page=', sp.sp_id) AS url</pre>
However the Links plugin needs to direct users to external sites when clicked, so providing the url from the database will suffice.

==== Full-Text SQL Query (optional) ====
* An array of two queries for both MSSQL and MySQL DBMS using the Full-Text search method.
This search method will take advantage of Full-Text indexes which will reduce search times. This should only be returned if the columns being searched have been properly indexed. The Full-Text SQL Query will only be executed if Full-Text searches have been enabled by the admin during the installation or upgrading process, otherwise the core will always fall back to the Standard SQL Query.

=== The SearchCriteria() Class ===
The process of returning the values is done by initializing a SearchCriteria() object, setting the parameters for the search then returning the object. Here is an example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setFTSQL($ftsql);
$search->setRank(4);</pre>
This indicates that the 'myplugin' plugin supports Full-Text searches and will have a ranking of 4.

==== buildSearchSQL() Function ====
As a lot of the plugins will be processing the same or similar SQL queries the buildSearchSQL() function has been provided to simplify things. This function will take four parameters then build the searching part of the SQL query. It will also return the Full-Text query strings should they be required. The parameters are:
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$query -- the query string.
*$columns -- the column names to search.
*$sql -- the sql query to append to. (optional)
And an example of how it can be put to use:
<pre>
$sql = 'SELECT ... FROM ... WHERE ... ';
$columns = array('title','bodytext');
list($sql,$ftsql) = buildSearchSQL('any', 'my geeklog', $columns, $sql);

// $sql => SELECT ... FROM ... WHERE ... AND ((title LIKE '%my%' OR bodytext LIKE '%my%') OR (title LIKE '%geeklog%' OR bodytext LIKE '%geeklog%'))
// $ftsql[mysql] => SELECT ... FROM ... WHERE ... AND MATCH(title,bodytext) AGAINST ('my geeklog' IN BOOLEAN MODE)
// $ftsql[mssql] => SELECT ... FROM ... WHERE ... AND CONTAINS((title,bodytext), '"my" OR "geeklog"')
</pre>
A proper example of its use is at the bottom of the page.

==== Enabling URL Rewrite ====
If the plugin requires the URL to be passed through the COM_buildUrl() function then it should set the setURLRewrite() function to true. For example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setURLRewrite(true);</pre>

==== Returning Multiple Objects ====
In some cases a plugin may be required to search across two or more tables that have no relation with one another. To accommodate this they may return an array of SearchCriteria() objects, each with a different SQL query. To allow the user to differentiate between the results an array of names can be passed, each name will be a separate sub group and will be appended to one another using the separator from the configuration.
The following example shows how this works:
<pre>
// Search the main table
// These results will be labelled 'My Plugin > Main'
$search_main = new SearchCriteria('myplugin', array('My Plugin', 'Main'));
$plugin_main->setSQL($sql_main);
$plugin_main->setFTSQL($ftsql_main);
$plugin_main->setRank(4);

// Search a sub tables
// These results will be labelled 'My Plugin > Sub'
$search_sub = new SearchCriteria('myplugin', array('My Plugin', 'Sub'));
$search_sub->setSQL($sql_sub);
$search_sub->setFTSQL($ftsql_sub);
$search_sub->setRank(4);

// Return both objects
return array($search_main, $search_sub);
</pre>
Note: The plugin identifier needs to stay the same across all objects, in this case 'myplugin'.

=== A Working Example ===
This example searches the Stories, although it's not a plugin it puts to use everything discussed here so it's a good example of how to implement the API in your plugin.
<pre>function plugin_dopluginsearch_searchStories($query, $datestart, $dateend, $topic, $type, $author, $keyType, $page, $perpage)
{
global $_TABLES, $_DB_dbms, $LANG09;

// Make sure the query is SQL safe
$query = trim(addslashes($query));

// Build the first part of the query
$sql = "SELECT
s.sid AS id,
s.title AS title,
s.introtext AS description,
UNIX_TIMESTAMP(s.date) AS date,
s.uid AS uid,
s.hits AS hits,
CONCAT('/article.php?story=',s.sid) AS url ";
$sql .= "FROM {$_TABLES['stories']} AS s, {$_TABLES['users']} AS u ";
$sql .= "WHERE (draft_flag = 0) AND (date <= NOW()) AND (u.uid = s.uid) ";
$sql .= COM_getPermSQL('AND') . COM_getTopicSQL('AND') . COM_getLangSQL('sid', 'AND') . ' ';

// If we are searching by date add that too
if (!empty($datestart) && !empty($dateend)) {
$delim = substr($datestart, 4, 1);
if (!empty($delim)) {
$DS = explode($delim, $datestart);
$DE = explode($delim, $dateend);
$startdate = mktime(0,0,0,$DS[1],$DS[2],$DS[0]);
$enddate = mktime(23,59,59,$DE[1],$DE[2],$DE[0]);
$sql .= "AND (UNIX_TIMESTAMP(date) BETWEEN '$startdate' AND '$enddate') ";
}
}
if (!empty($topic)) {
$sql .= "AND (s.tid = '$topic') ";
}
if (!empty($author)) {
$sql .= "AND (s.uid = '$author') ";
}

// Create a SearchCriteria instance with the name of the plugin
$search = new SearchCriteria('stories', $LANG09[65]);

// These are the columns in the table that need searching
$columns = array('introtext','bodytext','title');

// Get back the completed SQL query
list($sql,$ftsql) = $search->buildSearchSQL($keyType, $query, $columns, $sql);

// Set the Std. SQL Query
$search->setSQL($sql);

// Set the Full-Text Query, remember the columns _MUST_ be indexed first. If they are not then don't set this.
$search->setFTSQL($ftsql);

// Finally set a high ranking, enable URLRewrite and return the object.
$search->setRank(5);
$search->setURLRewrite(true);
return $search;
}</pre>

For more examples, there's a forum post ({{forum|87624}}) with updated search functions for the [[FAQ Manager Plugin|FAQ Manager]], [[Forum Plugin|Forum]], and [[File Management Plugin|File Management]] plugins.

[[Category:Plugin Development]]

Using Geeklog's Search Engine

2009-05-26T12:16:30Z

LWC: Formatted

==Old method==
This method is meant for Geeklog v1.5 and below.

===The functions===
Tying your plugin into Geeklogs search API is rather easy. Easy, that is, if you know how search your plugins data already. The Geeklog search API provides a way for you to return your search results back to Geeklog to be included in its search results page.

For the data in your plugin to be searched by Geeklogs search functions, there are two functions that you need to implement in your plugins function.inc:

* plugin_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
* plugin_dopluginsearch_{plugin_name}() returns the actual results to Geeklog.

Let's look at each of them in turn:

==== plugin_searchtypes_{plugin_name}() ====

This function takes no parameters and returns an associative array of the search type. The normal code for this
function will make it all clear. Normally the function looks like this:

<pre>
function plugin_searchtypes_{plugin_name}() {
global $LANG_PL00;
$tmp['{plugin_name}']= $LANG_PL00['searchtype'];
return $tmp;
}
</pre>
<sup>(don't forget to replace {plugin_name} with the actual name).</sup>

Naturally all occurrences of plugin would be replaced with the name of your plugin and the LANGUAGE varible $LANG_PL00 is just an example. Your Plugin needs to use a unique variable name so replace PL00.

The return array is of the format array['searchtype'] = 'Search Description', where searchtype is returned to your plugin search routine and Description is displayed in the Search Page Drop Down box.

You can have multiple search types and descriptions.

==== plugin_dopluginsearch_{plugin_name}() ====

This function is where the search is actually done. It is passed a number of parameters that can be used in your search. They are:

* $query -- the actual items being searched for.
* $datestart -- starting date to begin search.
* $dateend -- ending date to end search.
* $topic -- topic item is assigned to.
* $type -- type of item (see searchtypes above).
* $author -- author of item.

Depending on your plugin, some of these criteria may be meaningless and thus ignored. Here is a brief overview of what your function should do.

# Initialize plugin object
# Check to see if type is appropriate for this plugin -- if not, bail out.
# Get a list of all your items to search.
# Create Search object and Build search results header.
# Search each of your items in turn.
# If a match then add item to the results.
# When done set number of results and return search object

Looking at the example code should make all of this clear. The search results are returned in a object of type Plugin. You initialize the object by setting the Label and then setting the names of the columns you want returned. This is done in typical object fashion with this construct: $plugin->addSearch Heading.

The headings will vary according to what your plugin does, but should include a link to the item found. After searching each of your items in turn; you add your search results to an array having the same number of items as the labels you set earlier.

Note: your search should be case insensitive to be compatible with Geeklogs search. This array will correspond to the column headings entered above. In the example below, the array consists of the Title of the page, the url to the page (a link) and the number of hits. This array is then added to the Plugin object as a row.

The following construct is used: $plugin->addSearchResult.
When you are done searching you set the number of rows found and the number searched to the plugin object and return it. The example below is from the External Pages Plugin.

<pre>
function plugin_dopluginsearch_external($query,$datestart,$dateend,$topic,$type,$author)
{
global $_TABLES, $_CONF, $LANG_EX00;

if (empty($type)) {
$type = 'all';
}

// Bail if we aren't supppose to do our search
if ($type <> 'all' AND $type <> 'external') {
$plugin_results = new Plugin();
$plugin_results->plugin_name = 'external';
$plugin_results->searchlabel = $LANG_EX00['externpages'] . $LANG_EX00['results'];
return $plugin_results;
}

// Build search SQL - Modified to exclude static PHP pages from search.
$sql = "SELECT * from " . $_TABLES['external'];
$result = DB_query($sql);

// OK, now create new plugin object and insert table header labels
require_once($_CONF['path_system'] . 'classes/plugin.class.php');
$plugin_results = new Plugin();
$plugin_results->plugin_name = 'external';
$plugin_results->searchlabel = $LANG_EX00['externpages'] . $LANG_EX00['results'];
$plugin_results->addSearchHeading($LANG_EX00['titlemsg']);
$plugin_results->addSearchHeading($LANG_EX00['urlmsg']);
$plugin_results->addSearchHeading($LANG_EX00['hitsmsg']);
$mycount = DB_numRows($result);
// NOTE if any of your data items need to be links then add them here!
// make sure data elements are in an array and in the same order as your
// headings above!
for ($i = 1; $i <= $mycount; $i++) {
$A = DB_fetchArray($result);

if(SEC_hasAccess($A[owner_id],$A[group_id],$A[perm_owner],$A[perm_group],$A[perm_members],$A[perm_anon])){
if (preg_match("/^(http:\/\/)/i",$A['url']) == 1) {
$pth = $A['url'];
$url = $A['url'];
} else {
$pth = $_CONF['path_html'] . $A['url'];
$url = $_CONF['site_url'] . '/' . $A['url'];
}
$cnts = implode('',file($pth));
if (stristr($cnts,$query) != '') {
$rcnt++;
$A['title'] = stripslashes($A['title']);
$row = array($A['title'],
'<a href="' . $url . '">' . $A['url'] . "</a>",
$A['hits']);
$plugin_results->addSearchResult($row);
}
}

}
$plugin_results->num_searchresults = $rcnt;
$plugin_results->num_itemssearched = DB_count($_TABLES['external']);

return $plugin_results;
}
</pre>

==New method==
This method only works in Geeklog v1.6 and above.

There is an updated API which makes use of the new and improved [[Using Geeklog's Improved Search Engine|SearchCriteria()]] class.

[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Using Geeklog's Improved Search Engine

2009-05-26T12:13:06Z

LWC: /* A Working Example */ Link

Tying your plugin into Geeklogs search API is rather easy. Easy, that is, if you know how to search
your plugins data already. The Geeklog search API provides a way for you to return the SQL query back to Geeklog which will be executed in the core and the results included in its search page.

For the data in your plugin to be searched by Geeklog's search functions, there are two functions that you need to implement in your plugins function.inc:

*plugin_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
*plugin_dopluginsearch_{plugin_name}() returns the search SQL query back to Geeklog.

Let's look at each of them in turn:

== plugin_searchtypes_{plugin_name}() ==

This function takes no parameters and returns an associative array of the search type. The normal code for this
function will make it all clear. Normally the function looks like this:

<pre>function plugin_searchtypes_{plugin_name}()
{
global $LANG_PL00;
$tmp['searchtype']= $LANG_PL00['searchtype'];
return $tmp;
}</pre>

Naturally all occurrences of plugin would be replaced with the name of your
plugin and the LANGUAGE varible $LANG_PL00 is just an example. Your Plugin needs
to use a unique variable name so replace PL00.

The return array is of the format array['searchtype'] = 'Search Description', where searchtype
is returned to your plugin search routine and Description is displayed in the
Search Page Drop Down box.

You can have multiple search types and descriptions.

== plugin_dopluginsearch_{plugin_name}() ==
This section will outline the method used to search a plugin's data.

=== Input Parameters ===
The parameters that are passed to this function are as follows:
*$query -- a string containing the search term.
*$datestart -- starting date to begin search.
*$dateend -- ending date to end search.
*$topic -- topic item is assigned to.
*$type -- no longer used, deprecated.
*$author -- the user id of the author.
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$page -- no longer used, deprecated.
*$perpage -- no longer used, deprecated.

Depending on your plugin, some of these criteria may be meaningless and thus ignored. The function should then perform two basic operations:
#Build search SQL string using the input parameters.
#Return the query along with some plugin information.

=== Returned Values ===
The search API requires the following information to be returned by the plugin_dopluginsearch_{plugin_name}() function:

==== Plugin Name ====
* A name to display to the user, i.e. 'My Plugin' (singular preferred)
* A name used locally to identify the plugin, i.e. 'myplugin'

==== A Search Rank ====
* An integer between 1 and 5 based on how many result to extract from the query.
As all the results have been combined into a single list, the core needs to prioritise important plugins to non important ones. The higher the ranking the more results will be displayed to the user. A rank of 1 will show fewer results, where as a rank of 5 shows the most amount of results from the plugin. The rank is optional, if it's not provided it will default to 3.
Here is an example of Geeklog setup with three plugins, the different rank values will allow varying results from each plugin. The results page is set to display a total of 50 results.
plugin rank results
---------------------------
stories 5 23
forums 4 18
comments 2 9

==== Standard SQL Query ====
* A string containing a single query.
* OR An array of two queries for both MSSQL and MySQL DBMS.
All SQL queries returned should be without the LIMIT and ORDER BY clauses. The SQL query must have the following column names and look like:
<pre>SELECT id, title, description, date, user, hits, url FROM ... WHERE ...</pre>
If a column does not exist in the table then another value should be substituted, for example: '0' AS hits, ...

The url is where to take the user when they have clicked a result. It should start with a single slash if the target is within the current domain. Otherwise the result with be printed, as is, in the href attribute of the link. For example this url belongs to the Geeklog site
<pre>CONCAT('/staticpages/index.php?page=', sp.sp_id) AS url</pre>
However the Links plugin needs to direct users to external sites when clicked, so providing the url from the database will suffice.

==== Full-Text SQL Query (optional) ====
* An array of two queries for both MSSQL and MySQL DBMS using the Full-Text search method.
This search method will take advantage of Full-Text indexes which will reduce search times. This should only be returned if the columns being searched have been properly indexed. The Full-Text SQL Query will only be executed if Full-Text searches have been enabled by the admin during the installation or upgrading process, otherwise the core will always fall back to the Standard SQL Query.

=== The SearchCriteria() Class ===
The process of returning the values is done by initializing a SearchCriteria() object, setting the parameters for the search then returning the object. Here is an example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setFTSQL($ftsql);
$search->setRank(4);</pre>
This indicates that the 'myplugin' plugin supports Full-Text searches and will have a ranking of 4.

==== buildSearchSQL() Function ====
As a lot of the plugins will be processing the same or similar SQL queries the buildSearchSQL() function has been provided to simplify things. This function will take four parameters then build the searching part of the SQL query. It will also return the Full-Text query strings should they be required. The parameters are:
*$keyType -- search key type: 'all', 'phrase', 'any'.
*$query -- the query string.
*$columns -- the column names to search.
*$sql -- the sql query to append to. (optional)
And an example of how it can be put to use:
<pre>
$sql = 'SELECT ... FROM ... WHERE ... ';
$columns = array('title','bodytext');
list($sql,$ftsql) = buildSearchSQL('any', 'my geeklog', $columns, $sql);

// $sql => SELECT ... FROM ... WHERE ... AND ((title LIKE '%my%' OR bodytext LIKE '%my%') OR (title LIKE '%geeklog%' OR bodytext LIKE '%geeklog%'))
// $ftsql[mysql] => SELECT ... FROM ... WHERE ... AND MATCH(title,bodytext) AGAINST ('my geeklog' IN BOOLEAN MODE)
// $ftsql[mssql] => SELECT ... FROM ... WHERE ... AND CONTAINS((title,bodytext), '"my" OR "geeklog"')
</pre>
A proper example of its use is at the bottom of the page.

==== Enabling URL Rewrite ====
If the plugin requires the URL to be passed through the COM_buildUrl() function then it should set the setURLRewrite() function to true. For example:
<pre>$search = new SearchCriteria('myplugin', 'My Plugin');
$search->setSQL($sql);
$search->setURLRewrite(true);</pre>

==== Returning Multiple Objects ====
In some cases a plugin may be required to search across two or more tables that have no relation with one another. To accommodate this they may return an array of SearchCriteria() objects, each with a different SQL query. To allow the user to differentiate between the results an array of names can be passed, each name will be a separate sub group and will be appended to one another using the separator from the configuration.
The following example shows how this works:
<pre>
// Search the main table
// These results will be labelled 'My Plugin > Main'
$search_main = new SearchCriteria('myplugin', array('My Plugin', 'Main'));
$plugin_main->setSQL($sql_main);
$plugin_main->setFTSQL($ftsql_main);
$plugin_main->setRank(4);

// Search a sub tables
// These results will be labelled 'My Plugin > Sub'
$search_sub = new SearchCriteria('myplugin', array('My Plugin', 'Sub'));
$search_sub->setSQL($sql_sub);
$search_sub->setFTSQL($ftsql_sub);
$search_sub->setRank(4);

// Return both objects
return array($search_main, $search_sub);
</pre>
Note: The plugin identifier needs to stay the same across all objects, in this case 'myplugin'.

=== A Working Example ===
This example searches the Stories, although it's not a plugin it puts to use everything discussed here so it's a good example of how to implement the API in your plugin.
<pre>function plugin_dopluginsearch_searchStories($query, $datestart, $dateend, $topic, $type, $author, $keyType, $page, $perpage)
{
global $_TABLES, $_DB_dbms, $LANG09;

// Make sure the query is SQL safe
$query = trim(addslashes($query));

// Build the first part of the query
$sql = "SELECT
s.sid AS id,
s.title AS title,
s.introtext AS description,
UNIX_TIMESTAMP(s.date) AS date,
s.uid AS uid,
s.hits AS hits,
CONCAT('/article.php?story=',s.sid) AS url ";
$sql .= "FROM {$_TABLES['stories']} AS s, {$_TABLES['users']} AS u ";
$sql .= "WHERE (draft_flag = 0) AND (date <= NOW()) AND (u.uid = s.uid) ";
$sql .= COM_getPermSQL('AND') . COM_getTopicSQL('AND') . COM_getLangSQL('sid', 'AND') . ' ';

// If we are searching by date add that too
if (!empty($datestart) && !empty($dateend)) {
$delim = substr($datestart, 4, 1);
if (!empty($delim)) {
$DS = explode($delim, $datestart);
$DE = explode($delim, $dateend);
$startdate = mktime(0,0,0,$DS[1],$DS[2],$DS[0]);
$enddate = mktime(23,59,59,$DE[1],$DE[2],$DE[0]);
$sql .= "AND (UNIX_TIMESTAMP(date) BETWEEN '$startdate' AND '$enddate') ";
}
}
if (!empty($topic)) {
$sql .= "AND (s.tid = '$topic') ";
}
if (!empty($author)) {
$sql .= "AND (s.uid = '$author') ";
}

// Create a SearchCriteria instance with the name of the plugin
$search = new SearchCriteria('stories', $LANG09[65]);

// These are the columns in the table that need searching
$columns = array('introtext','bodytext','title');

// Get back the completed SQL query
list($sql,$ftsql) = $search->buildSearchSQL($keyType, $query, $columns, $sql);

// Set the Std. SQL Query
$search->setSQL($sql);

// Set the Full-Text Query, remember the columns _MUST_ be indexed first. If they are not then don't set this.
$search->setFTSQL($ftsql);

// Finally set a high ranking, enable URLRewrite and return the object.
$search->setRank(5);
$search->setURLRewrite(true);
return $search;
}</pre>

For more examples, there's a forum post ({{forum|87624}}) with updated search functions for the [[FAQ Manager Plugin|FAQ Manager]], [[Forum Plugin|Forum]], and [[File Management Plugin|File Management]] plugins.

[[Category:Plugin Development]]

Template:Forum

2009-05-26T12:11:35Z

LWC: New page: <includeonly>http://www.geeklog.net/forum/viewtopic.php?showtopic={{{1}}}</includeonly><noinclude>Supply an forum ID from the main site and get a link for it. ==Usage== <pre><nowiki>{{for...

<includeonly>http://www.geeklog.net/forum/viewtopic.php?showtopic={{{1}}}</includeonly><noinclude>Supply an forum ID from the main site and get a link for it.

==Usage==
<pre><nowiki>{{forum|forumID}}</nowiki></pre>

For example, <nowiki>{{forum|2004063013542379}}</nowiki> would display as:

{{forum|2004063013542379}}
</noinclude>

Template:Article

2009-05-26T12:08:51Z

LWC: Switched

<includeonly>http://www.geeklog.net/article.php/{{{1}}}</includeonly><noinclude>Supply an article ID from the main site and get a link for it.

==Usage==
<pre><nowiki>{{article|articleID}}</nowiki></pre>

For example, <nowiki>{{article|2004063013542379}}</nowiki> would display as:

{{article|2004063013542379}}
</noinclude>

Template:Main site

2009-05-26T12:08:47Z

LWC: Switched

#REDIRECT [[Template:Article]]

Template:Main site

2009-05-26T12:07:37Z

LWC: Undo revision 5451 by LWC (Talk) This wiki doesn't support advanced parser functions

Template:Main site

2009-05-26T12:05:42Z

LWC: Testing