phpns documentation and manual

Welcome to the the documentation and manual for phpns. The document aims to help you accomplish different tasks with the phpns software. The list below gives you a list of different topics explored:

  1. introduction
    1. license
  2. installing phpns
    1. guided installation
  3. how it works
    1. administration
    2. presentation
  4. pre-include variables
    1. how to use pre-include variables
  5. example of use
    1. just the HTML
    2. adding the phpns code
  6. the admin panel
  7. new article
  8. article management
    1. search
    2. sorting options
    3. other uses
  9. user management
    1. new user
  10. rank management
    1. new rank
  11. preferences
    1. general display options
    2. search engine friendly URLs
    3. category management
    4. comment options
    5. template management
    6. ban options
    7. feed options
    8. integration wizard
    9. freeze/cache management
    10. system log
    11. theme management
    12. database backup/restore
    13. WYSIWYG editor
    14. online/offline options
    15. system timestamp options
    16. delete login records
    17. global message
  12. conclusion

introduction

Phpns is a software project, designed to ease the process of content management for websites. The intended purpose is to include, or "put" a dynamic news system into your website HTML code. With most content management systems, the CMS takes control of almost every aspect of your website, and customization of the "look" of the website calls for editing theme files, and skins. However, with phpns, you can design your website however you like, and phpns will squeeze into your design, wherever you like, with one line of code in your HTML. This method of "including a dynamic news system" eases your job, and doesn't require you to mess with tedious website templates [albeit phpns does have a certain kind of templates] and theme files.

The project is FOSS (Free and Open Source Software), released under the GNU GPL license. The GPL gives you the freedom to modify the phpns source code without restriction.

License

Go to the license file

installing phpns

Installing the phpns software is designed to be quick and simple. The guided installation is located in /install, and phpns will automatically redirect you to the installation script if you have not completed it.

Guided installation

When you are first directed to the phpns install script, you will be presented with the license (which you should read). Continue by clicking "Continue" near the bottom.

Step 1

This installation step is where you need to enter all important data for phpns to function. Please complete the following:

  • database information: mysql host, mysql user, mysql user password, database name, and optionally a table prefix.
  • administrator information: your desired username and password.

In the "Advanced" drop-down, you have several options regarding the database.

  • Create DB: Phpns will attempt to create the database specified in Database Name. The user will need to have the permissions to create databases.
  • Existing DB: Phpns will NOT add, erase, or overwrite any data in the database. This is an ideal option if you are reinstalling the phpns package, without needing to touch the database.
  • Overwrite DB: Phpns will delete all current tables in the database (having to do with phpns, this will not touch unrelated tables) and recreate them. This is ideal for corrupted phpns tables.

After you are done supplying the information, and all information is valid, you can press "Continue" near the end of the page.

Step 2

After finishing step 1, you should be given a notice with a title of "Configuration finished". This message should inform you that phpns has successfully created the tables for phpns, and you will need to CHMOD the file /inc/config.php so phpns can write important information to the database file.

Once you have completed the instructions (or expect that the file permissions are already set correctly), click "Continue" near the bottom of the page.

Step 3

This is the final step in the installation process. If everything worked out, and /inc/config.php did indeed have proper write permissions, you should receive a successful message. You can now delete the whole /install directory. Return to your administration panel, and login with the data you provided in Step 1!

In the event of an error (probably because /inc/config.php didn't have proper write permissions), phpns will give you the intended contents of the file in a text area. You can do one of two things:

  1. Try to correct the permissions for the /inc/config.php file and refresh the page, or
  2. Copy and paste the intended file contents into the /inc/config.php, save, and upload. If using this method, you do not need to refresh the installation page.

Assuming success, you can now Delete the entire /install directory, and return to your administration panel to login.

how it works

For the sake of understanding, we can safely "split up" phpns into two different categories of functionality: presentation and administration. The administration-end is the bulk of the project, where you can create and manage articles, create categories, manage templates, create users (co-admins), ban users... etc etc. The presentation-end is what the average site visitor will see, the actual news, generated by the administration-end.

Below, we're going to go deeper into the administration and presentation end of phpns. You can click on the listed items to get a more detailed description of each topic.

Administration

As an administrator of the phpns installation, you can login to the panel, and do a variety of things, including:

All of these actions are protected from the general public, and only those who have user access can modify, or even look at them. You will spent the bulk of your phpns usage in the admin panel.

Presentation

While the administration-end of phpns is meant for the website admin, how will your viewers see the articles you have posted? This is where the presentation-end of phpns comes in, which will be held almost fully in the shownews.php file (/shownews.php).

"shownews.php" is probably the most important file in the phpns software package, because it's the file that presents the articles you have created to the public. You will want to "include", or "put" the contents of shownews.php into any (PHP) file on your web server, to literally "inject" a news system into your current HTML template/design.

Once again, the usage of shownews.php is used through an "include". Anywhere in your HTML design, as long as the file ends in .php, you can use <?php include("path/to/shownews.php"); ?> to fetch the phpns articles into your design. You can also use pre-include variables to customize how the articles are displayed. For an example of a phpns implementation, see: example of use.

pre-include variables

Pre-include variables are devices of customization that will "modify" how shownews.php generates news articles. There are a few pre-include variables, each for a specific use. See the table below for a complete list of variables, and examples of use further down.

Variable Usage Values
$phpns['limit'] Limits the number of articles displayed. This includes all articles in all pages. 1-9999
$phpns['order'] Modifies the order (chronologically) of articles displayed. ASC | DESC
$phpns['offset'] Offset of article generation. "Skip" x number of articles before displaying. 1-9999
$phpns['category'] Specifies that only articles belonging to category(ies) x should be displayed. Value should the the ID number of category. Default is all categories. 1 [,2,3]
$phpns['template'] Specifies the template (made in the admin panel) that will be used. Default is the "selected" template. Value should be the ID number of template. 1-9999
$phpns['items_per_page'] Specifies the number of articles for each page (when using pagination). Will only work with pagination enabled. Defaults to value specified in admin panel. 1-9999
$phpns['disable_pagination'] Disables pagination for generated articles. TRUE | FALSE
$phpns['always_show_extended_article'] Will always show the extended article (along with the article list) TRUE | FALSE
$phpns['disable_extended_article'] Disables the full stories for all articles in the phpns instance. TRUE | FALSE
$phpns['sef'] Enables SEF URLs in generated articles. The value is the path on the server before article title is presented in the URL. Example: http://example.org/VALUE/Example-news-post
  • $phpns['sef'] = '/';
  • $phpns['sef'] = 'mydirectory/';

Note: This variable was named $phpns['sef_override'] in previous versions. It has been changed to the current $phpns['sef'], but the old one will still work.

Path of SEF URL
$phpns['comment_override'] Automatically disables comments for all articles generated. TRUE | FALSE
$phpns['static'] Keeps phpns from displaying single articles. If news generation is set to static, the action (?a=whatever) will have no affect on this instance. This was designed so an admin could make a list of "recent articles" on every page, however, they will not be affected by clicking on the latest news post. TRUE | FALSE
$phpns['mode'] Sets the mode of article generation. Use this variable to generate RSS and ATOM feeds. If generating an rss or atom feed, there can be nothing in the file except the phpns include. 'rss' | 'atom'
$phpns['script_link'] Sets the file which all news articles will link to. Every article in the phpns instance requires a "link" to the item (where users can view the extended article, and comment). This will allow you to set where the link should be directed to. If you set as http://example.com/example.php, the resulting link: http://example.com/example.php?a=42. This variable can (and is preferred to) include a full URL beginning with http://; relative paths can be unreliable (and not tolerated with many RSS engines, when using RSS). It's also important to note that this variable won't affect the $phpns['sef_override'] pre-include variable. http://example.com/example.php
$phpns['freeze_file'] A special pre-include variable that can only be used when there is a freeze_file in /inc/freeze/. You will need to generate this in freeze/cache management. 'path/to/freeze.xxx.php'

How to use pre-include variables

To make use of the pre-include variables, they must be initialized, thus assigned values, before the actual include to shownews.php. An example of this process is below:


<?php
    $phpns
['limit'] = '15';
    
$phpns['category'] = '1,2,5';
    
$phpns['mode'] = 'atom';
    
    
//include the phpns shownews.php
    
include("path/to/shownews.php");
?>

To further the example, screenshots of a real-life examples of pre-include variables are shown below:

real life implimentation with pre-include variables real life implimentation with pre-include variables

example of use

Phpns is very easy to use; the entire program has been designed to work flawlessly with only one line of code: <?php include("path/to/shownews.php"); ?>. The process may seem complicated in writing, so we're going to give an example of a phpns implementation.

Just the HTML

The following code is HTML without any phpns inclusion. Your document will look different, of course.

<html>
<head>
	<title>Phpns testing</title>
</head>
<body>
	<h1>Phpns testing</h1>
	<p>This is my phpns testing page. This does not have news inclusion yet!</p>
	
	<div class="news">
		
	</div>
</body>
</html>

And the HTML rendered...

Just the HTML rendered

Adding the phpns code

The following code is HTML INCLUDING the phpns code, which will generate the phpns articles.

<html>
<head>
	<title>Phpns testing</title>
</head>
<body>
	<h1>Phpns testing</h1>
	<p>This is my phpns testing page. This <strong>does</strong> have news inclusion!</p>
	
	<div class="news">
		<?php include("path/to/shownews.php"); ?>
	</div>
</body>
</html>

And the HTML and PHP rendered...

HTML and PHP rendered (phpns!)

Although this shows the bare minimum of phpns, there is much more you can do. You can customize the way your articles are displayed with template management, and you can even use pre-include variables to customize which and how articles are displayed.

the admin panel

The administration panel is designed to be usable and customizable. A screenshot (with area identification) is shown below:

panel layout

The administration panel's HTML/CSS is contained in a theme directory (/themes/), with the default theme located at /themes/default/. You can learn more about phpns themes at theme management.

new article

Creating a new article with phpns is very easy, as the process only requires 2 fields. When you rrive at the new article page (Navigation->new article), you will see several input fields:

Input field Description Example Limit
Article title* Self-explanatory. Will be used in URLs when SEF URLs are turned on. Hello world! 150
Sub-title Self-explanatory. A subtitle (further describing the title) Hola, mundo! 150
Category Selected option will reflect "where" the article will be filed. Defaults to All Categories. All Categories N/A
Main article* The foundation of the article post, (optionally) powered by the TinyMCE WYSIWYG editor. The main article will be displayed on the article list (when including shownews.php). Today I went to the market and we... 20,000
Full story The extended article, which users will be able to see by clicking on the article itself. After that we joined our other friends over at the.... 20,000
Article image The image associated with the article. GIF/JPEG/TFF/PNG/SVG filetypes are accepted. N/A N/A
Start date The start date is the timestamp when the article begins availability to the public. If no end date is specified, it will continue indefinitely. 12/11/1991 10
End date The end date is the timestamp when the article ends availability to the public. 12/11/2084 10
Disable comments Check this box to disallow users commenting on this specific article. N/A N/A
Save as draft Check this box to keep the article away from the public's eye. This is a good option if you're working on an article, and it's not yet completed. N/A N/A

* Required fields

article management

article management allows you to view the articles you have posted in different ways, orders, and with conditions. By default, articles are listed in a descending date order. That means, the latest article that has been created will be shown at the TOP of the news management table. Although this might suite you, sometimes you may require ordering in a different way, scroll down to sorting options.

Search

Searching is really easy with phpns. At the top of article management, you will see a hyperlink named 'search' (with an expand/collapse option). Expand the search section, and you're presented with 2 fields: your query, and category. Whatever text you enter in the query box (the box with the text 'click here to start your search'), is the text we'll search for in every active article to date. The system will scan the title, subtitle, main article, and full story for that query entered. You also have the option to narrow your search by category. By default, it will search in all categories.

Sorting options

The article list can be sorted in various ways, so you can walk through your database articles easily. You have the following sorting options, which you can activate by clicking at the top of each column of the table.

Sort by date

This will allow you to sort the articles based on the time they were posted. Descending is the default sorting order, however, you may also set this to ascending.

Sort by title name (alphabetically)

This will allow you to sort the articles based on the articles' title. Ascending will order it from 0-9,A-Z. Descending will reverse the order.

Sort by author

This will allow you to sort the articles based on the author of the article. Ascending will sort the articles based on the name of the author, in alphabetical order. Therefore, ascending would present: Alan, Billy, Caty, George, Veronica, Zack. Descending would reverse the order.

Sort by Active or Activity

This will allow you to sort the articles based on their status as active or inactive. This is very useful for weeding out articles that have been dormant for a long time.

Other uses

View articles by a certain author

You can view all the articles posted by a specific user. While viewing articles, you can simply click on the username in the column "Author", and it will load up a selection of articles by that selected author.

View articles by category

You can do the same thing with the author, except clicking on the category next to any article. It will bring up a list of articles posted in that category.

user management

User management is a tool which lets you control and see various users on your installation, like creating new users, editing users, deleting users, and viewing different aspects of users. You can learn about editing ranks here.

The user management page will show a list of options, and a list of users with their information. The table which lists users has the following information:

New user

Each user must have a unique username. A full list of required and optional fields are listed below:

Input field Description Example Limit
Rank* The rank the user will be assigned to. The user will only have the permissions that the rank allows. Administrators N/A
Username* The username to be used for login and identification. Must be unique! RDawk 100
Full name* The full (real) name of the user. John Doe 150
Password* The password the user will use to login. Must match the second "confirm password" field. mySecretPassword123 N/A (No limit, hashed)
Confirm Pass* Second password field for verification. mySecretPassword123 N/A (No limit, hashed)
Additional Information The AIM, EMAIL, MSN, YAHOO, SKYPE fields are optional, and should be used for communication information. N/A 100

* Required fields

rank management

Phpns uses ranks to limit what users can accomplish with the phpns system. Sometimes, you don't want a user, or a group of users, to be able to post an article without being approved, or creating new users. Ranks can help you limit these users very easily.

new rank

Creating a new rank is fairly simple, however, each option requires a description to get full understanding:

Rank option Description
Logging in Determines if the user can login to the phpns system. If set to disallow, the user will get a message on their login attempt, telling them they can't login.
Create articles Determines if the user can post articles in phpns. If set to allow w/ approval, a user who can approve articles can activate it for the public's eyes.
Approve articles A user who can approve articles will be able to activate articles published by someone who can only post articles with approval.
Edit articles Determines whether a user can edit articles already published.
Delete articles Determines whether a user can delete users in article management.
Create users Determines whether a user can create users to access the phpns system.
Edit users Determines if a user can edit existing users.
Delete users Determines whether a user can delete other users in user management.
Login records Determines whether a user can access and review the login records.
Preferences Determines whether a user can edit any preferences/settings in the phpns admin panel
Create ranks Determines whether a user can create ranks in rank management.
Delete ranks Determines whether a user can delete ranks in rank management.

preferences

In the preferences section of phpns, you can modify different aspects of the phpns system, and how news generation is formed.

General display options

The display options (set in the administration panel, Navigation->Preferences) are used for setting the default values for article generation.

The date function described in "date format" is the date() function described at the php website.

Search engine friendly URLs

Search Engine URLs in phpns make the URLs to each specific article more descriptive, and thus better for search engines to index. Instead of http://example.com/index.php?a=23, Phpns will display something like http://example.com/My-first-article-in-phpns.

SEF URLs can be enabled on a per-include basis, with the pre-include variable $phpns['sef'] = '/' (more descriptive in the pre-include variable section of this document). SEF URLs make heavy use of the apache module "mod_rewrite", which you must have to use SEF URLs with phpns. The preferences page regarding this topic will give you a suggested .htaccess to use with phpns.

Category management

Category management is a cornerstone of article management in phpns. Categories are like file cabinets for your articles, allowing you to separate articles into groups, which can be very useful (explained further below).

By separating your articles into categories, you can refer to them, when including your news, as to only generate articles in that specific category. For example, you can have a "Site news" category, a "Blog" category, and a "Tutorials" category, each one displaying on a separate page on your website.

Comment options

This section, comment options, will dictate options and limitations set for comment posting by regular users. These settings are not overridable with pre-include variables.

Template management

Templates are used to customize the format, in HTML, in which your articles are displayed to the end user. You can have an unlimited amount of templates, but only one can remain the "default template". The default template is the template that is used without specifically implying a different template using pre-include variables. (Yes, you can use different templates in different instances of phpns on your website.)

New template

There are multiple variables that you can use in the templates, specified by using {}s. There is a list of them below:

Main article variables
  • {title} = article title
  • {sub_title} = subtitle
  • {date} = timestamp/date
  • {image_src} = article image src. (ex: <img src="{image_src}" alt="{title}" />
  • {main_article} = main article
  • {extended_article} = the extended article
  • {comment_count} = The number of articles this article has
  • {author} = author
  • {article_href} = the link to the article, but the actual href value
  • {reddit} = reddit social networking link
  • {digg} = digg social networking link
Comment variables
  • {author} = comment author
  • {website} = website
  • {comment} = comment
  • {date} = comment date
  • {ip} = comment ip address
Comment form variables

Please include ALL of the data in the form, or else things won't work. If you're not sure how to use these, copy them over from the default template included with the phpns installation.

  • {action} = value that goes inside the form
  • {hidden_data} = required value somewhere inside the form
  • {captcha_question} = In plain text, the question
  • {captcha_answer} = The answer encoded and passed through form
Pagination variables
  • {previous_page} = previous page number (ex: <a href="{previous_page}">)
  • {middle_pages} = middle pages, includes links already
  • {next_page} = next page number

Ban options

Ban options allow you to ban, or disallow, users from your website. This is a very useful function if a user is leaving inappropriate and/or offensive comments on your website.

To ban a user, you will need to gain the IP address of the user (which is available in the comments viewer of each article, with a "ban this user" link!). Bans will last forever unless you lift the ban yourself.

A list of valid IP addresses:

  • 127.0.0.7
  • 192.168.0.1
  • 601.923.334.20
  • 208.113.134.19

Rss/atom options

RSS/ATOM options let you modify different aspects of rss and atom generation. These options are not overrideable in individual includes.

Integration wizard

The integration wizard is a tool designed to streamline, and help you generate a custom phpns include script that you can copy and paste into your HTML. Consider it a GUI for setting variables like $phpns['category'] and $phpns['template'].

Freeze/cache management

Freeze management is a feature in phpns to optimize your news when you are expecting, or are currently experiencing a traffic/visit burst from the internet. Sites like reddit.com, digg.com, and other social networking sites often send thousands of visitors to your websiite in the event of a feature on their respective front pages. Usually, when you have a few mySQL queries being executed for each visitor, your server will eventually slow down, and shut down if it's extreme enough.

When you "freeze" a phpns instance (or shownews.php event), Phpns will create a static, HTML file of the current items on the phpns instance. That way, instead of executing SQL queries for each visitor, PHP will simply send a static HTML file to the user, saving a lot of processing power!

How to activate

The freeze/cache management preference doesn't have an on/off switch, you need to activate it for every phpns instance (every page which calls "shownews.php"). You will be asked for all the pre-include variables you want to modify how the "freeze file" (the static HTML file to be generated) is generated. Paste all the pre-include variables in this textbox, and click continue.

You will be given a new pre-include variable, that will look something like this:

  • $phpns['freeze_file'] = "inc/freeze/freeze.0c5f1062347d7885ba3c2dc534c2dc21.php";

Go back to the file where you want the freeze file to be used. Simply paste this line as another pre-include variable, and save. Phpns will now give the freeze file instead of dynamically generating a new version for each visitor!

Notes:

  • Comments cannot be used in a frozen instance.
  • The full story will be immediately below the main article, without going to a specific article (like the $phpns['always_show_full_story'] pre-include variable).
  • No new articles will be posted until the freeze-file pre-include variable is removed.

System log

The system log is a dynamic reference for what's been going on with your phpns installation. The log will display (almost) every action taken by every user with any access.

Theme management

Phpns uses a very easy theme system that will allow you to customize how the phpns administration panel looks.

Every theme has a theme directory, located in /themes/{theme}/. The theme file will have 3 required files:

  1. {theme}/theme.xml
  2. {theme}/admin.tpl.php
  3. {theme}/login.tpl.php

Creating a theme

To start creating a theme with phpns, it is recommended to take a look at the default theme included with every phpns installation (/themes/default/). Check phpns.com for more help on creating theme.

Theme replacement variables

Theme replacement variables can be used in admin.tpl.php, and login.tpl.php to add dynamic content to your HTML/source code. A list of theme replacement variables for the two files can be found below, respecively:

login.tpl.php
  • {content} = page content
  • {logo} = phpns logo
  • {version} = the phpns version installed
  • {current_page_name} = the page name
  • {head_data} = data that belongs in the <head> element/tag
  • {page_image} = the current page image
admin.tpl.php
  • {content} = page content
  • {username} = current user logged in
  • {version} = the phpns version installed
  • {current_page_name} = the page name
  • {head_data} = data that belongs in the <head> element/tag
  • {page_image} = the current page image

Database backup

You can (or anyone with access to the preferences page) backup the phpns database using the database backup tool. After some processing on the backend, phpns will send you the backup to download, allowing you to store the database file on your local computer for easy restoration later.

Restoring the database is easy. Just Click "Browse" next to the input field, and find the database file you previously backed up. This will delete/overwrite your current database, be careful!

WYSIWYG editor

This preference page will allow you to turn TinyMCE (The WYSIWYG editor used for making articles on phpns, Website, License file) on or off, depending on your needs as a publisher. If you set it to OFF, the editor will not load at all, you will need to write in HTML/CSS to design the post (of course, you can just use plain text too).

TinyMCE license file:

Phpns also uses CodePress (The Code editor used for editing templates on phpns, Website, License file) which currently cannot be turned on/off. This editor is disabled automatically with Opera browsers, due to incompatibility issues.

CodePress license file:

Many thanks to both of these projects and their communities, they have improved the functionality of phpns greatly!

Offline/online options

This option will allow you to temporarily (or permanently!) shut down phpns to the public. This is very useful when you're trying to sort out a problem dealing with phpns.

Timestamp options

Timestamp options let you change how the date() function is formatted throughout the phpns administration panel. Note: This does not affect any news generation on shownews.php.

You can learn more about the date() function at the php website.

Delete login records

Deletes all login records collected so far. Not recommended.

Rank management

See rank management.

Global message

The global message is a message displayed on every administration page of phpns. This is useful when you want to notify fellow administrators about a problem going on, or something worth spreading. To delete this message, simply leave the textarea blank and save.

conclusion

In closing, the phpns project aims to be a useful, yet simple application that can be used by website developers who need a reliable and easy-to-implement system. We're always looking for applications to embed in phpns, along with:

If you have something to offer the project, please, don't hesitate to contact us!