GeeklogWiki - User contributions [en]

Google Summer of Code

2012-03-09T21:42:22Z

Vinny: Updated mentor link

Google Summer of Code

2012-03-09T17:01:53Z

Vinny: Added mentors and co-mentors list

User:Vinny

2012-03-09T14:41:55Z

Vinny: Email update

Email: [mailto:vfuriaATgmailDOTcom vfuria AT gmail DOT com]

SoC template engine

2012-03-08T22:21:11Z

Vinny: Added cordiste as co-mentor, added "bonus" to objective

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

== Overview ==
Geeklog currently uses an antique template system that does not compile templates, nor does it support modern template library features such as loops or compilation. The student selecting this project should research modern template libraries, choosing one to integrate into Geeklog.

== Objective ==
The biggest concern replacing Geeklog's existing template engine is backwards compatibility. Existing templates should still be usable (or a conversion system created) and code modification to support the new template library should be kept to a minimum so plugins can be easily updated to use the new template library.

Geeklog currently uses a large number of (relatively) small template files. A big bonus would be a design that can reduce the number of template files to ease template development without sacrificing backwards compatibility.

== Level of Difficulty ==
''high''

'''Mentor:''' Vinny Furia

'''Co-Mentor:''' Ben aka "Cordiste"

== Further Reading ==
Some existing template libraries:
* [http://pear.php.net/package/HTML_Template_IT/redirected HTML Template IT]
* [http://pear.php.net/package/HTML_Template_Flexy/redirected HTML Template Flexy]
* [http://twig.sensiolabs.org/ Twig]
* [http://www.smarty.net/ Smarty]

Some relevant feature requests:
* [http://project.geeklog.net/tracking/view.php?id=1423 Allow a Topic to have it's own Theme]
* [http://project.geeklog.net/tracking/view.php?id=1424 Allow a Theme to have a Base Theme]

Google Summer of Code

2012-03-08T15:41:05Z

Vinny: Inserted missing spaces

Google Summer of Code

2012-03-02T03:15:45Z

Vinny: Fixed beginner link formatting (escape [ and ])

Google Summer of Code

2012-03-02T03:00:59Z

Vinny: Updated "beginner" link to exclude closed and resolved issues.

SoC template engine

2012-03-02T02:42:23Z

Vinny: Added further reading (links to relevant feature requests)

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

== Overview ==
Geeklog currently uses an antique template system that does not compile templates, nor does it support modern template library features such as loops or compilation. The student selecting this project should research modern template libraries, choosing one to integrate into Geeklog.

== Objective ==
The biggest concern replacing Geeklog's existing template engine is backwards compatibility. Existing templates should still be usable (or a conversion system created) and code modification to support the new template library should be kept to a minimum so plugins can be easily updated to use the new template library.

== Level of Difficulty ==
''high''

'''Mentor:''' Vinny Furia

== Further Reading ==
Some existing template libraries:
* [http://pear.php.net/package/HTML_Template_IT/redirected HTML Template IT]
* [http://pear.php.net/package/HTML_Template_Flexy/redirected HTML Template Flexy]
* [http://twig.sensiolabs.org/ Twig]
* [http://www.smarty.net/ Smarty]

Some relevant feature requests:
* [http://project.geeklog.net/tracking/view.php?id=1423 Allow a Topic to have it's own Theme]
* [http://project.geeklog.net/tracking/view.php?id=1424 Allow a Theme to have a Base Theme]

Google Summer of Code

2012-02-27T01:37:21Z

Vinny: Removed openid/oauth project

SoC template engine

2012-02-27T01:27:56Z

Vinny: Broad description in place. Details to come?

SoC php sessions

2012-02-27T00:49:24Z

Vinny: Broad description in place. Details to come?

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

== Overview ==
Geeklog currently uses custom session management to maintain users session information. The custom session implementation is antique and needs to be upgraded to a fully supported session management system such as the one provided by [http://www.php.net/manual/en/book.session.php PHP Sessions]. The implementation needs to be secure and should cache user data between page loads of a session.

== Objective ==
Implement new session handling in Geeklog.

This project could be extended by adding the ability for Geeklog to support http and https for the same site. By forcing logged-in users to use https, session hijacking can be prevented.

== Level of Difficulty ==
''medium to high''

Geeklog's existing session software must be understood before being replaced. Student's taking on this project will also have to ensure plugin compatibility with the new session implementation.

'''Mentor:''' Vinny Furia

== Further Reading ==
* [http://www.php.net/manual/en/book.session.php PHP Sessions]
* [http://phpsec.org/projects/guide/4.html PHP Security Guide: Sessions]

SoC php sessions

2012-02-27T00:38:09Z

Vinny: Template Only

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

== Overview ==

== Objective ==

== Level of Difficulty ==
''medium to high''

'''Mentor:''' Vinny Furia

== Further Reading ==

SoC template engine

2012-02-27T00:37:43Z

Vinny: Template Only

SoC core notification support

2012-02-27T00:35:49Z

Vinny: Update for 2012 GSOC

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

== Overview ==

There are a number of core GL features and plugins that send out email notifications and each plugin or module has to develop their own code. There is no central area for the site admin or members to moderate for what they can receive notifications or how they want them handled.

There is also the need to expand the ability of sites to provide alerts for events in which administrators may have an interest.

Many plugins would require a basic level of notification service. Others, such as the forum plugin, will require a more complex notification service. For instance, a notification service for the forum would need to allow a user to subscribe to a topic or a complete forum. If they have subscribed to a complete forum, they can selectively un-subscribe to some topics. The same level of control may be needed for stories (articles), where a user can subscribe to a complete site but then un-subscribe to certain topics or stories by a certain user.

== Objective ==

* Develop a set of core Geeklog API's to support the registration of new notification services and user notification of subscriptions. Ideally, an [https://en.wikipedia.org/wiki/Observer_pattern observer pattern] would be used for clarity and efficiency.
* Extend the plugin API to use the new services.
* Extend the core GL modules (polls, articles, links, etc) to use the new services.
* Develop the notification admin / site admin GUI.
* Develop the GUI for the users to manage their notification/subscription rules.

Support for:
* Alert Classification (admin, general, moderation, error ...)
* Alert Type (core, plugin ...)
* Alert Subtype (module specific)

Only Root or plugin Admin's have access to the admin and error type notifications but this should be a configurable mapping option and controllable via the online notification service admin.

Users should be able to determine how they want to receive their notifications.
* Admin wants to be emailed on all admin and error notifications
* Admin wants to receive daily digest of all other notifications
* User wants daily digest of all notifications
* Support for RSS Feed per user - possibly using a random hash like URL
* Daily digest format needs to use a template so the site admin can modify it

== Use Cases ==

* Site Admin wants to be notified of all new forum topics and MG albums created but not new replies and images uploaded
* User wants daily digest of all MG updates for albums they have access to
* User wants daily digest of all comments to content they have created or have replied to.
* Admin wants daily digest of all items awaiting moderation
* Admin wants to be notified via email of all site logins
* Admin wants to be notified via email of all bad login attempts so they know if a user is now locked out
* Admin wants to be notified of new user signups.

The site Admin and user can have multiple notification rules setup and setup the email subject, email address so they can filter or redirect notifications.

== Level of Difficulty ==

''medium to high''

This project will require someone to spend time understanding how the core GL plugin API works. Need to install a number of the more popular plugins that use notification-like features and develop a model of the new notification service API.

Students should have OO experience and knowledge of say the Observer Design Pattern as that would be a good base for the design of this project.

'''Mentor:''' Vinny Furia

== Further Reading ==

* We had a student interested in this project in 2008. Please see the discussion "GSoC 2008: Core Notification Service" in our [http://eight.pairlist.net/pipermail/geeklog-devel/2008-March/thread.html mailing list archives].

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

Google Summer of Code

2012-02-27T00:24:38Z

Vinny: Added two project ideas.

Geeklog.net Redesign

2012-02-18T02:17:12Z

Vinny: /* Homepage */

Geeklog.net Redesign

2012-02-18T02:16:17Z

Vinny: /* Components */

AddToConfiguration

2011-08-11T20:35:34Z

Vinny: New Article

=Guide to Adding 'Core' Configuration Items=

Geeklog's move from a static configuration array to a database-based, web-managed configuration system using the [[Configuration_Class|Configuration Class]] in Geeklog 1.7.x has made adding new configuration parameters more complex. This guide includes step-by-step instructions for adding new configuration subgroups, tabs, fieldsets, and configuration parameters. Configuration groups are ignored, as for configuration parameters for Geeklog should always be in the 'Core' group. Other documentation exists about adding [[PluginConfiguration|configuration items for plugins]].

This article will often refer to collective sort of organizing types, which includes groups, subgroups, tabs, and fieldsets, as grouping types.

==Adding subgroups, tabs, and fieldsets==
===Creating new subgroups, tabs, and fieldsets===
There are two locations where new grouping types (and configuration parameters as well, but more on them later) must be added. The first is <tt>public_html/admin/install/config-install.php</tt>, used by new Geeklog installs to add a complete set of configuration parameters to the Geeklog database. The second is <tt>public_html/admin/install/lib-upgrade.php</tt>, where the Geeklog upgrade script goes to upgrade the database when a new Geeklog version is installed.

In both locations and for all these grouping types, the [[Configuration_Class#function_add.28.29|add method of the configuration class]] is used to add new grouping types. Below are some examples of adding these different grouping types:
* subgroup: <tt>$c->add('sg_site', NULL, 'subgroup', 0, 0, NULL, 0, TRUE, 'Core', 0);</tt>
* tab: <tt>$c->add('tab_site', NULL, 'tab', 0, 0, NULL, 0, TRUE, 'Core', 0);</tt>
* fieldset: <tt>$c->add('fs_site', NULL, 'fieldset', 0, 0, NULL, 0, TRUE, 'Core', 0);</tt>

There is complete documentation for the [[Configuration_Class#function_add.28.29|add method]]. The following parameters are particularly important for the grouping types:
* First Parameter: The internal name (i.e. not the display name).
* Third Parameter: The type. For grouping types, these are 'subgroup', 'tab', and 'fieldset'.
* Fourth Parameter: The subgroup number. This is a unique internal number to reference the subgroup. The fieldset and tab types use this to indicate which subgroup they belong under.
* Fifth Parameter: The fieldset number. This is the unique internal number to reference the fieldset. Subgroups do not use this number and use 0 by convention. Tabs do not use this number and use the number of the first fieldset they contain by convention.
* Tenth Parameter: The tab number. This is the unique internal number to reference the tab. Subgroups do not use this number and use 0 by convention. Fieldsets use this to indicate which tab they belong under.

In <tt>lib-upgrade.php</tt>, the code for the addition of the variables should be placed in the switch statement case for the previous version (e.g. if adding config value to 1.8.1, add the methods to the case statement for 1.8.0). Also in <tt>lib-upgrade.php</tt>, you will need to initialize the config class before you can execute the add methods above. This is easily done by using the following code:
<pre>
global $_CONF;
require_once $_CONF['path_system'] . 'classes/config.class.php';
$c = config::get_instance();
</pre>

===Display text for subgroups, tabs, and fieldsets===
Once the new grouping type(s) are added, the language file (by editing <tt>language/english.php</tt> must be updated. Each grouping type has its own language associative array in this file. In these arrays, the key is the grouping types' name (such as 'sg_site' used above) and the value is the plain text display ('Site', for the same case).
* subgroup: <tt>$LANG_configsubgroups['Core']</tt>
* tab: <tt>$LANG_tab['Core']</tt>
* fieldset: <tt>$LANG_fs['Core']</tt>

==Adding configuration parameters==
===Creating new parameters===
Like the grouping types, configuration parameters use the [[Configuration_Class#function_add.28.29|add method]] of the [[Configuration_Class|configuration class]] to add new parameters. These add methods are placed in both <tt>public_html/admin/install/config-install.php</tt> to be used in new installs and <tt>public_html/admin/install/lib-upgrade.php</tt> to be used in upgrades. Here is an example of adding a new configuration variable:
* $c->add('site_url', <nowiki>''</nowiki>, 'text', 0, 0, NULL, 20, TRUE, 'Core', 0);

The configuration class supports three basic types of configuration parameters, these are:
* text: Manual text box entry.
* select: HTML Select box (i.e. choice dropdown).
* hidden: Undisplayed config parameters.

The configuration class also allows the use of arrays by prepending the base type above with one of the following characters:
* @: array, the administrator cannot add keys
* *: array, the administrator can add named keys
* %: array, the administrator can add numbered keys

The configuration class supports multidimensional arrays by prepending additional array symbols. For instance, @@example represents a two dimensional array.

Default/initial values are defined in the second parameter to the add method. These can be of any type (including arrays) and get serialized by Geeklog for storage in the database.

===Value validation===
Entered values for parameters are validated by a rules that are defined on a per-parameter basis. This rules are established in the <tt>$_CONF_VALIDATE</tt> array defined in <tt>public_html/admin/configuration_validation.php</tt>. Each parameter (for the 'Core' group) is a key in the <tt>$_CONF_VALIDATE['Core']</tt> array. For instance, to add a validation function function to the 'site_url' parameter, the following entry is needed:
* <tt>$_CONF_VALIDATE['Core']['site_url'] = array('rule' => 'url');</tt>

Every parameter should have an entry in this array. The 'rule' key is interpreted as follows:
# If a custom_validation_<rule> function exists, use that (e.g. "theme" -> custom_validation_theme() from <tt>public_html/admin/configuration.php</tt>).
# If a method from the validator class with the same name as the rule exists, use that (e.g. "stringOrEmpty" -> stringOrEmpty() from <tt>system/classes/validator.class.php</tt>). Currently the validator class supports the following rules: notEmpty, alphaNumeric, between, blank, comparison (isgreater, isless, greaterorequal, lessorequal, equalto, notequal), custom (regex), date, time, boolean, decimal, email, equalTo, extension, ip, minlength, maxlength, multiple, numeric, phone, range, string, stringOrEmpty, url, and inList.
# Otherwise assume the "rule" is a regexp

===Parameter documentation===
To reference additional information about variables from the congiruation web page, new parameters should be placed in <tt>public_html/docs/english/config.html</tt> (including their internal name, type, and description) with an anchor tag with the name 'desc_<parameter name>'.

===Display text for parameters and selects===
Finally, display text for each parameter name should be placed in the <tt>language/english.php</tt> file in the <tt>$LANG_confignames['Core']</tt> associative array with the key being the internal name and the value the display text. Also, parameters with the 'select' type, need to update the <tt>$LANG_configselects['Core']</tt> array. 'Select' types can use an existing numbered reference to an associative array of select values, or else create a new one. A new select needs a unique number index in <tt>$LANG_configselects['Core']</tt> with an associative array of containing the displayed text as keys and the select values as values in the array.

==Summary==
While these instructions can seem intimidating, by using other parameters and grouping types as reference adding to Geeklog's configuration is manageable. While the complexity of adding configuration has increased for developers, it is a necessary sacrifice for granting both a easy to manage web frontend and providing validation protection to entered configuration values.

Programmers/Developers Documentation

2011-08-11T17:49:57Z

Vinny: Added link to "AddToConfiguration"

Beginner's Guide to Programming

2011-08-11T17:36:50Z

Vinny: Squatty is completely gone, portalparts is "retired" with no active posts since mid-2010.

By [[User:Amckay|Alan McKay]]

[http://www.geeklog.net Geeklog] is a powerful weblog (blog) content management system (CMS) which is written in the popular programming language [http://www.php.net PHP], and uses the popular [http://www.mysql.com MySQL] database. While Geeklog is powerful enough that many users will not have a need to write their own applications for it, it is flexible enough to allow those who do require extra functionality to do so easily. These people write their programs in PHP, with some minor restrictions and using the Geeklog function library.

==Hello, World==

The first program you write in any computer language is "Hello World", and here it is in Geeklog. This is saved in a file "hello.php" in Geeklog's "public_html" directory, and so is surfable at http://www.example.com/hello.php

<pre>
<?php

require_once( 'lib-common.php' );
$display = COM_siteHeader();
$display .= "Hello World";
$display .= COM_siteFooter();
COM_output($display);

?>
</pre>

There are a few important things to be noted from the given program.

* geeklog programs stay in PHP mode - there is no flipping back and forth between PHP and HTML as is possible in the PHP language. This means that all programs have "<?php" on the first line, and "?>" on the last line, and everything in between is PHP code.
* the HTML is generated using a single function, COM_output() as on the last line of the above code. Although it is possible to use a simple 'echo' statement to spit out the HTML, newer versions of Geeklog use the COM_output() function. COM_output() takes the $display variable to which all your HTML output is appended throughout the code (note the ".=" which is used for the append) as an argument and simply echoes it out in this case. (Newer versions of Geeklog use the COM_output() function to allow for any output that may use compression. More on that later)
* "lib-common.php" is the single file which must be included in all your Geeklog programs. It includes everything else you need unless you decide to make your own include files, so it's one-stop shopping.
* there are functions in Geeklog to do lots of stuff for you - like for example COM_siteHeader() and COM_siteFooter(). In general Geeklog functions start with 2 or 3 capital letters and an understore - this tells you what type of function it is. Then the name of the function. COM_ functions are "common" functions - not a terribly meaningful name. But SEC_ functions like SEC_inGroup() which allows you to test if a user is in a particular group, allow your programs to access some of the powerful security features of Geeklog. And DB_ commands allow you to access the Geeklog database.

==Security==
Speaking of the powerful Geeklog security model (one of the key reasons I originally chose Geeklog for my sites), let's alter the hello world program such that any user in the "geeker" user group will see the "hello world" message, but anyone not in that group (which includes users not logged in) will get a "permission denied" error.

<pre>
<?php

require_once( 'lib-common.php' );

$display = COM_siteHeader();

if ( SEC_inGroup( 'geeker' ) )
$display .= "Hello World";
else
$display .= "Access Denied";

$display .= COM_siteFooter();

COM_output($display);

?>
</pre>

To check out the full range of security functions available to you, and how to use them, read the /path/to/geeklog/system/lib-security.php file, which is where they are implemented.

Though the above code format is a bit clunky and not terribly useful, so let's make another change which shows us how most programs deal with group permissions issues.

<pre>
<?php

require_once( 'lib-common.php' );

$display = COM_siteHeader();

if ( ! SEC_inGroup( 'geeker' ) )
{
$display .= "Access Denied";
$display .= COM_siteFooter();
COM_output($display);
exit;
}

$display .= "Hello World";

// do some other stuff here

$display .= COM_siteFooter();

COM_output($display);

?>
</pre>

The big difference in this version of the program is that right at the top of the program we test for group permissions, and if the user does not have them we display the site footer, then exit. So a user not in the 'geeker' group will end right there and never see what the rest of the program does. Very simple, but very powerful! This is precisely how you control access to your pages in Geeklog!

==Where to put it==

If you are only writing a small program, then sticking a single file in the public_html directory as shown above will work fine. As soon as you get to the point, however, when you start having your own include files and so on, you probably want to create a directory for it. In our case we could create a directory in "public_html" called "hello", and then create a file "index.php" with the above program. This will require a very minor change to the original program - see if you can pick it out before peeking :

<pre>
<?php

require_once( '../lib-common.php' );

$display = COM_siteHeader();

$display .= "Hello World";

$display .= COM_siteFooter();

COM_output($display);

?>
</pre>

Yup, that's right, we had to add "../" to the "lib-common.php" in the "require_once" (which BTW is a type of "include" in PHP). The reason is simple: lib-common.php lives in public_html, and our first program was in that directory as well. This new program is in a subdirectory of public_html, so we have to go to the parent directory to get our include file.

If you want to keep your geeklog installation "pure", as I usually do, you can also put your program directory somewhere outside of the geeklog directory, and use directives for your webserver to map that directory into the web space of your geeklog installation. That's easier than it sounds - with Apache just use the "Alias" directive in your apache config file, like this :

<pre>
Alias /hello/ "/path/to/your/hello/"
</pre>

Of course, this means that your require_once statement will have to contain the full path to lib-common.php

<pre>
require_once( '/path/to/geeklog/public_html/lib-common.php' );
</pre>

==To Plug it in, or not==

This is a bit of an advanced topic which in some ways is out of place at this point, but just about everyone who knows Geeklog and has used it a bit, knows about [[Plugin Developers Handbook|Geeklog plugins]]. And when writing your own Geeklog programs, this will obviously be something in your mind. Not all Geeklog programs are plugins - and the above examples are not. Plugins involve writing your program in a specific way, and defining specific functions which Geeklog will expect to find. It also involves making some entries in the Geeklog database to let Geeklog know that your plugin is there.

In general if you want to use the Geeklog comment engine, the Geeklog search engine (i.e. integrate your program data into the search feature of Geeklog), or the Geeklog submission engine, you must write a plugin. Otherwise you can just write code. Size doesn't matter. There is no limit after which you have to make it a plugin.

==Some Odds and Ends==

A couple of more quick points on some basic Geeklog stuff

* the $_USER array comes pre-populated for you by Geeklog. If $_USER['uid'] is greater than 1, then you know your user is logged on. Otherwise they are anonymous. So in the above example if you wanted to test for "logged on user" rather than "member of geeker group", just change the 'if' statement accordingly. This array contains all of the user table from geeklog, the next most useful subscript being $_USER['username']
* the $_CONF array contains everything you set in your config.php, if you need it. Just check config.php for what all is there.
* both of the above arrays are global, and as such if you use them in a function you must declare them in the function with the 'global' directive, as is normal for PHP. Outside of any function in the main body of the program they can be just used.

==Functions, Bring Me Functions!==

We've already seen three of the most widely used functions that Geeklog has to offer - COM_siteHeader(), COM_siteFooter() and COM_output(). It is important to note with this that there are optional parameters you can pass to each of them to achieve certain results. COM_siteHeader() displays the header and the left blocks, while its partner controls the footer and the right blocks. By default COM_siteHeader() displays the left blocks, and by default COM_siteFooter() does not display the right blocks. COM_output takes your $display variable which contains all your HTML and displays it, allowing for compressed data to be decompressed and displayed in the process. Check the source code in lib-common.php for details on how to change this behavior.

Another set of similar workhorse functions which are also defined in lib-common.php along with the aforementioned functions are COM_startBlock() and COM_endBlock(). COM_startBlock() accepts 3 optional parameters: title, helpfile and template. The most useful and almost always used is title, which is a text string which will appear in the title bar of the block. If a helpfile is specified, Geeklog will display the help question mark icon and link to a help file for that block. And by default the 'blockheader.thtml' template is used unless another is specified. COM_endBlock() '''must''' be called once for each call to COM_startBlock(), and its only optional parameter is template, the default being blockfooter.thtml.

Blocks can be nested inside of each other, which is obvious by simply looking at just about any geeklog website.

<pre>
<?php

require_once( 'lib-common.php' );

$display = COM_siteHeader();

$display .= COM_startBlock("Outer Block")
. "This text should be inside the outer block but outside the inner block"
. COM_startBlock("Inner Block")
. "This text should be inside the inner block"
. COM_endBlock()
. COM_endBlock();

$display .= COM_siteFooter();

COM_output($display);

?>
</pre>

When using nested blocks inside of HTML tables, one simply has to be certain to call COM_endBlock() in the right place since these functions output HTML tables as well, and otherwise the display may not render properly. COM_startBlock() and COM_endBlock() are used like COM_siteHeader() and COM_siteFooter() but for internal page elements.

<pre>
<?php

require_once( 'lib-common.php' );

$display = COM_siteHeader();

$display .= COM_startBlock("Outer Block")
. "This text should be inside the outer block but outside the inner blocks"
. "<table align=center width=100% border=0>"
. "<tr><td align=center width=50%>"
. COM_startBlock("Left Inner Block")
. "This text should be inside the left inner block"
. COM_endBlock()
. "</td>"
. "<td align=center width=50%>"
. COM_startBlock("Left Inner Block")
. "This text should be inside the right inner block"
. COM_endBlock()
. "</td></tr></table>"
. "This text should be below the inner blocks but inside the outer block"
. COM_endBlock();

$display .= COM_siteFooter();

COM_output($display);

?>
</pre>

The great advantage of using these two functions is that whenever the site admin or user changes their Geeklog theme, your GUI will change to match. Your program will always retain the same look-and-feel of the site in general.

There are also some useful HTML form functions found in lib-common.php which come in very handy and make life a bit easier. <pre>COM_optionList( $table, $selection, $selected='', $sortcol=1 )</pre>. This creates an HTML "<option" list generated from the given database table, using the passed variable "$selected" in the SELECT statement of the HTML query. See source code for a better idea of what the function does, but it is very useful.

In a similar vein, <pre>COM_checkList( $table, $selection, $where='', $selected='' )</pre> creates a list of check boxes from the given database table, with the given select and where clauses being passed to the SQL statement inside the function.

One more useful function is the <pre>COM_errorLog( $logentry, $actionid = '')</pre> function which logs to the Geeklog logfile if $actionid is 1, or to the screen if it is set to 2.

<pre>COM_checkWords( $Message )</pre> gives you access to Geeklog's (somewhat rudimentary) profanity filter. We find it to be not terribly useful since if you include for example the word "cock" in your filter, you will also filter out the completely innocuous word "peacock". If you nonetheless want to use the geeklog profanity filter, simply do this:

<pre>
$text = COM_checkWords( $text );
</pre>

<pre>COM_mail( $to, $subject, $message, $from = '', $html = false, $priority = 0 )</pre> does exactly what the name suggests and lets you send mail to someone.

There are far too many functions in lib-common.php to discuss here, so we'll end off with two very important ones which can be used for accessing query-string variables. What's a query string? If you have a URL like this:

<pre>
http://www.example.com/someprogram.php?variable=value&othervariable=othervalue
</pre>

The query string is the part after the question mark - the stuff you pass into your program. In this example, inside the text of someprogram.php, if the PHP installation has "register_globals" turned on, the variable "$variable" will automagically exist in the program and will have the value "value". But there are certain security problems with using "register_globals" in PHP so a lot of people do not like to have it turned on. Unfortunately Geeklog requires that it be turned on (at least for now until the programmers get it rewritten to eliminate the need), so to mitigate the risks involved you can use special functions to obtain your query string variables.

Near the top of your program simply insert something like the following, first to define which are the only global variables your program expects to see, then finally to safely obtain the value of those variables:
<pre>
COM_setArgNames(array('variable','othervariable'));
$variable = COM_getArgument('variable');
$othervariable = COM_getArgument('othervariable');
</pre>

==Using the Database==

Geeklog has a database abstraction layer which in theory makes it possible for you to use any database as the backend for it. Though in practice the Geeklog team has only implemented a backend for the popular [http://www.mysql.com MySQL] database. In any case, when programming Geeklog you do not use the regular PHP database functions - instead you use the DB_ functions which behave almost idenically to the PHP functions that have similar names.

Another important thing to note about Geeklog is that you should never use table names directly in your queries. Instead, you should use the $_TABLES global variable, and add your own table names to it if you make your own tables. The reason for this is simply that Geeklog allows the installer to specify a "table prefix", so if you use table names directly your code will not run on another Geeklog installation that uses a different table prefix. Even if you think you'll never want to run your code on another Geeklog installation, we recommend you do things properly because you never do know. I've written code that I thought would never have to run in another installation, and sure enough 2 years later I have to go back and convert it all to use the $_TABLES array because now I do indeed want to run it on another installation that is using a different table prefix.

One final very important thing to state about using the Geeklog database is that '''under no circumstances whatsoever should you ever alter the default Geeklog tables'''. One example of where you might be tempted to do this is if you want to track a specific option for users - you may be tempted to add a field or two to the Geeklog "users" table. Say for example you are writing a program "buysell" which allows users to enter items into the database to put them up for sale to other users. And when browsing the database to see what is for sale, you want each user to decide whether or not they want to see their own items. You may be tempted to add a boolean field "seeown" to the Geeklog users table, but don't do it! Instead, create your own table "buysell_userprefs" and add whatever fields you require to this new table. At very least we need a field for the userid - so we'll call it "bsp_uid", and we need a field for "see your own items" so we'll call it "bsp_seeown".

In general we like to give table fields names that have an abbreviation of the table name at the beginning of every field. So in our case this is a table which contains "buy sell preferences" for each user, so we'll name all the fields "bsp_". This is optional, but we've found it to be a good practice so that you do not end up with fields from various tables with the same name - something that can under circumstances cause problems in your queries, or unexpected results.

===Adding to $_TABLES===
As already mentioned, if you define your own tables, you have to add them to the global $_TABLES variable.

<pre>
$_TABLES['buysell_userprefs'] = $_DB_table_prefix . 'buysell_userprefs';
</pre>

Note that we've included the Geeklog global variable for table prefix, so that our code will work in all Geeklog installations. And of course you need one line for every table you are adding to the Geeklog database. And finally, like any global variable in Geelog you must declare it global in a function if you want to use it in that function.

When doing a plugin you usually put this into the config.php for your plugin. If not doing a plugin you have several options on where to put it, depending upon how you have your code organised. If you have one big file, then put it at the top of that file. If you have an include file that gets included by all the programs you are writing, put it there. Basically you have to put it whereever you can that will ensure it gets executed by all of your programs and is visible by all of your programs.

===Get on with it!===
And finally we can show you how to put it all together. Let's write a simple little program that does nothing more than show you what your 'bsp_seeown' preference is set to.

<pre>
<?php
require_once('lib-common.php');

$display = COM_siteHeader();

if ( $_USER['uid'] < 2 ) {
$display .= "You are not logged in";
$display .= COM_siteFooter();
COM_output($display);
exit;
}

$_TABLES['buysell_userprefs'] = $_DB_table_prefix . 'buysell_userprefs';

$sql = "SELECT bsp_seeown FROM {$_TABLES['buysell_userprefs']} "
. " WHERE {$_TABLES['buysell_userprefs']}.bsp_uid = {$_USER['uid']} ";
$result = DB_query( $sql );
if ( ! $result ) {
// some error condition and possibly exit
}
if ( DB_numRows( $result ) <> 1 ) {
// there should be precisely one entry for each user
// otherwise you may want to flag an error condition
// or you may want to alternately check to see if this
// value is less than 1 first, in which case they user
// has not yet set their preferences
}
$bsp = DB_fetchArray( $result );
if ( ! $bsp ) {
// some error condition
}

$display .= COM_startBlock("Your Preference is")
. $bsp['bsp_seeown']
. COM_endBlock();

$display .= COM_siteFooter();

COM_output($display);

?>
</pre>

Wow! There's lots going on in this program! A lot more than what we might have expected! First and foremost note that there are lots of potential error conditions to check for, when using the Geeklog database. This is no different from just programming MySQL with the normal PHP functions, actually. It is always a best practice to check for error conditions and react accordingly.

Before we looked up the user's preference, we of course first did a check to make sure they were logged on, and if not we exited. Then, you can see how we added our table to the $_TABLES global variable, and then inside of the SELECT statement used the $_TABLES variable to ensure our code is portable. If you wanted to move this to another system you do not have to change a thing!

As for the specific DB_ functions we used, they behave in the same way as the PHP MySQL functions with similar names. If you aren't familiar with how they work, check the Geeklog source code as well as the PHP manual. For a full listing of all the DB_ functions available to you, check out /path/to/geeklog/system/lib-database.php

==Defining Functions==
Defining functions in Geeklog is of course no different from doing so in PHP. Though there are a few lessons to be learned from the Geeklog coding style. One handy thing to do is pick a 3 to 5 character prefix for all of your functions. This will help prevent you and some other developer from walking on each others toes and writing plugins or other Geeklog programs which are incompatible with each other. For example in my User Pages Plugin I chose the prefix "UPAGE_" for every one of my own functions.

Figuring out how to do return codes from functions is never easy in Geeklog or PHP in general. Many functions will return strings of HTML formatted text, and so returning error conditions is not easy. There is no one solution for every circumstance - though I've found 2 solutions work most of the time. If you hit an error condition in your function you can either return a NULL string so the caller can check for NULL string, or you can just return a string with an error message about the problem encountered, in which case the caller will not really know something went wrong - which may or may not matter. It depends on your caller.

Let's have a look at a couple of functions for making HTML select boxes out of the database. The first function is essentially the same as the Geeklog function COM_optionList although it does get called with different parameters, and the Geeklog function is a bit more powerful.

One thing you will see first off in the below function definition is that PHP gives you a means to specify default values for function parameters. This means that when calling the function, only the first two parameters "myName" and "myOptions" need be specified. myName is the name this element will have (variable name) and myOptions is a list of options separated by the "mySep" character which by default is "|".

An important aspect to understand about default values for parameters is that you can only allow the X right-most parameters to have a default value. That is to say you cannot specify a default value for the 1st parameter, then none for the 2nd, then one for the 3rd and so on. The first zero or more parameters will have no default, then after the first one that has a default value all the rest must also have default values. And also when calling the function that we have below, if I wanted to override the default for "mySep" for example by passing a value in, then I also have to override the defaults for every parameter to the left of it - so I must also specify overrides for "myDefault", "myMulti" and "mySize".

So I could call the function in any of the following ways :

<pre>
$display .= SSM_inputSelect( "SelectBox", "one|two|three" );
$display .= SSM_inputSelect( "SelectBox", "one|two|three", "one" );
$display .= SSM_inputSelect( "SelectBox", "one|two|three", "one", 0 );
$display .= SSM_inputSelect( "SelectBox", "one|two|three", "one", 0, 1 );
$display .= SSM_inputSelect( "SelectBox", "one:two:three", "one", 0, 1, ":" );
</pre>

and so on. But I could not do this if all I wanted to specify was "mySep" :

<pre>
$display .= SSM_inputSelect( "SelectBox", "one:two:three", ,,, ":" );
</pre>

So the moral of the story is that if you are having parameters with default values you have to give some consideration to the order of the arguments. You want the ones least likey to be overridden to be the right-most, and the ones most likely to be overridden to be left-most.

<pre>
function SSM_inputSelect( $myName, $myOptions, $myDefault="", $myMulti=0,
$mySize=1, $mySep="|", $visible=true )
{
$retval .= ""
. "<SELECT size=\"" . $mySize . "\" name=\"" . $myName . "\"";

$retval .= ($myMulti == 0) ? ">" : " multiple>";

$arrayOptions = explode($mySep,$myOptions);

foreach ($arrayOptions as $oneOption) {
$oneOption = trim($oneOption);
if ( $myMulti == 0 )
if ( $oneOption == $myDefault )
$retval .= "<OPTION SELECTED>" . $oneOption . "</OPTION>";
else
$retval .= "<OPTION>" . $oneOption . "</OPTION>";
else
if ( in_array( $oneOption, $myDefault ))
$retval .= "<OPTION SELECTED>" . $oneOption . "</OPTION>";
else
$retval .= "<OPTION>" . $oneOption . "</OPTION>";
}

$retval .= ""
. "</SELECT>"
. "";

return $retval;

}
</pre>

Now let's have a look at another function which builds on the above by allowing us to pull stuff out of the database and present it in an options list.

<pre>
function SSM_inputSelectDBField( $myName, $myTable, $myField, $myDefault="",
$mySize=1, $myMulti=0, $extra="", $mySep="|" )
{
// select distinct entries from the given field of given table
$sql = "SELECT DISTINCT " . $myField . " FROM " . $myTable
. " ORDER BY " . $myField;

// allows us to add an extra entry that was not in the DB

if ( $extra != "" )
$myOpts = $extra . $myOpts;

$result = DB_query($sql);

// format the data as required by SSM_inputSelect()

while ( $R = DB_fetchArray( $result ) )
if ( $myOpts == "" )
$myOpts .= $R[$myField];
else
$myOpts .= $mySep . $R[$myField];

// now call the guy doing the actual work

$retstr .= SSM_inputSelect( $myName, $myOpts, $myDefault, $myMulti,
$mySize, $mySep );

return $retstr;
}

</pre>

And finally here is a similar function which once again builds upon "SSM_inputSelect" but this time it takes an field of type ENUM and builds a SELECT box out of all the possible preset values of the ENUM.

<pre>
// Does not yet allow multi select but should be rewritten to do this

function SSM_inputEnumDBField( $myName, $myTable, $myField, $myDefault="", $visible=true )
{
// query the DB to extract the enum values
$qqq = "DESCRIBE $myTable $myField";
$result = DB_query( $qqq );
$arow = DB_fetchArray( $result );
$myArr = explode( ",", trim( strstr( $arow['Type'], "(" ), "()")) ;

// now format the values as required by SSM_inputSelect()
$idx=0;
$cnt = count($myArr);
while($idx<$cnt)
{
$myArr[$idx] = trim( $myArr[$idx], "'" );
$idx++;
}
sort( $myArr );
$myList = implode( "|", $myArr );

// now call our workhorse

return SSM_inputSelect( $myName, $myList, $myDefault );
}
</pre>

The lesson here is that your functions should be well-defined and reusable. Here we could have written 2 different functions which have nothing to do with each other, but instead we wrote a 3rd base function first which the other 2 rely on to get the job done. Now if there is some substantial change in how I want the SELECT boxes drawn, I only have to make the change in one place.

==Support and Such==

The best place for Geeklog support is of course [http://www.geeklog.net the main Geeklog site].

If you want to report a bug or request a feature, set yourself up an account [http://project.geeklog.net/tracking/signup_page.php here] and do so. If they don't know it is broken, they can't fix it. I've reported several bugs and have had them fixed promptly. I've also tracked down and fixed several bugs and simply submitted the code which was accepted. And I've also requested several features which have been added over the years at my request. The Geeklog development team is small, but very dedicated and they love to get feedback from the user base.

[[Category:Development]]

Installing Geeklog:System Requirements

2011-07-01T20:30:29Z

Vinny: Update minimum requirement to reflect 1.8.0

== Installation - System Requirements ==

The system requirements for installing Geeklog 1.8.0 and later are as follows:

# Web server - one of the following
## Apache Web Server
## Microsoft IIS (Internet Information Server)
## Zeus
# PHP 5.2.0
# Database server - one of the following
## MySQL 3.23.2 or higher, preferably at least 4.x or later
## Microsoft SQL Server 2000 or later
## Postgresql 7 or later
# The ability to create a new database or to have access to an existing one

CommentAlgorithm

2011-05-13T01:33:35Z

Vinny:

=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</code>

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 
UPDATE comments SET rht = rht + 2 WHERE rht >= parent_comment.rht 
UPDATE comments SET lft = lft + 2 WHERE lft >= parent_comment.rht 
INSERT INTO comments SET lft = parent_comment.rht, rht = parent_comment.rht + 1 
COMMIT</code>

Deletions:

<code>START TRANSACTION 
UPDATE comments SET rht = rht - 2 WHERE rht > comment.rht 
UPDATE comments SET lft = lft - 2 WHERE lft > comment.rht 
DELETE FROM comments WHERE id = comment.id 
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 worthwhile.

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]

Calendarv2

2010-12-15T06:47:01Z

Vinny: /* Thoughts: */

== What needs to be done till the alpha release? ==

* Fix Ical Support. 
* Render recurring events immediately after an event was created, not just on page load.
* Review Security (specifically user access rights to events)
** Make use of SEC_createToken, SEC_checkToken to preven CSRF attacks.

== Future plans/improvements: ==

* When Geeklog moves to PHP 5.3 (or earlier, as time permits) switch to using MySQL Datetime types. PHP 5.3's enhanced DateTime class makes the switch easier.
* Conversion script to convert existing Geeklog calendars to Calendarv2.
* Use PHP's locale settings for Day of Week, Month Names, etc instead of the language file [http://php.net/manual/en/function.setlocale.php]

== Thoughts: ==

* AEvents Class
** Should the _events array be an associative array with the events' EIDs as keys?
* Event Class
** Should the class be aware of whether the event already exists in the DB? That way it know which of "update_to_database" and "save_to_database" function is appropriate?
** Should the class be aware of whether the event is the moderation or event table? That way the "modify" and "modify_moderation" functions wouldn't be necessary (the class would know the appropriate table automatically).
* addslashes is used extensively to sanitize input. Should Geeklog's filter routines be used instead in places?
* upload.php -- mentioned in a previous email, but we should be using the upload.class.php that comes with Geeklog.
* Geeklog allows the use of InnoDB tables. The calendar should use whatever table type the rest of Geeklog is using.

Calendarv2

2010-12-15T06:45:23Z

Vinny: /* Thoughts: */

Calendarv2

2010-12-15T06:44:14Z

Vinny: /* What needs to be done till the alpha release? */

Calendarv2

2010-12-15T06:43:33Z

Vinny: /* Thoughts: */

== What needs to be done till the alpha release? ==

* Fix Ical Support. 
* Render recurring events immediately after an event was created, not just on page load.
* Review Security (specifically user access rights to events)

== Future plans/improvements: ==

* When Geeklog moves to PHP 5.3 (or earlier, as time permits) switch to using MySQL Datetime types. PHP 5.3's enhanced DateTime class makes the switch easier.
* Conversion script to convert existing Geeklog calendars to Calendarv2.
* Use PHP's locale settings for Day of Week, Month Names, etc instead of the language file [http://php.net/manual/en/function.setlocale.php]

== Thoughts: ==

* AEvents Class
** Should the _events array be an associative array with the events' EIDs as keys?
* Event Class
** Should the class be aware of whether the event already exists in the DB? That way it know which of "update_to_database" and "save_to_database" function is appropriate?
** Should the class be aware of whether the event is the moderation or event table? That way the "modify" and "modify_moderation" functions wouldn't be necessary (the class would know the appropriate table automatically).
* addslashes is used extensively to sanitize input. Should Geeklog's filter routines be used instead in places?

Calendarv2

2010-12-14T08:02:48Z

Vinny:

== What needs to be done till the alpha release? ==

* Fix Ical Support. 
* Render recurring events immediately after an event was created, not just on page load.
* Review Security (specifically user access rights to events)

== Future plans/improvements: ==

* When Geeklog moves to PHP 5.3 (or earlier, as time permits) switch to using MySQL Datetime types. PHP 5.3's enhanced DateTime class makes the switch easier.
* Conversion script to convert existing Geeklog calendars to Calendarv2.
* Use PHP's locale settings for Day of Week, Month Names, etc instead of the language file [http://php.net/manual/en/function.setlocale.php]

== Thoughts: ==

* AEvents Class
** Should the _events array be an associative array with the events' EIDs as keys?

Calendarv2

2010-12-14T07:32:11Z

Vinny: /* Future plans/improvements: */

== What needs to be done till the alpha release? ==

* Fix Ical Support. 
* Render recurring events immediately after an event was created, not just on page load.

== Future plans/improvements: ==

* When Geeklog moves to PHP 5.3 (or earlier, as time permits) switch to using MySQL Datetime types. PHP 5.3's enhanced DateTime class makes the switch easier.
* Conversion script to convert existing Geeklog calendars to Calendarv2.
* Use PHP's locale settings for Day of Week, Month Names, etc instead of the language file [http://php.net/manual/en/function.setlocale.php]

Calendarv2

2010-11-29T03:24:43Z

Vinny: /* Future plans/improvements: */

Calendarv2

2010-11-28T03:07:17Z

Vinny: /* What needs to be done till the alpha release? */

Calendarv2

2010-11-28T03:05:54Z

Vinny: /* Future plans/improvements: */

== What needs to be done till the alpha release? ==

- Fix Ical Support. 
- Render recurring events immediately after an event was created, not just on page load.

== Future plans/improvements: ==

* When Geeklog moves to PHP 5.3 (or earlier, as time permits) switch to using MySQL Datetime types. PHP 5.3's enhanced DateTime class makes the switch easier.

Plugin Toolkit

2010-05-06T17:15:24Z

Vinny: grammer

The Geeklog Plugin Toolkit is set to eventually replace the aging [[Universal Plugin ToolKit|Universal Plugin]]. It will contain of a set of tools to assist plugin developers in creating and maintaining their plugins.

For now, there is only one tool available: The Plugin Generator.

== Plugin Generator ==

The Plugin Generator has to be called from the command line. For this, you need the CLI version of PHP.

<pre>cd plugin-toolkit
php plgen.php</pre>

Follow the on-screen instructions. Default values are given in square brackets and can be used by pressing enter. If you want to change a value, simply enter it and then press enter.

A plugin directory, using the name you entered, will be created in the current directory. This is a fully usable plugin, although it doesn't exactly do much yet. It does, however, perform install and uninstall and includes generic public and admin pages. Filling in the functionality is your job ...

'''Note:''' [http://project.geeklog.net/tracking/view.php?id=828 Currently] the created plugin requires Geeklog 1.6 or later.

== Links ==

* [http://www.geeklog.net/filemgmt/index.php?id=941 Download] from geeklog.net
* [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/plugin-toolkit/ Mercurial repository] for the Plugin Toolkit
* The Plugin Toolkit is a separate project in the [http://project.geeklog.net/tracking/ bugtracker]. Select "Plugin Toolkit" from the "Project:" dropdown.
* [[Plugin Developers Handbook|Plugin Developer Handbook]]
** also see [[Programmers/Developers Documentation]] for plugin API changes and additions

[[Category:Plugin Development]]

Plugin Toolkit

2010-05-06T17:14:59Z

Vinny: Updated compatible version information.

The Geeklog Plugin Toolkit is set to eventually replace the aging [[Universal Plugin ToolKit|Universal Plugin]]. It will contain of a set of tools to assist plugin developers in creating and maintaining their plugins.

For now, there is only one tool available: The Plugin Generator.

== Plugin Generator ==

The Plugin Generator has to be called from the command line. For this, you need the CLI version of PHP.

<pre>cd plugin-toolkit
php plgen.php</pre>

Follow the on-screen instructions. Default values are given in square brackets and can be used by pressing enter. If you want to change a value, simply enter it and then press enter.

A plugin directory, using the name you entered, will be created in the current directory. This is a fully usable plugin, although it doesn't exactly do much yet. It does, however, perform install and uninstall and includes generic public and admin pages. Filling in the functionality is your job ...

'''Note:''' [http://project.geeklog.net/tracking/view.php?id=828 Currently], the created plugin requires Geeklog 1.6 or later.

== Links ==

* [http://www.geeklog.net/filemgmt/index.php?id=941 Download] from geeklog.net
* [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/plugin-toolkit/ Mercurial repository] for the Plugin Toolkit
* The Plugin Toolkit is a separate project in the [http://project.geeklog.net/tracking/ bugtracker]. Select "Plugin Toolkit" from the "Project:" dropdown.
* [[Plugin Developers Handbook|Plugin Developer Handbook]]
** also see [[Programmers/Developers Documentation]] for plugin API changes and additions

[[Category:Plugin Development]]

SoC calendar plugin

2010-03-04T23:48:28Z

Vinny: added outlook sync to "nice to haves"

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

== Overview ==
Geeklog's current calendar plugin is old and unmaintainable. It has no support for modern calendar standards and cannot support such basic functionality as recurring events. It's interface is antiquated and its sharing/group features are extremely limited.

A new Calendar plugin, written from scratch, could be designed from the ground up to work with calendar standards and support a wide variety of use cases.

== Requirements ==
Listed below are an initial set of requirements. Students applying to complete this project can use the below list as a design outline. Though, don't let the requirement set here limit you!

=== Basic Requirements ===
* The calendar shall support events for individual users.
** Individuals shall be able to create multiple calendars (possibly limited to a number defined by an administrator).
** The calendar owner shall be able to control the visibility of the calendar (private, shared to a group, public).
* The calendar shall support site wide events.
** Who can submit site wide events shall be controlled by the site administrator.
** When given permission to submit site wide events, users can submit a copy of an existing individual events to the site wide calendar.
** The site administrator shall be able to moderate events submitted by non-admin users.
** Only site administrators shall be able to modify existing events.
* The calendar shall support recurring events.
* The calendar shall have an efficient implementation (responsive).
** A smart design will be needed to support recurring events without causing a lack of responsiveness.
* The calendar shall implement Geeklog's [[Multilingual Support|Multi-language support]].
* The calendar shall support "locales".
** Configurable date and time format (e.g. 01/21/2010 vs 2010/01/21 vs 21/01/2010, 8:00pm vs 20:00h)
*** also for date and time entry
** Configurable first day of week (e.g. Monday vs Sunday)

=== Nice to Haves ===
This is a set of items that would be nice for a calendar plugin to have. At the very least, a calendar plugin should be designed so that adding these features would not be difficult.
* The calendar shall support group events.
* The calendar shall have the ability to import, export and perhaps sync using the iCal ([http://tools.ietf.org/html/rfc5545 RFC5545]) format.
** Ability to share with services like [http://upcoming.yahoo.com/ Upcoming], [http://www.dopplr.com/ Dopplr], or [http://www.google.com/calendar Google Calendar], so events only have to be entered once.
** The calendar shall optionally support WebDAV ([http://tools.ietf.org/html/rfc2518 RFC2518]) for calendar and schedule sharing.
* The calendar shall be able to sync with MS Outlook (very difficult!).
* The calendar shall support [http://microformats.org/wiki/hcalendar HCalendar].
* The calendar shall support for event reminders.
* The calendar shall support sending event invitations and tracking responses.

=== Bonus Items ===
Listed here are items that do not have a direct impact on the plugin design, but are features that would be nice to have if time permits.
* A migration utility to convert existing Geeklog calendar tables to work with the new plugin.
* Create a calendar block for display in Geeklog's left or right blocks.

== Notes ==
If desired, a license compatible (Geeklog is licensed [http://www.gnu.org/licenses/gpl-2.0.html GPL 2.0]) PHP library/program can be used. However, this should definitely be researched and decided upon before an application is submitted.

== Level of Difficulty ==
''medium'' to ''difficult''

The level of difficulty on this project will be dependent upon the design and feature set chosen to be implemented.

== Further Reading ==
===References===
* [http://en.wikipedia.org/wiki/ICalendar Wikipedia: iCalendar]
* [http://en.wikipedia.org/wiki/CalDAV Wikipedia: CalDAV]

===Bug Tracker===
* [http://project.geeklog.net/tracking/view.php?id=974 0000974: Make order of day/month/year dropdowns configurable in editors (without template change)]
* [http://project.geeklog.net/tracking/view.php?id=635 0000635: Required visual cues in Calendar Plugin's Event Editor v1.5b1]
* [http://project.geeklog.net/tracking/view.php?id=993 0000993: calendar plugin: submit event's owner is not submit user.]
* [http://project.geeklog.net/tracking/view.php?id=946 0000946: Issue about "Submit an Event" form of the Calendar plugin]
* [http://project.geeklog.net/tracking/view.php?id=775 0000775: Mark links to future dates in calendar with rel="nofollow"]
* [http://project.geeklog.net/tracking/view.php?id=674 0000674: Calender Event invitations]
* [http://project.geeklog.net/tracking/view.php?id=675 0000675: Calendar Event Reminder Email]

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

SoC calendar plugin

2010-03-04T23:42:27Z

Vinny: Separated out "must haves" and "nice to haves". Added Notes section. Fixed some spelling, grammer, and "clarity" errors.

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

== Overview ==
Geeklog's current calendar plugin is old and unmaintainable. It has no support for modern calendar standards and cannot support such basic functionality as recurring events. It's interface is antiquated and its sharing/group features are extremely limited.

A new Calendar plugin, written from scratch, could be designed from the ground up to work with calendar standards and support a wide variety of use cases.

== Requirements ==
Listed below are an initial set of requirements. Students applying to complete this project can use the below list as a design outline. Though, don't let the requirement set here limit you!

=== Basic Requirements ===
* The calendar shall support events for individual users.
** Individuals shall be able to create multiple calendars (possibly limited to a number defined by an administrator).
** The calendar owner shall be able to control the visibility of the calendar (private, shared to a group, public).
* The calendar shall support site wide events.
** Who can submit site wide events shall be controlled by the site administrator.
** When given permission to submit site wide events, users can submit a copy of an existing individual events to the site wide calendar.
** The site administrator shall be able to moderate events submitted by non-admin users.
** Only site administrators shall be able to modify existing events.
* The calendar shall support recurring events.
* The calendar shall have an efficient implementation (responsive).
** A smart design will be needed to support recurring events without causing a lack of responsiveness.
* The calendar shall implement Geeklog's [[Multilingual Support|Multi-language support]].
* The calendar shall support "locales".
** Configurable date and time format (e.g. 01/21/2010 vs 2010/01/21 vs 21/01/2010, 8:00pm vs 20:00h)
*** also for date and time entry
** Configurable first day of week (e.g. Monday vs Sunday)

=== Nice to Haves ===
This is a set of items that would be nice for a calendar plugin to have. At the very least, a calendar plugin should be designed so that adding these features would not be difficult.
* The calendar shall support group events.
* The calendar shall have the ability to import, export and perhaps sync using the iCal ([http://tools.ietf.org/html/rfc5545 RFC5545]) format.
** Ability to share with services like [http://upcoming.yahoo.com/ Upcoming], [http://www.dopplr.com/ Dopplr], or [http://www.google.com/calendar Google Calendar], so events only have to be entered once.
** The calendar shall optionally support WebDAV ([http://tools.ietf.org/html/rfc2518 RFC2518]) for calendar and schedule sharing.
* The calendar shall support [http://microformats.org/wiki/hcalendar HCalendar].
* The calendar shall support for event reminders.
* The calendar shall support sending event invitations and tracking responses.

=== Bonus Items ===
Listed here are items that do not have a direct impact on the plugin design, but are features that would be nice to have if time permits.
* A migration utility to convert existing Geeklog calendar tables to work with the new plugin.
* Create a calendar block for display in Geeklog's left or right blocks.

== Notes ==
If desired, a license compatible (Geeklog is licensed [http://www.gnu.org/licenses/gpl-2.0.html GPL 2.0]) PHP library/program can be used. However, this should definitely be researched and decided upon before an application is submitted.

== Level of Difficulty ==
''medium'' to ''difficult''

The level of difficulty on this project will be dependent upon the design and feature set chosen to be implemented.

== Further Reading ==
===References===
* [http://en.wikipedia.org/wiki/ICalendar Wikipedia: iCalendar]
* [http://en.wikipedia.org/wiki/CalDAV Wikipedia: CalDAV]

===Bug Tracker===
* [http://project.geeklog.net/tracking/view.php?id=974 0000974: Make order of day/month/year dropdowns configurable in editors (without template change)]
* [http://project.geeklog.net/tracking/view.php?id=635 0000635: Required visual cues in Calendar Plugin's Event Editor v1.5b1]
* [http://project.geeklog.net/tracking/view.php?id=993 0000993: calendar plugin: submit event's owner is not submit user.]
* [http://project.geeklog.net/tracking/view.php?id=946 0000946: Issue about "Submit an Event" form of the Calendar plugin]
* [http://project.geeklog.net/tracking/view.php?id=775 0000775: Mark links to future dates in calendar with rel="nofollow"]
* [http://project.geeklog.net/tracking/view.php?id=674 0000674: Calender Event invitations]
* [http://project.geeklog.net/tracking/view.php?id=675 0000675: Calendar Event Reminder Email]

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

CommentAlgorithm

2010-02-25T18:37:45Z

Vinny: Added missing /code

=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</code>

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 
UPDATE comments SET rht = rht + 2 WHERE rht >= comment.rht 
UPDATE comments SET lft = lft + 2 WHERE lft >= comment.rht 
INSERT INTO comments SET lft = comment.rht, rht = comment.rht + 1 
COMMIT</code>

Deletions:

<code>START TRANSACTION 
UPDATE comments SET rht = rht - 2 WHERE rht > comment.rht 
UPDATE comments SET lft = lft - 2 WHERE lft > comment.rht 
DELETE FROM comments WHERE id = comment.id 
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]

SoC calendar plugin

2010-02-24T18:29:09Z

Vinny: Added some more links, WebDAV

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

== Overview ==
Geeklog's current calendar plugin is old and unmaintainable. It has no support for modern calendar standards and cannot support such basic functionality as recurring events. It's interface is antiquated and its sharing/group features are extremely limited.

A new Calendar plugin, written from scratch, could be designed from the group up to work with calendar standards and support a wide variety of use cases.

== Requirements ==
Listed below are an initial set of requirements. Students applying to complete this project can use the below list as a design outline.

* The calendar shall support events for individual users.
** Individuals shall be able to create multiple calendars (limited to number defined by an administrator).
** The calendar owner shall be able to control the visibility of the calendar (private, shared to a group, public).
* The calendar shall support group events.
* The calendar shall support site wide events.
** Who can submit site wide events shall be controlled by the site administrator.
** When given permission to submit site wide events, users can submit a copy of an existing individual events to the site wide calendar.
** The site administrator shall be able to moderate events submitted by non-admin users.
** Only site administrators shall be able to modify existing events.
* The calendar shall have the ability to import, export and perhaps sync using the iCal ([http://tools.ietf.org/html/rfc5545 RFG5545]) format.
** Ability to share with services like [http://upcoming.yahoo.com/ Upcoming], [http://www.dopplr.com/ Dopplr], or [http://www.google.com/calendar Google Calendar], so events only have to be entered once.
** The calendar shall optionally support WebDAV ([http://tools.ietf.org/html/rfc2518 RFC2518]) for calendar and schedule sharing.
* The calendar shall support [http://microformats.org/wiki/hcalendar HCalendar].
* The calendar shall support recurring events.
* The calendar shall have an efficient implementation (responsive).
** A smart design will be needed to support recurring events without causing a lack of responsiveness.
* The calendar shall support for event reminders.
* The calendar shall support sending event invitations and tracking responses.
* The calendar shall implement Geeklog's [[Multilingual Support|Multi-language support]].
* The calendar shall support "locales".
** Configurable date format (e.g. 01/21/2010 vs 2010/01/21 vs 21/01/2010)
** Configurable first day of week (e.g. Monday vs Sunday)

== Bonus ==
* A migration utility to convert existing Geeklog calendar tables to work with the new plugin.
* Create a calendar block for display in Geeklog's left or right blocks.

== Level of Difficulty ==
''medium'' to ''difficult''

The level of difficulty on this project will be dependent upon the chosen design and implemented features.

== Further Reading ==
===References===
* [http://en.wikipedia.org/wiki/ICalendar Wikipedia: iCalendar]
* [http://en.wikipedia.org/wiki/CalDAV Wikipedia: CalDAV]

===Bug Tracker===
* [http://project.geeklog.net/tracking/view.php?id=974 0000974: Make order of day/month/year dropdowns configurable in editors (without template change)]
* [http://project.geeklog.net/tracking/view.php?id=635 0000635: Required visual cues in Calendar Plugin's Event Editor v1.5b1]
* [http://project.geeklog.net/tracking/view.php?id=993 0000993: calendar plugin: submit event's owner is not submit user.]
* [http://project.geeklog.net/tracking/view.php?id=946 0000946: Issue about "Submit an Event" form of the Calendar plugin]
* [http://project.geeklog.net/tracking/view.php?id=775 0000775: Mark links to future dates in calendar with rel="nofollow"]
* [http://project.geeklog.net/tracking/view.php?id=674 0000674: Calender Event invitations]
* [http://project.geeklog.net/tracking/view.php?id=675 0000675: Calendar Event Reminder Email]

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

SoC calendar plugin

2010-02-24T17:36:44Z

Vinny:

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

== Overview ==
Geeklog's current calendar plugin is old and unmaintainable. It has no support for modern calendar standards and cannot support such basic functionality as recurring events. It's interface is antiquated and its sharing/group features are extremely limited.

A new Calendar plugin, written from scratch, could be designed from the group up to work with calendar standards and support a wide variety of use cases.

== Requirements ==
Listed below are an initial set of requirements. Students applying to complete this project can use the below list as a design outline.

* The calendar shall support events for individual users.
** Individuals shall be able to create multiple calendars (limited to number defined by an administrator).
** The calendar owner shall be able to control the visibility of the calendar (private, shared to a group, public).
* The calendar shall support group events.
* The calendar shall support site wide events.
** Who can submit site wide events shall be controlled by the site administrator.
** When given permission to submit site wide events, users can submit a copy of an existing individual events to the site wide calendar.
** The site administrator shall be able to moderate events submitted by non-admin users.
** Only site administrators shall be able to modify existing events.
* The calendar shall have the ability to import, export and perhaps sync using the iCal ([http://tools.ietf.org/html/rfc5545 RFG5545]) format.
** Ability to share with services like [http://upcoming.yahoo.com/ Upcoming], [http://www.dopplr.com/ Dopplr], or [http://www.google.com/calendar Google Calendar], so events only have to be entered once.
* The calendar shall support [http://microformats.org/wiki/hcalendar HCalendar].
* The calendar shall support recurring events.
* The calendar shall have an efficient implementation (responsive).
** A smart design will be needed to support recurring events without causing a lack of responsiveness.
* The calendar shall support for event reminders.
* The calendar shall support sending event invitations and tracking responses.
* The calendar shall implement Geeklog's [[Multilingual Support|Multi-language support]].
* The calendar shall support "locales".
** Configurable date format (e.g. 01/21/2010 vs 2010/01/21 vs 21/01/2010)
** Configurable first day of week (e.g. Monday vs Sunday)

== Bonus ==
* A migration utility to convert existing Geeklog calendar tables to work with the new plugin.
* Create a calendar block for display in Geeklog's left or right blocks.

== Level of Difficulty ==
''medium'' to ''difficult''

The level of difficulty on this project will be dependent upon the chosen design and implemented features.

== Further Reading ==
===From the Bug Tracker===
* [http://project.geeklog.net/tracking/view.php?id=974 0000974: Make order of day/month/year dropdowns configurable in editors (without template change)]
* [http://project.geeklog.net/tracking/view.php?id=635 0000635: Required visual cues in Calendar Plugin's Event Editor v1.5b1]
* [http://project.geeklog.net/tracking/view.php?id=993 0000993: calendar plugin: submit event's owner is not submit user.]
* [http://project.geeklog.net/tracking/view.php?id=946 0000946: Issue about "Submit an Event" form of the Calendar plugin]
* [http://project.geeklog.net/tracking/view.php?id=775 0000775: Mark links to future dates in calendar with rel="nofollow"]
* [http://project.geeklog.net/tracking/view.php?id=674 0000674: Calender Event invitations]
* [http://project.geeklog.net/tracking/view.php?id=675 0000675: Calendar Event Reminder Email]

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

SoC calendar plugin

2010-02-24T17:20:55Z

Vinny: Initial Overview and Requriements.

GSoC Brainstorming

2010-02-24T17:16:48Z

Vinny: Moved calendar plugin into its own GSOC page.

These are new and not fully fleshed-out ideas for the [[Google Summer of Code]]. Contributions welcome!

* Site Migration for PostgreSQL and/or MS SQL
* Database Migration: Switch from Postgres to MySQL or MS SQL or the other way around
* E-Mail Subsystem: Geeklog sometimes has to send out a lot of emails. Instead of sending them all at once (and running into timeouts), we could queue them and send them out in batches. This queue should allow for other job types as well.
* Facebook Connect: Allow users to login to a Geeklog site with their Facebook Account. Could become part of the [[SoC socialnetworking|Social Networking Features]] Project.
* Multi-site Setup: Run several websites off of one codebase. There's a [http://geeklog.fr//wiki/doku.php/hack:geeklog-multi-sites-1.5.0 hack] for that, but it's a pain for upgrades.
* Admin toolbox: A collection of mini-plugins for admin tasks (e.g. reset stats, change a default setting for all users, etc.). Should have super easy install, e.g. just drop (upload?) a file in a predefined directory.
* Migration from/to other systems is always a hot topic. How could we make that easier?
* Multi user blogs. Geeklog can handle blogs of several users, actually, if you give one topic to a user then it is almost unlimited. There are a few existing discussions on the forum and also feature requests concerning the improvement of user blogs. E.g. read only topics, using GL for a large site with many users. Basically it is a native function of GL but it need some improvement.
* Add shopping cart and/or e-commerce functionality to Geeklog (in the form of a plugin). Using an existing open source shopping cart or e-commerce web application would probably be a good idea, but the result should be fully integrated with Geeklog's security model ([http://www.geeklog.net/forum/viewtopic.php?showtopic=74449 related forum discussion])

As we flesh out these ideas, they will be moved to their own pages and linked to from our [[Google Summer of Code|GSoC Start Page]].

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

Google Summer of Code

2010-02-24T15:54:37Z

Vinny: Added calendar plugin

User:Vinny

2010-02-16T23:08:07Z

Vinny:

Email: [mailto:vinny01ATusersDOTsourceforgeDOTnet vinny01 AT users DOT sourceforge DOT net]

GSoC Brainstorming

2010-02-16T23:07:12Z

Vinny: Added e-commerce idea

These are new and not fully fleshed-out ideas for the [[Google Summer of Code]]. Contributions welcome!

* Site Migration for PostgreSQL and/or MS SQL
* Database Migration: Switch from Postgres to MySQL or MS SQL or the other way around
* E-Mail Subsystem: Geeklog sometimes has to send out a lot of emails. Instead of sending them all at once (and running into timeouts), we could queue them and send them out in batches. This queue should allow for other job types as well.
* Facebook Connect: Allow users to login to a Geeklog site with their Facebook Account. Could become part of the [[SoC socialnetworking|Social Networking Features]] Project.
* Multi-site Setup: Run several websites off of one codebase. There's a [http://geeklog.fr//wiki/doku.php/hack:geeklog-multi-sites-1.5.0 hack] for that, but it's a pain for upgrades.
* Admin toolbox: A collection of mini-plugins for admin tasks (e.g. reset stats, change a default setting for all users, etc.). Should have super easy install, e.g. just drop (upload?) a file in a predefined directory.
* Migration from/to other systems is always a hot topic. How could we make that easier?
* Multi user blogs. Geeklog can handle blogs of several users, actually, if you give one topic to a user then it is almost unlimited. There are a few existing discussions on the forum and also feature requests concerning the improvement of user blogs. E.g. read only topics, using GL for a large site with many users. Basically it is a native function of GL but it need some improvement.
* New Calendar Plugin - Our current calendar plugin is, to say the least, lacking in lots of important features. Tries to enhance the calendar to add these features doesn't seem feasible from prior experience. A new calendar plugin could have the following features:
** Support for "site wide events", "user events" and "group events".
** Moderation for submission of site events. Ability to submit an existing "user event" as a site wide or group event.
** Ability to share personal calendars with other users.
** Ability to import, export and perhaps sync using the iCal format.
** Ability to create recurring events.
** Have an efficient implementation (especially important when implementing recurring events)
** Support for event reminders.
** Invitations and attendance tracking.
* Add shopping card and/or e-commerce functionality to Geeklog (in the form of a plugin). Using an existing open source shopping card or e-commerce web application would probably be a good idea, but the result should be fully integrated with Geeklog's security model.

As we flesh out these ideas, they will be moved to their own pages and linked to from our [[Google Summer of Code|GSoC Start Page]].

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

GSoC Brainstorming

2010-02-16T23:03:53Z

Vinny: Added Calendar Plugin Suggestion

These are new and not fully fleshed-out ideas for the [[Google Summer of Code]]. Contributions welcome!

* Site Migration for PostgreSQL and/or MS SQL
* Database Migration: Switch from Postgres to MySQL or MS SQL or the other way around
* E-Mail Subsystem: Geeklog sometimes has to send out a lot of emails. Instead of sending them all at once (and running into timeouts), we could queue them and send them out in batches. This queue should allow for other job types as well.
* Facebook Connect: Allow users to login to a Geeklog site with their Facebook Account. Could become part of the [[SoC socialnetworking|Social Networking Features]] Project.
* Multi-site Setup: Run several websites off of one codebase. There's a [http://geeklog.fr//wiki/doku.php/hack:geeklog-multi-sites-1.5.0 hack] for that, but it's a pain for upgrades.
* Admin toolbox: A collection of mini-plugins for admin tasks (e.g. reset stats, change a default setting for all users, etc.). Should have super easy install, e.g. just drop (upload?) a file in a predefined directory.
* Migration from/to other systems is always a hot topic. How could we make that easier?
* Multi user blogs. Geeklog can handle blogs of several users, actually, if you give one topic to a user then it is almost unlimited. There are a few existing discussions on the forum and also feature requests concerning the improvement of user blogs. E.g. read only topics, using GL for a large site with many users. Basically it is a native function of GL but it need some improvement.
* New Calendar Plugin - Our current calendar plugin is, to say the least, lacking in lots of important features. Tries to enhance the calendar to add these features doesn't seem feasible from prior experience. A new calendar plugin could have the following features:
** Support for "site wide events", "user events" and "group events".
** Moderation for submission of site events. Ability to submit an existing "user event" as a site wide or group event.
** Ability to share personal calendars with other users.
** Ability to import, export and perhaps sync using the iCal format.
** Ability to create recurring events.
** Have an efficient implementation (especially important when implementing recurring events)
** Support for event reminders.
** Invitations and attendance tracking.

As we flesh out these ideas, they will be moved to their own pages and linked to from our [[Google Summer of Code|GSoC Start Page]].

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

CommentAlgorithm

2009-07-23T22:36:15Z

Vinny: /* Representing Geeklog's Comments in the Database */

=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.

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 
UPDATE comments SET rht = rht + 2 WHERE rht >= comment.rht 
UPDATE comments SET lft = lft + 2 WHERE lft >= comment.rht 
INSERT INTO comments SET lft = comment.rht, rht = comment.rht + 1 
COMMIT</code>

Deletions:

<code>START TRANSACTION 
UPDATE comments SET rht = rht - 2 WHERE rht > comment.rht 
UPDATE comments SET lft = lft - 2 WHERE lft > comment.rht 
DELETE FROM comments WHERE id = comment.id 
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).

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]

CommentAlgorithm

2009-07-23T20:42:51Z

Vinny: New page: =Representing Geeklog's Comments in the Database= Since Geeklog 1.4.x, Geeklog's comments have been stored in the database with columns (''lft'', ''rht'') representing a (modified) pre-or...

=Representing Geeklog's Comments in the Database=

Since Geeklog 1.4.x, 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.

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 
UPDATE comments SET rht = rht + 2 WHERE rht >= comment.rht 
UPDATE comments SET lft = lft + 2 WHERE lft >= comment.rht 
INSERT INTO comments SET lft = comment.rht, rht = comment.rht + 1 
COMMIT</code>

Deletions:

<code>START TRANSACTION 
UPDATE comments SET rht = rht - 2 WHERE rht > comment.rht 
UPDATE comments SET lft = lft - 2 WHERE lft > comment.rht 
DELETE FROM comments WHERE id = comment.id 
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).

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]

Programmers/Developers Documentation

2009-07-23T19:39:44Z

Vinny:

Development Environment

2009-04-27T20:33:36Z

Vinny: /* Getting things up and running */

= What is it? =

We're providing a "ready to roll" development environment for Geeklog and AptitudeCMS in a VMware image that includes

* Ubuntu Linux as the operation system
* Apache Web Server
* PHP
* MySQL
* Mercurial and Subversion
* checked-out repository for Geeklog
* pre-installed version of Geeklog

We hope that in providing this environment, we make it easier for those interested in working on Geeklog and AptitudeCMS to start developing without having to install all the required tools first.

= Getting things up and running =

== Downloading the VM image ==

The URL for the image will be provided on request (due to bandwidth limitations - it's about 1 GB). Requests for the URL can be sent to <contact-us AT lists DOT geeklog DOT net>. Download and unpack it using bzip2 and tar.

== Get a Virtual Machine ==

Most providers of virtual machine software provide a free version with minor (or no) limitations. Try one of these:

* [http://www.virtualbox.org/ VirtualBox] from Sun, available for Linux, Solaris, Mac OS X, and Windows
* [http://www.vmware.com/products/player/ VMware Player] from VMware, available for Linux and Windows
* [http://www.vmware.com/products/server/ VMware Server] from VMware, available for Linux and Windows

Follow the installation instructions for the software you chose. When asked for the image to use, select the "primaryMaster.vmdk" file from the GeeklogVM.tar.bz2 archive.

= First Steps =

''TBD''

[[Category:Development]]

Development Environment

2009-04-02T19:39:54Z

Vinny: /* Get a Virtual Machine */

= What is it? =

We're providing a "ready to roll" development environment for Geeklog and AptitudeCMS in a VMware image that includes

* Ubuntu Linux as the operation system
* Apache Web Server
* PHP
* MySQL
* Mercurial and Subversion
* checked-out repository for Geeklog
* pre-installed version of Geeklog

We hope that in providing this environment, we make it easier for those interested in working on Geeklog and AptitudeCMS to start developing without having to install all the required tools first.

= Getting things up and running =

== Downloading the VM image ==

The URL for the image will be provided on request (due to bandwidth limitations - it's about 1 GB). Download and unpack it using bzip2 and tar.

== Get a Virtual Machine ==

Most providers of virtual machine software provide a free version with minor (or no) limitations. Try one of these:

* [http://www.virtualbox.org/ VirtualBox] from Sun, available for Linux, Solaris, Mac OS X, and Windows
* [http://www.vmware.com/products/player/ VMware Player] from VMware, available for Linux and Windows
* [http://www.vmware.com/products/server/ VMware Server] from VMware, available for Linux and Windows

Follow the installation instructions for the software you chose. When asked for the image to use, select the "primaryMaster.vmdk" file from the GeeklogVM.tar.bz2 archive.

= First Steps =

''TBD''

[[Category:Development]]

Development Environment

2009-04-02T19:35:14Z

Vinny:

= What is it? =

We're providing a "ready to roll" development environment for Geeklog and AptitudeCMS in a VMware image that includes

* Ubuntu Linux as the operation system
* Apache Web Server
* PHP
* MySQL
* Mercurial and Subversion
* checked-out repository for Geeklog
* pre-installed version of Geeklog

We hope that in providing this environment, we make it easier for those interested in working on Geeklog and AptitudeCMS to start developing without having to install all the required tools first.

= Getting things up and running =

== Downloading the VM image ==

The URL for the image will be provided on request (due to bandwidth limitations - it's about 1 GB). Download and unpack it using bzip2 and tar.

== Get a Virtual Machine ==

Most providers of virtual machine software provide a free version with minor (or no) limitations. Try one of these:

* [http://www.virtualbox.org/ VirtualBox] from Sun, available for Linux, Solaris, Mac OS X, and Windows
* [http://www.vmware.com/products/player/ VMware player] from VMware, available for Linux and Windows

Follow the installation instructions for the software you chose. When asked for the image to use, select the "primaryMaster.vmdk" file from the GeeklogVM.tar.bz2 archive.

= First Steps =

''TBD''

[[Category:Development]]