Skip to content

Latest commit

 

History

History
126 lines (81 loc) · 7.3 KB

README.md

File metadata and controls

126 lines (81 loc) · 7.3 KB
Raw

#Flat-Blog

##Description A simple, effective, and configurable flat-file blog system.

##Installation

  1. Ensure that your web hosting supports PHP 5.0.3
  2. Download the latest revision of Flat-Blog from the downloads tab.
  3. Upload all of the files to your website, ensuring to keep the directory structure.
  4. You're finished!

The site should now be running the Flat-Blog system. At present it will be displaying three test posts, which are stored by default within the posts directory, each test post shows a range of features available within Flat-Blog.

##Configuration Flat-Blog offers simple yet effective configuration of many elements within the system, allowing you to create your own experience for your readers.

All of the configuration is handled via the configuration.class.php file. This contains an array, config, which you can add keys and values to, allowing to override the default configurations of the system. Below both the blog_title and post_read_more values have been overridden, which will change the blog title and read more tags throughout the generated HTML markup.

private static $config = array(
	'blog_title' => 'My Blog',
	'post_read_more' => 'More'
);

Alternatively you can directly modify each of the config arrays in appropriate classes, although this is not recommended as it will result in a loss of default Flat-Blog values.

###Options Below is a list of the available configuration options, along with short descriptions of what they do.

  • blog_title - Defines the title of the blog. It is used when displaying the HTML title attribute, and also within the main header.

  • post_directory - Defines the directory which will be searched for post files.

  • post_sticky_enabled - Enables or disables sticky posts. When enabled any post with the attribute "sticky": true will automatically be displayed first in relation to other posts.

  • post_date_format - Defines the format which the date will be output with when retrieved via get_date().

  • post_time_format - Defines the format which the time will be output with when retrieved via get_time().

  • post_date_time_connector - Defines the connector used to join the date and time strings when retrieved via get_time_date().

  • post_excerpt_length - Defines the number of words to be included within an excerpt of a post. This doesn't include any tags, which are stripped before excerpt processing.

  • post_read_more - Defines the text displayed when a read more link is output.

  • post_nav_enabled - Enables or disables post navigation. This is navigation displayed at the end of a post allowing the user to move to the previous or next post, by date.

  • post_nav_next - Defines the text displayed when a next post link is output. This supports the tags %title%, %date%, %author%, and %category%, which are set to the appropriate values from the next post.

  • post_nav_prev - Defines the text displayed when a previous post link is output. This supports the tags %title%, %date%, %author%, and %category%, which are set to the appropriate values from the previous post.

  • post_header_image_enabled - Enables or disables header images globally across posts. Header images are images displayed at the top of a post, before any text content.

  • post_header_image_directory - Defines the directory where the header images are stored, and will be loaded from, by default this is images.

  • post_header_image_full - Enables or disables header images on full posts.

  • post_header_image_excerpt - Enables or disables header images of exerpts of posts.

  • post_category_display - Enables or disables the displaying of categories within the post meta data section.

  • paginator_enabled - Enables or disables the paginator. The paginator is used to split content, allowing the homepage to display only a certain number of posts per page, navigation is also automatically added to move forward and backward between pages. When disabled the content is not displayed in pages, and all pagination navigation disabled.

  • paginator_posts_per_page - Defines the number of posts to be displayed per page.

##Posting Publishing a post in Flat-Blog is as simple as creating a text file (with a just little JSON)!

  1. Create a file within the posts directory (its default location is posts), ensure it has a .txt file extension.

  2. Add the following code block to the file. This forms the bare-minimum basis of a post, and is a JSON object which can be decoded and handled by Flat-Blog. There are some optional attributes, but we'll talk about those later.

     {
 	"title": "",
 	"date": "",
 	"time": "",
 	"author": "",
 	"content": ""
 }

  3. You can now add your data!

There are some things to watch out for though:

  • Ensure that the date you specify is valid, and in the format d-m-Y, or m/d/Y - this is due to how PHP handles European and American time. If you do give an invalid date it will default to 01-01-1970, the unix epoch.

  • Ensure that the time you specify is valid, and in the format h:m, or h:maa, where aa is either am or pm. If the time given is invalid, then it again default to the unix epoch, which has a time of 00:00.

  • Instead of using the return key to dictate a newline, you should use \\n, this acts just like \n although the extra slash escapes the newline so it only acts as a newline within the JSON data, and not the JSON source.

  • HTML tags can be used within posts, such as images or headings.

###Optional Attributes Below are the optional attributes, unlike the attributes listed in the template above these are not required, and no errors will occur if these are not included in the post file.

{
	"sticky": ,
	"category": "",
	"header_image": ""
}

sticky - This is a boolean value, accepting either true or false. When true the post is classed as sticky and will be displayed as the first post regardless of date; if multiple posts have a this set to true, then they will all be displayed first, but in date order.

category - This is a string value, and allows you to assign a category to posts. This category can be used when querying posts to filter results to just posts containing a specific category.

header_image - This is the path to an image which will act as the header image for the post. This is displayed before any of the text content of the post. This only display if the path supplied is a file which exists, and the configuration is set to display it.

##Styling Flat-Blog is styled purely with CSS via the css/style.css document. All changes to style should made here, or alternatively a different css document could be linked within the _partials/header.php file.

<link rel="stylesheet" href="css/style.css">

###Clearing One important styling class I have included is .clear, this should be applied to an element when it contains child elements which are have floats applied. This will result in the child floats being cleared, and stop other content floating as well. It is also applied to any element with a class of .wrapper, which is a class used to horizontally center some elements.

.clear::after,
.wrapper::after{
	content: '';
	display: block;
	clear: both;
}

##To Do

  • Add more generic CSS styling for HTML elements, such as tables.
  • Add unpublished attribute to posts to allow posts to be hidden.

##Author Flat-Blog was developed by Jack Watling over the course of a week.