PT News - Plain Text files News
================================


INSTALL
==========

1./ Get system archive:
    http://worldzone.net/computers/sto/news/ptnews-x.y.zip
    x.y is the number of current version 
2./ Unzip archive in some directory:
    unzip ptnews-x.y.zip
    The zip file contain the following files:
    - news.inc - news system engine
    - admin.inc - administrator functions (NEW in v1.7.8)
    - index.php - sample file for displaying news
    - news.php - sample file for displaying news details
    - auth.php - password protection support (NEW in v1.7)
    - admin.php - sample admin file
    - wap.php - sample WAP news file (NEW in v1.6)
    - search.php - sample search news file (NEW in v1.7)
    - README.txt - short description of system
    - INSTALL.txt - detailed instructions for installation and usage
    - images directory with one file for each topic. (NEW in v1.6)
    - themes directory with themes (NEW in v1.7)
    
3./ Edit news.inc:
    - $config array: names of news and admin pages, news directory name, 
                     news in one page limit

    *** WARNING: ***
      If news.php and admin.php pages are in different directories
      you need to input $config[newsdir], $config[imgdir] and
      $config[themedir] AS ABSOLUTE PATHS
      !!! From v1.7.4 $config[newsdir] not exists. $newsdir is defined
      in the php files.
       
    - $RSS array: name of RSS file, name of news site, URL to news
    - $topics array: news topics for this site
    - $lang array: language setting (NEW in v1.5)
    - $sconfig array: search box and search results properties
    
4./ Prepare directory for news files. Web server must have write permitions
    for this directory. For example:
    $ mkdir news
    $ chmod 777 news
    
5./ Uncompress archive in this directory

6./ Change path to news.inc file in index.php, news.php

7./ Change path to admin.inc in admin.php file

8./ Edit theme files for your needs. Supported tags are: 
    #DATE#, #TITLE#, #TOPIC#, #CONTENT#, #TOPICIMG#(NEW in v1.6), 

    #TOPICLNK#(NEW in v1.6), #TITLELNK#(NEW in v1.7), #ABSTRACT#(NEW in v1.7),

    #FSIZE#(NEW in v1.7)


USAGE
==========

* Display news: support for [more...], topic and << 1 2 ... >>

include ("/path/to/news.inc");
if (!isset($pageNum)) $pageNum = 1;
if (!isset($topic)) { 
   $topic="";
} else { 
   $topic="topic=$topic"; 
}
// !!! New for v1.7.4. See trailing slash
if (!isset($newsdir)) $newsdir = "/path/to/news/";

if (isset($detail)) {
   displayNewsEntry($newsdir.$detail, "theme.inc", "yes");
} else {
   displayNews($newsdir,$topic,"theme.inc", $pageNum);
}

With code above you can pass topic as argument and display short story+
[more...] link for full story
For example: http://my.news.com/news.php?topic=general


* Administration - create, edit, delete news:

if(!isset($topic)) $topic="";
include ("/path/to/admin.inc");  // admin.inc is new in v1.7.8
$mode="full";
displayNewsAdmin($newsdir,"admtheme.inc",$mode);


* If you have ONLY ONE DIRECTORY on web server:
  - put everithing in it
  - change permitions to 777
  - in news.inc: 
    $RSS[rssfile]="./filename.rss";
  - before call to displayNews(), define $newsdir="./";


* News without paging (all news on one page): 
  In news.inc set $config[pglimit] to some big number for example: 
  $config[pglimit] = 10000;

  
* News without topics: do not pass topic argument when refer to the news.php
  http://my.news.com/news.php
  This will display all news

  
* Images for topics (NEW in v1.6):
   In $config array (news.inc) imgdir need to point images directory. For each
   topic the name of file must be the same as array index. For example:
   general - general.gif
   ptnews - ptnews.gif
   Now just put #TOPICIMG# tag somewhere in theme file.
   In $config[imgattr] member you can add additional attributes for images


* One page with news header and different page for detail ( click on [more...]
  go to new page )
  - in news header file ( for example index.php ):
  displayNews($newsdir,$topic,"theme.inc", $pageNum);
  - in details file ( for example news.php ):
  if (isset($detail)) {
      displayNewsEntry($newsdir.$detail, "theme.inc", "yes");
  } else {
      echo "Nothing to do<br>\n";
  }
  And also in news.inc: $config[mainpg]="index.php", $config[morepg] = "news.php", 
  so link in [more...] to point to details file

  
* Support for themes (CHANGED in v1.7):
  Now all pages are theme driven - news page, admin page, search page. In 
  distribution all themes are in themes/ dir. If your put them in other place 
  please change $config[themedir] parameter.


* Support for other #tags# in theme file (CHANGED in v1.7):
  In v1.7 tags replace engine is rewritten from scratch. Now it is easier to implement
  your own tags. Just write new function with format:
  string mod_<lower_case_tag_name>($story, $fn, $detail)
  where,
     - $story is story information array - Title, Text etc.
     - $fn - full path to story file (directory+filename) (from v1.7.4)
     - $detail - extra parameters
  It is possible to use only some of parameters. 
  
  *** Here is example for #AUTHOR# custom ***
  tag:
     - in theme file - #AUTHOR#
     - some changes in createNewsEntry(), editNewsEntry() and displayNewsAdmin() 
       functions:
       * createNewsEntry() - save author data in file
          fwrite($fp, "Author::".htmlentities(stripslashes($author))."\n");
       * displayNewsAdmin() - add author textbox
          <INPUT type="text" NAME="author" size="40" VALUE=""><BR>
       * editNewsEntry() - add author textbox
          <INPUT type="text" NAME="author" size="40" VALUE="'.$story[Author].'"><BR>
     - and this is mod_... function:
       
       function mod_author($story) {
          return $story[Author];
       }
       
  Function can be more complicated. For example #TITLELNK# tag support:
     function mod_titlelnk($story,$dr_fn) {
        global $config;
        $fn = basename($dr_fn);  // new for v1.7.4
        $title_link="<a href=\"$config[morepg]?detail=$fn\">$story[Title]</a>";
        return $title_link;
     }
  
  With new schema is very easy to change the format of tags. In function
  displayNewsEntry() have line:
  preg_match_all("/#(.*)#/U",......
  This is for tags with format #...#. Now for example for tags {{....}} just
  change this line to:
  preg_match_all("/{{(.*)}}/U",......

       
* Support for other languages:
  Change $lang members to appropriate values


* Support for timezones (NEW in v1.7):
  If you want dates in news to belong to some timezone (if server with your news pages
  is in different timezone from your news readers) just put the name of time zone in 
  the $config[tzname]. For example:
  
  $config=array(
  ...
  tzname   => "Japan Standard, USSR Zone 8",
  ...);


* Password protection for admin page (NEW in v1.7):
  It is realised by include auth.php page. That's all ;0) Admin username and 
  password, also time for its expiring are in the auth.php DEFINE expresions. 
  If you want to protect your admin page in other way (directory protect with 
  .htaccess etc.) just remove PHP code before <HTML> tag in admin.php. Default
  distribution user/pass are ptnews/ptnews
  
  
* Search news (NEW in v1.7):
  - Search news text box for enter keywords - put on some page:
    <? searchBox(); ?>   // Simple ah? ;0)
    You can customize the look of search box with $sconfig array:
    * $sconfig[action] - page that process query - it can be different from index.php
      or the same. Try the both with distribution files.
    * $sconfig[theme] - output format for each found file - stheme.inc in distrib
    * $sconfig[method] - "GET" or "POST" - both are supported ;0)
    * $sconfig[size] - size of textbox control
    * $sconfig[button] - "yes" or "no" - do you have [search] button near the textbox
      or single textbox only. Work in both cases
    * $lang[srch_submit] - title of search button if present
    * $lang[srch_total], $lang[srch_disp] - messages in search result
    * $lang[srch_zero] - if news not found 
    The search results are paged << 1 2 3...>> with $config[pglimit] entries on one 
    page
  
  - Query processing page. You can use index.php (news display page). It has search
    support embedded. Or you can use different search page (search.php in distrib).
    For example:
    <?
       // Just to be sure that every param is defined ;0)
       if (!isset($pageNum)) $pageNum = 1;
       if (!isset($topic)) { 
          $topic="";
       } else { 
          $topic="topic=$topic"; 
       }
       $newsdir = "news/";
    
       // Search news
       include ("news.inc");
       
       if (isset($querybox)) $q=$querybox;
       else if (isset($HTTP_POST_VARS[querybox])) 
               $q=$HTTP_POST_VARS[querybox];
       else $q="";
       if ($q!="")
          searchNews($newsdir,$topic,$querybox,$pageNum);
   ?>

KNOWN BUGS
================
* When reload admin page there is unexpected results. Maybe because
  browser cache the page?

TODO
================
I'm already not working actively on 1.7.x tree. The future is 2.x
  
  
That's all story
Enjoy ;0)
  
Stoyan Jekov <sto@{NO_SPAM}openbg.net>
// Remove {NO_SPAM} from the email address
