GNU Sovix

Tutorial

Content

1 Set up a website with Sovix

1.1 Basic setup

1.1.1 Copy a template

1.1.2 Decide copyright for the web page

1.1.3 Set configuration

1.1.4 Description of setting files

1.1.5 Secure Sovix

1.1.5.1 Enable SSL login

1.1.5.2 Granular previlegies

1.1.6 Share files with Sovix

1.1.7 Distribute software code under GNU AGPL or as private software

1.1.8 User Interface

1.1.8.1 Customize UI

1.1.8.2 Translate filenames in the select menu

1.1.9 Page index

1.1.10 Links

1.1.11 Web template engine

2 Learn how to use Sovix

2.1 Write and validate

2.1.1 Write semantically valid HTML and XHTML

2.1.2 Validate a webpage with different DTDs

2.2 Revise website

2.2.1 Log in and log out

2.2.2 Update files

2.2.3 View load time for page

25 sections

Basic setup

Copy a template

Copy /srv/d_dbe/www/www.sovix.org/htdocs/sovix/Templates/Default/ to DocumentRoot (/srv/d_dbe/www/www.sovix.org/htdocs/ in your current configuration) or to some other place. We will use DocumentRoot as example in this Tutorial since that is default.

Set proper base path that is used by different settings in /srv/d_dbe/www/www.sovix.org/htdocs/Default/include/dotsovix/files.inc;
Change $sovix__directory__base="$sovix__url__sovix/Templates/Default";
to $sovix__directory__base="$sovix__directory__document_root/Default";

Decide copyright for the web page

Go to http://sovix.org/Default/ in a web browser.

Do as the text in the page suggest. Verbatim copying and distribution is preferred to personal text while the GNU Free Documentation License is preferred to distribute text who anyone can copy, modify and redistribute. The GNU FDL is recommended for software manuals. We publish personal web documents that are not part of Sovix under verbatim copying but we use free documentation for documents that are part of Sovix as you can see at the footer of this page.

Open /srv/d_dbe/www/www.sovix.org/htdocs/Default/Main_page.php in your favorite text editor

Modify <year> <name of author> in the $sovix__copyright variable but do not remove any text about GNU Affero General Public License and do not remove $sovix__copyright_pointer until you have read “Distribute software code under GNU AGPL or as private software”.

Reload http://sovix.org/Default/Main_page.
Your “copyright” appears at the beginning of the file, at the bottom (called footer) of the web page and at the page source (view page source with your web browser).

Set configuration

Modify the variable that points to the configuration directory in Main_page.php;
Change $sovix__directory__dotsovix="";
to     $sovix__directory__dotsovix=$_SERVER['DOCUMENT_ROOT']."/Default/include/dotsovix";

Copy sovix/dotsovix/public.inc to your dotsovix directory and modify any settings that you wish not to be global and remove rest of the settings to let Sovix take care of them. For example, copy the line with sovix__array__public_variables__array__variable to your public.inc file and set it to a ISO-8859-1 if you wish to show Swedish characters with Sovix.

Set any variable before the header to override a variable set by the configuration files. The header line look like this: require_once "$sovix__directory__src/header.inc"; ?>

Description of setting files

• $sovix__directory__base: Base directory used by the configuration.
• $sovix__directory__document_root: Sovix uses this instead of PHP's predefined variable DOCUMENT_ROOT since the web server might not allow it. $sovix__directory__document_root: can be set to DOCUMENT_ROOT however.
• $sovix__directory__include: Intended directory for special files
• $sovix__directory__private: Private directory. All private setting files for Sovix should be located here.
• $sovix__directory__sovix: Sovix directory. Its the “internal Sovix site” to describe the program. It has tutorial, sandbox and more.
• $sovix__file__copyright_mod: Execute given file. The file is intended to give a link to the license in $sovix__page__copyright that can be seen at the web page.
• $sovix__file__footer_body: File to be included at the bottom of the web page above the copyright notice.
• $sovix__file__header: File to be included in the top of the header. It may be useful to point to a file with personal variables.
• $sovix__file__header_before_dtd: File to be included before the DTD tag.
• $sovix__file__header_body: File to be included at the header below the top bar.
• $sovix__file__header_bodytag_end: File to be included at the end of the body tag
• $sovix__file__header_dtd_end: File to be included at the end of the DTD tag
• $sovix__file__header_head: File to be included within <head> and </head> for custom purpose
• $sovix__file__header_html_end: File to be included at the end of the <html
• $sovix__file__icon: The icon file that represent the website that is typically showed in graphical web browsers.
• $sovix__file__personal: File with personal information related to the website.
• $sovix__file__public: File for settings
• $sovix__file__public__global: File for global settings
• $sovix__file__read_file: File that accepts which files should be readable and downloadable by the public.
• $sovix__file__select_menu_data: File that defines which directories and files types should be listed in the select menu.
• $sovix__file__select_menu_translate: File to translate filenames in the select menu.
• $sovix__file__translations: File that list available translations of the web page.
• $sovix__url__etc: URL to Sovix etc directory that contains images and relevant text files
• $sovix__url__sovix: URL to Sovix.
• $sovix__url__websrc: URL to Sovix directory that contains special files.

• $sovix__file__ip_block: File that lists blocked IP addresses
• $sovix__file__auth_sovix: File with authentication data
• $sovix__file__select_menu_ignore: File that defines which directories should not be listed in the select menu.
• $sovix__file__hits_unique: File that list unique hits. You can show the number of hits with the command “server-hits-uniqe”
• $sovix__file__log: Login history
• $sovix__file__private: Private settings that cannot be modified by public
• $sovix__file__rdbms: File with variables to connect to a PostgreSQL or MySQL. This file is used by the web template engine.
• $sovix__file__read_file_ignore: File that defines which files should not be readable and downloadable by the public

Secure Sovix

Enable SSL login

Set sovix__ssl_login to true in dotsovix/private/private.inc.php to execute a https request for logins with the command “login” or “Tools > Log in” from the menu bar. You need to configure Apache and PHP to use a SSL certificate in order to make this work.

Granular previlegies

Set usernames and passwords in the commented text in dotsovix/private/auth_sovix.inc.php and uncomment it.
. Regular users (other then root) can only update the system while root can do anything. Avoid to log in as root if you don't have to.

It is recommend to copy dotsovix/private/auth_sovix.inc.php to any location outside DOCUMENT_ROOT and set $sovix__file__auth_sovix to that location in dotsovix/private/files.inc.php by security.

Password

Example: $sovix__password="x".date("ymdHi");
NOTE! Do not use the example above since it does not contain a capital, special character or is not long enough to be secure enough. Use at least a 8 characters long password and create your own algoritm.

Allways use the command 'server-time' to get the the system date and time from the server that host Sovix.

Username

IP

Share files with Sovix

Sovix has a mechanism to read files as plain text and another to download them. This is very useful when you want to share a file that is otherwise parsed by the HTTP sever such as file with a .php extension.

The file /srv/d_dbe/www/www.sovix.org/htdocs/Default/include/dotsovix/read-file.inc is configured by default to instruct Sovix to read or download any file from $sovix__directory__base/ is you uncomment the array in the file. subdirectories that is listed in /srv/d_dbe/www/www.sovix.org/htdocs/Default/include/dotsovix/private/read-file-ignore.inc is used to exclude desired subdirectories.

Distribute software code under GNU AGPL or as private software

User who is in charge of a website typically keep the software code that generates the website as private software. That user keeps it and uses it, and does not release it to the public either as source code or as binaries. This makes it impossible for the visitors to contribute to the software code and learn. We distribute files at Sovix website under GNU AGPL; Anyone can read the software code as plain text by downloading it or view it direct from the web browser. Both you and us have been benefited with this many a time. We can for example read how Sovix is configured with the current release if there is something we need to do backward-compatible in our development version. And you can learn how to configure Sovix when you are in trouble.

Files in $sovix__directory__sovix are readable over network by default since Sovix is distributed under GNU Affero General Public License. You can for example read sovix/Sovix.php by execute 'read-file /srv/d_dbe/www/www.sovix.org/htdocs/sovix/Sovix.php' in the command line. Files in subdirectories of $sovix__directory__sovix named 'private' are not readable by default since they contain sensitive data such as passwords etc.

We are convinced that we can push the web to adapt this concept by demonstrating the usability from Sovix. You can help us doing this by adopting this mechanism for your website. The PHP Group advocates this at php.net, see the footer of any page at php.net where you can view the software code.

Distribute software code under GNU AGPL

1. Make sure Sovix shares the files, see “Share files with Sovix” for how to do that.
2. Leave the commented GNU AGPL notice that appears at the top of Main_page.php.

Distribute software code as private software

1. Remove the GNU AGPL notice that appears at the top of Main_page.php.

User Interface

Customize UI

Sovix has all elements visible by default to make it as user friendly as possible so change these settings to suit your needs.
You can find the settings in dotsovix/public.inc.

• Screen mode: $sovix__screen_mode. This is set to “normal” by default which means that these user interfaces are configured, they are also visible by default:
  • “Window” border: $sovix__window_border_mode
  • Menu bar: $sovix__menu_bar_mode
  • Tool bar: $sovix__tool_bar_mode
  • Top select menu: $sovix__select_menu_header_mode
  • Side pane: $sovix__menu__side_pane_mode
  • Bottom select menu: $sovix__select_menu_footer_mode
  • Command line: $sovix__command_line_mode

Note that you need the command line to perform commands with Sovix. So if you hide it you wont be able to update your configuration files from Sovix.

Translate filenames in the select menu

1. Copy http://sovix.org/sovix/copy/select-menu-translate.inc to your dotsovix directory
2. Change $sovix__file__select_menu_translate=""; to $sovix__file__select_menu_translate="$sovix__directory__dotsovix/select-menu-translate.inc";
3. Modify the search and replace arrays in /srv/d_dbe/www/www.sovix.org/htdocs/Default/include/dotsovix/select-menu-translate.inc.

Page index

Page index can be showed in different modes

1. In normal mode the page index links to a section at the page and that section links back to the page index. This is presented in (X)HTML.
2. The link sections placed at the page can be text without a link to the page index. This is useful when you do not use the page index since you can convert it to be a link that points to the page index any time by removing the $sovix__toc_index__hide_link. Example: <?php sovix__toc_index__base($sovix__toc_index__base="Name of topic or headline", $sovix__toc_index__hide_link="y"); ?>
3. “File > Format as text” at the menu bar or “format-txt” presents the whole page index and its links as plain text

Links

This is how it looks

Web template engine

• Modify database, username and password in /srv/d_dbe/www/www.sovix.org/htdocs/Default/include/dotsovix/private/rdbms.inc.php to be able to connect to the database
• Copy the text in http://sovix.org/sovix/copy/RDBMS.inc to an existing file used by Sovix such as Main_page.php.
• Modify http://sovix.org/sovix/copy/RDBMS.inc

• $sovix__wte__rdbms: The name of the database. Possible values = PostgreSQL, MySQL.
• $sovix__wte__rdbms__rdbms__host_address: The host address of the specified RDBMS. Use 127.0.0.1 for localhost.
• $sovix__wte__rdbms__port: The port of the RDBMS. This is usally 5432 for PostgreSQL 8.1 and 3306 for MySQL 4.1.
• $sovix__wte__rdbms__username: The username for the RDBMS
• $sovix__wte__rdbms__password: The password for the RDBMS
• $sovix__wte__rdbms__database: The database name used by the RDBMS
• $sovix__wte__rdbms__table: The database table used by the RDBMS
• $sovix__wte__query_free: Extra query used to define conditions for example
• $sovix__wte__order_by: Defines which row that should be sorted
• $sovix__wte__main_table: Set to file if you want custom layout
• $sovix__wte__highlight_boolean: Shows green color for 'Yes' and red color for 'No'. Possible values = y, n

Lets decribe how the arrays used by the web template engine work

• sovix__array__wte__column': The name of the column selected from the database table
• sovix__array__wte__topic': The topic that you want to show for the column at the web page
• sovix__array__wte__dbtype': Defines the data type the column is. This is needed to be able to update the column to the database when you are logged in. Possible values = date, time, id, varchar, char, integer, text, boolean
• sovix__array__wte__value': Used for booleans to set a default value if they have no values. Possible values = 't' (PosgreSQL) or '1' (MySQL)
• sovix__array__wte__private': Only display the data if you are logged in. Possible values = y, n
• sovix__array__wte__give_topic': Enable topic. Note that private must be set to n if you want to make it public. Possible values = y, n
• sovix__array__wte__showcontent': Show what showcontent is set at instead of the text provided by the column. Value "y" is the same as leaving it empty
• sovix__array__wte__require_value': Require a value when you want to update the column when you are logged in
• sovix__array__wte__beg': Start a text before the text in the column. This is used to customize the layout
• sovix__array__wte__beg_link': Set what the 'link' should start with
• sovix__array__wte__link': Set the value provided by the column in a link
• sovix__array__wte__end_link': Set what the 'link' should start with
• sovix__array__wte__end': End with this text after the text in the column. This is used to customize the layout

Write and validate

Write semantical valid HTML and XHTML

Validate a webpage with different DTDs

Log in and log out

You need to log in to perform operator activities like updating text in files. Such actities are gray in the menu bar and begin with two lines (--) in the completion list (execute “?” in the command line to see them).

Log in

Log out

Update files

View load time for page