Create A Blog Site With KAN CMS 1.0 Beta RC5+

To set up a blog using KAN CMS is fairly simple with the upcoming KAN CMS RC5+, with the introduction of the Unified Articles Management. All that would be required is to setup/create a theme with Blog specific functionality and a fair bit of imagination. We will demonstrate how put together a simple theme which mimic the Enterprise WordPress Theme.

Setting Up KAN

Once you have KAN installed, setting it up to deliver a blog is a matter of the purpose of the site. There are two ways to handle this in my opinion:

  1. Blog Article Category – part of the main site
  2. Dedicated Blog Site/Sub Site

Blog Article Category

One other option would be to set up your site blog as part of the general content of the site; in this case the Blog will not be a stand alone site for which its content can be managed solely. In that instance, the blog URL structure would potentially be something like: http://www.mysite.com/site_id/articles/blog/ which would use a Blog Article Category to manage the content.  Articles can be posted directly to this category or you can create sub categories for the articles to be posted, giving you URLs such as

Note: Currently, the KAN articles URL structure does not show the category hierarchy that well, but we can expect this to improve in subsequent releases.

Dedicated Blog Site / Sub Site

You can set up as many sites as you want with KAN (multi-site administration), so your primary site can be the blog or you can set up a sub site to handle your blog. Using dedicate domains for your site is one alternative here, e.g.:

Using the sub site approach would require you to configure your server to handle the multi site environment, by modifying the DOCUMENT_ROOT setting to point to the same folder as the primary site, and updating your sub site’s “Site Domain” property to have the value “blog.mysite.com” in order for KAN to auto load the site based on the URL.

Using Friendly URLs

If you do not have access or capabilities to modify the DOCUMENT_ROOT settings of your site in order to use a multi site installation, you can however use the Friendly URLs option in the Site Configuration, to enable your site have URLs such

To use this option

  • First enable the UseFriendlyURLs setting in the Site Configuration screen under Site Settings.
  • Next, ensure your .htaccess file is present, and that the RewriteEngine setting is set to ON. This should be OFF by default in most new KAN installations. This step is dependent on the fact that you have the Apache MOD_Rewrite extension enabled.
  • Next create your sites with the unique ids as necessary, e.g. “mysite” and “blog”, and that should be it

Once Friendly URLs are enabled, you can then have a better blog site structure for your URLs, hence

These are significantly better and also much easier to manage on the CMS point of view, since you can easily identify where your blog content is, and how to manage it. Also, much like Blogging solutions like WordPress, you will then have the ability to create pages on your blog site, giving you such content with URLs such as

I believe all these options are still being fine tuned and will only get better as KAN ages.

From here you can view your sites, potentially with raw content for now, and the next step would be to style the sites for their intended purposes via the use of Themes.

Recommendations

  1. I personally would recommend the Friendly URLs option in this case, since using the http://blog.mysite.com would ultimately have KAN adding the extra SiteID parameter for content loading purposes, hence the URL would be http://blog.mysite.com/blog/. Not the very best of URLs but it gets the job done. If you choose the sub domain option however, then a simpler SiteID might in order, e.g. http://blog.mysite.com/b/articles/general/my-first-article (note the SITE_ID is simply, “b”)
  2. Again, for significantly large multi-site installations, this analogy could break down, as several of the multi-sites may choose to have their own blogs, and this can have an impact on URL formation. In such as case, I would recommend extending KAN to handle a new content type, a.k.a blog, which would effectively use the Articles Management system. Hence you can have:

These are all a matter of choice, and however you choose to go, KAN should be ready to go with you.

Creating the Theme

The next major step would be to create your theme(s), depending on whether you are setting up a dedicated blog site, or you are managing both a blog and a dedicated site. In this article I will concentrate on the theme for the blog site.

For the blog theme, you will need to implement two specific theme files:

  • index.php
  • articles.php

Optionally, if you theme plans on supporting Custom Blog Pages, then you will also need to implement

  • sections.php

All these should be located at /kancms/themes/your_theme/pages/, and the default style sheet for the theme would potentially be located at /kancms/themes/your_theme/css/default/default.css. This path can however be different depending on how skilled you are at manipulating the theme. These basic files, would be generated for you once you use the “Create Theme” option from under Theme Manager in the CMS.

At this point you will need to update your Blog Theme index.php file to display the list of newly posted articles and each actual article will be displayed using the articles.php file. As an example, here is a basic example of how to display the list of recently posted articles on your blog home page.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
   <head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
      <title><?php echo $site->siteName; ?> - Home Page</title>
      <?php echo $site->baseHTMLHeadData; ?>
      <link rel="alternate" type="application/rss+xml" title="<?php echo $site->getSiteName() . " Feed"; ?>" href="<?php echo $site->getArticlesManager()->getArticlesFeedURL(); ?>" />
   </head>

   <body>
      <div id="page">
         <?php include('header.php'); ?>

        <div id="content">
            <div class="sidebar">
            	<?php include('sidebar.php'); ?>
            </div>

            <div class="main">
            	<?php
		    include('article_summary.php');
		    renderArticleSummary("");
		?>
            </div>
        </div>

         <?php include('footer.php'); ?>
      </div>
   </body>
</html>

In the above code example, the section of interest is the PHP Code Block in the DIV with id “main”. This includes a theme specific PHP file called “article_summary.php” which has the renderArticleSummary function, which accepts several parameters, the first two being a title for the list of articles to be rendered, and an array of KAN Article objects, usually obtained via an instance of the ArticlesManager class. In this case, the ArticlesManager is retrieved from the global site object.

The above code snippet also shows several other theme specific PHP files which are used to help complete the theme. These include:

  • header.php
  • sidebar.php
  • footer.php

When developing themes, you have can as many PHP files as required to put together the design, but the page loaders will look for specific files with specific file names. You can however, extend your own KAN install and theme system to look for other theme files as you see fit. You can find out more on the KAN Documentation Portal.

Here is the source code for the renderArticleSummary() function which demos how you can put together a relatively completed articles summary list to take advantage of Article Management features.

<?php 

function renderArticleSummary($listTitle = "Recent Articles", $category = NULL, $limit = 10) {
	global $site;
	$articles = NULL;
	$feedURL = NULL;
	$start = isset($_GET['page']) ? $_GET['page'] - 1 : 0;
	$totalPosts = NULL;

	if( $category == NULL ) {
		$articles = $site->getArticlesManager()->getArticles($start, $limit);
	} else {
		$articles = $category->getArticles($start, $limit);
	}

	if( $category == NULL ) {
		$feedURL = $site->getArticlesManager()->getArticlesFeedURL();
	} else {
		$feedURL = $category->getFeedURL();
	}

	echo "<div class='article_summary'>";

	if( $listTitle != "" ) {
	     echo "<h2>
		     $listTitle
		     <a class='feed-link' href='$feedURL'></a>
	           </h2>";
	}

	for( $i = 0; $i < count($articles); $i++ ) {
		$article = $articles[$i];

		$authorsURL = $article->getCategory()->getURL();
		$authorsURL = $authorsURL . (strpos($authorsURL,'?') ? '&' : '?') . "author=" . urlencode($article->getAuthor());

		echo "<div class='article_group'>";
		echo "<h3>" . $article->getLinkedTitle() . "</h3>";
		echo "<div class='summary_footer'>"

		   . "<span class='date_info'>" . $article->getPostDate("d M, Y") . "</span> "

		   //. "<span class='cat_name'>" . $article->getCategory()->getLinkedCategoryName() . "</span> "

		   . " By <span><a href='$authorsURL'>" . $article->getAuthor() . "</a></span> "

		   . "<span class='comment_info'><a href='" . $article->getURL() . "#comments'>Leave A Reply (" . $article->getCommentCount() .")</a></span>"

		   . "</div>";

		// create summary content
		echo "<div class='summary_content'>";
		if( $article->getImageThumbnail() != "" ) {
			echo "<img src='{$article->getImageThumbnail()}' alt='' />";
		}

		echo "{$article->getSummary()} </div>";

		// bottom of summary
		echo "<div class='summary_footer'>"

		   . "FILED UNDER <span class='cat_name'>" . $article->getCategory()->getLinkedCategoryName() . "</span> "

		   . "</div>";

		// end article group
		echo "</div>";
	}	

	if( !isset($category) ) {
		$totalPosts = $site->getArticlesManager()->getTotalArticleCount('approved');
	} else {
		$totalPosts = $category->getTotalArticleCount();
	}

	$lastPage = ceil($totalPosts / $limit);

	echo "<div class='navbar'>";
	if( isset($_GET['page']) && $_GET['page'] > 1 ) {
		$page = isset($_GET['page']) ? $_GET['page'] - 1 : 1;
		echo "<a class='newer-posts' href='?page=$page'>Newer Posts</a>";
	}

	// if there are more pages than the current or if not on the last page
	if( (isset($_GET['page']) && $_GET['page'] < $lastPage) || (!isset($_GET['page']) && $lastPage > 1) ) {
		$page = isset($_GET['page']) ? $_GET['page'] + 1 : 2;
		echo "<a class='older-posts' href='?page=$page'>Older Posts</a>";
	}
	echo "</div>";

	echo "</div>";
}

?>

As can be seen, the code basically loops through the available articles returned and prints out a list articles with their summaries and a links to the comments section.

This can then be styled using CSS to achieve the necessary effect. Here is a screen shot of the in progress blog theme:

An Example Blog Theme For KAN
An Example Blog Theme For KAN

As can be seen from the above screen shot, the Friendly URL option is in use, and the site currently being viewed has a SITE_ID of “blog”.

RSS Feed Support In RC5+

This theme also makes use of the RSS Feed support for Articles added in 1.0 Beta RC5, which is used in two places:

  • The HTML Head via a LINK tag, and
  • In the navigation bar as a link.

This was achieved using the following two snippets: first the HTML Head Links

<link rel="alternate" type="application/rss+xml" title="<?php echo $site->getSiteName() . " &raquo; All Articles"; ?>" href="<?php echo $site->getArticlesManager()->getArticlesFeedURL(); ?>" />
<?php if( isset($category) ) { ?>
<link rel="alternate" type="application/rss+xml" title="<?php echo $site->getSiteName() . " &raquo; Articles In " . $category->getCategoryName(); ?>" href="<?php echo $category->getFeedURL(); ?>" />
<?php } ?>

And secondly, the navigation bar links:

<div class="feeds">
    <a href="<?php echo $site->getArticlesManager()->getArticlesFeedURL(); ?>">Posts</a>

    <?php
    // if we are on the articles page with the category variable available, the provide the
    // feed for that
    if( isset($category) ) { ?>
    <a href="<?php echo $category->getFeedURL(); ?>">Posts In <?php echo $category->getCategoryName(); ?></a><?php
    } ?>
</div>

In the two above examples, you will realise, that a check is made for the $category variable to determine whether or not to provide a feed for the specific category for the articles. This variable  is expected to always be present on the “articles.php” file via the KAN page loader, i.e. /kancms/pages/articles.php. The expected variables are:

  • $manager – the ArticlesManager Instance for the articles page
  • $category – the current ArticleCategory of the articles being viewed
  • $article – the Article object containing all the current article information

These are similar to the global variables used in other KAN page loaders, more on that in another article.

Missing Features

As can be seen from the screen shot, the theme design is a mimic of the Enterprise WordPress Theme. If you do comparison, you can see several missing features from the Article Management system, which include:

  • Tag Support
  • Search Field (support)
  • Comments Feed

These are all in the works features which should mostly be in the CMS being the time it goes in final.

Conclusion

KAN CMS has come a long way since its inception about a year ago, and with its steady move towards a final API and system, KAN is really shaping up, especially with the revamping of the Page and Article Management system. These and many other features being added to the system is set to make KAN a viable platform for developing some of the next generation web 2.0 sites, and hence compete with other vastly mature PHP based content management platforms.

This theme is available for download as part of the RC5 release of KAN.

Advertisements