How to add a configuration option to osTicket 1.8.1.2

So you wrote a mod or a plugin and want to add some configuration options directly to into the osTicket Admin panel. This is a short tutorial on how to add a setting to osTicket 1.8.1.2, and then have your mod (or plugin) check that setting.

First off realize that modding osTicket can result in the breaking of your site, and you should really perform a backup of both the site and your database prior to making changes.

Next is to decide what you want your setting to be; where you want to put it in the admin panel; and what you want to label it.  Personally I wrote a mod a while back that adds a client side open ticket list and think it would be great to be able to toggle this feature on and off, and control how many open tickets the mod displays.  You do not have to have this mod installed to follow this tutorial, but I figured a real world example might be easier so this tutorial will assume that mod is already installed. To that end I've decided on two settings:

  • "Display Open Tickets to Clients" which will be a check box., and have the help text of " Allow clients to view a safe summary of open tickets on the landing page"
  • "Display # open ticket to Clients:" which will be a text field, and have a help text of " (Limit the number of open tickets to display to clients - default 10)"

I've decided to put both of these settings in Admin panel -> Settings -> Tickets, as the last two options before the "Attachments" section.  So lets start editting with adding these fields there.

Let's open and edit: /include/class.config.php
Scroll down to line 304.
Just after the closing } add:

    function clientDisplayOpen() {
        return $this->get('client_display_open');
    }

    function clientDisplayNum() {
        return $this->get('client_display_num');
    }
This will let us use those functions to get the config variables values later.

Next scroll down to line 903.
After the line that reads:
'allow_client_updates'=>isset($vars['allow_client_updates'])?1:
add:
'client_display_open'=>isset($vars['client_display_open'])?1:0,
'client_display_num'=>$vars['client_display_num'],

This will make sure that our fields get updated when we hit save.

Now lets open and edit: /include/staff/settings-tickets.inc.php.
Scroll down to line 138.
Place your cursor after the </tr> and hit enter.
We are going to add a new tr here to display the settings on the page.
add:
        <tr>
            <td>Display Open Tickets to Clients:</td>
            <td>
                <input type="checkbox" name="client_display_open" <?php
                echo $config['client_display_open']?'checked="checked"':''; ?>>
                Allow clients to view a safe summary of open tickets on the landing page
            </td>
        </tr>
        <tr>
            <td>Display # open ticket to Clients:</td>
            <td>
                <?php
                    if($config['client_display_num'] == '0' || $config['client_display_num'] == null) {
                        $client_display_num = '10';
                    } else {
                        $client_display_num = $config['client_display_num'];
                    } ?>
                <input type="text" name="client_display_num" size=4 value="<?php echo $client_display_num ?>">
                <em>(Limit the number of open tickets to display to clients - default 10)</em>
            </td>
        </tr>

Let's go over this a little.
$config['client_display_open'] is the variable that holds if our check box is checked.
$config['client_display_num'] is the variable that holds the # of tickets to display.  Additionally it defaults to 10 if its not set, or is set to 0. This is redundant as its also checked in the display_help_topics.php also. 

Note: if you have a LOT of tickets open on a regular basis you may want to consider hard coding in a default for maximum also so that way staff cannot set it to say 500 and have it display 500 open tickets to the client.

Lastly we need to change the display logic a little to determine if we should be displaying the open ticket list.
lets open and edit: /index.php

replace last 9 lines with:
<?php
    if($cfg && $cfg->isKnowledgebaseEnabled()){ $displayfaq = '1'; }
    else { $displayfaq = '0'; }
    if ($ost->getConfig()->clientDisplayOpen()) { $displayopen = '1'; }
    else { $displayopen = '0'; }
    
    if ($displayopen == '1' && $displayfaq == '1') { ?>
        <p>Be sure to browse both our <a href="kb/index.php">Frequently Asked Questions (FAQs)</a>, and the open tickets below before opening a ticket.  Thank you.
        <div id="openticks"><?php include('display_open_topics.php'); ?></div>
        </p>
    <?php }
    else {
        if($displayfaq == '1') { ?>
            <p>Be sure to browse our <a href="kb/index.php">Frequently Asked Questions (FAQs)</a> before opening a ticket.  Thank you.
        <?php }
        if($displayopen == '1') { ?>
            <div id="openticks"><?php include('display_open_topics.php'); ?></div>
        <?php }   
    } ?></div><?php require(CLIENTINC_DIR.'footer.inc.php'); ?>

What this does is based on how displayfaq and displayopen are set it shows different things. The important part here if you're going to do this for something else is how we reference the setting specifically: $ost->getConfig()->clientDisplayOpen().

Lastly to be complete we need to edit the display_open_topics.php.  This file is not part of the standard osTicket distribution (yet?) and is included in the mod archive I mentioned earlier.  Currently its hard coded to display 10 records.  Locate lines 21-22 which should look like this:

// The maximum amount of open tickets that you want to display.
$limit = '10';

Replace them with the following:
// The maximum amount of open tickets that you want to display.
$limit = $ost->getConfig()->clientDisplayNum();

// if limit is 0 or null set to default [10].
if($limit == '0' || $limit == null) {
    $limit ='10';
}
What this does is check for the setting in the database and if it doesn't exist or is 0 for some reason sets the number to 10.  This is a little redundant because we also check to make sure that if its 0 or null that it gets set to 10 in /include/staff/settings-tickets.inc.php.

Now if you log into your osTicket installation and go to Admin panel -> Settings -> Settings -> Tickets you should see something like this:
new config options