The display width of the device is not suitable for displaying this website.
Please turn your mobile phone into landscape mode.
Gnew

Documentation Posted by raoul on Apr 1st 2013, 15:34; Edited by raoul on Feb 11th 2017, 7:46

  1. Overview
  2. Installation
  3. Languages
  4. Templates
    1. Caching of pages and {CACHE:x} variable
    2. RSS feeds and {*_FEED:x:y} variables
  5. Can I have a website that looks like what I want?
  6. Can I add menu blocks?
  7. Can I add personal pages?
  8. Is it possible to delete my comments?
  9. Is it possible to delete my posts?
  10. How to hide a comment?
  11. How to close a post or create a sticky one?
  12. What are these purge links in the advanced admin section?
  13. Apache, PHP and databases settings
    1. Suhosin
    2. Security
    3. Cookies
    4. post_max_size and upload_max_filesize
    5. Garbage collection and sessions
    6. PostgreSQL and backslashes
    7. MySQL column can't have a default value
  14. Settings
    1. Accounts expiry
    2. Allow emoticons
    3. Allow HTML
    4. Articles order
    5. Articles per page
    6. Articles sorting
    7. Categories order
    8. Categories per page
    9. Categories sorting
    10. Comments interval
    11. Comments order
    12. Comments per page
    13. Comments sorting
    14. Cookies expiry
    15. Date format
    16. Date offset
    17. Headlines per feed
    18. Language
    19. Max pixels of avatars
    20. Max submissions per user
    21. Max length of texts
    22. Min length of passwords
    23. Min length of usernames
    24. Allow comments in news
    25. News order
    26. News per page
    27. Allow news sending
    28. News sorting
    29. Allow news submitting
    30. Pages limit
    31. Posts interval
    32. Posts order
    33. Posts per page
    34. Posts sorting
    35. Questions order
    36. Questions per page
    37. Questions sorting
    38. Search limit
    39. Sender e-mail
    40. Sender name
    41. Site name
    42. Site URL
    43. Stories expiry
    44. Stories per page
    45. Template
    46. Threads expiry
    47. Threads per page
    48. Users order
    49. Users per page
    50. Allow users registration
    51. Users sorting
    52. Votes interval


  1. Overview

    Gnew is a simple Content Management System (CMS) written with the PHP language and using a database server (MySQL or PostgreSQL or SQLite) for storage. It is fully customizable since it uses a templates system and supports multiple languages.

    Gnew is an open-source software distributed under the terms of the GNU GPL license version 3.

    Main features:

    - Easy installation
    - Multi-languages interface
    - Full customization with templates
    - Simple but complete administration section
    - Multi-levels categories
    - Articles management
    - News management with an advanced comments system
    - Polls management
    - Users management
    - Forum
    - Search engine
    - RSS feeds generation
    - BBCode tags and HTML tags support
    - Emoticons support
    - And more...

    Requirements:

    - A webserver or a web hosting account
    - PHP 5.6 or higher (with mail() function and GD library enabled, preferably)
    - A MySQL database (5.5 or higher) or a PostgreSQL database (9.2 or higher) or SQLite 3 database support in PHP

  2. Installation

    See the readme.txt file. It is as simple as:

    - copying/uploading the files to the webserver
    - visiting the install/index.php location
    - filling in the informations about the database server and the administrator

    This can be done in less than 5 minutes.

  3. Languages

    Gnew is provided with several language files. These files are located in the languages/ directory. They consist of an array containing predefined variables and their replacement strings. Each language file contains the same predefined variables where only replacement strings are translated. Example:

    Code:1// in english.php file:
    2
    'JANUARY' => 'January',
    3
    4
    // in french.php file:
    5
    'JANUARY' => 'Janvier',


    It is possible to add more variables to this array but take care to not use already assigned variable names.

    If you are interested in creating and/or maintaining one language file, please contact us at webmaster at gnew dot xyz. Thanks in advance.

  4. Templates

    A simple template class allows to keep HTML code in external files (.htpl extension) which are completely free of PHP code. These files are located in the templates/ directory and its subdirectories. They contain predefined variables (see the list in the templates/variables.txt file) substituted when the PHP code is interpreted. These variables can be various types: a portion of HTML code, a string, a function...

    Temporary variables have been added [ Note: disabled for the moment ] to store forms data when an error occurs during submissions. These variables are defined as follows: {_variable_} (see the list in the templates/temporary_variables.txt file). The main differences with other template variables are the underscores and the lowercase.

    The template class has the following features: substitution of variables and blocks (recursive or not). Below, the documentation about the class:

    Code:1// Include the class file
    2// template.php is located in the includes/ directory
    3
    include('./includes/template.php');
    4
    5
    // To create a $template object and set the root directory where the template
    6// files are stored
    7
    $template = new template($root);
    8
    9
    // Example:
    10
    $template = new template('./templates/clean');
    11
    12
    13
    // To set a template file (paths are relative to root)
    14
    set_file($name, $file);
    15
    16
    // Example:
    17
    set_file('index', 'news/index.htpl');
    18
    19
    20
    // To set a variable in a block or a file
    21
    set_var($name, $value = '');
    22
    23
    // Example with a single variable:
    24
    set_var('PAGE_TITLE', 'News - Index');
    25
    26
    // Example with an array of variables:
    27
    set_var(array('PAGE_TITLE' => 'News - Index',
    28
                  'SITE_NAME' => 'Gnew'));
    29
    30
    31
    // To set a block in a parent file
    32
    set_block($parent, $name, $block);
    33
    34
    // Example with the previous file:
    35
    $template->set_block('index', 'NEWS_BLOCK', 'news');
    36
    37
    38
    // To substitute the values of variables in a block or in a file
    39
    parse($name, $block = '', $loop = false, $related_tables = null);
    40
    41
    // Example with the previous block:
    42
    parse('NEWS_BLOCK', 'news', true);
    43
    44
    // Example with the previous file:
    45
    parse('index');


    Then, these variables (or blocks) can be used in template files:

    Code:1// A template variable must be used between braces
    2
    {variable}
    3
    4
    // Example:
    5
    {PAGE_TITLE}
    6
    7
    8
    // A variable in a block
    9
    <!-- BEGIN block -->
    10{
    variable}
    11<!--
     END block -->
    12
    13
    // Example:
    14
    <!-- BEGIN NEWS_BLOCK -->
    15{
    NEWS_SUBJECT}
    16<!--
     END NEWS_BLOCK -->


    1. Caching of pages and {CACHE:x} variable

      To avoid processing the same data several times, caching of pages for high-traffic websites can be useful. How it works? In the templates files (.htpl), located in the templates/ directory and its subdirectories, add the reserved variable {CACHE:x} where x being the time during which the page will be cached. This template variable can be placed wherever you want in the templates files.

      x should be an integer from 1 to 5 digits

      x alone is a time in seconds
      xM is a time in minutes
      xH is a time in hours
      xD is a time in days

      M, H and D should be capitalized

      Example:

      You want to cache the news index page? Add in templates/*/news/index.htpl file (* = clean and/or your personal templates directories):

      {CACHE:60} and the page will be cached for 60 seconds
      or
      {CACHE:1M} an equivalent of the above but in minutes.

      The first time the page will be visited it will be cached for 1 minute. Then, the cache file will be sent to visitors until its expiration. After expiration, the page will be cached once visited again. And so on.

      Caution:

      It's not necessary to cache header.htpl and footer.htpl files since they are automatically included in other pages.
      It's not advisable to cache error.htpl, success.htpl and users/register.htpl files because they will display dynamic contents necessary for proper functioning of Gnew (various messages, CAPTCHA image...).


      Some results using the Apache HTTP server benchmarking tool (ab) with the following command:

      Code:ab -c 50 --n 1000 -"Accept-Encoding: gzip" URL

      to check how the server can handle 1000 requests with 50 requests running concurrently on URL. URL is an index page displaying 10 news per page. All news are cutted because their length is above 1000 characters (default setting) and the database was filled with 1000 identical news.

      Without caching of pages:

      http://www.gnew.xyz/medias/images/documentation_cache_1_t.png

      With caching of pages:

      http://www.gnew.xyz/medias/images/documentation_cache_2_t.png

      You can see that with caching of pages, and in this case, the gain is around 53% meaning that the same 1000 requests were handled with 53% less time. Please note that the gain will depend on the page being cached and its content.

    2. RSS feeds and {*_FEED:x:y} variables

      Six reserved variables are available for RSS feeds:

      {ARTICLES_FEED}
      {COMMENTS_FEED}
      {NEWS_FEED}
      {POLLS_FEED}
      {POSTS_FEED}
      {USERS_FEED}
      (since Gnew 2016.2)

      Each of these variables will display a list of the last articles or comments or news or polls or posts or users added to the database.

      The number of items displayed in these lists is, by default, defined by the headlines per feed setting. But you can also set a lower limit (lower than the previous setting) directly inside a feed variable. Even the bullets displayed in these lists can be set within these variables. These 2 parameters can be differents, set or not set, from one variable to another.

      Example:

      {NEWS_FEED} will display the last news defined by the headlines per feed setting with no bullet
      {NEWS_FEED:*} will display the last news defined by the headlines per feed setting with the * bullet prefixing the items
      {NEWS_FEED:5} will display the last 5 news with no bullet
      {NEWS_FEED:*:5} will display the last 5 news using the * bullet

      The bullet parameter must always by defined before the limit parameter if the 2 parameters are set in the variables. Bullets allowed are * (asterisk), - (hyphen), . (dot), o (lower O), · (middot) and (bullet).


  5. Can I have a website that looks like what I want?

    Yes. Simply edit template files (.htpl) and the stylesheet (.css) located in the templates/ directory. By default, Gnew uses (X)HTML 5 and CSS 3 languages but you can use other versions if you want.

    You can also create your own layout/template and then use the predefined templates variables as you want.

  6. Can I add menu blocks?

    Yes. Simply edit template files, usually header.htpl or footer.htpl. It depends on if you are using default templates provided with Gnew or your own layout/template. In the last case, you should know better than us how to add menu blocks ;-) .

    Below, an example of code to add a menu block to the clean template (between <aside> tags in the footer.htpl file):

    Code:1<nav>
    2
      <header>Menu title</header>
    3
      <ul>
    4
        <li><a href="/path/to/first_link" title="First link">First link</a></li>
    5
        <li><a href="/path/to/second_link" title="Second link">Second link</a></li>
    6
        <li><a href="/path/to/third_link" title="Third link">Third link</a></li>
    7
      </ul>
    8</
    nav>


  7. Can I add personal pages?

    Yes. You can use the articles section to do so. Or you can also use the following method that allows you to use the PHP language and its capabilities if needed.

    Below, an example of code to generate a simple page with basic use of PHP. A PHP file named test.php is placed in the WHERE_GNEW_IS_INSTALLED/pages/ directory of your webserver, for example:

    Code:1// Include required file
    2// common.php is located in the includes/ directory
    3
    include('./../includes/common.php');
    4
    5
    // Display page header (content of the header.htpl file)
    6// 'Test' will be the title of the page following the site name
    7// Example: Gnew - Test
    8
    page_header('Test');
    9
    10
    // Set the template file
    11
    $template->set_file('test', 'pages/test.htpl');
    12
    13
    // Example with an array of template variables
    14
    $current_time = date('l jS \of F Y h:i:s A');
    15
    $template->set_var(array('CURRENT_TIME' => $current_time,
    16
                             'TIMESTAMP' => time()));
    17
    18
    // Substitute the values of variables and display them in the template file
    19
    $template->parse('test');
    20
    21
    // Display page footer (content of the footer.htpl file)
    22
    page_footer();


    A template file named test.htpl is placed in the WHERE_GNEW_IS_INSTALLED/templates/clean/pages/ directory, if you are using the clean template. Its content:

    Code:1<p>My test page</p>
    2<
    p>The Unix timestamp is {TIMESTAMP} and the formatted local time is {CURRENT_TIME}.</p>
    3<
    footer><a href="./../index.php" title="{BACK_HOME}">{BACK_HOME}</a></footer>


    Also remember that this way you still have the possibility to use the multiple languages feature. In the previous example, the {BACK_HOME} variable is part of languages files and provides a translated string.

    Take a look at Gnew code for more examples :-) .

  8. Is it possible to delete my comments?

    No. You can only edit them. Only administrators can hide or delete comments.

  9. Is it possible to delete my posts?

    No. You can only edit the text of your posts. Only administrators can delete posts, edit their subjects and more... (see below)

  10. How to hide a comment?

    Only administrators can hide comments. When editing a comment, directly from the Edit link of the comment itself, the following option appears:

    http://www.gnew.xyz/medias/images/documentation_hide_comment.png

  11. How to close a post or create a sticky one?

    These possibilities are reserved to administrators. When editing a post, directly from the Edit link of the post itself, the following options appear:

    http://www.gnew.xyz/medias/images/documentation_closed_sticky.png

  12. What are these purge links in the advanced admin section?

    The Purge cache files link is a way to remove all the cache files from the cache/ directory and to clean the cache database file (cache/cache.db). Useful when pages visited with invalid query strings (by suspicious visitors...) have been cached.

    The Purge users link is a way to remove from the database the users who have registered but have not activated their accounts then (invalid e-mail addresses, for example). See also the accounts expiry setting.

  13. Apache, PHP and databases settings

    Make sure to read the following if you get in trouble with Gnew.

    1. Suhosin

      If your webserver is running with Suhosin (http://www.hardened-php.net/suhosin/), make sure to disable sessions encryption.

      In the PHP configuration file php.ini or in the Suhosin configuration file suhosin.ini:

      Code:1[suhosin]
      2
      # Transparent Encryption Options
      3
      suhosin.session.encrypt = Off


      or in an Apache .htaccess file:

      Code:php_flag suhosin.session.encrypt Off

    2. Security

      Please, make sure to keep the file includes/config.php secured by using the Apache .htaccess file provided, containing:

      Code:1<Files "config.php">
      2
        Order Allow,Deny
      3  Deny from all
      4
      </Files>


      The includes/config.php file is the place where your database informations are stored.

    3. Cookies

      Lot of people are paranoid about cookies but Gnew don't store any private informations. Five cookies are used:

      - one that stores the session identifier (SID) for every users
      - four that store none-critical user preferences: date format, offset, language and template for logged users

      If cookies are not allowed on your computer, you won't be able to log in! Only the cookie storing the session ID is required for everything to work.

    4. post_max_size and upload_max_filesize

      The medias section in admin depends directly on these 2 directives of the PHP configuration. The post_max_size directive sets the max size of POST data and the upload_max_filesize directive sets the maximum size of an uploaded file.

      upload_max_filesize < post_max_size < memory_limit

      If you get in trouble when uploading files in the medias section, please check or set these directives depending on your needs.

    5. Garbage collection and sessions

      The garbage collection routine of PHP is started with a probability sets by session.gc_probability and session.gc_divisor in the PHP configuration file or using an Apache .htaccess file. Check the values of these 2 options and ensure that, at least, session.gc_probability is not set to 0. If set to 0, sessions data stored in the databases will never be cleaned (or you will need to do it manually).

      Default values are 1 for session.gc_probability and 100 for session.gc_divisor, meaning that there is a 1% chance that the garbage collection process starts.

    6. PostgreSQL and backslashes

      If you are getting strings with backslashes as I can\'t instead of I can't make sure that the value of standard_conforming_strings is Off in the PostgreSQL server configuration. Since PostgreSQL 9.1 this value defaults to On.

    7. MySQL column can't have a default value

      If you are getting an error during installation such as BLOB/TEXT column 'xxx' can't have a default value make sure that the value of sql_mode doesn't contain STRICT_TRANS_TABLES statement in the MySQL server configuration.

  14. Settings

    The following is a brief description of the settings encountered in the admin sections and their effects. Please contact us if you have any other questions.

    1. Accounts expiry

      The number of days an incomplete user account (e-mail address not confirmed) will remain in the database. See also the purge users section.

    2. Allow emoticons

      Enabling or disabling emoticons. Emoticons codes and their substitution images are defined in the advanced admin section.

    3. Allow HTML

      Enabling or disabling HTML language. Be careful with this setting since you will have to trust your users and their knowledge of the HTML syntax. Most of the time, BBcodes are enough for common uses.

    4. Articles order

      The way articles are ordered for display. This can be ascending or descending.

    5. Articles per page

      The number of articles displayed per page.

    6. Articles sorting

      The way articles are sorted for display. This can be by creation date, edition date or subject.

    7. Categories order

      The way categories are ordered for display. This can be ascending or descending.

    8. Categories per page

      The number of categories displayed per page.

    9. Categories sorting

      The way categories are sorted for display. This can be by creation date, edition date or name.

    10. Comments interval

      The number of seconds to wait before allowing a user to add a new comment.

    11. Comments order

      The way comments are ordered for display. This can be ascending or descending.

    12. Comments per page

      The number of comments displayed per page.

    13. Comments sorting

      The way comments are sorted for display. This can be by creation date, edition date or subject.

    14. Cookies expiry

      The number of days cookies, set by the website, will remain stored in the users browser.

    15. Date format

      The string used to format the date (see the PHP documentation). In doubt, leave the default value.

    16. Date offset

      The number of hours between your location and the webserver location (where Gnew is installed), if any. It can be a negative or a positive value.

    17. Headlines per feed

      The number of items displayed in RSS feeds.

    18. Language

      The default language of the website. You can also choose to only allow this language and no other for all users.

    19. Max pixels of avatars

      The maximum number of pixels allowed for height and width in the avatar of users.

    20. Max submissions per user

      The maximum number of news submissions allowed for registered users before that a moderator add them to the database or delete them.

    21. Max length of texts

      The maximum number of characters displayed before that the Read more link appears in a text. This applies to comments, news and posts.

    22. Min length of passwords

      The minimum number of characters allowed in the password of users.

    23. Min length of usernames

      The minimum number of characters allowed in the name of users.

    24. Allow comments in news

      Enabling or disabling comments in news.

    25. News order

      The way news are ordered for display. This can be ascending or descending.

    26. News per page

      The number of news displayed per page.

    27. Allow news sending

      Enabling or disabling news sending.

    28. News sorting

      The way news are sorted for display. This can be by creation date, edition date or subject.

    29. Allow news submitting

      Enabling or disabling news submissions.

    30. Pages limit

      The maximum number of pages displayed before that the + link appears in the pages list. This link will display the next pages.

    31. Posts interval

      The number of seconds to wait before allowing a user to add a new post.

    32. Posts order

      The way posts are ordered for display. This can be ascending or descending.

    33. Posts per page

      The number of posts displayed per page.

    34. Posts sorting

      The way posts are sorted for display. This can be by creation date or edition date.

    35. Questions order

      The way questions are ordered for display. This can be ascending or descending.

    36. Questions per page

      The number of questions displayed per page.

    37. Questions sorting

      The way questions are sorted for display. This can be by creation date, edition date or text.

    38. Search limit

      The maximum number of search results returned.

    39. Sender e-mail

      The e-mail address that will appear in every e-mail sent by the website.

    40. Sender name

      The name that will appear in every e-mail sent by the website.

    41. Site name

      The website name/title.

    42. Site URL

      The website URL.

    43. Stories expiry

      The number of days during which stories will remain active and registered users will be allowed to add or edit comments inside them.

    44. Stories per page

      The number of stories displayed per page.

    45. Template

      The default template of the website. You can also choose to allow only this template and no other for all users.

    46. Threads expiry

      The number of days during which threads will remain active and registered users will be allowed to add or edit posts inside them.

    47. Threads per page

      The number of threads displayed per page.

    48. Users order

      The way users are ordered for display. This can be ascending or descending.

    49. Users per page

      The number of users displayed per page.

    50. Allow users registration

      Enabling or disabling users registration.

    51. Users sorting

      The way users are sorted for display. This can be by creation date, edition date or name.

    52. Votes interval

      The number of days to wait before allowing a user to add a new vote.


Thanks for using Gnew and please report any bug.