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

Documentation Posted by raoul on Apr 1st 2013, 15:34; Edited by raoul on Oct 14th 2018, 18:45

  1. Overview
  2. Installation
  3. Languages
  4. Templates
    1. Caching of pages and {CACHE:x} variable
    2. RSS feeds and {*_FEED:x:y:z} 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. Sessions validity
    42. Site name
    43. Site URL
    44. Stories expiry
    45. Stories per page
    46. Template
    47. Threads expiry
    48. Threads per page
    49. Users order
    50. Users per page
    51. Allow users registration
    52. Users sorting
    53. Votes interval
    54. YouTube default dimensions
    55. YouTube controls
    56. YouTube related
    57. YouTube showinfo


  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 web server 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 web server
    - 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:z} variables

      Six reserved variables are available for internal 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.

      Another reserved variable is available for external RSS feeds (since Gnew 2018.2):

      {URL_FEED}

      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
      {URL_FEED:-:10:http://rss.slashdot.org/Slashdot/slashdotMain} will display the last 10 news from Slashdot website 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 web server, 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 web server 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 during which an incomplete user account (e-mail address not confirmed) will remain in the database. See also the purge users section. A value between 1 and 999.

    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. A value between 1 and 99.

    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. A value between 1 and 99.

    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. A value between 1 and 60.

    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. A value between 1 and 99.

    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 during which cookies, set by the website, will remain stored in the users browser. A value between 1 and 999.

    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 web server location (where Gnew is installed), if any. It can be a negative or a positive value. A value between -14 and 14.

    17. Headlines per feed

      The number of items displayed in RSS feeds. A value between 1 and 99.

    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. A value between 1 and 999.

    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. A value between 1 and 99.

    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. A value between 1 and 99999.

    22. Min length of passwords

      The minimum number of characters allowed in the password of users. A value between 1 and 99.

    23. Min length of usernames

      The minimum number of characters allowed in the name of users. A value between 1 and 99.

    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. A value between 1 and 99.

    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. A value between 1 and 99.

    31. Posts interval

      The number of seconds to wait before allowing a user to add a new post. A value between 1 and 60.

    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. A value between 1 and 99.

    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. A value between 1 and 99.

    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. A value between 1 and 99.

    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. Sessions validity

      The number of minutes during which sessions, set by the website, will remain valid in the users browser. Sessions are automatically regenerated during these minutes if an activity is detected. A value between 1 and 60.

      Caution:

      The value of Sessions validity should always be higher than the value of any {CACHE:x} variable that have been set in templates files.


    42. Site name

      The website name/title.

    43. Site URL

      The website URL.

    44. 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. A value between 1 and 999.

    45. Stories per page

      The number of stories displayed per page. A value between 1 and 99.

    46. Template

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

    47. 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. A value between 1 and 999.

    48. Threads per page

      The number of threads displayed per page. A value between 1 and 99.

    49. Users order

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

    50. Users per page

      The number of users displayed per page. A value between 1 and 99.

    51. Allow users registration

      Enabling or disabling users registration.

    52. Users sorting

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

    53. Votes interval

      The number of days to wait before allowing a user to add a new vote. A value between 1 and 999.

    54. YouTube default dimensions

      The number of pixels for the default height and width of the YouTube video player. Two values between 10 and 9999.

    55. YouTube controls

      Enabling or disabling YouTube video player controls.

    56. YouTube related

      Enabling or disabling suggested videos when the YouTube video finishes.

    57. YouTube showinfo

      Enabling or disabling video title and actions in YouTube video player.


Thanks for using Gnew and please report any bug.