Themes and Customization

Topik comes with just what you need to get started for a presentation layer. The core of the install is the Post class and the Posts directory. How you choose to display it is up to you. However, we do start you out with a few files to get you going:

• config.php: This is where all your options are.
• index.php: The home page.
• header.php, footer.php: Page parts, which keeps your code DRY.
• blog.php: Single post page
• posts.php: A place to show a preview of all posts.

To get started with customization, there are a few options. In most cases, you'll want to create another directory for your stylesheets, javascript, and images. You'll then have to link to them. You can do this in the header.php file using <style /> and <script></script> tags.
Edit the included files to reflect the markup you want. Below are some code snippets to get you going:

Get Most Recent Posts

This function returns an array of the latest 3 posts.

  
$posts = Post::get_recent_posts();
foreach ($posts as $post) :
?>
  <div>
    <h1><?php echo $post->title; ?></h1>
    <p>
      <?php echo $post->description; ?>
    </p>
    <a href='<?php echo $post->link; ?>'>Read More</a>
  </div>
<?php
endforeach;
  

---

Get More Posts

This function returns array of the latest 9 posts. The function accepts the "offset" parameter, which is the page number the user has navigated to. The default value is 1. Only integers are accepted, no strings. We suggest using ?page=1 in the URL and the $_GET array to access the ['page'] key.
You can later use that variable to get the pagination.

  
$offset = isset($_GET['page'])?$_GET['page']:1;
$posts = Post::get_posts($offset);
if ($posts) {
  foreach ($posts as $post) {
    ?>
      <div>
        <h1><?php echo $post->title; ?></h1>
        <p>
          <?php echo $post->description; ?>
        </p>
        <a href='<?php echo $post->link; ?>'>Read More</a>
      </div>
    <?php
  }
}
  

Displaying A Post

Displaying a specific post requires use of the get_post method. The function accepts the parameter $filename, which should be a string containing just the file name, not the parent folder, and with or without the '.php' extension.
To access the filename, assuming the post is being linked the same way it's linked in the previous code blocks, use the $_SERVER global, and the ['REQUEST_URI'] key. This will return the request URL without the base URL. In this case, the Request URI is blog/2021-01-20-Documentation. We need to remove the leading part of that, including the slash. That can be done with the PHP basename() function. So, the filename is $filename = basename($_SERVER['REQUEST_URI']);.

  
    $post = Post::get_post(basename($_SERVER['REQUEST_URI']));
    ?>
    <h1 class='is-size-1'><?php echo $post->title;?></h1>
    <p class='subtitle'>
      <?php echo $post->description; ?>
    </p>
    <small><?php echo $post->format_date; ?></small>
  

Post Pagination/Canonical

Adjacent posts can be accessed using a property and a function. To start, part of the post object are the next_link and prev_link properties, which only have a value if there is an adjacent post.
Note that these values are just the links, not the post arrays. To get the post details, the get_post_meta() function must be used. That function works similarly to the get_post() function: it acceps a file name as a string without a leading folder name or slash. The link is just the file name, so the basename() function won't be needed. Instead of using $_SERVER, the $post->next_link or $post->prev_link property can be used. Pass that property to the get_post_meta() function to get the post meta array.

  
    if ($post->next_link !== false) {
      $next_post = Post::get_post_meta($post->next_link);
      ?>
      <div>
        <div>
          <small>Next Post:</small>
          <h3><?php echo $next_post['title']; ?></h3>
          <p>
            <?php echo $next_post['description']; ?>
          </p><br />
          <a href='<?php echo $next_post['link']; ?>'>Read</a>
        </div>
      </div>
      <?php
    }
  

Posts Page Pagination

You can also get pagination for the Posts page. This function returns an array. It accepts an integer, which should be the current page. The default value is 1. The properties are as follows:

• count: How many total pages exist. This will always be returned.
• next: The next page (older posts). This will not be returned if offset is equal to count.
• prev: The preceding page (newer posts). This will not be returned if offset is equal to 1.
• current: The current page. This will always be returned.

An example of usage is below.

  
$offset = isset($_GET['page'])?$_GET['page']:1;
$pagination = Post::get_pagination($offset);
/*Later in the document*/
if ($pagination['prev']):?>
&lgt;a href='posts?page=<?php echo $pagination['prev']; ?>'>Newer Posts</a>
<?php endif; ?>
<?php echo "Page " . $pagination['current'] . " of " . $pagination['count']; ?>
if ($pagination['next']):>
<a href='posts?page=<?php echo $pagination['next']; ?>'>Older Posts</a>
<?php endif; ?>
  

The above will output something like this section below:

---

Search

The search function is built in to the Post class. It accepts a string and returns an array of posts. The posts returned will either have a title or content that matches. This function is not verbose, though, so simple strings like "a" or "is" will likely match multiple posts. Below is demo implementation code.

  
if (isset($_GET['term'])) $results = Post::search($_GET['term']);
....
if ($results) {
  foreach ($results as $result) {
    //do stuff (like display the posts)
  }
}
  

The form used on Topik uses the GET method, which appends the input value to the end of the URL string. For example, if the page that runs the function is search.php, the URL when a search is executed becomes search.php?term=crocodile. Below is some starter code for the search form.

  
<form action='search' method='get'>
  <input type='text' name='term' id='term' />
  <label for='term'>Search For</label>
  <button type='submit'>Search</button>
</form>
  

There are other things that can be done there, like adding an autofilled value if there is already a term in the $_GET array, but we'll let you make those decisions.

---

Config File

The config file contains a lot of customizable options to improve SEO. The only variables that are required are the $blogName and $base, but the rest really help SEO. This list describes all of the available options and what they're used for.

• $blogDescription: A description of your blog. This will be overwritten by the post description on post pages.
• $blogSubject: The subject of your blog. This will be overwritten by the post subject on post pages (if the subject is set). If empty or unset, it defaults to the blog name.
• $googleSiteVerification: Your Google Site Verification key
• $generator: The program used to generate the page. Usually your text editor.
• $postsPage: The page that will have all of your posts displayed. Defaults to "posts.php". This helps with canonical links and defines the Archive meta tag.
• $blogPage: The page that is called when displaying a blog post. Default is "blog.php"
• $blogHumans: The location of the humans.txt file. No default.