The framework supports two independent blog implementations:

  1. Simple blogs that do not require a database.
  2. A database driven set of blogs.

This help deals with the second option (database driven blogs). Here is a summary of the key differences between the two methods of creating blogs and blog posts.

Simple Blog   Database Blog
Any model can be used to define the pages of a simple blog.   The database blog pages are all based on the WYSIWYG editor.
Any number of independent blogs can be created. Each blog is defined by a blog id and can contain any number of posts. Any number of independent blogs can be created. Each blog is defined by a topic id. Each blog topic can include any number of posts.
Simple blogs do not support categories. A list of categories can be defined for each blog (topic). Each post can be associated with any number of categories.
Lists of posts (within a blog) are defined using the simple_bloglist model. If there are more posts than are shown on a page, pagination links can be added to navigate to any list page. A short list of posts can be generated using the latest_blog_posts model. Standard (system) pages are available to list categories and posts.
Posts must be defined in the sandbox and promoted to production. Posts are normally defined directly within the production environment. This allows end users to maintain the blog without assistance from technical staff.

If you are looking for help related to simple blogs. Please visit this link.

Defining and Configuring your Blog Database

Before you can start to create your first blog, if you have not yet loaded a gh_blog database in your environment you will need to do this next. For this procedure please visit loading and configuring the gh_blog database.

Defining Which Users Can Maintain the Blog

All of the blog maintenance pages can only be accessed by users who are logged into your website. Furthermore, they are configured with Function Security as shown here:

Blog Maintenance Pages - Function Security

This means that users who you wish to designate to maintain your blog must be assigned the role of blogger as shown here on this user definition.

Users who maintain the blog must be assigned the blogger role

Notice that users can be restricted to maintaining the blog within a certain environment. By leaving this unselected it means this user can maintain the blogs in all environments.

Whenever users attempt to access any of the blog maintenance pages they will be presented with a login screen if they are not already logged on. If a user logs in who is not defined with the role of blogger they will be shown the following page:

Permission Denied

You are not permitted to access the requested page.

Using the Blog Administration Menu

Make sure the database is loaded into your environment and running before proceeding with these steps to define topics, categories and posts. Generally speaking, you should have at least four or five posts in mind before launching your blog. Otherwise, users will perceive that the website (blog) is incomplete or under development. 

All of the pages described below are defined within the system pseudo site. This means that they are available to all of your websites without explicitly defining them at the site level.

The blog administrative functions should be accessed using the page blogadmin/menu of the site whose blog you wish to maintain. This will present the following menu:

Blog Administration Menu

Begin by selecting the first link, Blog Topic Maintenance. This will present the page named blogadmin/edit-site:

Blog topic maintenance

If this is the first time you have visited this page, a blog_site record will be stored automatically. In order to define posts you must first define one or more blog topics. This function would normally be performed by your web development staff, as opposed to your end users. 

Topics are very high-level subject areas. Generally speaking, topics are not changed very often. We will see later that topics can be broken down into categories.

Here we have defined two topics:

Define blog topics

URL Node

Notice that column 1 specifies a url node. All of the blog posts are stored with a url structure such as:

http://www.example.com/post/sometopic/post-summary

Consider a site that deals with fitness. Such a site might want to separate blog posts into two topic areas:

  1. Nutrition
  2. Exercise

Most sites will only deal with one topic. In that case you could assign the url node to something general such as "blog" or use a word that is specific to your business.

Try to keep the URL nodes as short as possible. The url node associated with a topic should not be changed after posts have been created. If a change is necessary, you should update your .htaccess file to redirect all of the posts within the topic.

Topic Id

The Topic Id is an output only field. This will be populated once you have stored your topics.

Topic Title

If you are presenting your users with a list of topics from which to select, the topic title will be used as the link to posts within this topic.

Topic Description

The topic description provides more information about what the posts within the topic are about.

Meta Description

The supplied meta description will be added to posts within the designated topic.

Image Id

Enter the id of the image to be shown next to the topic.

Topic Selection

The system program blog-browse-topics can be used to allow your users to choose from the available blog topics or you can create a custom page for this purpose. Here is a sample of this page's output using the definitions shown above.

Page used to select a topic

Defining Blog Categories

After defining your overall topics, the next step is to define categories within each topic. Categories allow your users to focus on subject areas they are interested in.

Defining blog categories

When adding categories, the category Id is not entered, this will be generated automatically. The URL node is used when showing a list of posts for the category, the length of the url node should be kept short and may not contain blanks or special characters. The URL node must be unique for each category within a given topic and should not be changed once posts have been added using the category. Avoid adding categories until you are ready to create posts which refer to the category. Otherwise, users who select the category will be disappointed to find there are no posts available within the selected category.

The image id is optional. This is used to show an image next to the category to help users ascertain the purpose of the category. 

Continue to add as many categories as you require for the initial set of posts that you are planning to create. Click the Add New button after entering the details of each category.

Adding Posts to a Blog

The blog posts are the main pages/articles of your blog. These are maintained using the follow WYSIWYG editor.

Blog Post Maintenance

Let's review the key fields associated with a blog post.

Post Id

The Post Id is generated automatically when saving a post. To change an existing post you can use the magnifying glass to search for the id of the post you want to change.

Topic Id

Select the topic Id of the topic under which the new post will reside. Each post can only belong to one topic.

Author

If you want to show the author at the top of the post, enter the author details to be shown.

Publish Date

Enter the date to be associated with this post. The system allows articles to be post-dated. In such a case, the article will not appear on the website until the specified date/time has been reached. This is useful for posting future-dated press releases. For example, if you wish to "release" your post say tomorrow at 8:00 AM. Just enter this date and time and set the status to Published. You won't be able to see the post on the website until the specified date/time but you can use the Preview link to review the post before the general public can see it.

Status

Only posts in the published status will be shown on the website. The other statuses can be used to create posts that are not yet ready to be published. Note that future-dated posts should be assigned a status of Published (not Pending) if you want them to appear on the specified publish date.

Long Link

When a post is shown, the page also shows links to the previous and next posts. Use the long link value to indicate what the link text for the current post should be when it is linked to from the next or previous post.

Short Link

Some lists of posts may use a shorter version if the link. Enter this here.

Latest Blog

This flag is used to indicate whether the current post should appear under the list of latest posts shown by components generated using the latest_blog_posts model. If the current post is not very interesting or important you can leave this unchecked. For most pages this will be checked.

URL

All blog post URLs take the form www.example.com/post/some-topic/some-url-snippet. In the url field, enter the last portion to appear in the url here. Generally, this should be as short as possible while being as descriptive as possible. This cannot contain blanks or special characters with the exception of a dashes.

Title

This is the title that will be assigned to the post. The title is not actually shown on the page but is used internally within the HTML of the page. It is very important for Search Engine Optimization purposes to try to make this as descriptive as possible without being overly long. Depending on the site settings, the title you enter here may be supplemented by information about your company. If you don't want this, precede the value you enter with !.

Post Content

The post content is entered in this WYSIWYG (What You See Is What You Get) editor. Due to styling differences between the editor and your website, the post may, in fact, appear slightly differently when viewed on your website. Therefore it is a good idea to save the post with a pending status before publishing. That will allow you to preview the post on the live site (using the preview link) before others can view the post.

Summary

The summary text is show in lists that show what posts are available for viewing.

Meta Description

The meta description is used internally on the page to provide a suggestion to search engines regarding what the post is about. If your leave this summary blank, it will default to the summary text.

Imageid

Use this field to associate an image with your post. These images must be predefined in your sandbox environment.

Categories

Each post can belong to one or more categories that are linked to the topic under which the post is stored. Categories must be defined in advance so if you don't see a category that fits your post, open a new browser tab and create a new category associated with the topic for which you want to create a post. You can also leave the category designation empty and add a category later once you have created a few posts that fit the category.

Creation Data

This section provides information about who first saved the post.

Last Update Data

This section provides information about who last modified the post.

Adding Images to Your Blog Post

There are three primary methods by which you can add images to your post.

  1. Paste an image from the clipboard.
  2. Upload an image.
  3. Link to an existing image.

These options are described in the following sections.

Pasting Images

In order to paste an image, you first have to copy an image to the clipboard. If you are on a Windows PC, you can use the Windows Snipping Tool to select and paste an image. You could also open a drawing tool such as Paint on Windows or Paintbrush on the Mac and use this to open an image and select a portion of the image to copy it to the clipboard. 

Position your cursor to the location within the WYSIWYG editor where you want the image to appear and then use Ctrl+V (or Cmd+V on a Mac) to paste the image. When pasting images in this manner, by default, the images are stored as a data "blob" directly within the blog post. It is generally poor practice to keep these images as blobs within the blog because this prevents browsers from caching the images and it can slow down your pages and undermine SEO. If your images are very small, there could be a performance benefit to keeping these as blobs but in most cases you will want to convert these blobs to saved images. GenHelm supports a feature that makes this easy to do, we will describe this next.

To convert your blob into an image, begin by clicking one the image. You will see an overlay graphic like the one shown here.

Image Overlay Graphic

We will be using the pencil icon but make note that this same toolbar can be used to float the image to the left or the right. This would be used if you want your text to flow beside your image.

Click on the pencil icon of the left to edit the properties of the image. This will pop up a window like the following:

Image title

You can tell that this is a blob image because the Source field refers to the image beginning with data:image. On the first tab, enter a suitable title for your image. The title will also be used as the alt value or you can enter a different alt value if you wish.

Navigate to the Attributes tab. This will present the screen shown below:

Assign your image a name

Use this tab to name the image to be saved. Generally, your image names should contain descriptive lower-case words separated by a dash character. If you have created an image_sizes definition, you can also refer to this on this page. Click OK when finished.

If you want your image to link to a page, you can use the link tab for this purpose.

When you update or insert the blog post, this image will automatically be saved within your site's images/blog folder. If you want to store the image within a subfolder of this, you can prefix your image name with a path. For example, if you enter a Save Name of help/overview. The image overview.pgn will be saved in the folder images/blog/help.

Uploading Images

If the image you want to include in your blog is saved on your current PC or Mac, you can upload it to your blog. To do so, begin by clicking in the editor at the location where you want the image to be inserted then click on the image icon in the toolbar as shown here:

Icon used to upload images 

This will present a form, as shown below, where you can click on the Choose Files button and navigate to an image file to be uploaded.

Select the image to be uploaded

Once your image appears in the editor, follow the steps shown in the Pasting Images section (above) to give your image a suitable name and title.

Link to an Existing Image

Notice the form above allows you to specify the URL of an image to link to from your blog. It is poor form and generally illegal to link to images hosted on other sites but you can use this method to link to an image that has been uploaded to your site's images folder.

Configuring Image Quality

As you have learned, images can be created by the wysiwyg editor by converting pasted images into saved images. Since the number and size of images often plays a significant role in the performance of web pages it is important to be cognizant of the size of images you are rendering. Size has two connotations in this context:

  1. The visual size of the image (on the screen).
  2. The data storage size of the image when saved on disk.

These are somewhat related in that images that are visually large tend to take up more disk space and vise-versa. Nevertheless, there are techniques that can be applied to reduce the disk size of images without degrading the visual appearance of the images. By shrinking the disk size of your images, the pages that render these images will load faster and these pages will use less bandwidth on your server.

The recommended method for optimizing the disk size of images is to use the third-party tinify api. This can be done seamlessly by configuring GenHelm to call this API when generating images. To use this approach, begin by configuring the tinify API as outlined in the image model help. Once you have configured your tinify API key you must indicate that tinify should be used during wysiwyg editing. This is done by editing site_settings and adding the following configuration:

Use the site_settings model to configure WYSIWYG image quality

This setting applies to both the wysiwyg model and database driven blog editing using the function blogadmin/edit-posts.

There are a few minor downsides to using tinify to shrink images rather than the default image compression however these are generally offset by the benefits of improved image quality and performance. The main disadvantages to using tinify are:

  1. You will only be able to save posts or use the WYSIWYG model if you are connected to the internet.
  2. Stowing posts containing new images will be somewhat slower and will use internet bandwidth.
  3. If you compress more than 500 images per month you will need to register a credit card with tinypng.com and you will incur minor charges for image compression.

If you don't want to use the tinify API, you can still use this setting to configure the quality of your images by entering a number from 1 to 100 in the Value column. Higher numbers should render higher quality images; however, these images will tend to be larger and result in slower page loads. The default value is 35 if this setting is not configured.

Presenting Blog Posts on Your Website

If you only have a handful of posts, it is not necessary to provide a lot of functionality to allow your users to browse posts by category, etc. Therefore, for new websites that only contain a few posts, access to the posts can be provided exclusively using a component generated using the latest_blog_posts model. Later, once your site has say, more than 15 post, you can offer some of the built-in pages described here to allow users to search for posts of interest. In this section we describe the built-in components you can use to provide access to blog topics, categories and posts.

Using System Pages

The framework provides many built-in pages that are defined in the pseudo site called system. These pages can be accessed from any site without requiring any coding (other than linking to the page).  When using these pages, be sure to use the xml_sitemap model to register the pages on your site so that they get added to the default sitemap.xml generated by the site.

Selection a Topic

Recall that topics are broad collections of posts. If your site's blog posts all belong to the same topic there is no need to offer a topic selection page. Even if you only have two or three blog topics you may not want to show the topic browse page. In cases, where you do want to provide such a page you can use the built-in topic browse page named blog-browse-topics. This is the page that we saw earlier.

Page used to select a topic

Notice that this page offers two links per topic. If you don't want to show this topic browse on your site you simply need to provide access to the same pages linked to by this browse.

Browsing Posts by Title

To browse posts by title you can use the system page blog-browse-by-title. This must be followed by a slash and the url of the topic to be browsed. For example:

www.example.com/blog-browse-by-title/tarp would show the tarp blog posts by title as we see here:

Browse blog posts by title

This page can also be rendered using the $link function as in $link(blog-browse-by-title,topic=tarp,Browse Tarp Posts)

You can see that this page shows posts in order of title. Users can restrict the posts to those belonging to certain categories by selecting the categories of interest. Note that the shift key should be held down to select a range of categories and the ctrl key can be used to select individual categories.

Browsing Blog Categories

The blog-browse-categories page allows users to see descriptions of all of the categories associated with a blog topic. This page name must be followed by a slash and the name of the browse topic being browsed. Here is an example of this system page:

Browse categories of a blog topic

From this page, users can click on a category to see the posts associated with this category. This is done using page blog-browse-posts-by-category. This page must be followed by the topic then the category. For example: www.example.com/blog-browse-posts-by-category/tarp/care. This link can also be built using $link(blog-browse-posts-by-category,topic=tarp&category=care,Browse Tarp Care Posts).

Here we see an example of this page:

Blog Posts by Title within Category

Help Index

GenHelm Architecture GenHelm Architecure.
Why GenHelm? Summary of the GenHelm methodology.
Getting Started Learn how to start a new website.
Naming Conventions Naming web pages and other items.
Common Web Page Fields Descriptions of fields that are common to all page models.
Layouts Defining codeframes and layouts.
Styles and Scripts Descriptions of fields that are common to all page models.
Meta Tags How to configure meta tags for your site and specific pages.
Dollar Functions General information about dollar functions.
Navigation Tips Navigation Tips and Techniques
Favourite Icons How to configure favorite icons for your site.
Blog Maintenance Blog and post administration.
Direct Command Help Help for the direct command field.
Programming with GenHelm Writing programs that interact with the GenHelm framework.