A sitemap file is an XML file that defines the pages that you provide to search engines that you specify the files that are to be indexed in your site.  By using this protocol, you specify the exact pages that want the search engines to find, even though they may be database driven, or difficult to find through deep links on your site.  Sitemap files can be indexes where they contain a list of other sitemap files or sitemap entries containing links to web pages.  More information on the sitemaps protocol can be found at sitemaps.org.

This add on reads the knowledge base categories and articles from the WHMCS database tables and generates a list of the SEO titles from those table entries in a sitemap entry file.  It then reads the specified sitemap file, if it exists, and matches up the database table entries with the entries in the sitemap file.  If there are KB categories or articles that are not included in the sitemap file, the WHMCS admin is given the ability to add the articles to the sitemap file.  If the categories and articles are already in the sitemap file, then the WHMCS admin has the ability to update the timestamp in the sitemap file or remove the item from the sitemap file entirely.  The sitemap file can also contain additional static entries that will be listed in a separate table at the bottom of the page.   The WHMCS admin then has the ability to remove or update the timestamps on the static items.

The problem with creating sitemap entries from the WHMCS database is that the KB articles and categories are generated from the database versus stored as files in the file system which would contain timestamps of when the file was last written.  The WHMCS database does not store the time the article or category is updated so there is no way to know when the last update to the article was made.  To overcome this in the add on, the WHMCS admin must manually specify when to update the sitemap lastmod time of the articles by checking the box in the update column and re-generating the sitemap file.

To access this WHMCS module, the admin logs in and selects the Addon Modules menu item under the Utilities Menu.  From there, they are presented with a list of add on modules available.  If the KB Sitemap Generator was installed correctly, the module is listed as Kb Sitemap Gen.  Clicking on this title will access the module, which first must be installed.  To install, select the button that says “Install”.  This will create an additional WHMCS database table which will hold the sitemap file name.

Once the add on module is installed, the module presents three general areas of information. 1) WHMCS and Sitemap File information, 2) Table to manage WHMCS KB database data in the sitemap file, and 3) Table to manage static sitemap tables.

The WHMCS and Sitemap File information shows the WHMCS Root Path which is the path WHMCS believes it is installed in.  This URL path will be used to generate the URL in the sitemap file.  The next entry in this area shows the file path that the sitemap file will be created or exists in.  It defaults to the path where WHMCS is installed plus the file name “kbsitemap.xml”.  The file name and location can be changed by entering optional additional path information and file name and pressing the “Set File” button.  This will cause the add on module to store the new file location in its database table and will be available for future use of the module.  The input box will accept additional path information as well, so the sitemap file could reside in a different location.  For example setting the file to ../kbsitemap.xml will generate a sitemap file one directory higher than the WHMCS install directory.

The “Files From WHMCS KB Database” table lists the Type, URL , LastMod, and three check boxes to Add, Update, or Remove the item.  The Type is whether the item is a Category or an Article and each type is displayed with a different color in the table.  The URL is the address that is generated from the WHMCS installed directory plus the knowledge base sub-directory, plus the category or article id from the database, and finally the SEO friendly filename generated from the title or name of the article or category.  The LastMod column is the LastMod time from the sitemap if the item is in the sitemap, otherwise it is empty if it has not been generated.  The three check box columns allow the admin to manage the items in the sitemap file and all changes are made when the user presses the “Make Changes To Sitemap” button at the bottom of the admin module.  If the item is already in the sitemap file, the Add check box will be disabled and if the item is not yet in the sitemap file, the Update and Remove check boxes will be disabled.

The following image shows the WHMCS and Sitemap File Information as well as the begining of the table that lists the Files From WHMCS KB database.

KB Sitemap Generator Top Half

In addition to the sitemap information generated from the WHMCS database, this add on module can also manage additional static sitemap file information.  Beneath the Files From WHMCS KB Database area, the add on module will display sitemap entries that are not generated from the WHMCS knowledge base database tables.  These could include static entries or KB article and category that were manually entered and contained spelling or format errors.  The image below shows several entries that were static entries for the affiliates, tutorials, downloads, and announcements pages.  From this table the admin can Update or Remove the items in the sitemap file.

The image below shows the bottom of the WHMCS KB database table items as well as the static sitemap items.

KB Sitemap Generator Bottom Half

Now you can add your automatically generated sitemap to a sitemap index file.  For more information on using sitemaps and sitemap index files, click on the link to the article ”Building A Comprehensive Sitemap for SEO” in our blog.

This add on was developed for WHMCS version 4.1.1.   For more information on WHMCS, visit their home page.

You can download the script as a zip file for free in our shop by following this link.  Installation instructions can be found in the text file contained in the zip file.

The WHMCS system consists of code written in the PHP language with a MySQL database backend. The PHP code is obscured from viewing by a tool called Ioncube however the database is freely viewable and editable using standard MySQL tools such as phpMyAdmin. Normally the obscured code would cause a problem in creating modifications to databases and using the data, but the developers of WHMCS had the forethought to include the ability to create add-on modules within the WHMCS system. An add-on module is simply some PHP code that can be written and is called by the WHMCS system to display the information that the add-on provides.  Any information that needs to be displayed by the add-on module can be displayed within the WHMCS administration panels and can interact with the WHMCS database to retrieve and store information.

The add-on discussed in this article will add an additonal column to the WHMCS announcement table and create the code to interact with the column data.  When this add-on is installed, it is available in WHMCS under the ‘Utilities’ tab and selecting the ‘Addon Modules’ menu item.

Normally the PHP code to get the announcements from the database and show them on the home page looks something like this:

$result = mysql_query("SELECT * FROM tblannouncements WHERE published='on' ORDER BY id DESC LIMIT 3");
if (mysql_num_rows($result) == 0) {
echo '<p>There are no new announcements.</p>';
} else {
while($data = mysql_fetch_array ($result))
{
$id = $data['id'];
$date = $data['date'];
$announcement = $data['announcement'];
$title = $data['title'];
$date = formatdate($date);
echo'<div><span>'.$date.' - '.$title.' <a href="/hosting/announcements.php?id='.$id.'"><img src="/images/more.gif" width="30" height="15" alt="Display More News Detail" /></a></span></div>';
echo'<img align="middle" src="/images/news_sep.gif" alt="" width="237" height="2" />';
}
echo'<div><span>News &amp; announcements: <a href="/hosting/announcements.php">view more</a></span></div>';
}


This code will query the WHMCS database (connecting to the database not shown) and get all of the announcements from the ‘tblannoucements’ table.  It loops through each returned row and prints out the data from each row in HTML format to be displayed on the page.  Now let’s add our customization to the mix.
The first thing to do when creating the add-on is to BACKUP THE DATABASE!  This module will make modifications to the structure of the database and table data. Any incorrect code has the ability to wipe out the WHMCS tables or data, so you have been warned.

This WHMCS add-on has 4 overall stages:

1. Pre-install
2. Install
3. Operational
4. Uninstall

The WHMCS add-on system will check to see if the add-on is installed. If it is not, we are in the Pre-install stage. Our add-on will install an addtional column to the WHMCS MySQL announcement table, so the check to see if is installed will consists of querying the database for our column in the table:
if(!mysql_num_rows(mysql_query("SHOW COLUMNS FROM tblannouncements LIKE 'show_frontpage'")))

This simply asks the database to see if there are any columns named show_frontpage and if there is nothing returned, we complete the Pre-install stage. In the Pre-install stage, we show some HTML code to tell the user the add-on is not installed and display a button for them to click on to install the add-on:

if(!$_GET['install']){
echo '<h1>Not Yet Installed</h1>
<p>This add-on defines an additional field for the announcements table for display on external pages such as the home page.</p>
<p>To install it, click on the button below.</p>
<p><input type="button" value="Install Homepage Annoucements" onclick="window.location=\''.$modulelink.'&install=true\'"></p>';
}

This section of code is inclosed in a conditional block that checks the parameters passed to the page to determine if the user pressed the install button or not. If the install parameter is not set, the user has not requested installation of the add-on yet. The button has an onclick handler for the install button that when clicked, sends us back to this page with the install $_GET parameter set to true which will execute the else conditional block.  The $modulelink PHP variable is a pre-defined WHMCS name for our add-on.   Once this code is executed, when we return to this page, we will be in the Install stage and perform the the actual installation of the add-on which is defined by these lines:

} else {
// request install, create the table and send us back to this file
$query = "ALTER TABLE tblannouncements ADD `show_frontpage` BOOL NOT NULL DEFAULT 0";
$result=mysql_query($query);
header("Location: $modulelink");
exit;
}

This code creates a MySQL query string and sends it to the MySQL database. The query creates a column called show_frontpage in the existing WHMCS table tblannouncements.  This field is a BOOL field that cannot be null and has a default of zero when new items are added to the table.  Once the query is executed, the header function sends us back to this file with no install parameter set. When we test if the column exists after running this code, it will be true, and we will continue on to the Operational phase.

The Operational phase is where we perform any work we want to do with the add-on. There are three conditional blocks within the Operational phase. The second which we will talk about first is where there are no POST variables passed to the add-on. In this case, we simply display a table with all of the announcements listed and a check box next to them that is filled in with the yes-no value on whether to display the announcement on the front page. We get this information by getting all the information out of the announcements table and loop through each row returned printing the data out to the client.  This is done whether we complete the first conditional block or not.

The first conditional block that we skipped over temporarily, is when the user makes changes to the check boxes to change the display of the annoucement. In this case there will be a $_POST variable called announcements_id with values that will be fill in to the show_frontpage column that is passed to the script. When this variable has data, the first thing we do is to go to the tblannouncments table and set each show_frontpage column value to zero.  This is because the array that is passed back to us in the $_POST variable does not include unset values, only set values, so we cannot determine which ones were set before showing the page, so we just quickly clear them all.  Next we loop through each returned checkbox array item and set the show_frontpage values to one where the user had selected values in the check boxes.  This is the code that performs these actions:

// the table already exists in the database, get the values from the $_POST var if any
if ($_POST["announcements_id"]) {
$upquery = "UPDATE tblannouncements SET show_frontpage=0";
$result = mysql_query($upquery);
$announcements_id = sanitize($_POST["announcements_id"]);
// create a query to update values in the column based on the passed parameters
while (list($key,$val) = @each ($announcements_id)) {
$newquery = "UPDATE tblannouncements SET show_frontpage=1 WHERE id=".$val;
$result=mysql_query($newquery);
}
}

Now lets go back to our original code that displays the announcments in the home page and make the changes.  The only change necessary is how we select the items out of the database.  Using this new show_frontpage column we simply change the filter to only get the the results that have that column set:

$result = mysql_query("SELECT * FROM tblannouncements WHERE show_frontpage=1 ORDER BY id DESC LIMIT 3");

Now we can selectively display announcements in pages that are outside the WHMCS billing system.

The full source code for this article can be found in a zip file in our shop by following this link.

To install from the zip file, create a directory in the <WHMCS>/modules/admin/ directory called ‘homepage_announcements’ without the quotes and place the PHP file in this directory.  Log into your WHMCS and select ‘Addon Modules’ from the ‘Utilities’ Menu and you should see a item titled ‘Homepage Announcements’.  Clicking on that will allow the module to be installed.

Note that this script was built and tested to work with WHMCS version 4.1.1.  Any upgrades or changes to the WHMCS version may overwrite the changes here.  Ensure you backup your database before you install upgrades to WHMCS.

WHMCS has a quick and easy way to generate reports as add-ons to the core WHMCS functionality. They are implemented by creating a PHP script file and setting some predefined variables within the script. Uploading the file to the correct directory installs the file to be used in the WHMCS admin area. The hardest part is getting the correct data out of the WHMCS database for use.

The requirement for this report was to display the top 20 articles from the knowledgebase along with their category and the additional information that is stored for articles (number of votes cast, number of people that found it useful, and whether it is a private article only visible to logged in clients).
Start by creating a empty PHP file and giving it a useful file name. For this report we named this file knowledgebase_usage.php. We then copied the contents of the sample given under the documentation for the WHMCS reports into the empty file and fill in the obvious information for the description, header text, and footer text.

Next, we needed to determine what fields we would like to display for each article and the titles for them. Looking at the WHMCS database structure with a database tool such as phpMyAdmin, the categories are stored in a separate table from the articles and are linked with a link table, so we will have to join these tables to get all of the information about the articles.

The articles table stores the number of views, the total number of votes on whether the user found it useful, the number of those votes that found it useful , and whether the article is for private clients only. We will display each of these values in our report.

Now that we have this information we can create the table headings. Back in the knowledgebase_usage.php, we create the array for the headings:

$reportdata["tableheadings"] = array("Category","Title","Views","Stats","Is Private");

We also have the information to create our SQL query statement. We have to select the title,views, useful, votes, and private columns from the tblknowledgebase table and the name column from the tblknowledgebasecats table and join them through the tblknowedgebaselinks table. Also we want to sort them by the most views and only show the top 20 articles. Our SQL statement looks like this:

SELECT `title`, `views`, `useful`, `votes`, `private`, `name` FROM `tblknowledgebase` LEFT JOIN `tblknowledgebaselinks` on `tblknowledgebase`.`id`=`tblknowledgebaselinks`.`articleid` LEFT JOIN `tblknowledgebasecats` on `tblknowledgebaselinks`.`categoryid`=`tblknowledgebasecats`.`id` ORDER BY `views` DESC, name LIMIT 0,20

We execute the query and for each row that is returned, extract the data, perform some formatting and put the values we want displayed into the existing report data variable:

$result=mysql_query($query);
while($data = mysql_fetch_array($result)) {
$category = $data["name"];
$title = $data["title"];
$views = $data["views"];
$useful = $data["useful"];
$votes = $data["votes"];
$stats = $useful." (".$votes.")";
$private = $data["private"];
$reportdata["tablevalues"][] = array($category,$title,$views,$stats,$private);
}

Upload this file to the WHMCS/modules/reports directory and the report will appear when logged in to the admin area and clicking on the reports tab. The name of the report on the Reports page will be the file name with underscores turned into spaces and each word capitalized so for this report it will take knowledgebase_usage.php and title it ‘Knowledgebase Usage’ in the Report list.

The source code for this report is free and can be found as a downloadable zip file product in our shop.