Coranto - Installation to First News Item

This document provides a general overview of Coranto, installation instructions, and guides you through creating your first news item. I recommend you read it through completely before you begin with Coranto. This explains the simplest usage of Coranto with no addons. It is intended to get users started.

There are a lot of screen captures used in this document. I included these so that after you read this you will feel more comfortable when first using Coranto. The maximum width of any graphic used is 800 pixels.

Using this Document

If you are new to Coranto read this document through completely at least once. You can then follow along with it as you install Coranto. This is a long file with lots of pictures intended for inexperienced users.

Notes

Server side includes are not required but will increase the flexibility of your installation.

On Windows NT systems, the administrator may need to change permissions so that coranto.cgi can write to files in its directory. Or, more specifically: change the permissions on the Coranto directory so that IUSR_SERVERNAME has CHANGE access to it and the directory Coranto is running in has execute access in IIS. Contact your administrator if you are having permissions problems.

Coranto does not appear to work properly on MacOS 9 or lower systems (with MacPerl).

Coranto does not run on servers having mod_perl.

Installation

Important Considerations before you start

All files MUST be uploaded in ASCII not binary mode.

Some servers are set up to only allow execution of scripts in a specified directory. On Unix/Linux servers this is usually named cgi-bin. Check with your hosting provider to see if you have this limitation.

Some servers are set up so that you cannot use files in the cgi-bin or a sub-directory of the cgi-bin as includes when using SSI. This means that you must set up a directory outside of the cgi-bin for storage of the files that Coranto creates.

You must know the absolute paths to directories on your server. You may need to contact your hosting provider for this information.

Quick Install - Experienced Users

Already very experienced with Perl scripts? Then follow these instructions:

1. Copy all files into a world-writable directory that scripts can be executed from (CHMOD 755).
2. Make crcfg.dat, newsdat.txt, nsettings.cgi, and nsbk.cgi world-writable (CHMOD 666).
3. Make coranto.cgi and viewnews.cgi executable (CHMOD 755) and edit their Perl paths.
4. Launch coranto.cgi from browser.

You URL to your Coranto installation will look like one of these examples, depending on whether you install into Coranto into the cgi-bin or into it's own directory:

http://www.yourdomain.com/cgi-bin/coranto/coranto.cgi
http://www.yourdomain.com/coranto/coranto.cgi

If you have done the quick install and your installation is working OK (You can log into the new install and view the various menus) , you can skip the full installation directions below and read the INSIDE CORANTO section to get started.

If you have any problems, read the full instructions below.

Full Installation Instructions

• Step One

  Two files: coranto.cgi and viewnews.cgi, must have the perl path for your host set correctly. This is the first line of the file and often referred to as the shebang line. The default is:

  #!/usr/bin/perl

  and will work on most servers. Check with your host for the proper path.

  If you don't know the path to Perl 5 on your server, check your web host's support pages or contact your web host.

  For most users, this is all the text file editing that you have to do.

  IMPORTANT: Some servers also have Perl 4 installed, an older version, alongside Perl 5. If you have problems, make sure your paths are pointing to Perl 5.001 or higher, as Coranto will not work at all with Perl 4.

• Step Two

  Next, you should upload Coranto files to your server.

  Where you choose to put the Coranto files on your site depends somewhat on the web server. Many servers will allow you to put Coranto in any directory. Others will require that you use a special directory called cgi-bin . If there's a cgi-bin directory on your web server, you generally can't go wrong in using it. Though most servers no longer require that you use this directory, none will complain if you do. If you're running other CGI scripts, you may also choose to try cgi-bin/coranto to avoid cluttering the cgi-bin directory. The directory you use must have read, write and execute permissions (CHMOD 755).

  Once you've chosen a directory, FTP all Coranto files except for newsdat.txt to this directory IN ASCII MODE (not binary mode or auto-detect).

  IMPORTANT: If there's already a file called .htaccess in the directory you are uploading to, don't overwrite it with the version in the Coranto zip. Instead, you should copy the contents of the .htaccess file to the .htaccess file that already exists.

  The directory that you just uploaded files to is your Program Files directory. There is one other directory that Coranto needs to use, the News Files directory. The Program Files directory holds the CGI code that runs Coranto, the News Files directory will hold the HTML files that contain your site's news. If your Program Files directory was cgi-bin (or a subdirectory), then you should create a separate directory outside cgi-bin for your News Files directory. A directory called news beneath your main directory is generally a good choice. If your Program Files directory was not cgi-bin, then you can usually use the same directory as both your News Files and Program Files directory, though you can still choose to use an external directory to avoid clutter.

  Once you've chosen your News Files directory, upload newsdat.txt to that directory, in ASCII mode.

• Step Three

  The next step is to set file and directory permissions. On Unix/Linux this is done with the CHMOD command. You should be able to set the permissions using your FTP client.

  If your server runs the Windows NT/2000 operating system, you can skip this step. (You may need to ask your server administrator to make coranto.cgi and viewnews.cgi executable, and crcfg.dat, nsettings.cgi, nsbk.cgi, and newsdat.txt writable.) If you're not sure of which operating system your server runs, then chances are that it's a form of Unix, in which case you must CHMOD files.

  More About CHMOD - A Tutorial

  If you installed Coranto's cgi (program) files in a directory other than the cgi-bin (or your hosts specified cgi directory) you will have to set that program files directory to 755.

  First, CHMOD your News Files directory 777. (On a few servers, this may cause problems; if problems occur, try 755.)

  Next you must CHMOD certain Coranto files. newsdat.txt should be in the News Files directory, and all others should be in the Program Files directory.

  • coranto.cgi CHMOD 755 (or 777 if problems occur)
  • viewnews.cgi CHMOD 755 (or 777 if problems occur)
  • crcfg.dat CHMOD 666 (or 777 if problems occur)
  • nsbk.cgi CHMOD 666 (or 777 if problems occur)
  • newsdat.txt CHMOD 666 (or 777 if problems occur)

  There are several other files that are part of Coranto but they don't need any specific CHMOD values.

  If your ftp client does not allow setting permissions using the number you may have to set the permissions by checking boxes. There are three groups that permissions are set for; owner, group, other (or public or world).

  666 - all three groups have read and write permissions

  755 - Owner has read, write, execute permissions. Group and World have only read and execute permissions.

  777 - all three groups have read, write, and execute permissions.

• Step Four

  Now access coranto.cgi via your web browser. The URL to your Coranto installation will look like one of these examples, depending on whether you install into Coranto into the cgi-bin or into it's own directory:

  http://www.yourdomain.com/cgi-bin/coranto/coranto.cgi
http://www.yourdomain.com/coranto/coranto.cgi

  At the login screen:

  If everything has gone right to this point you should now see the first login screen:

  

  Enter "setup" (no quotes) as the username.
  Leave the password blank.
  Click the Log IN button.

You will now be looking at the initial welcome screen. The first prompt in setup asks if you agree to the Coranto License. Other setting are grayed out until you agree to the license.

Privacy and version check settings are next. Read the explanation of these settings and set them according to your preferences.

You will next have to specify the file paths you wish to use. You must enter absolute paths here, not URLs.

Coranto does a good job of figuring out the path to your install. This is a local test install and the path is:

I usually set the path for my news and archives outside of Coranto's install directory. I use:

How you set this up is your choice. Give it some thought before you install Coranto. The folders you choose must exist, Coranto will not create them. If you are going to use a news folder that is outside your Coranto install copy the 0 byte newsdat.txt file that directory and make sure that the permissions for the file ar 666.

Click on the Continue Setup Button and you will see:

On this page you will enter the login information for the first user. This user will be the super admin for the install until that setting is changed. I will use test/testing for this example but make sure that you use something more secure.

You will also be ask to enter an e-mail address. Read the information carefully about what this may be used for.

Language settings are available and can be set for each user later. For more information about the translations available see this discussion in the forums at coranto.gweilo.org.

Click on the Continue Setup Button and you are on the last setup page:

Here you enter the name of your site and the URL. The name will be displayed on Coranto's internal screens and the URL (if supplied) will be used to link to your site from Coranto's internal screens.

This is where you set the time options. Set the time zone to your local zone and put the time offset between you and the server. You can choose to use a 12 or 24 hour clock.

When you click on the Continue button you will see a message screen:

Here you are given information about resources that will help you manage your Coranto installation.

Click on the "Return to your Coranto installation" button and you will be taken back to the login screen. Enter the username and password you set and you can begin using Coranto.

INSIDE CORANTO

You now have Coranto installed and ready to use. Unlike other content management scripts there is no 'out of the box' generic page created by Coranto. Your site design is separate from the content management provided by Coranto. Before detailing basic usage it is helpful to understand the basics of how Coranto works.

At submission each newsitem is assigned to a specific category. (In a clean install of Coranto you only have access to the default category but the News Category addon is included in the distribution, ready for you to enable.) When Coranto goes through the full BUILD process that generates your content in a usable form, each newsitem in the database is read once and assigned to one or more PROFILES, depending on which CATEGORY the profile includes. Each Item that is included in that profile from the database is processed by the STYLE assigned and the result is wrapped in the TEMPLATE, if one is specified.

What follows is an very brief overview of the database file, Profiles, Styles, and Templates which are the building blocks of Coranto.

• The DATABASE - newsdat.txt

  This is a text file that holds every item that is submitted through the Coranto interface. Each time you make a submission with Coranto it becomes a line in the newdat.txt file. This file is Coranto's database. This file is used by Coranto and is not directly used by the end user.

• PROFILES

  Your content is managed using Profiles. Each profile is a collection of settings that determine what items are extracted from the database (newsdat.txt) and included in the usable output. The details of these settings will be discussed later.

  Each profile generates a text file that extracts items from the database. Which items from the database are included are determined by the Profile Settings. The items are formatted with a STYLE you specify in the Profile Settings. If you wish to generate static pages you can also specify a TEMPLATE in the Profile Settings.

• STYLES

  Coranto uses styles to format the data for presentation to your end users. Each profile has a style specified in the profile settings. For now the most important thing to remember about styles is that the style is applied to EACH item extracted from the database for the profile.

• TEMPLATES

  Think of Coranto templates as wrappers that placed around all of the items extracted from the database for a given profile. You use templates when you want to generate a static page.

  When Coranto goes through the BUILD process the database is processed once for each profile. Each Item that is included in that profile from the database is processed by the style assigned and the result is wrapped in the template, if one is specified.

MAIN SETTINGS

Before we get into usage we will review the main Coranto settings. Log into your Coranto installation. You will be at the Main Page.

Click on Administration

Then click on Change Settings.

File Paths

The first three settings are server paths for the various files Coranto uses and creates. The settings you entered at setup will be displayed here. You can make changes here if you want to change where Coranto stores files. Remember - old files and folders will not be deleted from your server by Coranto if you stop using them.

General Settings

Site Name

This is the name of your site. It is cosmetic and is only used on the Coranto administration pages.

Site Link

This is the URL of your site. If you wish to be able to jump to your site from inside Coranto fill this in.

Super Administrator

This is a drop down list of users. Only one can be super admin. Only the current Super Admin can change this setting.

Privacy Settings

Public or Private

This is a privacy setting. If you set it to PRIVATE access to some of Coranto's documentation will not be available. Setting this to PRIVATE disables the next two settings.

Version Check Image?

If you want notification of new versions turn this on. When on an image will be shown on Coranto's main page that shows the current version. This accesses the Coranto site to download the image.

Urgent Notification?

Set this to on if you want your e-mail to be added to a mailing list for news (bug fixes, new releases, etc.). Your email will not be sold or disclosed to a third party, nor will it be publicly viewable or used for any other purposes than those previously mentioned.

Miscellaneous Settings

Enable XHTML BR?

If you want your news to use <br /> instead of <br> set this to yes.

Modify News Link?

When you modify an item the default is to open the item in a new window. Set this to yes if you want the item opened in the current browser window.

Enable SQL?

This settings allows SQL-based addons such as CorantoSQL to work. At this time it is a kind of future proofing and is only used by the CorantoSQL addon, which has not been updated to work with the latest versions of Coranto. Leave it at the default setting for now. If you are using one of the addons that build a MySQL database consult the addon documentation for instructions on the proper setting.

DEBUG OPTIONS

Show Config?
Show Newsdat.txt?

Setting these two to yes will cause the config and newsdat files to be shown whenever there is an error running Coranto. These should be set to NO unless you are trying to solve a problem or are in a testing mode (for an addon or modification of the program).

Regardless of the setting for these options you can still access the configuration by passing showconfig as a parameter to Coranto, like so:

Advanced Settings

Build News Automatically (Submit)?

If set to Yes, Coranto will automatically build news each time you submit a new item. This results in changes being visible to users immediately after making them.

You may want to turn this off if you are submitting many items in a short period of time to reduce the load on the server and so that all of your changes appear at once on the pages viewed by your visitors.

Build News Automatically (Modify)?

If set to Yes, Coranto will automatically build news when you modify a news item. This means that changes will be visible as soon as you make them, but it also means that things may be slow if you modify several news items.

You may want to turn this off if you are submitting many items in a short period of time to reduce the load on the server and so that all of your changes appear at once on the pages viewed by your visitors.

Automatically Link URLs?

When set to YES any url entered into the text of an item will be turned into a link to that url. so

becomes

Archive HTML file extension

Enter the extension of your archive files here.

Items Per Modify News Page

Enter the number of items you want to be seen on the modify news page here.

BASIC USAGE

Coranto, as installed, has one profile. This profile is called news and we will use it to discuss basic usage of Coranto.

As we go through the profile settings some will include instructions for a demo that will walk you through creating your first content. If you want to follow the example make the changes suggested.

Go to Coranto's main page.

Click on Administration

Then click on Manage Profiles

Then click Edit General Settings under the news profile.

You are now at the page that controls which items from your database will be included in the text file that if generated when the build process takes place. We are going to discuss what each setting is used for.

Display Name

This setting defaults to the profile name. If you want something more descriptive to show on the Coranto's Edit News Profiles page enter it here. This a cosmetic change that is only displayed inside Coranto.

No change needed for the demo.

File Name

This is the name of the file created when the build process is run. You can set it to whatever you want. It defaults to {profilename}.txt.

No change needed for the demo.

File Path

This is where you want the output placed. Each profile can specify a directory. It defaults to the news path that is set in the main settings. Using a separate directory for each profile (or group of related profiles) is a common method of managing your content.

No change needed for the demo.

Filter By Time

If you want to limit the output of the profile to show only items added in the last X days enter a value here. If left empty all items will be included in the output file regardless of age.

Delete the default value so that the field is blank for our demo.

Filter By Number

If you want to limit the output of the profile to show only the last X items enter a value here. This will show the X newest items. Leave blank to include all items.

Leave blank for our demo.

Skip Days

To skip items entered in the last X days items enter a value here. Leave blank to include all items.

Leave blank for our demo.

Skip Items

To skip the newest X items enter a value here. Leave blank to include all items.

Leave blank for our demo.

News Style

You can select the style you wish to use for the profile from a drop down box.

Choose the Default Style for our demo.

Display Coranto Link

If you wish to have Coranto add a link to the Coranto site at the end of the file set this to yes.

Set to Link pointing to Unofficial Site for the demo.

Enable Headlines?

Setting this to yes causes a second file to be generated by the build process. As the setting name implies this is usually used for headlines.

Leave off for the demo.

Headlines Style

Select the style for to be used for the headlines file from a drop down box.

Number of Headlines

Set to the number of headlines you want created. This can be different than the number of items set earlier.

Advanced Profile Settings

HTML Template

If you wish to create a static page choose the template you want to use from a drop down list here. Template files are separate file that reside in the Coranto directory and have a tmpl file extension. Without using an addon you can not edit or create a template through the Coranto interface. You must create them offline and upload them to the Coranto directory.

Select the viewnews.tmpl for the demo.

HTML File Title

If you are using a template you can set the page title here.

Enter "My First Page", without the quotes for the demo.

Sort Order

Set the order you want your news sorted in. The available settings are:

Reverse Chronological - Newest items first.
Chronological - Oldest items first.
Alphabetical (by Subject)
True Alphabetical (aAbBcC) (by Subject)

Important Note: When the build process is run filtering is done before sorting. So if you have 4 items and you skip 2 of them in the filter settings you will always get the same 2 items regardless of the sort options. The items not filtered out are sorted according to the preference set here. There are ways of solving this but that is out of scope for this document.

Leave at the default for the demo.

Anchor Tags?

Set to yes if you want Coranto to generate HTML anchors for each item. This will enable you to jump directly to the spot on the page where the item is located when linking from a headline or a menu.

Leave at the default for the demo.

After making your changes click on the Save Settings button.

Your First News

After saving the profile settings click on Submit News on the menu bar.

In the subject field enter "My First Item" without the quotes.

In the News Text box enter anything you like and then click on Submit. If Autobuild is ON you will see:

If you left auto build on in the main settings you now have a HTML page created by Coranto in the news directory. If you turned autobuild off click on Build News in the menu bar.

In your browser enter the url to the file in the address bar. It should look like:

http://www.yoursite.com/yournewsdirectory/news.html

Press enter key or the GO button on your browser. The page created by Coranto should now be shown in your browser. Here is my page:

Yes, it look very generic, but this is the simplest example of Coranto's usage you can do. If everything went according to plan you now know that Coranto is working properly. Formatting your content will be discussed further along.

At this time you can enter a few more example items and play with the profile settings to see what impact they have on the final product.

Using SSI or PHP to display your news

Incorporating the content into an existing page. If you want to insert the content created by Coranto into an existing page you can use SSI (Server Side Includes). Most servers use the .shtml extension for pages that will be procesed for SSI. A different extension is used so that the server won't process files without includes saving time and resources.

Assuming that the page you want the content inserted into is in the same directory on your server you would place:

<!--#include virtual="news.txt" -->

in the page where you want the content at. When the page is viewed your server will replace this command with the content of the news.txt file.

Note: Some servers require that the space before the --> be removed for the #include to work.

Here is what the item entered above looks like included in this page:

Displaying the same file in a php page could be done with this code:

Most servers require the .php extension for files that use php code.

Any method you are currently using to include text files into your web pages will work with the files created by Coranto, since they are just text files themselves.

Thanks

I want to thank everyone who has contributed to Coranto.
In particular I want to thank Parahead, who read and commented on an earlier version of this document.

Revision History and Copyright

February 19, 2005

• Added CSS style to improve readablity and appearence.

My thanks to Mark Evans for the suggestions.

February 18, 2005

• Corrected minor typos.
• Corrected errata in regard to the debug options.
• Replaced some screen shots for the first news item section to better reflect the options specified in the text.
• Added example of php code to include file.

My thanks to SrNupsen for these corrections and suggestions.

Originally published February 17, 2005

This document copyright February 17, 2005

This document is copyrighted by the author, Dale Ray. Please see: Copyright and Other Legal Information

If you reproduce this document I ask that you contact me and let me know where and how you are using it.

No warranty, promises. or guarantees

The information in this document is accurate to the best of my knowledge. Use this information at your own risk. Make back ups and back ups of your back ups. There are no promises or guarantees of the fitness of this information for any use. There are no implied or stated warranties.

Dale Ray