pMachine Overview

Jump to a Section

Overview Of Files And Directories

This list provides an overview of the pMachine files and directories.

Top of Page

The Control Panel

The administrative control panel is where all of the behind-the-scenes action takes place. This is where you create and manage weblog entries, manage members, set preferences, edit your templates, etc.

The control panel is accessed through a page called index.php, located inside the pm directory (which you might have renamed during installation). Actually, if you simply go to your pm directory, you'll be directed automatically to the control panel log-in screen.

When you first log-in, pMachine sets "cookies". These allow pMachine to know you are logged in while you travel through the various pages of the control panel. If you click the "Remember Me" button during login, the cookies are set permanently, allowing you to access the control panel without logging in on subsequent visits. If you do not click the "Remember Me" button, the cookies will only remain active while your browser is open. Once you close your browser (quit on Macs) the cookies are destroyed and you'll have to log-in to access the control panel once again.

You can optionally run the control panel without the use of cookies (using session ID's) by changing a preference in your config.php file. Under normal circumstances, cookies are the preferred method. Session ID's are intended as a backup alternative for people with cookie problems. Unlike cookies, if you leave the control panel to browse the internet, you'll have to log-in again.

Most of the areas within the control panel are described in more detail later in the manual.

There is an "exit" button in your control panel which you can click once you're done. Doing so will destroy the cookies. It is only necessary to log out if you share your computer with someone else, or access your control panel from a public computer. In that event you must log-out, or risk someone else having access to your information.

Top of Page

Your Weblog

When you install pMachine, it configures one fully functional weblog. This weblog consists of several pages, but as far as pMachine is concerned, it's one weblog. In fact it's called that - "weblog". Since pMachine allows multiple weblogs (Pro version only), each weblog must have a name so that pMachine can keep track of things like preferences. The default name assigned to your weblog is "weblog". You can't change this name. In any event, it doesn't matter because this isn't a name that people will see, it's just a name that pMachine uses internally to know how to manage things. Just keep in mind when you see the word "weblog" in your control panel that it refers specifically to the first weblog that pMachine installed. You'll also frequently encounter the word "weblog" as you read the manual and begin working with pMachine tags (covered later). Most of the time this refers specifically to your primary weblog.

Top of Page

Preferences

There are four places in the control panel where you'll set preference for your site: General Preferences, Weblog Management, Calendar Prefs, and Form Preferences.

Top of Page

Creating Your Web Pages

You'll be surprised to find that all of the pMachine pages that make up your site — the weblog and member pages — are strikingly similar to standard HTML pages you are familiar with. In fact, you'll find that these pages are cleaner looking than normal HTML pages, since some aspects are created with templates in the control panel.

In this sense, pMachine is a hybrid system; there are both traditional HTML pages, as well as dynamically generated page elements. This is an important concept in pMachine:

The HTML pages contain the static elements of your site — the stuff that doesn't change. All of the dynamic stuff — weblog entries, comments, etc., as well as the formatting and presentation of those elements is managed in the control panel through templates and preference settings.

You'll code your static HTML pages using your favorite HTML editor, like "Dreamweaver", or by hand. These pages may contain any web-enabling elements you normally use: HTML, JavaScript, Flash, scripting elements, etc. There are only two requirements that pMachine pages must meet:

  1. They must have a PHP suffix. Similar to HTML pages, which must end in .html, PHP pages must end in .php
  2. On the vary first line of each page, before any HTML, you must place the following PHP tag: <?php include("pm_inc.php"); ?> This tag allows the page to communicate with pMachine.

Top of Page

pMachine Tags

Contained within your pages, in addition to HTML, you'll find short lines of PHP code we call "pMachine tags". These tags pull dynamic information out of your database and display it.

There are over eighty tags that you can use to create your site with. These tags are the primary building of pMachine so it is highly recommended that you spend time reading the Tag Library learning about them. There are many more tags available than the ones in the sample pages. To fully take advantage of pMachine you will utilize these tags.

Here is an example of a pMachine tag:

<?php total_weblog_entries(); ?>

This particular tag is a "statistics" tag. It displays the total number of weblog entries in the database.

Some tags, like the above example, are "stand-alone" tags, meaning the full functionality is provided by the tag itself — put the tag on one of your web pages and it will show you a particular piece of information whenever the page is loaded.

Other tags interact with one or more templates in the Control Panel. In addition to putting those tags on your pages, you will need to modify the template(s) associated with them.

Here is an example of a tag that utilzes templates:

<?php weblog_entries($id,"weblog"); ?>

This tag displays your weblog entries. By default, you will find this tag located in weblog.php. There are eight separate templates that interact with this tag in order to render your weblog. The Tag Library will indicate the name of the template associated with each tag.

Many tags, like the one above, contain "parameters". Parameters are the information contained within the parenthesis: ($id, "weblog"). This information gets "passed" to the scripts, altering the behavior of that particular tag.

This tag, for example, has two parameters:

<?php weblog_headlines("weblog,"3"); ?>

The first parameter (weblog) tell the tag you want to show headlines from your primary weblog. The number three means you want to show three headlines. Each tag may have a different number of parameters. Some parameters are required while others are optional. In all cases they have an effect on the behavior of the tag. The Tag Library will describe the parameters available for each tag.

A final note regarding paramters: You will notice that some parameters have a dollar sign in them ($id). These parameters are dynamic: They receive information from the URL of the page containing the tag.

Tag syntax is critically important. When you use pMachine tags on your pages, the spelling must be exactly as shown or you'll get nasty messages in your browser called "parse errors". If you ever get one of these errors, check the syntax of the tags on your page.

You'll find a description of all pMachine tags in the Tag Library.

Top of Page

Templates

Templates are found in the control panel in the "Edit Template" menu. The purpose of a template is to define how information stored in your database should look. By modifying the various templates, you have total control over how weblog entries, comments, etc. are presented on your pages. You can think of templates as containers that hold formatting information for the various dynamic elements of your site.

As an example, let's look at a typical weblog: A weblog consists of a series of sequential entries. Although the information in each entry is different, how each entry presents that information is not. Every one of your entries will share one thing in common: formatting. The layout for each entry will be identical. In pMachine, you'll use templates for this purpose; to define the presentation, or layout, of the various chunks of information — weblog entries, comments, member information, etc.

Don't let the word template make it sound complicated. Modifying a template is very simple. Just find the template you want to alter, and change the HTML in it.

Top of Page

Templates Sets

There are around twenty templates that you will use within your weblog pages. This group of templates is called a "template set". By default, we've named this template set "weblog". pMachine has other template sets as well. If you choose to require member registration, for example, you'll use the "membership" set of templates to manage those areas. pMachine installs with five different template sets:

  1. Weblog: This is the set of templates associated with your weblog, comments and archives.
  2. Membership: These templates are used if you require member registration. They let you define the look of the member registration form, the login form, the member profile page, etc.
  3. Email: Various email related templates, like the contact form and the mailing list form.
  4. Search: Search related templates. The search forms, search results, etc.
  5. Calendar: The template that formats the look of your events.

Multiple Templates

pMachine (Pro version) also allows you to create additional copies of the weblog templates. If you only plan to have one weblog, you'll probably never need this feature. But since pMachine allows you to create more than one weblog, it also allows more than one set of templates so that each weblog can be completely independent.

One final note regarding templates: You'll notice that there are two versions of some templates. One version is used if you require member registration, the other version is used if you do not. The form that visitors use to submit comments is an example of this. If you do not require registration, you'll use the version of the form that has input boxes for the person's name, email, etc. If you require registration, all of that information is already in the database so you can use the simplified version of the comment form. To make if easier on you, we provided each version in it's own template. Based on your preferences, pMachine will automatically use the right one.

Top of Page

Variables

Contained within your templates, in addition to HTML, are variables. Variables are placeholders for the individual pieces of information — your weblog title, the body of the entry, the date the entry was created, the author's name, etc. Variables tell pMachine where to insert a specific piece of information pulled from the database. In pMachine, variables are wrapped between two percent signs like this:

%%title%%

This particular variable tells pMachine to display the title of your weblog entry. The title will be different for each entry, of course, which is why we need variables — to serve as placeholders. If you go into the control panel and look at any template, you'll see how variables are used.

A description of all variables is found at the top of every template by clicking the "variables" link. There are more variables available than the ones we used for the sample weblog, so be sure and read about them.

Top of Page

Summary

Your weblog pages are the overall framework of your site. These pages are coded like traditional static HTML pages. Templates, which you access from the control panel, define the presentation of smaller chunks of information stored in your database. Variables are the placeholders for individual data components. To make templates appear on your pages, you'll use pMachine tags.

Top of Page