Getting Started
To get started with using Topik, read the readme file.
Then, come back here to read about installation.
Installation
Install the unzipped package at the root of the URL. In config.php,
set the $blogName variable to the name of your blog. Set
the $base variable to the URL of your blog, leading with
http:// or https:// and ending with a slash
"/". That will be enough to get started.
Pages
Pages are stored at in the root folder. They are standard PHP pages.
Pages must have config.php included at the top, using the
following code:
include 'config.php';
To use the Post class in a page, include the following line at the top,
after the opening PHP tag:
include 'Post.php';
There are sections of the final HTML output that are not in the page
file. This is done using the PHP include function. Examples
of this include the 'header' file, which on this demo site, includes
the HTML head tag and the navigation. The 'footer' file is the sibling
to the 'header' file. The header file opens the 'main' HTML tag, and
the footer file closes that tag, as well as the HTML tag.
Those files can be edited to include whatever is needed, including
stylesheets, scripts, meta tags, and more.
Include the file header.php at the top of your page, after the
call to include the Post class if you're using it. The file uses the
$title variable to set the HTML <title> tag,
so make sure you set that before calling the file to pass that in. If it's
not set, the title will read just the $blogName variable
set in config.php. Include the footer.php file
at the bottom of your page to properly close everything off.
Page Structure
The final code of a page should look like this:
<?php
include 'config.php';
/*If you want to use the Post class*/
include 'Post.php';
$title = "Demo Page";
include 'header.php';
?>
<!--Page HTML/code goes here!-->
include 'footer.php';
The Post Class
The Post Class contains all of the functions to view a post, list
posts, list recent posts, and get post information.
Variables
Variables in the post class are not set within the class itself. They
are generated by the post's content. The only exception to this rule
is the posts directory, defined by const Dir at the top
of the file.
Getting a post
To retrieve a specific post, use the public function get_post($file),
where the $file parameter is the name of the file. The parameter
does not require but does accept the value to end with '.php'. Do not
pass the file name with the parent folder leading - just the file name
is needed.
<?php
$post = Post::get_post('2021-01-21-Getting-Started.php');
?>
Getting Multiple Posts
To retrieve multiple posts, use get_recent_posts() or
get_posts($x = 1).
get_recent_posts() will return an array of three post objects.
get_posts($x = 1) will return an array of nine post objects. It accepts
a parameter integer value, which is the offset (times 9) to start from.
The parameter is not required and defaults to 1. If no parameter or a parameter
of 1 is passed, the 9 latest posts will be returned. If a parameter of 2 is
passed, the 10th through the 17th latest posts will be returned. If there
are no available posts, nothing is returned. If there are some posts,
but not 9, some posts will be returned, and the function will not die.
$latest = Post:get_recent_posts();
//returns
Array (
[1] => Array (
[title] => Getting Started
[date] => January 21, 2021
[description] => An Intro to this system
[link] => blog/2021-01-21-Getting-Started
)
...
[3] => Array (
[title] => Hello, World!
[date] => January 29, 2021
[description] => Just dropping in to say hi!
[link] => blog/2021-01-19-Hello-World
)
)
$page2posts = Post::get_posts(2);
//returns
Array (
[10] => Array (
[title] => Getting Started
[date] => January 21, 2021
[description] => An Intro to this system
[link] => blog/2021-01-21-Getting-Started
)
...
[17] => Array (
[title] => Hello, World!
[date] => January 29, 2021
[description] => Just dropping in to say hi!
[link] => blog/2021-01-19-Hello-World
)
)
Get Post Information
To get information about a post without retrieving the whole post object,
get_post_meta($file) can be used. The function accepts the $file
parameter, which is a string of the filename, with or without the file extension,
without the leading folder name. If a file is found, an array of details
is returned (see below). If a file is not found, false is returned.
$file = '2021-01-20-Documentation.php';
$post_details = Post::get_post_meta($file);
//returns
Array (
[title] => Documentation
[date] => January 20, 2021
[description] => Topik Documentation
[link] => blog/2021-01-20-Documentation
)
Using The Post Object
The Post object has a number of available properties.
Post Object (
[title] => Documentation
[content] => Hello, this is an introduction to this system.
[description] => Topik Documentation
[raw_date] => 2021/01/20
[format_date] => January 20, 2021
[link] => blog/2021-01-20-Documentation
[next_link] => 2021-01-21-Getting-Started.php
[prev_link] => 2021-01-19-Hello-World.php
)
To use any of these properties, access them with the arrow syntax.
$post->title;
Content
Content is stored in files in the "posts" directory. Files have a strict
naming convention that allows Topik to sort by new and link canonical
posts. The naming convention is as follows:
YYYY-MM-DD-Title-With_Underscores-or-hyphens.php
The date helps the get_posts() function and related functions
sort by date, and helps retrieve adjacent posts. The title convention
makes saving posts easier and helps with URLs. The easy to read URLs
is better for SEO and UX.
File Content
At the top of your post, there should be opening PHP tags and 3 variables:
the post title (string), description (string), and date (string), as shown in the below example:
<?php
$title = "Test";
$description = "A test post";
$date = "2021/01/01";
?>
All variables must be strings. The date can be written in any format because
it will be compiled to local format when the post is generated for viewing.
After the initial variables are declared, the rest of the file's content
can be in HTML or plain text and will be the content displayed in the final view.
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.
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.
Customization
The package you receive will have very little styling and scripts and no images.
Everything will show up with only the most basic things to get you going.
The idea here is to have you, the developer or designer, customize the
software to fit your needs. Everything outside of the Post class and posts directory is a
suggestion. You have the power to customize output, styles, and functionality.
The Post class is extendable, so you can use the functions already there
to build a search function or a random post function or even categories.
The world is your oyster. Well, this project is, at least.
But for starters, Topik is set up to at least let you add in a style
sheet and JavaScript by enclosing the style and script tags in the header,
which gets loaded with every page. It ships with a CDN call to Bulma,
and all the included markup will get you set up nicely with that, but
by no means is it necessary. If you want to strip down to just the core (index.php, blog.php, Post.php, posts.php, config.php, and the posts directory) and
rebuild, you totally can, and I think you should, but you don't have to.
To read up on customization, take a look at the blog post on it.
Help
For additional help, feel free to message me at nate@natenorthway.com.
Please keep in mind that this is a side project of mine, and though I'd
love to see it thrive, I'm not making money from this and thus, won't
be able to pay as close attention to it as I might want to. Additionally,
if you'd like to contribute, I'd love to hear from you, too.