About this Document

This overview of Coranto was written by Mark Olson and is reproduced here substantially as he wrote it. Changes made include:

  • Correcting links
  • Eliminate dead links
  • Notes added with information relating to newer versions of Coranto
  • Spelling Corrections

You can view the original at:

http://coranto.org/wiki/examples/Coranto-MyGuide.htm

Dale Ray

This document references the Style Guide by Mark Olson. Links to that document (except the one in this note) open in a new window.

There are also self-referencing links that jump to other sections of this page. You can use your browser back-button to return to the spot you were reading.

Introduction

1.1 - About

I wrote this for a two reasons:
For me to have a quick, nice looking reference to link to for questions in the forum. As a general resource to give to people for getting started with Coranto that ask for help This isn't an a FAQ, readme, or whatever for Coranto, nor will I try to make it either of those. I repeat, I am not trying to make this an 'official' thing. It's here. Use it if you want.

1.2 - License

Copy, paste, email, print and staple to power poles, just have a link back to here.

The site referred to was http://www.sardonica.net.

↑ Contents

Basic Configuration

2.1 - Settings

All the necessary settings for running Coranto are done in the inital setup. Changing them afterwards is a simple matter of going to the 'Change Settings' section in the Admin area.

2.2 - Users

If you wish, you may allow more users to post news on your site. If you want to create a new user, goto the Admin Section, and choose 'Edit Users'. Here, you may create a new user, change existing users permissions, or passswords. Standard Level can only post news, and modify his or her own news. High Level users can post news, and modify all the news. Administrater can post news, modify all the news, and change all the settings Guests (done by making the name guest_name) can only post news.

2.3 - Date/Time Settings

In all likelyhood, you are not going to want to keep the current Date and Time settings. To change them, goto the Admin Section, and then to Date & Time Settings, where it presents you will all the fields. Year, Month_Name, Month_Number, Weekday, Day, Hour, Minute, Second, AMPM, Time_Zone, TwoDigitYear, TwoDigitMonth, TwoDigitHour, TwoDigitDay

The setting that you enter for the General Date Format will be used to replace <Field: Date> in your styles. Set this to the way you want the date displayed most often. You can also use all of the date/time fields in your style, your are not limited to <Field: Date>

2.4 - Adding & Editing News Fields

To add another field to the 'submit news' page, goto the Admin Section, and then to the Edit News Fields page. Scroll down to the bottom, and type in the name of the field, what it should be called, and what kind it is.

You can also edit the properties of existing fields, including where they will be shown on the submit and modify news pages (move up, move down). If it is a field that you have created, you also have the option of deleting it, and all the data that has been submitted to it.

To edit the properties, choose 'edit' under the field you want to change. For Text Areas, you will be able to set the width (height if it's multiline), permissions for posting and modifying, maximum length, display name, whether or not to disable HTML, and to convert newlines. For checkboxs, there are only a few options, display name, permissions, and the value for 'on'.

Use the X Multisubmit addon to customize the Coranto submit news page. X Multisubmit allows to create multiple submit pages with just the fields you need and to control the order they are displayed in. This means that each profile or group of similar profiles can have a custom submit page with only the fields needed, Coranto defaults to having one submit page with all of the fields shown.

2.5 - Adding & Editing User Fields

To add another field to the 'User Info' page, goto the Admin Section, and then to the Edit User Fields page. Scroll down to the bottom, and type in the name of the field. You will then be able to edit or delete it.

↑ Contents

Profiles

3.1 - Creating, Enabling & Deleting

Much like Styles, profiles are incredibly important as to how the display of news pages are handled. Profiles however, deal with the mechanics of the news, not the looks. To create a new profile, click on 'Profies' while in the Admin Section scroll down to the bottom and type in the name. Simple as that. Now scroll down until you see the profile you just created, and hit 'enable'. If you ever want to delete a profile, simply click 'delete'.

3.2.0 - General Settings

The General Settings are what control the amount of posts in a file, where the file is, and how long the posts should stay in the file. To get to it, click on 'General Settings' under the profile you want to edit..

3.2.1 - Main Profile Settings

Coranto does a fairly good job at explaining what all the fields do, and what they mean. For lengths sake, I'm going to go through them though.

The file name, is obviously what the file will be called. It does no add the extension (.dat, .txt, etc..) automaticaly, so you haveto be sure that you do. Coranto also does not create this file, so make a blank file of the same name, upload it, and CHMOD it to 777.

The file Path is the absolute path to the folder where you want the above file to be made in. If the path is not correct (ie. can't find the above file), Coranto will give you a big honking error.

The next 3 settings deal with time and numbers, and all are explained well.

The next settings makes you choose what style you want Coranto to use for this profile.

The final standard setting in the Main Profile Settings s the option of whether or not to display a link back to the Coranto page.

3.2.2 - Headlines

For all standard profiles, you have the option to create a headlines file. If you want headlines, be sure to enable it by selecting 'yes' from the dropdown box. The style for headlines varies from person to person. If you want to link to the main news page, you'll probably use something like the following code for the style:

<a href="/newspage.html#<ItemAnchor>"><Field: Subject></a>

Just change newspage.html to the page where the news will be at. The next setting, the number of headlines, should be easy enough for you to figure out :)

3.2.3 - Advanced Profile Settings

The Advanced Profile Settings in the dumping ground for the 'other' settings. By far one of the most useful is the ability to create the entire page from a template, instead of just something to be included. The sort order should be fairly self-explanatory, but I recommend that you leave it as is. If you have enabled headlines you *must* enable 'Anchor Tags'.

3.3.0 - Archiving Settings

As should be expected, Archiving Settings allow you to configure how the old news will be archived, if at all.

3.3.1 - General Archiving Settings

The only 3 settings in this section are all straightforward with what they do;

Archive type lets you choose what kind of archive (if any) to use for that profile, Archive File Path lets you choose where the files will be made. Make sure that this folder is writable, the News Style is quite obviously the style that it will use when creating the archives.

3.3.2 - Additional Settings

Below those settings are the ones to be used if you selected monthly, weekly, or daily archiving. They are used to create the files that link the archives together.

For the Archive Links File, I recommend that you name it index.shtml, index.php, or you're default index page.

For the .tmpl files leave them at there defaults unless you have other ones made already.

3.4 Categories

If you have multiple users posting, and you want to restrict what profiles they can and can't post to, you need the categories addon. I have included this in the profile section because that is where it is used. Once you have uploaded and enabled it, head to the admin section, where you *should* see a new box, appropriately called 'Categories'. When you enter it, you'll see all the categories that you have, at first, only (default). If, for instance, you want to limit the people that can post to the 'News' profile, you could make a category called 'news'. Then hit 'edit permissions' to see a list of all the available users. Highlight the ones that you want to be able to post to 'news', and hit the 'Save Changes Button'. Now head over to the General Settings for the profile you want to limit, and scroll down until you see a new field, again, called Categories. Here you can choose what Category to use for that profile, thus limiting who can post to it.

The categories addon is now included in the Coranto distribution. You must go to the the addon manager page and enable it.

3.5 - .tmpl files

In the profile settings, for both archiving and general settings, you have the option to use .tmpl files to generate HTML, Text, or whatever other kinds of pages you want. I highly recommend naming your .tmpl files along the lines of profilename-arclink.tmpl or profilename-archive.tmpl, so that you know exactly what profile each tmpl file is for. Creating a .tmpl file is much like creating a news style. You have access to all of the variables that you do in news styles, as well as two others, which should be used, but doesn't have to be; <Field: Content> and <Field: Title>. Anything that you use in styles, can be used in .tmpl files, with the addition of Server Side Includes.

↑ Contents

Styles

4.1 - Intro to Styles

Ok, now that I've spent 10 minutes praying that I can do this section before I fall asleep (it 3:38am, sue me), I'm ready to go.

Styles are what control what the output looks like. You can include tables, images, whatever. When you edit styles, you are working in an environment that, in theory, will allow you to do damn near anything you want with regards to appearance. To do this, you are given a plethora of variables to choose from. Each of them, if they are included in the style, must be in the following syntax;

<Field: Name>

so ...

<Field: Text> would display the newstext, whereas <Field: TwoDigitYear> would display the last two digits of the year (ex. 01 for 2001. Any HTML that you have in the style will be left alone, as Coranto doesn't look for them.

In addition, any News Fields you may have created will be available in the form of <Field: CustomField_fieldname>. Likewise, any User Fields you may have created will be in the form of <Field: UserField_fieldname>

4.2 - Conditionals

Believe it or not, the fun doesn't stop there. Oh no, Coranto has a rudimentary programming language built into the styles. Well, If you think that If-Else is a rudimentary programming language, we're on the same page. If not, eh. Anyway..

Instead of explaining, then showing, I'm going to show, then explain. Ok, now that you've glanced over that example, I'll explain it. When we run the If: on a subroutine (hence the Sub: ), we are checking if it returns a 'true' variable, signaling to do something, in this case, print the date above all the other posts from that day.

The Else command is used to perform something if the If: returns as false. In that example, it checks to see if the user has set their email address by looking up the UserField_Email variable. If it finds one, it prints out a link to it with their name. Otherwise, it will simply print the name.

The eq attribute is used inside of the If tag to check whether or not two pieces of text are the same. Using the Else tag in conjunction with this makes the 'ne' attribute (used in the same way) pointless. That example checks to see if the Subject is "w00t, Coranto", and, if it is, it prints "Don't we all love Coranto?". Otherwise, (ie. !=) it prints "Grr..".

Much like the 'eq' and 'ne' attributes, the == attribute is used inside of the If tag to check whether or not two things are the same, this time, numbers. That checks if the Field Day is equal to 32. If it is, it prints "Something isn't right here...", otherwise it does nothing.

4.3 - PerlCode

In order to use PerlCode in styles, it must be enabled in cruser.pl, so go and check, I'll wait.

To enable raw perl in styles open cruser.pl in a text editor and look for:

  1. ** RAW PERL IN NEWS STYLES **
  2. When editing news styles, it's possible to use raw Perl code
  3. enclosed inside <PerlCode>print 'code here';</PerlCode> tags.
  4. This is a useful and powerful feature if you know Perl, but can
  5. also be slightly dangerous: it allows anyone who can gain access
  6. to an Administrator-level account to run arbitrary commands on
  7. your server. Set to 1 to enable this feature, 0 to disable.

$EnableRawPerl = 1;

If this variable is set to 1 (one) perl can be used. If it is set to 0 (zero) perl is not allowed.

Once it is enabled, try this out. That code, when called, will change the Day number to the number, and the appropriate suffix. June 17, '01 would become June 17th, '01. Make these changes to save room in the style. If you want to print something in the HTML, you have to do it like the following:

$newshtml .= "this is wherever I put this code in the style";

4.4 - Basic Examples

Example 1. Pretty straightforward, checking isNewDate , and printing the date above that days' news
Example 2 is an example of how to use the <Field: newsid>, as a link to viewnews.cgi.

4.5 - Advanced Examples

Example 1. This one is, more or less the fullnews feature. Once it finishes checks the length, it strips all the HTML out (except <br />), and checks the length again. If it was shortened too much, it restores the original $Text variable, and stops. However, if it still is longer than the minimum length, it will shorten it, and then link it to the viewnews.
You can create the same result, with the exception of the linebreaks staying, simply by using:

<PerlCode>
if(length($Text) > 150) {
    $Text = SnipText($Text, 150);
    $Text .= qq~<br><a href="/cgi-bin/viewnews.cgi?id=$newsid" title="more">more...</a>~;
}
</PerlCode>

where you want the snip.

↑ Contents

Miscellaneous

5.1 - Addon Manager

The addon manager is found in the Admin Section, and gives you control over what addons are enabled to make changes to Coranto and it's functions. It automatically detects all the files that are in the form cra_*.pl , and then checks them for certain settings. You will always see, the filename, description, and certain times, other attributes, such as 'Documentation'. Enabling addons requires only that you click 'enable' under the addon you want. Disabling is the same process. If an addon misbehaves, Coranto may have to forcibly disable it, so that it doesn't damage files or processes.

5.2 - User Info

Available to all users except for guests, User Info is where users can change there passwords, or enter any UserFields there may be.

5.3 - Of guests and Admins

There are 2 special user levels in Coranto, guests, and Administrators. Guests are only allowed to use the submit page, nothing more. Admins, on the other hand, have total control over every facet of the Settings; They can post to all categories, regardless of restrictions, modify any news, and change any settings for any user under user info. It is for that reason, that you must trust your Admins implicitly. As a general rule of thumb, If you trust them enough with the password to your FTP or file manager, you trust them enough to give them administrator privileges in Coranto. If, for some reason you decide to remove the title of Administrator from them, you have to download nsettings.cgi, open it and find where it says user-theirname and then find the '3' and change it to '2'. You can then go in and delete them if need be.

5.4 - viewnews

As of build27, the viewnews is able to display only 1 news item at a time. An example of how to do this can be found here.

↑ Contents

Exit Stage Left

6.1 - Closing

My goal in creating this was not to injure my eyes further from looking at computer screens , but to give you a base knowledge to use with Coranto, and, hopefully to be able to help others with problems that they might have.

If you want to contribute email me and I'll be more than happy to add what you wrote (for the love of God, have it written when you send it in).

6.2 - Thanks

Big thanks to elvii for letting me in on the Alpha all those months ago.

Thanks to everyone on the eGroups (Y! Groups) lists who helped me out, I'd name names, but I really don't feel like looking through the archives now.

And finally, thanks to my mom . . . for bringing me Chinese food without asking alot of questions.

6.3 - Errors

If you think you've found an error in this document, feel free to email me with the error.

The e-mail address that was listed in the source of the original document was:

ticketyboo(at)sardonica.net

↑ Contents

Discussion/Comments

You can discuss this article in this forum thread.

Categories:




Page last modified on February 02, 2009, at 06:40 PM