pMachine User Manual
Ver 1.1.0  

  1. Copyright
  2. License
  3. Requirements
  4. Installation
  5. The PHP Extension
  6. Your Home Page
  7. What's New in Version 1.1
  8. pMachine Overview

  • Weblog Entries
  • Weblog Categories
  • Member Privileges
  • The Post Office
  • pMcode
  • Bookmarklet
  • IP Banning
  • Security Issues
  • Collective Weblogs
  • Multiple Weblogs/News pages
  • Multiple Template Sets
  • Intro to pBlocks
  • Timestamp Overview
  • Timestamp Codes
  • pMachine Tags
  • pMachine Files and Directories


    Copyright

    pMachine - © copyright 2001 - Rick Ellis - All Rights Reserved.




    LICENSE

    Use of this software indicates acceptance of this license agreement. pMachine reserves the right to alter this Agreement at any time, for any reason.

    Publication Date: January 1, 2002

    1. PERMITTED USE:  A licensed copy of the program is required for each installed instance of the program. One license grants the licensee the right to install and use one copy of the pMachine program on one website, residing on one server.
    2. SOFTWARE MODIFICATION:  License holders may alter or modify this software for their own use, but may NOT resell or redistribute the modified, or derivative version without prior written consent from pMachine.
    3. DISPLAY OF COPYRIGHT NOTICES:  All copyright notices appearing in the pMachine control panel MUST remain intact. Furthermore, license holder must display at least one "powered by" credit giving banner, or text credit on the main page of their publicly viewable site. This banner may be downloaded from the pMachine web site, or created by the license holder.
    4. TECHNICAL SUPPORT  Technical support is not included in the license. Free online support is available through the Online Support Forum.
    5. DISCLAIMER OF WARRANTY: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. LICENSE HOLDERS ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING THIS SOFTWARE AND ASSUME ALL RISKS ASSOCIATED WITH IT'S USE, INCLUDING BUT NOT LIMITED TO THE RISKS OF PROGRAM ERRORS, DAMAGE TO OR LOSS OF DATA, PROGRAMS OR EQUIPMENT, AND UNAVAILABILITY OR INTERRUPTION OF OPERATIONS.




    Requirements

    Your site must be hosted on a server with PHP version 4 or higher and mySQL 3.23.x or higher installed.




    Installation

    PLEASE NOTE: If your server requires a different extension than .php, proceed FIRST to the next section which describes the process of renaming your files.

    pMachine is installed in four steps:

    1. Set up your configuration file.

      Find "config.php", located in the "admin" directory. Open this file with a text editor such as Notepad on Windows, or SimpleText on Mac. Do NOT use a word processing program like Microsoft Word. The config file contains four variables which you'll need to set. You do this by replacing the information between the quotes with your particular information. If you don't know what the values of these variables should be, contact your system administrator. Most installation problems occur as a result of an error at this stage.

    2. Upload all files to your web server.

      Use an FTP program to upload all pMachine files to your web server. Do not change the directory structure, since pMachine relies on certain files being in a specific place for proper installation.

    3. Run the pMachine installation script. Point your browser to a file called:

      install.php

      located in the "install" directory. The installation program will take care of all installation details. Once you've successfully installed pMachine you MUST remove the installation script from your server for security reasons.

    4. Image directory permissions: For many, the above installation steps are all that is required. With some servers, however, you'll have to set "permissions" on the directory where you plan to save uploaded images to. To see if this applies to you, log-into into your control panel (after installing pMachine), click "create a new entry" and try to upload an image. If you are able to, nothing else is needed. If you get an error, set (chmod) the "uploads" directory to "777". It is located inside the "images" directory.




    The PHP Extension

    Similar to HTML pages which must end in .html, PHP pages must end in .php You'll notice that virtually every pMachine page ends this way. Some hosting providers may require a slightly different extension, like .php4. If this applies to you, you'll have a bit of file renaming on your hands.

    To change pMachine to a different extension:

    1. Find the file called "suffix.inc" located in the "admin" directory. Open this file with a text editor and change .php to the new extension.
    2. Rename EVERY SINGLE file in EVERY directory that currently ends in .php to the new extension.
    3. Change the "include" tag located on the first line the pages listed below to the new extension. The tag currently looks like this:

      <?php include("pm_inc.php");?>

      Or like this:

      <?php include("member_inc.php");?>

      1. Every file inside the "members" directory, except "member_inc.php4".
      2. The following files at the root level:
        archives.php
        comments.php
        index.php
        more.php
        search.php




    Your Home Page

    The home page for most sites is named "index.html". Web servers are normally set up show this page when they get a domain request (www.somesite.com) or a directory request (www.somesite.com/somedirectory/).

    Since pMachine pages require a .php suffix, if you decide to make your weblog page (weblog.php) be your home page (by renaming it to index.php), your web server might not automatically treat it as the default page. Some servers are configured to look for "index.php" in addition to the standard "index.html", but not all.

    Since many servers are not set up to automatically look for "index.php", you can create a re-direct page as follows:
    1. Create a page called index.html
    2. Copy the following code to that page:

      <html>
      <head>

      <meta http-equiv="refresh" content="1; url=weblog.php">

      </head>
      <body>
      </body>
      </html>
    Don't forget to change "weblog.php" in the above code to whatever you page is called.




    What's New in Version 1.1




    pMachine Overview

    This table provides a quick overview of the pMachine files and directories. An in-depth discussion is found at the very end of the manual. There is a lot of information regarding how pMachine works contained in that discussion, so you'll want to read through it at some point.

    NAME
    TYPE
    DESCRIPTION
    admin
    directory
    Contains all the scripts related to the control panel
    archives.php
    page
    The page where your weblog archives are displayed.
    calendar.php
    page
    The page where your calendar is displayed.
    calendar_style.css
    page
    The CSS stylesheet used to format aspects of the calendar.
    comments.php
    page
    The page where comments to your entries are displayed.
    docs
    directory
    pMachine documentation.
    images
    directory
    Your site images are stored here. There are two subdirectories in this folder. One contains the hit counter images, the other is the "uploads" directory where images uploaded through pMachine are stored.
    lib
    directory
    The PHP library files used to generate your weblog and member pages.
    members
    directory
    Contains all the the member management pages. If you do not required member registration, you can ignore these files.
    more.php
    page
    Used to display "more", or extended entries.
    pm_inc.php
    page
    A PHP "include" file. pMachine needs this file to know where certain things are. You'll notice a similar one inside the members directory.
    pm_style.css
    page
    The CSS style sheet used by your weblog pages. You'll also notice two stylesheets in the "members" directory: "member_style.css", used for the member pages, and "calendar_style.css", used by the calendar page.
    search.php
    page
    Displays search results.
    weblog.php
    page
    Your main weblog 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 "pmachine.php", located inside the "admin" directory. Actually, if you simply go to the admin directory, you'll be directed automatically to the control panel log-in screen.

    When you first log-in, pMachine creates a "session". A session allows pMachine to know you are logged in while you travel through the various pages of the control panel. The session will remain active even if you leave the control panel to browse the internet. Once you close your browser (quit on Macs) the session is destroyed and you'll have to log-in to access the control panel once again.

    The control panel should seem intuitive, even if you've never used a content management system before. Most of the areas within it are described in more detail later in the manual if you have questions.

    There is a "log-out" button in your control panel which you can click once your done. It's not necessary, however, unless you share your computer, 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.

    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". You see, since since pMachine allows multiple weblogs, 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. Remember this name as well if you're ever asked to use it in a pMachine tag (covered later).

    PREFERENCES

    There are two places in the control panel where you'll set preference for your site: General Preferences and Weblog Management

    General Preferences are the global preferences for your site. This is where you'll specify things like the name of your site, the email address of the admin, whether your site requires membership, etc.

    Weblog Management. This page lets you access the specific preferences for your weblog and comments: How many entries per page, what order to display them in, etc. There are over thirty different preferences which will affect the behavior of your weblog.

    If you have more than one weblog, each one will have it's own preferences page so that each can behave independently. That's why we called the page "Weblog Management". Because in addition to setting preferences for your weblog, this is where you'll create additional weblogs.

    CREATING YOUR WEB PAGES

    You'll be surprised to find that all of the pMachine pages which 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 are 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 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 VERY 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.

    pMACHINE TAGS

    Contained within your pages, In addition to HTML tags, you'll find short lines of PHP code we call "pMachine tags". These tags pull dynamic information out of your database - both content and formatting - and display it. Here's an example of a pMachine tag:

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

    This particular tag displays your weblog entries. By default, we've placed this tag on "weblog.php".

    Most pMachine tags interact with one or more templates in the control panel. Once you place a pMachine tag on your page, you can log into the control panel and modify the template(s) associated with that tag.

    You'll find a description of all pMachine tags toward the end of the manual. There is quite a bit of information regarding how pMachine works contained in the description of those tags, so you'll want to read through that section.

    Also, tag syntax is VERY important. When you use pMachine tags on your pages, the spelling must be EXACTLY as shown, or you'll get nasty things called "parse errors" which will spit ugly stuff at your screen. We've tried to keep the tags as simple as possible. If you've never worked with PHP, though, even the simple tags might look like gibberish.

    TEMPLATES

    Templates are found in the control panel in the "Template Sets" 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.

    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. The let you change 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. Collective: The collective weblog submission form.

    pMachine 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.

    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 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 a place-holder. 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 default site, so be sure and read about them.

    SUMMARY

    Your weblog pages are the overall framework of your site. These pages will be 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 place-holders for individual data components. To make templates appear on your pages, you'll use pMachine tags.




    Weblog Entries

    Once your site is set up, you'll spend most of your time creating and managing weblog entries. To create a new entry click "Create a new entry". You'll be presented with a form where you'll enter the information.

    The "subject" and "body" fields are required, the "more" field is optional. If you do not put anything in the "more" field, pMachine will not create the link to your more page in that particular entry.

    At the time of creation, you can choose whether the entry is "open" or "closed". Open entries are displayed on your weblog page, closed entries are not.

    Images are added to your entry by clicking the "Upload image" link at the top of the form. Upon clicking it, the link opens a small window which enables you to upload an image. In your preferences you can optionally pre-define HTML formatting which will be applied to all uploaded images.

    If you have multiple weblogs, you can choose the destination of your new entry with the "display in" pull-down menu. You can also specify a default weblog to post in at the bottom of your profile page so you don't have to manually choose.

    Once you've entered all the information, click "submit" to add it to the database, or "preview" to preview it on a page.

    In your preferences you can also specify how HTML submitted in your entries should be handled. Read the section on pMcode for more information.

    View/edit entries:

    The "view/edit entries" page lets you see a list of all the entries you've created listed by subject along with other relevant information about your entry like the date it was created, the author, whether the entry is open or closed, and how many comments have been submitted for each entry.

    To view a weblog entry click the title of that entry. To edit an entry, click the word "edit". To view the comments visitors have submitted, click the word "comments". To flip the status of an entry from open to closed, or vice versa, click the word "open" or "closed".

    Search for an entry.

    pMachine allows you to do keyword searches to quickly find old entries. You can submit a single word, or multiple words separated by spaces.




    Weblog Categories

    pMachine lets you create a list of categories (Rock, Jazz, Blues, Metal, etc.). Then, every time you create a weblog entry you can assign it to one of your categories. Visitors of your site can then view entries from a specific category.

    Categories are defined in your control panel by clicking "Weblog Categories". You can "add", "edit", and "delete" categories from this page.

    Once you've defined the categories, you can choose one from the list every time you create a new weblog entry.

    In order for your visitors to browse your entries by category, they'll need to see a list of them - a "category menu". pMachine will generate two different types of menus: 1. A list of text links. 2. A "drop down" menu. If you choose the "drop down" menu, it can either have a submit button, or not. You'll have to put a couple lines of JavaScript in your page header if you choose to use the buttonless version.

    TEXT VERSION
    To display the "text links" version of the menu, place the following tag on your page wherever you want the list to appear:

    <?php weblog_categories("weblog","text"); ?>

    Note: If you have more than one weblog, you'll need to change the word "weblog" to match the name of the weblog being shown on that page.

    DROP DOWN VERSION
    To display the "drop down" version of the menu, place this tag on your page wherever you want the list to appear:

    <?php weblog_categories("weblog","drop"); ?>

    As with the previous tag, change the word "weblog" if you are displaying the menu in something other than your main weblog.

    By default, the "drop-down" version does not have a "submit" button since most people (we think) will prefer the cleaner look. Because of that, you'll have to put the following JavaScript function in the header of the page where the menu is being displayed (or you can place it in an external .js file).

    <script language="JavaScript">
    <!--
    function gotoCategory(index) {
    document.categories.submit()
    }
    //-->
    </script>


    CUSTOMIZING THE DROP DOWN MENU
    In order to customize the look of the drop-down menu, or make the submit button appear, do the following:

    Using a text editor like NotePad or SimpleText, open the file called "category_fns.php", located in your "lib" directory. Near the top of the page you'll see a few configuration options that you can change.

    Notes:
    There is a template which defines the message that will appear if a visitor tries to view a category for which there are no entries assigned. It is in the same page as the "weblog multi-entry templates".

    Category list variable: You will find the following variable in the "collective weblog form templates": %%categorylist%%. This variable allows the list of categories to appear in the form that people use to submit entries.




    Member Privileges

    As far as pMachine is concerned, the only difference between a registered member who can post comments on your site, and you, as the "superuser", is access privilege. You have the highest level of privilege, normal members do not. Both are stored in the same database. If you choose to, you can "promote" members to higher access levels.

    There are seven levels of access privileges for members. The first three levels determine general access to your site, the last four grant varying levels of access to your control panel. The levels are as follows:




    The Post Office

    The post office enables you to send individual email to anyone, as well as send personalized email en-mass to selected groups of members. The Post Office is where you'll also send email to everyone in your mailing list.

    If you are sending email to members, you can place the following tag in title or the body of the message and it will be replaced with the name of the member:

    <<name>>

    You'll also notice a box at the bottom of the email forms that lets you select how many emails at once to send. You can either select "all", or specify a range, like 1 through 50. You might need to use the "range" feature if you have a very large number of emails to send, more than a couple hundred or so, since there could be server "time out" issues.




    pMcode

    pMcode is our own adaptation of the now famous UBB code. pMcode lets members add "style" or "formatting" to their entries which would normally require HTML. It's a good security practice not to allow your visitors to submit HTML into your database. pMcode allows some formatting options without the security risk.

    pMachine goes one step further by looking for allowed HTML tags and automatically replacing them with pMcode. pMachine will also automatically turn URL's and email addresses into "click-able" links, and even image tags if you allow them. You'll have to enable these features in your preferences. There are, in fact, four different preferences which determine how HTML and pMcode is handled in weblog entries and comments. A description of those preferences is found in the next to each preference in the control panel.

    USING PMCODE:

    URL's
    You can set pMachine's preferences to automatically format any URL, like www.somesite.com in to a click-able link. Or you can use pMcode as follows:

    [url]www.somesite.com[/url] or

    [url=www.somesite.com]my site[/url]

    You can of course include "http://" in the above links if you'd like.
    EMAIL
    As with URL's, pMachine will also format email addresses automatically, or you can use pMcode:

    [email]you@yoursite.com[/email]
    IMAGES
    In your preferences you can specify whether image tags (<img src="pic.jpg">) are allowed in member entries. If so, they will be formatted into the pMcode equivalent:

    [img]pic.jpg[/img]
    FONT SIZES AND COLORS
    You can specify font sizes and colors like so:

    [size=4]Hey look at this![/font] and

    [color=blue]Some blue text[/color]

    You can nest font tags as well lik this:

    [size=4][color=red]some red text[/color][/font]
    BOLD AND ITALIC
    Bold and italic tags are automatically formatted by pMachine (if enabled), or you can do this:

    [b]some bold text[/b] and

    [i]some italic text[/i] and
    QUOTING
    You can surround text written by someone else which you'd lik to "quote" like this:

    [quote]Some text. bla, bla, bal...[/quote]

    Those tags will be replaced with <blockquote> tags.
    CODE
    If you need to include any kind of pre-formatted text like script examples, you can use:

    [code]Some pre-formatted text...[/code]
    ONE FINAL NOTE
    When you upload images for placement in your weblog entries, you might notice some tags that looks like this:

    [q]

    pMachine adds them to uploaded images to compensate for a JavaScript issue involving quotes. The JavaScript function we are using does not work if there are quotes in the image tag. To get around this, we temporarily replace all quotes with the [q] tag. Once you submit your entry, the [q] tags will be turned back into quotes.



    Bookmarklet

    A bookmarklet allows you to add entries to your weblog without being logged into the control panel. A bookmarklet gives you the convenience of "one click" publishing while surfing the internet. You can additionally highlight text on a web site, then when you launch your bookmarklet the text will be added to the form (highlighting only works on non-framed pages). Since the highlighted text is passed through the URL (URL encoded), you can't highlight a very large section of text. It works well with a couple paragraphs, or so.

    To set up your bookmarklet, Click on the bookmarklet menu in the control panel. You'll see a link, which you'll drag to your "favorites" menu.




    IP Banning

    pMachine allows you to ban IP addresses to prevent users from registering and logging-in. Banning IP's is not foolproof because many users, especially those using dial-up accounts are assigned a different IP address each time they access the internet. The good news is that the numbers assigned to those users usually fall within a range of numbers. Since pMachine allows you to ban partial IP's, you can prevent an entire range of numbers from having access. You must exercise caution when doing this since you could inadvertently ban someone you did not intend to.

    To ban a partial IP, you'll need to look at all the IP addresses associated with a particular person to try to figure out the best approach. If you see that all the IP's are identical you can simply ban that one address. If you find the IP's are different, you'll need to find the point in the IP address where they start to become different.

    Let's say a member has these three IP's:

    176.45.37.9
    176.45.34.5
    176.45.44.6

    Since the first five numbers are the same, you can ban 176.45 and be reasonably confident that the member will be totally banned. Unfortunately there is a small chance that another member with the same provider could share the same first five numbers.

    pMachine logs the IP address each time someone posts a comment, or weblog entry. If you require membership it's especially easy to find all the IP addresses for a particular person. Just find the person's profile in the control panel and click the "view all IP's" link at the bottom of the page. You'll be given the option of banning all IP addresses assigned to that member. If you are banning someone's IP addresses it is also recommended that you revoke all access privileges. You could, of course, delete the member as well.

    If you do not require membership, it'll take a little more "leg work" to find all the IP addresses. You'll have to find all the entries posted by that person and copy their IP addresses manually to the ban list.




    Security Issues

    There is always a security risk associated with allowing people to submit information through forms on your site. A malicious individual, for example, instead of submitting a harmless comment, could use the comment form to submit a script designed to damage your files.

    pMachine takes security issues seriously and has many built-in features to prevent these kinds of situations. For example, pMachine "filters" all information submitted through forms, allowing only "clean" information to get to the databases.

    However, because pMachine allows flexibility in it's configuration, security issues can be greater of lesser. As the administrator of your site, there are a number of things you can do to increase security.

    1. Unless absolutely necessary, HTML should NOT be allowed in any publicly accessible forms - comment form, forum entry form, etc. These options are defined in the preferences page.
    2. All directories - even image directories - should contain a blank index.html page so that a user can not get a raw directory listing.
    3. All form fields should include a "maxlength" value set no higher than needed to prevent users from submitting more information than they should, or information they shouldn't.
    4. In your preferences, set a "maximum allowed number of characters" value to prevent someone spamming your comment pages or your collective weblogs.




    Intro to pBlocks

    Introduction:

    A pBlock is a container that holds elements of your web site. You can put anything you want in a pBlock - text, images, HTML, mp3's, scripting elements - absolutely anything that can be placed on a web page can be stored in a pBlock. What makes a pBlock powerful is that you can assign a behavior to it. Behaviors automate the presentation of the elements contained in the pBlock.

    For example, let's say you want to display a different image on your opening page each time someone visits. Simply create a pBlock and fill it with the various images. Then assign a behavior to it (in this case it would be "random"). Finally place the pBlock tag on your page where you want it to appear. Each time the page is loaded, one of the images is randomly displayed. Or let's say you want the background color and fonts on your site to change every time the page is loaded. Create a pBlock, fill it with different stylesheets, give it a behavior and place the tag in the header of your page. Each time the page is loaded, a different stylesheet is applied.

    pBlocks are extremely simple to set up and maintain, but give you a lot of interesting creative possibilities. You can make as many pBlocks as you need and each pBlock can hold an unlimited number of items.

    Note: pBlocks can also hold static elements - things that don't change. This allows you to manage that element through the control panel with your browser.



    Creating a pBlock

    1. Click View-Edit pBocks in the control panel menu.
    2. Click Create a new pBlock. You will be presented with a form with these fields:
      • Name of your pBlock: A descriptive name you'd like to call it. Can be several words.
      • Short name: A single word that will be used in the pMachine tag on your web page.
      • Behavior: You have four behavior choices:
        1. Random. Selects elements randomly.
        2. Cycle forward. Cycles forward in order.
        3. Cycle backward. Cycles backward in order.
        4. Static. Displays only the most recent element.

    Once you've filled the form out, submit it. You have now created a pBlock!



    Adding Members to Your pBlock

    1. Click pBlock Manager in the control panel menu. You will see a list of all the pBlocks you have created.
    2. Click add/edit members next to the pBlock you want to add a member to. You will be presented with a form where you will fill in these fields:
      • Name: A descriptive name for the element you are adding. This name is for your reference only.
      • pBlock Data: This is where you'll place the element you are adding to your pBlock. You can click the "upload an image" link to add an image, or place whatever else you'd like in the form.
      • Convert line-breaks into <br> tags?: Check this box ONLY if you are adding text, and ONLY if you want your line breaks (carriage returns) automatically turned into <br> tags. If you are placing any other kind of element - HTML, images, etc. do not check the box.
    Once you've filled the form out, submit it. You have now added a member to your pBlock. Repeat the preceding steps for each additional element you want to add to your pBlock.




    Displaying Your pBlock

    pBlocks are displayed the same way you display other pMachine elements; by placing a pMachine tag on your page wherever you want it to be displayed. In the case of pBlocks, the tag is as follows:

    <?php pblock("name_of_your_pBlock"); ?>

    In the above tag, you'll replace "name_of_your_pBlock" with the short name you gave your pBlock. Leave the quotes. For example, if your pBlock is called "pictures", your pBlock tag will be:

    <?php pblock("pictures"); ?>



    pBlock Behavior Cookies

    If you choose either "cycle forward", or "cycle backward" as the pBlock behavior, you will have to place a "cookie tag" on the second line (below the "include" tag) of whichever page contains your pBlock. The reason for the cookie is so that pMachine can keep track of what it is displaying for each visitor. Cycle forward and cycle backward are "sequential" behaviors, meaning they must increment or decrement in order. Without the cookie, pMachine has no way of knowing what each visitor saw last.

    To set a behavior cookie:

    On the second line of your page, place the following tag:

    <?php pblock_cookie("name"); ?>

    Replace "name" with the name of your pBlock.

    It's very important that you place this tag BELOW the include tag:

    <?php include("pm_inc.php"); ?>

    AND ABOVE ANY HTML.

    Here's what the top of your page should look like:

    <?php include("pm_inc.php"); ?>
    <?php pblock_cookie("name"); ?>
    <html>
    <head>
    etc.....

    If you have multiple pBlock cookies you can add them below the first one. If you are using the alternate (multiple instance) method of displaying pBlocks, place the master pBlock tag below the cookies, but above the HTML.



    Multiple Instances of the Same pBlock

    Although you can place the same pBlock in multiple places on the same page, each pBlock will normally operate independently.

    For example, if you are doing a random photo display, you can place the same pBlock tag in several places on the same page and each pBlock will independently pull a random photo out of the database.

    In some situations, however, you might need several pBlocks to work synchronously. That is, display the same information at the same time. Let's say you're changing the color scheme of your page and you want the same color placed in multiple places simultaneously. To do this you'll use slightly different pBlock tags as follows:

    1. Place a "master" pBlock tag at the top of your page, just below the "include" tag. This master tag looks like this:

    <?php $name_of_your_pBlock = pblock("name_of_your_pBlock","multi"); ?>

    You'll replace "name_of_your_pBlock" with the name you gave your pblock. If your pBlock is called "pictures", the tag will look like this:

    <?php $pictures = pblock("pictures","multi"); ?>

    Notice the word "multi" in the tag. This is important.

    Here is what the top of your page will look like with the above tag:

    <?php include("pm_include.php"); ?>

    <?php $pictures = pblock("pictures","multi"); ?>

    <html>
    <head>

    1. You'll then place the following tag in as many places on your page as you want:

    <?php echo "name_of_your_pBlock"; ?>

    Replacing, of course, "name_of_your_pBlock" with whatever you called it.

    Note: If you're using a "behavior cookie" tag, place it BELOW the include tag and ABOVE the master pBlock tags.




    Collective Weblogs

    pMachine allows you to designate any weblog as "collective". A collective weblog is one in which your site visitors can submit entries. Sort of like a discussion forum. Your visitors can submit entries, then other visitors can submit comments to those entries. You can even set up multiple collective weblogs - like a forum with different categories. Not as full-featured as a real forum, of course, but it does allows for a lot more dialog on your site. If you do set up more than one, you might want to use the same template set for all of them so that they will all look identical.

    Depending on whether your require membership or not, pMachine will dynamically create the correct version of the entry form. You'll find templates for both in the control panel, which you can modify to your liking.

    There are a few things you need to do to set up a collective weblog. We've done this as a safety mechanism to keep you from inadvertently enabling this if you don't want to.

    The first step is to go to the "Weblog Management" page and click "preferences" for the weblog you want to make collective. Look for the menu item that says "Is this a collective weblog?". Set it to yes. While you're on that page, you should also set your HTML options. It's recommended that you DO NOT allow HTML in entries, and possibly not images as well for security reasons.

    The next step is to decide whether you want the entry form on the same page as your weblog entries, or a separate page. Once you decide, you'll to place a pMachine tag wherever you want the form to appear.There are two ways to set up the pMachine tag to cover a couple different scenarios:

    If you have multiple collective weblogs and your want them to all share the same entry form on a separate page, you'll use the linking method. If you only have one collective weblog, or you want the entry form on the same page as your entries, you'll use the reference method

    Linking Method:

    This is the tag you'll use:

    <?php collective_weblog_entry_form($which); ?>

    This is a generic tag that has no way of knowing which weblog you want the entries submitted into. Because of that, you must make a link to the entry page with a URL that looks like this:

    name_of_your_entry_page.php?which=weblog

    In the above tag you'll replace "name_of_your_entry_page" with the name of the page, and "weblog" with the name of the weblog. For example. If your weblog is called "talkpage" and the entry page is called "newentry.php", this is how the tag will look:

    newentry.php?which=talkpage

    You'll make links like this for every weblog that is collective.

    Reference Method

    The reference method lets you specify within the tag itself which weblog you want to submit entries into. This is the tag you'll use:

    <?php collective_weblog_entry_form("name_of_your_weblog"); ?>

    Of course you need to replace "name_of_your_weblog" with the actual name. Make sure and leave the quotes.




    Multiple Weblogs/News pages

    pMachine allows the creation of multiple weblogs. pMachine, by default, installs with one weblog (called "weblog"), but as many as you require can be created.

    Multiple weblogs can be used whenever you need to separate your information into more specific groupings. If, for example, you want separate weblogs for different authors. You could create a "Bob's weblog", "Jill's weblog, and "Fred's weblog, and have each appear on it's own page with it's own look and preferences.

    You don't have to think of weblogs strictly as weblogs. Using a little ingenuity you can use additional weblogs to manage all kinds of content. For example, you could create a mini newspaper with "news", "sports", and "politics" categories. In this scenario, each category would be a separate weblog. You could even place the three categories together on the same page, each in it's own column. There is a lot of flexibility in what you can do with weblogs.

    When you create a new weblog, a new set of preferences for that weblog is created, allowing you to customize it independently of other weblogs. You can, for example, allow comments in one weblog, but disallow them in another. Or display one in ascending order and the other in descending. Once you create your new weblog, a new set of preferences will appear for it in the "preferences" menu.

    CREATING A NEW WEBLOG

    To create a new weblog, click on the "Weblog Management" menu in the control panel. You'll see a form where you can submit the name of your new weblog set. The name of your weblog set must be one word with no spaces.

    You've created a new weblog, now what?

    First, go to the preferences page. You'll see a set of preferences for your new weblog. The first four sets of preferences are the names of your new pages.

    You'll need to create four pages with these names (or with whatever name you'd like as long as you change the preferences accordingly). On the very first line of your new pages, just like all your other pages, you must place the following line of code:

    <?php include("pm_inc.php"); ?>

    You can place these new pages in their own directory if you'd like. If you do, you MUST make a copy of the page called: pm_inc.php and put it in the directory with the new pages. You might also have to open this page and change the path information if the path to the "lib" and "admin" directories has changed.

    Once you've created your new pages, you'll you'll need to place pMachine tags in them.

    Please note: Some pMachine tags require the name of the weblog in the tag. This one for example:

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

    You'll have to change the word "weblog" to the name of your new weblog.

    ADDING ENTRIES TO YOUR NEW WEBLOG

    Entries are added the way you currently add entries; by clicking the "create new entry" link. In the form you'll see a "pull-down" menu where you can select the weblog you want your entry to appear in. In your member profile you can also assign which weblog you'd like the "create new entry" form to default to.




    Multiple Template Sets

    Since pMachine allows you to create multiple weblogs, it also allows you to create multiple sets of the weblog templates. That way, each weblog can be assigned it's own template set, and appear on it's own set of pages, allowing total flexibility in the presentation of information.

    You should note that templates and weblogs operate independently of one another. You can have multiple weblogs all sharing a single template set. Before creating an additional template set, make sure you need it. If you've gone to a lot of trouble to customize the look of your existing templates, you can just assign the same set to your new weblog. Of course, if you need your new weblog to look completely different, you'll want to create a new template set.

    CREATING A NEW TEMPLATE SET

    To create a new set of templates, click on the "Template Sets" menu in the control panel. At the top of the page you'll click a link called "Create New". Once there, you'll see a form where you can submit the name of your new template set. The name of your template set must be one word with no spaces.

    When creating a new set you are given the option of duplicating an existing set in it's current state, or creating a copy of the set originally installed with pMachine. If you've spent a lot of time customizing your templates you don't need to start from scratch.

    Once you've created your new set, you need to assign it to a specific weblog. You do this in the "Weblog Management" preferences page.

    To modify your new templates, click to the "Template Sets" menu in the control panel.




    Timestamp Overview

    Every weblog entry and comment is timestamped. This timestamp can be displayed in many different ways using the codes below. Each letter of the code applies a particular format.

    For example, if we use this code: M d, y

    Our timestamp would be formatted like this: Jan 21, 2001

    The letter "M" formats formats the month in "textual short format". The letter "d" formats the day. The letter "y" is the year in "four digit" format, and the comma is just a comma.

    We could also add the time to the above example by doing this:

    M d, y - g:i a

    Our timestamp would then be formatted like this:
    Jan 21, 2001 - 5:22 pm

    Notice we used a comma between the day and the year, and a dash between the year and the time, and a colon to separate the hour from the minutes. You are allowed to add alpha-numeric, and punctuation characters between the formatting codes.

    Here's a more complex example to illustrate this:

    j\t\h o\f\ F Y | g:i a

    This would return: 15th of December | 5:22 am

    What are all the backslashes ("\") for?

    If you want characters to be treated as text, rather than timestamp codes, you'll have to "escape" them (add the backslash). Otherwise pMachine has no way to know if you intended the letter to be a formatting code or just a letter.

    Note: Make sure to use a backslash "\", NOT a forward slash "/". Also, be sure to escape single quotes (') and double quotes (") if you use them.




    Timestamp Codes

    a - "am" or "pm"s

    A - "AM" or "PM"

    B - Swatch Internet time

    d - day of the month, 2 digits with leading zeros ("01" to "31")

    D - day of the week, textual, 3 letters ("Fri")

    F - month, textual, long ("January")

    g - hour, 12-hour format without leading zeros ("1" to "12")

    G - hour, 24-hour format without leading zeros ("0" to "23")

    h - hour, 12-hour format ("01" to "12")

    H - hour, 24-hour format ("00" to "23")

    i - minutes ("00" to "59")

    I (capital i) - "1" if Daylight Savings Time, "0" otherwise.

    j - day of the month without leading zeros ("1" to "31")

    l (lowercase 'L') - day of the week, textual, long ("Friday")

    L - boolean for whether it is a leap year ("0" or "1")

    m - month ("01" to "12")

    M - month, textual, 3 letters ("Jan")

    n - month without leading zeros ("1" to "12")

    r - RFC 822 formatting ("Thu, 21 Dec 2000 16:01:07 +0200")

    s - seconds ("00" to "59")

    S - English ordinal suffix, 2 characters; ("th", "nd")

    t - number of days in the given month ("28" to "31")

    T - Timezone setting of this machine ("MDT")

    U - seconds since the epoch

    w - day of the week, numeric - "0" (Sunday) to "6" (Saturday)

    Y - year, 4 digits ("1999")

    y - year, 2 digits ("99")

    z - day of the year ("0" to "365")

    Z - timezone offset in seconds ("-43200" to "43200"). The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.




    pMachine Tags




    Description of All pMachine Files and Directories


    WEBLOG PAGES:

    The root directory contains all of the pages associated with your weblog. You'll edit these pages to change their look. There are a number of templates in the control panel that relate to the dynamic chunks of information, as well as many preference settings.
    1. weblog.php
      This is your main weblog, or "home" page. By default, it's called "weblog.php". You may rename this file as long as you also change the name in the control panel preferences. If you do, make sure the file retains the .php suffix.

      Contained within this page you'll find the following pMachine tag:

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

      This tag tells pMachine to display your weblog entries. There are quite a few other pMachine tags. A complete list is found later in the manual.

      In the control panel, you'll find several templates that you can modify to change the look, as well as the type of information your entries display. In addition, there are a number of preferences which relate to your weblog as well.
    2. comments.php
      This is the page where visitors post comments relating to a specific weblog entry. There are some pMachine tags on this page as well, which you'll manage through templates in the control panel.
      The comments page has an entry form which your visitors will use to submit comments. Based on whether you've chosen to require membership to post, or not, pMachine will display one of two entry forms. One designed for members, the other for non-members. There are some templates that determine the look of the forms.
    3. more.php
      This is an optional page containing "extended" entries. You've seen this approach in newspapers where the main page has a short introduction to the article, while the entire article is on another page. A link to this page will only appear in those weblog entries that contain "more" information. You may optionally use the comments page instead to display "more" information along with user comments, as long as you specify this in the preferences.
    4. archives.php
      This page contains the archived weblog entries which are not longer displayed on your main page. The archives page can either be a separate page or your weblog page. The pMachine tag used is identical for both, so pMachine doesn't care whether the page is separate or not. To display archived entries your visitors must click the archive links. Archive links are the list of months/years where you've created entries. These links contain information that tells pMachine to display a particular month's worth of archives.
    5. calendar.php The calendar turns the day of the month into a link every day that you have weblog entries. You can click the link to view that day's worth of entries. The calendar also shows member birthdays. The look of the calendar is defined in two places: In your general preferences, and in a CSS style sheet called "calendar.css"

      By default pMachine places the link to the calendar in the member nav bar. You don't have to have the link there if you don't want. You could always just make a different link to the calendar page.

      Note: The calendar only links to entries from your main weblog.
    6. search.php
      This is the page where search results are shown. In your preferences you'll need to specify the name of this page so that when you submit a search, it knows where to show the results. The formatting for the results is defined in the search templates.

      If this page is accessed by itself - in other words, not as a result of a search form being submitted - the page will display the advanced search form.
    7. pm_inc.php
      pMachine needs this file in order for your weblog pages to communicate with scripts in the "lib" and "admin" directory. If you move your weblog pages, and this changes the path to the "lib" and "admin" directories, you'll need to open "pm_inc.php" and update the path information.
    8. pm_style.css
      This is the CSS stylesheet used by the weblog pages. You can change alter it or create you own.

    ADMIN DIRECTORY

    The admin directory contains all of the files relating to the administrative control panel. Other than the files described below, there are no files that are user-modifiable.
    1. config.php This is the main configuration file for pMachine.
    2. suffix.inc This file defines the php suffix used by pMachine. By default the suffix is .php The only time you'll need to change the suffix definition in this file is if your particular server requires a different suffix than the default. See the installation instructions for more information.

    DOCS DIRECTORY

    This directory contains all pMachine documentation.

    IMAGES DIRECTORY

    By default there are two directories contained within the images directory: digits, and uploads. You may rename, or move any of these directories, as long as you specify this in your preferences.
    1. digits.
      The digits directory contains the individual images used by the hit counter. There are ten images: 1.gif, 2.gif, 3.gif, etc. You can create your own hit-counter images, or use a text-based version.
    2. uploads.
      When you upload an image through the control panel for placement in a weblog entry, or in a pBlock it is stored here.

    LIB DIRECTORY

    The lib directory contains all of the associated library files that generate your weblog, pBlocks, comments and other pages. Other than the one file described here, there is nothing user-modifiable.
    1. messages_lib.php This file contains the various "messages" that users might encounter while accessing your site. These messages will only apply if you require member registration. Most are error messages that occur as a result doing something wrong, like submitting a form without filling in the required fields, or trying to register a username that is already taken. There are around 60 messages, covering every conceivable situation. It's doubtful you'll need to edit these messages. If you do, make a backup of the file first. These messages are stored in an array, so they must be edited very carefully.

    MEMBERS DIRECTORY

    This directory contains all of the pages relating to member registration and management. You will only need these pages if you require member registration, otherwise you can ignore them. You'll need to edit these pages if you decide to change their look. There are a number of templates in the control panel that relate to these pages as well.
    1. activate.php The purpose of this page is to activate new member accounts. This page is only needed if you set your preferences to require member activation. The activation process is this: Upon registering, new members are sent an email with a URL to the activation page. The URL contains their activation code. When the member access the activation page, their account is automatically activated. If you access this page without the member code, or if a "pending" member tries to log-in to your site, it will instead display a form where a member can submit their email address to receive activation instructions.
    2. email_member.php This page contains an email form which allows registered members to email other registered members directly from your site. This feature is not available to non-members since granting emailing privileges to the general public could have negative consequences. Members have the option of not accepting email, in which case sending an email to them will not be permitted. The emails are always sent without the person sending the email knowing the email address of the person they are sending to.
    3. forgot_pw.php If a member has forgotten their password, this page allows them to retrieve it by submitting their email address in a form. The username and password are emailed automatically.
    4. login.php This page contains the login form as well as a link to the "forgotten password" page.
    5. mailinglist.php This page adds and removes members from the mailing list. When a person submits their email address through the "mailing list" form, they are directed to this page where they receive a confirmation message. Every time you send and email to members of the list, at the bottom of the email there will be an "unsubscribe" link. When they click the link, they will be directed to this same page where they will receive a "you are unsubscribed" message.
    6. messages.php This is a "container" page for the various messages that are dynamically generated. If a user does something wrong like logging-in with an incorrect password, they are redirected to this page where the appropriate message is displayed.
    7. profile_edit.php This page allows members to update their personal information: username, password, email address, etc.
    8. profile_view_all.php This page displays a list of all registered members.
    9. profile_view_ind.php This page allows site visitors to view information about specific members. pMachine allows you to place a "profile" link next to each comment so that people can find out about the person who left the comment.
    10. profile_view_update.php If a member changes information in their profile, the changes are displayed here.
    11. register.php This page contains the member registration form.
    12. member_style.css The CSS stylesheet for these pages.
    13. pm_inc.php This is a configuration file similar to the one described earlier. It enables pMachine to communicate with with all the member pages. It MUST always remain in the same directory as these files. If you decide to move the member pages into a different directory, thereby changing the relationship of those pages to the other pMachine files, you'll have to open "pm_inc.php" and change the path information.