[geeklog-devel] Checkout plugin

[Euan McKay]

Hello,

I just wrote a plugin that, I think, is not useless. Even if I do say so myself.
The catch is it doesn't do anything. Well, not until other plugins co-operate.

I know this is not core development stuff, but I figured the right
people are on this list so I'm posting here. Also, I think it is
pretty useful functionality that later could be kept as a core plugin.

One, it will check out items when users edit them, so that other users
cannot edit them. Then, after a time limit and/or the user cancels or
saves, it will check the item in again.

Two, it will keep versions of items. All the plugin does is keep
pointers to items, and requires other plugins to actually add/delete
the versions (with two simple functions).

It just requires a single line call to the checkout plugin on edit,
save, cancel and delete.

I have a beta that works fine for me, but I'd like some feedback for
two reasons: one, if other plugin developers don't co-operate, this is
pretty useless, and two, I want to know if my way of adding version
tags to ids is going to mess up anything.

Part of the README file is posted below. If anyone interested would
like a tarball, email me and I'll send you one tomorrow.

Goodnight.

Euan.

-- 
-----------------------------------------------------------------------------
Euan McKay
PhD Candidate in International Relations
Department of Advanced Social and International Studies
Graduate School of Arts and Sciences
The University of Tokyo




README for Checkout plugin


6. Integration with other plugins

The Checkout plugin does nothing on its own; it is only of use when
another plugin uses its functionality. Integration is simple, and
consists of two calls on opening a document in edit mode, and on
saving a document. The code required in each case is as follows
(examples shown are for the staticpages plugin version 1.4.3 included
in Geeklog 1.4.1):

You only need to add the following line wherever you edit a page:

$out = checkout_item ('checkout', $sp_id, 'staticpages');

and the following line wherever you save, cancel or delete a page.

$in = checkout_item ('checkin', $sp_id, 'staticpages');


In more detail, with a box to inform the user in case the item was
already checked out.

Editing:

} else if ($mode == 'edit') {
    // Call the plugin to checkout the item, telling it the id and plugin.
    // The checkout plugin function will check whether the user has
enabled the checkout function or not.
    $out = checkout_item ('checkout', $sp_id, 'staticpages');
    if (is_array($out)) {
        // We were returned an array, so the item was already checked
out to someone. Display a message.
        // the value of $out['message'] is a formatted block, so you
could also show the page with the
        // block above.
        $display .= COM_siteHeader ('menu', $LANG_STATIC['staticpageeditor']);
        $display .= $out['message'];
        $display .= COM_siteFooter ();
    } else {
        // we checked out the item successfully. Show the page editor as usual.
        $display .= COM_siteHeader ('menu', $LANG_STATIC['staticpageeditor']);
        $editor = '';
        if (isset ($_GET['editor'])) {
            $editor = COM_applyFilter ($_GET['editor']);
        }
        $display .= staticpageeditor ($sp_id, $mode, $editor);
        $display .= COM_siteFooter ();
    }
} else if ($mode == 'clone') {



The following two API functions are also required:

This function, when asked, clones an item in the database and gives it
a unique id based on the version number provided. e.g. 200804041234
becomes 200804041234_v_1

function checkout_add_version_staticpages ($sp_id, $version)
{
    global $_TABLES;
    $new_id = $sp_id . '_v_' . $version;

    // get existing page
    $result = DB_QUERY ("SELECT * FROM {$_TABLES['staticpage']} WHERE
sp_id='$sp_id'");
    $A = DB_FetchArray ($result);

    // save a copy with the new id
    DB_save ($_TABLES['staticpage'],
'sp_id,sp_uid,sp_title,sp_content,sp_date,sp_hits,sp_format,sp_onmenu,

sp_label,owner_id,group_id,perm_owner,perm_group,perm_members,perm_anon,sp_php,sp_nf,
                sp_centerblock,sp_help,sp_tid,sp_where,sp_inblock,postmode',

"'$new_id',{$A['sp_uid']},'{$A['sp_title']}','{$A['sp_content']}',NOW(),{$A['sp_hits']},

'{$A['sp_format']}',{$A['sp_onmenu']},'{$A['sp_label']}',{$A['owner_id']},{$A['group_id']},

{$A['perm_owner']},{$A['perm_group']},{$A['perm_members']},{$A['perm_anon']},'{$A['sp_php']}',

'{$A['sp_nf']}',{$A['sp_centerblock']},'{$A['sp_help']}','{$A['sp_tid']}',{$A['sp_where']},
                '{$A['sp_inblock']}','{$A['postmode']}'");
    return;
}

This function, when asked, deletes a version from the database which
it works out from the version number provided.

function checkout_delete_version_staticpages ($sp_id, $version)
{
    global $_TABLES;
    $delete_id = $sp_id . '_v_' . $version;
    $sql = "DELETE FROM {$_TABLES['staticpage']} WHERE
sp_id='{$delete_id}' LIMIT 1";
    DB_query ($sql, 1);
    if (DB_error ()) {
        return false;
    }
    return true;
}