2.2.0 release ready for packaging.
[phpns.git] / help.php
blob0edf45c634b425b4fa703d72389972ea031d3ed3
1 <?php
3 /* Copyright (c) 2007-08 Alec Henriksen
4 * phpns is free software; you can redistribute it and/or modify it under the
5 * terms of the GNU General Public Licence (GPL) as published by the Free
6 * Software Foundation; either version 2 of the Licence, or (at your option) any
7 * later version.
8 * Please see the GPL at http://www.gnu.org/copyleft/gpl.html for a complete
9 * understanding of what this license means and how to abide by it.
13 //written by Alec Henriksen, took me quite awhile. Enjoy, masses! >_>
15 //defining some phpns example text (we need it to be sent through htmlspecialchars)
17 $html_code['example_html'] = htmlspecialchars('<html>
18 <head>
19 <title>Phpns testing</title>
20 </head>
21 <body>
22 <h1>Phpns testing</h1>
23 <p>This is my phpns testing page. This does not have news inclusion yet!</p>
25 <div class="news">
27 </div>
28 </body>
29 </html>');
31 $html_code['example_phpns'] = htmlspecialchars('<html>
32 <head>
33 <title>Phpns testing</title>
34 </head>
35 <body>
36 <h1>Phpns testing</h1>
37 <p>This is my phpns testing page. This <strong>does</strong> have news inclusion!</p>
39 <div class="news">
40 <?php include("path/to/shownews.php"); ?>
41 </div>
42 </body>
43 </html>');
45 $php_code['pre_include_variables'] = highlight_string('<?php
46 $phpns[\'limit\'] = \'15\';
47 $phpns[\'category\'] = \'1,2,5\';
48 $phpns[\'mode\'] = \'atom\';
50 //include the phpns shownews.php
51 include("path/to/shownews.php");
52 ?>', TRUE);
55 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
56 <html xmlns="http://www.w3.org/1999/xhtml">
57 <head>
58 <title>phpns &raquo; manual</title>
59 <link rel="shortcut icon" href="images/icons/favicon.ico" type="image/x-icon" />
60 <style type="text/css" media="all">
61 h2 {
64 h3, h4, h5, h6 {
65 color: black;
66 font-variant: italic;
68 ol ol {
69 list-style: lower-roman;
71 img {
72 margin-left: 15px;
74 #logo {
75 float: right;
77 #topics {
78 margin-left: 20px;
80 #topics .topic {
81 margin-left: 10px;
83 #topics .topic .topic {
84 margin-left: 30px;
85 padding-left: 10px;
86 padding-bottom: 10px;
87 border-left: 1px dotted #333;
89 #topics .topic .topic .topic {
90 margin-left: 37px;
92 #topics .topic p, #topics .topic table {
93 margin-left: 10px;
95 textarea {
96 width: 100%;
97 height: 200px;
99 pre {
100 margin-top: 27px;
101 margin-left: 20px;
102 padding: 6px;
103 border: 1px inset #666;
104 background: #F8F8F3;
105 width: auto;
106 white-space: pre;
108 table {
109 width: 99%;
111 table tr td.table_value {
112 width: 140px;
114 code {
115 color: gray;
117 </style>
118 </head>
119 <body>
120 <h1>phpns documentation and manual</h1>
121 <p>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:</p>
122 <div>
123 <img src="images/login.png" alt="phpns logo" id="logo" />
124 <ol>
125 <li><a href="#introduction">introduction</a>
126 <ol>
127 <li><a href="#introduction_license">license</a></li>
128 </ol>
129 </li>
130 <li><a href="#install">installing phpns</a>
131 <ol>
132 <li><a href="#install_guided">guided installation</a></li>
133 </ol>
134 </li>
135 <li><a href="#how_it_works">how it works</a>
136 <ol>
137 <li><a href="#how_it_works_admin">administration</a></li>
138 <li><a href="#how_it_works_pres">presentation</a></li>
139 </ol>
140 </li>
141 <li><a href="#pre_include_variables">pre-include variables</a>
142 <ol>
143 <li><a href="#pre_include_variables_how">how to use pre-include variables</a></li>
144 </ol>
145 </li>
146 <li><a href="#example">example of use</a>
147 <ol>
148 <li><a href="#example_html">just the HTML</a></li>
149 <li><a href="#example_phpns">adding the phpns code</a></li>
150 </ol>
151 </li>
152 <li><a href="#admin_panel">the admin panel</a></li>
153 <li><a href="#new_article">new article</a></li>
154 <li><a href="#article_management">article management</a>
155 <ol>
156 <li><a href="#article_management_search">search</a></li>
157 <li><a href="#article_management_sorting">sorting options</a></li>
158 <li><a href="#article_management_other">other uses</a></li>
159 </ol>
160 </li>
161 <li><a href="#user_management">user management</a>
162 <ol>
163 <li><a href="#user_management_new_user">new user</a></li>
164 </ol>
165 </li>
166 <li><a href="#rank_management">rank management</a>
167 <ol>
168 <li><a href="#rank_management_new_rank">new rank</a></li>
169 </ol>
170 </li>
171 <li><a href="#preferences">preferences</a>
172 <ol>
173 <li><a href="#preferences_display_options">general display options</a></li>
174 <li><a href="#preferences_sef_urls">search engine friendly URLs</a></li>
175 <li><a href="#preferences_categories">category management</a></li>
176 <li><a href="#preferences_comment_options">comment options</a></li>
177 <li><a href="#preferences_template_management">template management</a></li>
178 <li><a href="#preferences_ban_options">ban options</a></li>
179 <li><a href="#preferences_rss_options">feed options</a></li>
180 <li><a href="#preferences_integration_wizard">integration wizard</a></li>
181 <li><a href="#preferences_freeze">freeze/cache management</a></li>
182 <li><a href="#preferences_system_log">system log</a></li>
183 <li><a href="#preferences_theme_management">theme management</a></li>
184 <li><a href="#preferences_database_backup">database backup/restore</a></li>
185 <li><a href="#preferences_wyiwyg_editor">WYSIWYG editor</a></li>
186 <li><a href="#preferences_online_offline_options">online/offline options</a></li>
187 <li><a href="#preferences_timestamp_options">system timestamp options</a></li>
188 <li><a href="#preferences_delete_login_records">delete login records</a></li>
189 <li><a href="#preferences_global_message">global message</a></li>
190 </ol>
191 </li>
192 <li><a href="#conclusion">conclusion</a></li>
193 </ol>
194 </div>
195 <div id="topics">
196 <div class="topic">
197 <h2 id="introduction">introduction</h2>
198 <p>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.</p>
199 <p>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.</p>
200 <div class="topic">
201 <h3 id="introduction_license">License</h3>
202 <p><a href="docs/LICENSE">Go to the license file</a></p>
203 <p><textarea><?php include("docs/LICENSE"); ?></textarea></p>
204 </div>
205 </div>
207 <div class="topic">
208 <h2 id="install">installing phpns</h2>
209 <p>Installing the phpns software is designed to be quick and simple. The guided installation is located in <code>/install</code>, and phpns will automatically redirect you to the installation script if you have not completed it.</p>
211 <div class="topic">
212 <h3 id="install_guided">Guided installation</h3>
213 <p>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.</p>
215 <div class="topic">
216 <h4>Step 1</h4>
217 <p>This installation step is where you need to enter all important data for phpns to function. Please complete the following:
218 <ul>
219 <li>database information: mysql host, mysql user, mysql user password, database name, and optionally a table prefix.</li>
220 <li>administrator information: your desired username and password.</li>
221 </ul>
223 <p>In the "Advanced" drop-down, you have several options regarding the database.</p>
225 <ul>
226 <li>Create DB: Phpns will attempt to create the database specified in Database Name. The user will need to have the permissions to create databases.</li>
227 <li>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.</li>
228 <li>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.</li>
229 </ul>
231 <p>After you are done supplying the information, and all information is valid, you can press "Continue" near the end of the page.</p>
232 </div>
234 <div class="topic">
235 <h4>Step 2</h4>
236 <p>After finishing step 1, you should be given a notice with a title of "<code>Configuration finished</code>". This message should inform you that phpns has successfully created the tables for phpns, and you will need to CHMOD the file <code>/inc/config.php</code> so phpns can write important information to the database file.</p>
237 <p>Once you have completed the instructions (or expect that the file permissions are already set correctly), click "Continue" near the bottom of the page.</p>
238 </div>
240 <div class="topic">
241 <h4>Step 3</h4>
242 <p>This is the final step in the installation process. If everything worked out, and <code>/inc/config.php</code> did indeed have proper write permissions, you should receive a successful message. You can now <strong>delete the whole <code>/install</code> directory.</strong> Return to your administration panel, and login with the data you provided in Step 1!</p>
243 <p>In the event of an error (probably because <code>/inc/config.php</code> 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:</p>
245 <ol>
246 <li>Try to correct the permissions for the <code>/inc/config.php</code> file and refresh the page, or</li>
247 <li>Copy and paste the intended file contents into the <code>/inc/config.php</code>, save, and upload. <strong>If using this method, you do not need to refresh the installation page.</strong></li>
248 </ol>
250 <p>Assuming success, you can now <strong>Delete the entire <code>/install</code> directory</strong>, and return to your administration panel to login.
251 </div>
252 </div>
253 </div>
255 <div class="topic">
256 <h2 id="how_it_works">how it works</h2>
257 <p>For the sake of this section of the guide, 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.</p>
258 <p>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.</p>
259 <div class="topic">
260 <h3 id="how_it_works_admin">Administration</h3>
261 <p>As an administrator of the phpns installation, you can login to the panel, and do a variety of things, including:</p>
262 <ul>
263 <li><a href="#new_article">create new articles</a></li>
264 <li><a href="#article_management">manage existing articles</a></li>
265 <li><a href="#user_management">create/edit users</a></li>
266 <li>and much more...</li>
267 </ul>
269 <p>All of these actions are protected from the general public, and only those who have user access can modify, or even look at them. <strong>You will spent the bulk of your phpns usage in the admin panel.</strong></p>
270 </div>
272 <div class="topic">
273 <h3 id="how_it_works_pres">Presentation</h3>
274 <p>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).</p>
275 <p>"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.</p>
276 <p>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 <code>&lt;?php include("path/to/shownews.php"); ?&gt;</code> to fetch the phpns articles into your design. You can also use <a href="#pre_include_variables">pre-include variables</a> to customize how the articles are displayed. For an example of a phpns implementation, see: <a href="#example">example of use</a>.</p>
277 </div>
278 </div>
280 <div class="topic">
281 <h2 id="pre_include_variables">pre-include variables</h2>
282 <p>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.</p>
283 <table border="1">
284 <tbody>
285 <tr>
286 <td><strong>Variable</strong></td>
287 <td><strong>Usage</strong></td>
288 <td class="table_value"><strong>Values</strong></td>
289 </tr>
290 <tr>
291 <td>$phpns['limit']</td>
292 <td>Limits the number of articles displayed. This includes all articles in all pages.</td>
293 <td>1-9999</td>
294 </tr>
295 <tr>
296 <td>$phpns['order']</td>
297 <td>Modifies the order (chronologically) of articles displayed.</td>
298 <td>ASC | DESC</td>
299 </tr>
300 <tr>
301 <td>$phpns['offset']</td>
302 <td>Offset of article generation. "Skip" x number of articles before displaying.</td>
303 <td>1-9999</td>
304 </tr>
305 <tr>
306 <td>$phpns['category']</td>
307 <td>Specifies that only articles belonging to category(ies) x should be displayed. Value should the the ID number of category. Default is all categories.</td>
308 <td>1 [,2,3]</td>
309 </tr>
310 <tr>
311 <td>$phpns['template']</td>
312 <td>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.</td>
313 <td>1-9999</td>
314 </tr>
315 <tr>
316 <td>$phpns['items_per_page']</td>
317 <td>Specifies the number of articles for each page (when using pagination). Will only work with pagination enabled. Defaults to value specified in admin panel.</td>
318 <td>1-9999</td>
319 </tr>
320 <tr>
321 <td>$phpns['disable_pagination']</td>
322 <td>Disables pagination for generated articles.</td>
323 <td>TRUE | FALSE</td>
324 </tr>
325 <tr>
326 <td>$phpns['always_show_extended_article']</td>
327 <td>Will always show the extended article (along with the article list)</td>
328 <td>TRUE | FALSE</td>
329 </tr>
330 <tr>
331 <td>$phpns['disable_extended_article']</td>
332 <td>Disables the full stories for all articles in the phpns instance.</td>
333 <td>TRUE | FALSE</td>
334 </tr>
335 <tr>
336 <td>$phpns['sef_override']</td>
337 <td>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
338 <ul>
339 <li>$phpns['sef_override'] = '/';</li>
340 <li>$phpns['sef_override'] = 'mydirectory/';</li>
341 </ul>
342 </td>
343 <td>Path of SEF URL</td>
344 </tr>
345 <tr>
346 <td>$phpns['comment_override']</td>
347 <td>Automatically disables comments for all articles generated.</td>
348 <td>TRUE | FALSE</td>
349 </tr>
350 <tr>
351 <td>$phpns['static']</td>
352 <td>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.</td>
353 <td>TRUE | FALSE</td>
354 </tr>
355 <tr>
356 <td>$phpns['mode']</td>
357 <td>Sets the mode of article generation. Use this variable to generate RSS and ATOM feeds. If generating an rss or atom feed, <strong>there can be nothing in the file except the phpns include.</strong></td>
358 <td>'rss' | 'atom'</td>
359 </tr>
360 <tr>
361 <td>$phpns['script_link']</td>
362 <td>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 <code>http://example.com/example.php</code>, the resulting link: <code>http://example.com/example.php?a=42</code>. This variable can (and is preferred to) include a full URL beginning with <code>http://</code>; <strong>relative paths can be unreliable.</strong> It's also important to note that this variable won't affect the $phpns['sef_override'] pre-include variable.
363 <td>http://example.com/example.php</td>
364 <tr>
365 <td>$phpns['freeze_file']</td>
366 <td>A special pre-include variable that can only be used when there is a freeze_file in <code>/inc/freeze/</code>. You will need to generate this in freeze/cache management.</strong></td>
367 <td>'path/to/freeze.xxx.php'</td>
368 </tr>
369 </tbody>
370 </table>
372 <div class="topic">
373 <h3 id="pre_include_variables_how">How to use pre-include variables</h3>
374 <p>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:</p>
376 <pre class="code"><?php echo $php_code['pre_include_variables']; ?></pre>
378 <p>To further the example, screenshots of a real-life examples of pre-include variables are shown below:</p>
379 <img src="images/guide/rl_window1.png" alt="real life implimentation with pre-include variables" />
381 <img src="images/guide/rl_window2.png" alt="real life implimentation with pre-include variables" />
382 </div>
383 </div>
385 <div class="topic">
386 <h2 id="example">example of use</h2>
387 <p>Phpns is very easy to use; the entire program has been designed to work flawlessly with only one line of code: <code>&lt;?php include("path/to/shownews.php"); ?&gt;</code>. The process may seem complicated in writing, so we're going to give an example of a phpns implementation. </p>
388 <div class="topic">
389 <h3 id="example_html">Just the HTML</h3>
390 <p>The following code is HTML without any phpns inclusion. Your document will look different, of course.</p>
391 <pre class="code"><?php echo $html_code['example_html']; ?></pre>
393 <p>And the HTML rendered...</p>
394 <img src="images/guide/window1.png" alt="Just the HTML rendered" />
395 </div>
396 <div class="topic">
397 <h3 id="example_phpns">Adding the phpns code</h3>
398 <p>The following code is HTML INCLUDING the phpns code, which will generate the phpns articles.</p>
399 <pre class="code"><?php echo $html_code['example_phpns']; ?></pre>
401 <p>And the HTML and PHP rendered...</p>
402 <img src="images/guide/window2.png" alt="HTML and PHP rendered (phpns!)" />
403 </div>
404 <p>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 <a href="#preferences_theme_management">template management</a>, and you can even use <a href="#pre_include_variables">pre-include variables</a> to customize which and how articles are displayed.
405 </div>
407 <div class="topic">
408 <h2 id="admin_panel">the admin panel</h2>
409 <p>The administration panel is designed to be usable and customizable. A screenshot (with area identification) is shown below:</p>
411 <img src="images/guide/window_layout.png" alt="panel layout" />
413 <p>The administration panel's HTML/CSS is contained in a theme directory (<code>/themes/</code>), with the default theme located at <code>/themes/default/</code>. You can learn more about phpns themes at <a href="#preferences_theme_management">theme management</a>.</p>
414 </div>
416 <div class="topic">
417 <h2 id="new_article">new article</h2>
418 <p>Creating a new article with phpns is very easy, as the process only requires 2 fields. When you rrive at the new article page (<code>Navigation->new article</code>), you will see several input fields:</p>
419 <table border="1">
420 <tbody>
421 <tr>
422 <td><strong>Input field</strong</td>
423 <td><strong>Description</strong></td>
424 <td><strong>Example</strong></td>
425 <td><strong>Limit</strong></td>
426 </tr>
427 <tr>
428 <td><strong>Article title*</strong></td>
429 <td>Self-explanatory. Will be used in URLs when SEF URLs are turned on.</td>
430 <td>Hello world!</td>
431 <td>150</td>
432 </tr>
433 <tr>
434 <td>Sub-title</td>
435 <td>Self-explanatory. A subtitle (further describing the title)</td>
436 <td>Hola, mundo!</td>
437 <td>150</td>
438 </tr>
439 <tr>
440 <td>Category</td>
441 <td>Selected option will reflect "where" the article will be filed. Defaults to All Categories.</td>
442 <td>All Categories</td>
443 <td>N/A</td>
444 </tr>
445 <tr>
446 <td><strong>Main article*</strong></td>
447 <td>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).</td>
448 <td>Today I went to the market and we...</td>
449 <td>20,000</td>
450 </tr>
451 <tr>
452 <td>Full story</td>
453 <td>The extended article, which users will be able to see by clicking on the article itself.</td>
454 <td>After that we joined our other friends over at the....</td>
455 <td>20,000</td>
456 </tr>
457 <tr>
458 <td>Article image</td>
459 <td>The image associated with the article. GIF/JPEG/TFF/PNG/SVG filetypes are accepted.</td>
460 <td>N/A</td>
461 <td>N/A</td>
462 </tr>
463 <tr>
464 <td>Start date</td>
465 <td>The start date is the timestamp when the article begins availability to the public. If no end date is specified, it will continue indefinitely.</td>
466 <td>12/11/1991</td>
467 <td>10</td>
468 </tr>
469 <tr>
470 <td>End date</td>
471 <td>The end date is the timestamp when the article ends availability to the public.</td>
472 <td>12/11/2084</td>
473 <td>10</td>
474 </tr>
475 <tr>
476 <td>Disable comments</td>
477 <td>Check this box to disallow users commenting on this specific article.</td>
478 <td>N/A</td>
479 <td>N/A</td>
480 </tr>
481 <tr>
482 <td>Save as draft</td>
483 <td>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.</td>
484 <td>N/A</td>
485 <td>N/A</td>
486 </tr>
487 </tbody>
488 </table>
489 <p>* Required fields</p>
490 </div>
492 <div class="topic">
493 <h2 id="article_management">article management</h3>
494 <p>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.</p>
496 <div class="topic">
497 <h3 id="article_management_search">Search</h3>
498 <p>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.</p>
499 </div>
501 <div class="topic">
502 <h3 id="article_management_sorting">Sorting options</h3>
503 <p>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.</p>
505 <div class="topic">
506 <h4>Sort by date</h4>
507 <p>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.</p>
509 <h4>Sort by title name (alphabetically)</h4>
510 <p>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.</p>
512 <h4>Sort by author</h4>
513 <p>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.</p>
515 <h4>Sort by Active or Activity</h4>
516 <p>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.</p>
517 </div>
518 </div>
520 <div class="topic">
521 <h3 id="article_management_other">Other uses</h3>
522 <h4>View articles by a certain author</h4>
523 <p>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.</p>
525 <h4>View articles by category</h4>
526 <p>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.</p>
527 </div>
528 </div>
530 <div class="topic">
531 <h2 id="user_management">user management</h3>
532 <p>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 <a href="#rank_management">here</a>.</p>
533 <p>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:
534 <ul>
535 <li>username</li>
536 <li>full name</li>
537 <li>date</li>
538 <li>rank</li>
539 <li>#/articles</li>
540 </ul>
542 <div class="topic">
543 <h3 id="user_management_new_user">New user</h3>
544 <p>Each user must have a <strong>unique username</strong>. A full list of required and optional fields are listed below:</p>
545 <table border="1">
546 <tbody>
547 <tr>
548 <td><strong>Input field</strong</td>
549 <td><strong>Description</strong></td>
550 <td><strong>Example</strong></td>
551 <td><strong>Limit</strong></td>
552 </tr>
553 <tr>
554 <td><strong>Rank*</strong></td>
555 <td>The rank the user will be assigned to. The user will only have the permissions that the rank allows.</td>
556 <td>Administrators</td>
557 <td>N/A</td>
558 </tr>
559 <tr>
560 <td><strong>Username*</strong></td>
561 <td>The username to be used for login and identification. Must be unique!</td>
562 <td>RDawk</td>
563 <td>100</td>
564 </tr>
565 <tr>
566 <td><strong>Full name*</strong></td>
567 <td>The full (real) name of the user.</td>
568 <td>John Doe</td>
569 <td>150</td>
570 </tr>
571 <tr>
572 <td><strong>Password*</strong></td>
573 <td>The password the user will use to login. Must match the second "confirm password" field.</td>
574 <td>mySecretPassword123</td>
575 <td>N/A (No limit, hashed)</td>
576 </tr>
577 <tr>
578 <td><strong>Confirm Pass*</strong></td>
579 <td>Second password field for verification.</td>
580 <td>mySecretPassword123</td>
581 <td>N/A (No limit, hashed)</td>
582 </tr>
583 <tr>
584 <td>Additional Information</td>
585 <td>The AIM, EMAIL, MSN, YAHOO, SKYPE fields are optional, and should be used for communication information.</td>
586 <td>N/A</td>
587 <td>100</td>
588 </tr>
589 </tbody>
590 </table>
591 <p>* Required fields</p>
592 </div>
593 </div>
595 <div class="topic">
596 <h2 id="rank_management">rank management</h2>
597 <p>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.</p>
599 <div class="topic">
600 <h3 id="rank_management_new_rank">new rank</h3>
602 <p>Creating a new rank is fairly simple, however, each option requires a description to get full understanding:</p>
603 <table border="1">
604 <tbody>
605 <tr>
606 <td><strong>Rank option</strong</td>
607 <td><strong>Description</strong></td>
608 </tr>
609 <tr>
610 <td><strong>Logging in</strong></td>
611 <td>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.</td>
612 </tr>
613 <tr>
614 <td><strong>Create articles</strong></td>
615 <td>Determines if the user can post articles in phpns. If set to <code>allow w/ approval</code>, a user who can approve articles can activate it for the public's eyes.</td>
616 </tr>
617 <tr>
618 <td><strong>Approve articles</strong></td>
619 <td>A user who can approve articles will be able to activate articles published by someone who can only post articles with approval.</td>
620 </tr>
621 <tr>
622 <td><strong>Edit articles</strong></td>
623 <td>Determines whether a user can edit articles already published.</td>
624 </tr>
625 <tr>
626 <td><strong>Delete articles</strong></td>
627 <td>Determines whether a user can delete users in article management.</td>
628 </tr>
629 <tr>
630 <td><strong>Create users</strong></td>
631 <td>Determines whether a user can create users to access the phpns system.</td>
632 </tr>
633 <tr>
634 <td><strong>Edit users</strong></td>
635 <td>Determines if a user can edit existing users.</td>
636 </tr>
637 <tr>
638 <td><strong>Delete users</strong></td>
639 <td>Determines whether a user can delete other users in user management.</td>
640 </tr>
641 <tr>
642 <td><strong>Login records</strong></td>
643 <td>Determines whether a user can access and review the login records.</td>
644 </tr>
645 <tr>
646 <td><strong>Preferences</strong></td>
647 <td>Determines whether a user can edit any preferences/settings in the phpns admin panel</td>
648 </tr>
649 <tr>
650 <td><strong>Create ranks</strong></td>
651 <td>Determines whether a user can create ranks in rank management.</td>
652 </tr>
653 <tr>
654 <td><strong>Delete ranks</strong></td>
655 <td>Determines whether a user can delete ranks in rank management.</td>
656 </tr>
657 </tbody>
658 </table>
659 </div>
660 </div>
662 <div class="topic">
663 <h2 id="preferences">preferences</h2>
664 <p>In the preferences section of phpns, you can modify different aspects of the phpns system, and how news generation is formed.</p>
666 <div class="topic">
667 <h3 id="preferences_display_options">General display options</h3>
668 <p>The display options (set in the administration panel, <code>Navigation->Preferences</code>) are used for setting the default values for article generation.</p>
669 <p>The date function described in "date format" is the <code>date()</code> function described at the <a href="http://php.net/date">php website</a>.
670 </div>
672 <div class="topic">
673 <h3 id="preferences_sef_urls">Search engine friendly URLs</h3>
674 <p>Search Engine URLs in phpns make the URLs to each specific article more descriptive, and thus better for search engines to index. Instead of <code>http://example.com/index.php?a=23</code>, Phpns will display something like <code>http://example.com/My-first-article-in-phpns</code>.
675 <p>SEF URLs can be enabled on a per-include basis, with the <a href="#pre_include_variables">pre-include variable</a> <code>$phpns['sef_override'] = '/'</code> (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.</p>
676 </div>
678 <div class="topic">
679 <h3 id="preferences_categories">Category management</h3>
680 <p>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).</p>
681 <p>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.</p>
682 </div>
684 <div class="topic">
685 <h3 id="preferences_comment_options">Comment options</h3>
686 <p>This section, comment options, will dictate options and limitations set for comment posting by regular users. These settings <strong>are not</strong> overridable with pre-include variables.</p>
687 </div>
689 <div class="topic">
690 <h3 id="preferences_template_management">Template management</h3>
691 <p>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.)</p>
692 <div class="topic">
693 <h4>New template</h4>
694 <p>There are multiple variables that you can use in the templates, specified by using {}s. There is a list of them below:</p>
695 <h5>Main article variables</h5>
696 <ul>
697 <li>{title} = article title</li>
698 <li>{sub_title} = subtitle</li>
699 <li>{date} = timestamp/date</li>
700 <li>{image_src} = article image src. (ex: &lt;img src="{image_src}" alt="{title}" /&gt;
701 <li>{main_article} = main article</li>
702 <li>{extended_article} = the extended article</li>
703 <li>{comment_count} = The number of articles this article has</li>
704 <li>{author} = author</li>
705 <li>{article_href} = the link to the article, but the actual href value</li>
706 <li>{reddit} = reddit social networking link</li>
707 <li>{digg} = digg social networking link</li>
708 </ul>
709 <h5>Comment variables</h5>
710 <ul>
711 <li>{author} = comment author</li>
712 <li>{website} = website</li>
713 <li>{comment} = comment</li>
714 <li>{date} = comment date</li>
715 <li>{ip} = comment ip address</li>
716 </ul>
717 <h5>Comment form variables</h5>
718 <p><em>Please include ALL of the data in the form, or else things won't work.</em> If you're not sure how to use these, copy them over from the default template included with the phpns installation.</p>
719 <ul>
720 <li>{action} = value that goes inside the form</li>
721 <li>{hidden_data} = required value somewhere inside the form</li>
722 <li>{captcha_question} = In plain text, the question</li>
723 <li>{captcha_answer} = The answer encoded and passed through form</li>
724 </ul>
725 <h5>Pagination variables</h5>
726 <ul>
727 <li>{previous_page} = previous page number (ex: &lt;a href="{previous_page}"&gt;)</li>
728 <li>{middle_pages} = middle pages, includes links already</li>
729 <li>{next_page} = next page number</li>
730 </ul>
731 </div>
732 </div>
733 <div class="topic">
734 <h3 id="preferences_ban_options">Ban options</h3>
735 <p>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.</p>
736 <p>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.</p>
737 <p>A list of valid IP addresses:</p>
739 <ul>
740 <li>127.0.0.7</li>
741 <li>192.168.0.1</li>
742 <li>601.923.334.20</li>
743 <li>208.113.134.19</li>
744 </ul>
745 </div>
747 <div class="topic">
748 <h3 id="preferences_rss_options">Rss/atom options</h3>
749 <p>RSS/ATOM options let you modify different aspects of rss and atom generation. These options are <strong>not</strong> overrideable in individual includes.</p>
750 </div>
752 <div class="topic">
753 <h3 id="preferences_integration_wizard">Integration wizard</h3>
754 <p>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 <code>$phpns['category']</code> and <code>$phpns['template']</code>.</p>
755 </div>
757 <div class="topic">
758 <h3 id="preferences_freeze">Freeze/cache management</h3>
759 <p>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.</p>
760 <p>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!</p>
762 <div class="topic">
763 <h4>How to activate</h4>
764 <p>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 <a href="#pre_include_variables">pre-include variables</a> in this textbox, and click continue.</p>
765 <p>You will be given a new pre-include variable, that will look something like this:</p>
767 <ul>
768 <li>$phpns['freeze_file'] = "inc/freeze/freeze.0c5f1062347d7885ba3c2dc534c2dc21.php";</li>
769 </ul>
771 <p>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!</p>
772 <h4>Notes:</h4>
774 <ul>
775 <li>Comments cannot be used in a frozen instance.</li>
776 <li>The full story will be immediately below the main article, without going to a specific article (like the <code>$phpns['always_show_full_story']</code> pre-include variable).</li>
777 <li>No new articles will be posted until the freeze-file pre-include variable is removed.</li>
778 </ul>
779 </div>
780 </div>
782 <div class="topic">
783 <h3 id="preferences_system_log">System log</h3>
784 <p>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.</p>
785 </div>
787 <div class="topic">
788 <h3 id="preferences_theme_management">Theme management</h3>
789 <p>Phpns uses a very easy theme system that will allow you to customize how the phpns administration panel looks.</p>
790 <p>Every theme has a theme directory, located in <code>/themes/{theme}/</code>. The theme file will have 3 required files:</p>
791 <ol>
792 <li><code>{theme}/theme.xml</code></li>
793 <li><code>{theme}/admin.tpl.php</code></li>
794 <li><code>{theme}/login.tpl.php</code></li>
795 </ol>
797 <div class="topic">
798 <h4>Creating a theme</h4>
799 <p>To start creating a theme with phpns, it is recommended to take a look at the default theme included with every phpns installation (<code>/themes/default/</code>). Check <a href="http://phpns.com/">phpns.com</a> for more help on creating theme.</p>
800 <div class="topic">
801 <h5>Theme replacement variables</h5>
802 <p>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:</p>
803 <h6>login.tpl.php</h6>
804 <ul>
805 <li>{content} = page content</li>
806 <li>{logo} = phpns logo</li>
807 <li>{version} = the phpns version installed</li>
808 <li>{current_page_name} = the page name</li>
809 <li>{head_data} = data that belongs in the &lt;head&gt; element/tag</li>
810 <li>{page_image} = the current page image</li>
811 </ul>
813 <h6>admin.tpl.php</h6>
814 <ul>
815 <li>{content} = page content</li>
816 <li>{username} = current user logged in</li>
817 <li>{version} = the phpns version installed</li>
818 <li>{current_page_name} = the page name</li>
819 <li>{head_data} = data that belongs in the &lt;head&gt; element/tag</li>
820 <li>{page_image} = the current page image</li>
821 </ul>
822 </div>
823 </div>
824 </div>
826 <div class="topic">
827 <h3 id="preferences_database_backup">Database backup</h3>
828 <p>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.</p>
830 <p>Restoring the database is easy. Just Click "Browse" next to the input field, and find the database file you previously backed up. <strong>This will delete/overwrite your current database, be careful!</strong></p>
831 </div>
833 <div class="topic">
834 <h3 id="preferences_wyiwyg_editor">WYSIWYG editor</h3>
835 <p>This preference page will allow you to turn TinyMCE (The WYSIWYG editor used for making articles on phpns, <code><a href="http://tinymce.moxiecode.com/">Website</a></code>, <code><a href="inc/js/tinymce/license.txt">License file</a></code>) 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).</p>
837 <div class="topic">
838 <h4>TinyMCE license file:</h4>
839 <p><textarea><?php include("inc/js/tinymce/license.txt"); ?></textarea></p>
840 </div>
842 <p>Phpns also uses CodePress (The Code editor used for editing templates on phpns, <code><a href="http://codepress.org">Website</a></code>, <code><a href="inc/js/codepress/license.txt">License file</a></code>) which currently cannot be turned on/off. This editor is disabled automatically with Opera browsers, due to incompatibility issues.</p>
844 <div class="topic">
845 <h4>CodePress license file:</h4>
846 <p><textarea><?php include("inc/js/codepress/license.txt"); ?></textarea></p>
847 </div>
849 <p><em>Many thanks to both of these projects and their communities, they have improved the functionality of phpns greatly!</em></p>
850 </div>
852 <div class="topic">
853 <h3 id="preferences_online_offline_options">Offline/online options</h3>
854 <p>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.</p>
855 </div>
857 <div class="topic">
858 <h3 id="preferences_timestamp_options">Timestamp options</h3>
859 <p>Timestamp options let you change how the <code>date()</code> function is formatted throughout the phpns administration panel. <em>Note: This does not affect any news generation on <code>shownews.php</code></em>.</p>
860 <p>You can learn more about the <code>date()</code> function at the <a href="http://php.net/date">php website</a>.</p>
861 </div>
863 <div class="topic">
864 <h3 id="preferences_delete_login_records">Delete login records</h3>
865 <p>Deletes all login records collected so far. Not recommended.</p>
866 </div>
868 <div class="topic">
869 <h3 id="preferences_rank_management">Rank management</h3>
870 <p>See <a href="#rank_management">rank management</a>.</p>
871 </div>
873 <div class="topic">
874 <h3 id="preferences_global_message">Global message</h3>
875 <p>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.</p>
876 </div>
877 </div>
879 <div class="topic">
880 <h2 id="conclusion">conclusion</h2>
881 <p>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:</p>
882 <ul>
883 <li>TinyMCE</li>
884 <li>CodePress</li>
885 </ul>
887 <p>If you have something to offer the project, please, don't hesitate to contact us!</p>
888 </div>
889 </div>
890 </body>
891 </html>