Making a KAN CMS Downloads Component

KAN CMS is a great tool with a well developed CMS interface, but there are still a few things lacking, and some of those are a great set of easy to use and integrate components. There are a few, but the documentation and tutorials on building more is a not as public as it needs to be.

A friend asked for assistance recently on how to build access the list of downloads uploaded via the CMS interface using KAN CMS RC2. After a bit of thinking, here are the options to achieve that:

  1. Build a Component to access and display the content
  2. Write a PHP script in a page to obtain the content
  3. Build a dedicated theme loader and view file to display the content

All these options are what I find make KAN very flexible, but at times also confusing. I will focus on how to build a Component to display a list of downloads, using KAN RC2 to RC4 codebase, and using the recent Beta Snapshot 1 code base.

Using RC2 to RC4 Codebase

In both the RC4- codebase and RC+ codebase, Component creation via the CMS is virtually similar, except a few UI differences. So to create a Component, follow the steps below:

  1. log in to the CMS interface, then go to the Manage Components section to Create a New Component.
  2. In the new component form Choose Full Page Component
  3. Enter a unique ID of “downloads_view” for the component and then name “Downloads” and a description
  4. In the Component path field, change the template name from “../components/<comp-dir>/<comp-file>.php” to “../components/downloads/downloads_view.php”
  5. Save the component, so that a new file gets created on the local disk for the component.
  6. Now open the file with your IDE (DW, Notepad, etc), and then copy and paste the contents of “downloads_view_rc2.php” in the file and save
  7. Go to the CMS, and manage the site. Then create a page or edit an existing one.
  8. In the editor (form), choose to “Use Page Level Content“, and then on the tabs below, choose “Component”.
  9. In the Component section, select the “Downloads” component you created, and check the “Include As Content” option.
  10. Save the page and preview.

Here is the content of “downloads_view_rc2.php”

<?php
$query = "SELECT * FROM downloads ORDER BY id DESC";
$result = mysql_query($query) or trigger_error(mysql_error()); ?>
<table width="500" cellpadding="5" cellspacing="0">
   <tr>
      <th colspan=2>Download Name</th>
      <th>Options</th>
   </tr><?php
   $count = 1;
   while($row_result = mysql_fetch_assoc($result)) { ?>
       <tr>
          <td><?php echo $count++; ?></td>
          <td>
             <?php echo $row_result['Name']; ?>
          </td>
          <td align="center">
            <a href='<?php echo $row_result['URL']; ?>'>Download Now</a>
          </td>
       </tr>
     <?php
   }

   mysql_free_result($result);
?>
</table>

Using the Beta Snapshot 1 (Released 11 March, 2011)

In the case of the Beta snapshot and RC6,

  1. Repeat above steps for creating the component, but paste the content of “downloads_view_beta” in the file instead.
  2. Then go to the site, and then the pages section. Choose to create a new page or edit an existing one.
  3. In the HTML Editor for the main Content, choose the “Last but 1 button on the last toolbar” labeled “Components“. Then in the popup dialog, select the Downloads component to insert it into the page.
  4. Save and preview.

Here is the content of the “downloads_view_beta.php” file:

<?php 

  $dm = new DownloadsManager(); // get an instance of the API
  $categories = $dm->getDownloadCategories(); // retrieve all download categories as an array
?>

<table border='0' cellpadding='5' cellspacing='0' width='100%'>
    <tr>
        <th colspan="2" align="left">Name</td>
        <th width="56%">Options</td>
    </tr><?php 

    foreach($categories as $category) {  ?> // get each DownloadCategory object
        <tr>
           <th colspan="3" align="left"><?php echo $category->getCategoryName(); ?></th>
        </tr>

        <?php
        $count = 1;
        $downloads = $category->getDownloads(0,3); // 3 most recent Downloads, returns an array of Download Objects
        foreach($downloads as $download) { ?>
            <tr>
                 <td width="6%" align="right"><?php echo $count++; ?>.</td>
                 <td width="38%" align="left"><?php echo $download->getName(); ?></td>
                 <td align="center">
                    <a href="<?php echo $download->getDownloadURL(); ?>">Download Now</a>
                 </td>
            </tr><?php
        }
    } ?>
</table>

Observations

As can be seen from the above code, you can immediately observe that pre RC5 code uses traditional PHP and MySQL code, and the post RC5 code base is using OOP PHP. I personally find the OOP PHP code much more powerful and flexible, as it requires little or no knowledge of the underlining database structure, and offers quite an amount of abstraction. The API is quite consistent with other parts of the system, such Media, Articles and Events can all be accessed in a similar manner.

One other feature to note, is that the new utility functions, take an array of options as a 3rd parameter, so you can actually filter or provide different search criteria for the downloads. For e.g.

<?php
$downloads = $dm->getDownloads(0,3, array(
    'filter' => array('Name LIKE' => '%Report%')
));
// above will generate SQL similar to
SELECT * FROM downloads WHERE Name LIKE '%Report' ORDER BY id DESC LIMIT 0, 3
?>

The above code will return all Downloads which have a Name containing the word Report.

The most interesting thing is that, the all the above pieces of code can be easily used in any of the other 3 scenarios mentioned at the beginning of the article, with very little  issue. One flexibility about KAN is that although a framework of sorts, you can still use normal PHP without any restrictions.

Conclusion

Adding new code to the KAN system is pretty easy, and building a Component for KAN is one cool way of extending the system. I hope more of these types of simple components are included in the default KAN installation in the future, so it is easier to get some basic things done. For now, we get to enjoy writing our own code into the system.

Happy development.

Advertisements