User Function Guide functions.custom.php in Cotonti

Cotonti Custom Functions Guide

This guide provides a detailed description of four functions designed to identify the owner or author of content. Each function is accompanied by code examples and usage instructions.

1. Activating the Functions File

Before using the functions, you need to ensure that the file /system/functions.custom.php is enabled in the site configuration.

Open the file /datas/config.php. 

Find the line:

$cfg['customfuncs'] = false;

And change it to:

$cfg['customfuncs'] = true;

Now Cotonti will automatically load your custom functions from /system/functions.custom.php.

2. Placing the Function Code

All the code provided below should be placed in a single file: /system/functions.custom.php.

Function Descriptions and Examples 

1. Function cot_getUserDataOwner()

This function is a helper function. It searches for the page owner based on their ID or name in the URL.

Purpose

Retrieve a complete array of data from the cot_users table for a specific user. This data can be used to display user information.

When to Use

When you need to programmatically retrieve data about the page owner, such as their login, email, registration date, etc. This function returns a PHP array and is not intended for direct use in templates.

Where to Use

Within other PHP functions or files that work with user data.

Function Code

/**
 * Retrieves data for the page owner.
 *
 * This function identifies the page owner based on the 'id' or 'u' parameters from the URL.
 * If no parameters are provided, it uses the ID of the currently authenticated user.
 *
 * @return array|null Array of user data or null if the user is not found.
 */
function cot_getUserDataOwner()
{
    // Import the 'id' parameter from GET as an integer (INT), this is the user ID
    $id = cot_import('id', 'G', 'INT');
    // Import the 'u' parameter from GET as a string (TXT), this is the username
    $u = cot_import('u', 'G', 'TXT');

    // If a username is provided but no ID
    if (!empty($u) && empty($id)) {
        // Execute a database query: select user_id from the users table where user_name matches $u
        $id = Cot::$db->query(
            'SELECT user_id FROM ' . Cot::$db->users . ' WHERE user_name = ? LIMIT 1',
            [$u]
        )->fetchColumn();
    }
    // If neither ID nor username is provided, but the current user is authenticated
    elseif (empty($id) && empty($u) && Cot::$usr['id'] > 0) {
        // Use the ID of the currently authenticated user
        $id = Cot::$usr['id'];
    }

    // Check if the user exists in the database by the obtained ID and return their data
    if ($id > 0) {
        return Cot::$db->query(
            'SELECT * FROM ' . Cot::$db->users . ' WHERE user_id = ? LIMIT 1',
            [$id]
        )->fetch();
    }

    return null;
}

Example Usage in PHP

// Example of using the function in PHP code
$userData = cot_getUserDataOwner();
if ($userData) {
    echo "Hello, " . $userData['user_name'] . "!";
}

2. Function cot_isOwner()

This function is designed to check access rights. It uses cot_getUserDataOwner() to determine if the currently authenticated user is the page owner.

Purpose

Display or hide content depending on whether the current visitor is the page owner.

When to Use

When you need to display "Edit" or "Delete" buttons that should only be accessible to the page owner.

Where to Use

Exclusively in templates (.tpl) using the {PHP|...} tag.

Function Code

/**
 * Checks if the current user is the page owner.
 *
 * This function uses cot_getUserDataOwner() to retrieve the owner's data
 * and compares their ID with the ID of the currently authenticated user.
 *
 * @return bool True if the current user is the page owner, otherwise False.
 */
function cot_isOwner()
{
    // Retrieve the page owner's data using the helper function
    $ownerData = cot_getUserDataOwner();

    // Return true if data is found and the owner's ID matches the current user's ID
    if (!empty($ownerData) && Cot::$usr['id'] > 0 && Cot::$usr['id'] == $ownerData['user_id']) {
        return true;
    }

    // If conditions are not met, return false
    return false;
}

Example Usage in a Template

<!-- If the current user is the page owner -->
<!-- IF {PHP|cot_isOwner()} -->
    <a href="{PAGE_ID|cot_url('page','m=edit&id=$this')}">{PHP.L.Edit}</a>
<!-- ENDIF -->

3. Function cot_isTopicAuthor()

This function is specifically designed for forums. It checks if the current user is the author of the topic they are currently viewing.

Purpose

Display or hide content for the author of a specific topic.

When to Use

When you need to show a special message, button, or any other content only to the topic creator, for example, on the page with the first post of the topic.

Where to Use

In forum templates, usually in forums.posts.tpl outside the posts loopBEGIN: FORUMS_POSTS_ROW and END: FORUMS_POSTS_ROW  .

Function Code

/**
 * Checks if the current user is the topic author.
 *
 * This function retrieves the topic ID directly from the URL and compares the topic author's user_id
 * with the ID of the currently authenticated user.
 *
 * @return bool True if the current user is the topic author, otherwise False.
 */
function cot_isTopicAuthor()
{
    // Declare a global variable containing the forum topics table name
    global $db_forum_topics;

    // Import the topic ID directly from the URL parameter 'q'
    $topicId = cot_import('q', 'G', 'INT');

    // Check if the user is authenticated and if a topic ID is provided
    if (!Cot::$usr || Cot::$usr['id'] <= 0 || empty($topicId)) {
        return false;
    }

    // Execute a database query
    $posterId = Cot::$db->query(
        "SELECT ft_firstposterid FROM $db_forum_topics WHERE ft_id = ? LIMIT 1",
        [$topicId]
    )->fetchColumn();

    // Return true if the topic author's ID matches the current user's ID
    if ($posterId > 0 && Cot::$usr['id'] == $posterId) {
        return true;
    }

    // If conditions are not met, return false
    return false;
}

Example Usage in a Template

<!-- IF {PHP|cot_isTopicAuthor()} -->
    <b>Hello {PHP.usr.profile.user_name}, you've missed a lot</b>
<!-- ENDIF -->

4. Function cot_isPageAuthor()

This function works similarly to cot_isTopicAuthor(), but is designed for pages (articles) and uses the page owner's ID.

Purpose

Display or hide content for the author of a specific article.

When to Use

When you need to show special content, a button, or a message only to the article's creator. This is useful for articles where highlighting the author is important.

Where to Use

In page templates, usually in page.tpl.

Function Code

/**
 * Checks if the current user is the article author.
 *
 * This function retrieves the article ID directly from the URL and compares the article author's user_id
 * with the ID of the currently authenticated user.
 *
 * @return bool True if the current user is the article author, otherwise False.
 */
function cot_isPageAuthor()
{
    // Declare a global variable containing the pages table name
    global $db_pages;

    // Import the article ID directly from the URL parameter 'id'
    $pageId = cot_import('id', 'G', 'INT');

    // Check if the user is authenticated and if an article ID is provided
    if (!Cot::$usr || Cot::$usr['id'] <= 0 || empty($pageId)) {
        return false;
    }

    // Execute a database query
    $ownerId = Cot::$db->query(
        "SELECT page_ownerid FROM $db_pages WHERE page_id = ? LIMIT 1",
        [$pageId]
    )->fetchColumn();

    // Return true if the article owner's ID matches the current user's ID
    if ($ownerId > 0 && Cot::$usr['id'] == $ownerId) {
        return true;
    }

    // If conditions are not met, return false
    return false;
}

Example Usage in a Template

<!-- IF {PHP|cot_isPageAuthor()} -->
   <b>Hello {PHP.usr.profile.user_name}, you are the author of this article.</b>
<!-- ENDIF -->

.