NEWS STYLE DOCUMENTATION

INTRODUCTION

When editing news styles via the Coranto interface, you can use a set of special tags to include specific news fields, format news items in different ways, and... well, to do just about anything. Just mix them in with your HTML when editing news items. One note: be sure to use them exactly as they appear here, with the same spacing and uppercase/lowercase characters. For instance, while <Field: Date> is valid, <field:DATE> contains several errors.

Coranto is written in a programming language called Perl, and this style language is often closely integrated with Perl. There are some comments below which will only be useful if you know Perl; if you do, there are several interesting things you can do, but if you don't know Perl, or how to program at all, don't worry. This should be perfectly usable with zero programming experience. Just ignore the Perl-specific comments.

INSERTING FIELDS

This is the most basic of the Coranto tags, and the one you'll use most often. Its format is simple:

 <Field: FieldName>

where FieldName is the name of the field, i.e. Text or User or Date or UserField_Email or one of several others. It simply inserts the value of the appropriate field, that is <Field: Text> will be replaced in the generated news item with the actual text of the news item. (An aside for those who know Perl: these fields are simply global variables, and you can use the <Field: FieldName> syntax to insert any global scalar variable.)

INSERTING FIELDS (ADVANCED)

You may want to create a text-only news style. If so, you can use

 <TextField: FieldName>

which works exactly like <Field: FieldName> but strips out all HTML.

To get the first few words of a field, for instance to excerpt the text of a news item, use

 <Snip Number: Field: FieldName>

where Number is the approximate number of characters to excerpt (the Snip command may take more characters than the given number to avoid stopping mid-word). For example <Snip 45: Field: Text>; would take roughly the first 45 characters of the Text field.

Finally,

 <ItemAnchor>

is used to link to the same news item on another page. This is generally used to link a headline to a full item. For instance, if full news items are at yoursite.com/fullnews.html, then

 <a href="http://www.yoursite.com/fullnews.html<ItemAnchor>"><Field: Subject></a>

will link directly to that item on the full news page.

DOING THINGS CONDITIONALLY (Using If)

If you've done any basic computer programming in the past, you'll be familiar with the If command. If you haven't, it's quite simple: if a certain condition is met, one particular thing is done; if the condition isn't met, either something else or nothing is done. This is simpler than it sounds from that description. Here's a useful example:

 <If: Field: UserField_Email>
 <a href="mailto:<Field: UserField_Email>">send an e-mail</a>
 </If>

This will include a link to send e-mail to the author of a news item, but only if the author has provided an e-mail address. The <If: Field: FieldName>(something)</If> syntax does whatever's in (something) as long as the contents of field FieldName isn't empty or set to 0. If the field is empty, then everything up until the next </If> is ignored.

When If is paired with an <If: Else> command, then when the If condition is not met, instead than nothing being done, something else is inserted. To provide an example, what if we wanted to modify the previous example to, rather than adding a separate e-mail link, link the author's name directly to her e-mail address? The simplest way to do this is as follows:

 <If: Field: UserField_Email>
 <a href="mailto:<Field: UserField_Email>"><Field: User></a>
 <If: Else>
 <Field: User>
 </If>

This checks if the author entered an e-mail address. If so, the author's name is linked to that e-mail address. If not, the author's name is displayed without any link.

USING IF (ADVANCED)

Previous examples have only checked whether a field is empty or not. It's also possible to check what a field is set to. For example:

 <If: Field: User eq "Guido">
 I've always loved the name Guido.
 <If: Else>
 Your name, is, unfortunately, <Field: User>. Try Guido instead.
 </If>

In this case, the If tests if the author's name is set to Guido. That ``eq'' is Perl for ``these two pieces of text are equal to each other''. Another option is ``ne'' for ``these two pieces of text do not equal each other''. You can also compare numbers:

 <If: Field: Day == 13>
 Boo.
 </If>

Just as eq is used to test if two pieces of text are identical, == tests if two numbers are equal. And, just as ne is the opposite of eq, != is the opposite of ==.

SPEAKING PERL

If you know Perl -- and don't worry, if you don't, you can do just about everything by reading the instructions above or copying examples -- then you can do some Perl-specific things. The simplest is:

 <Sub: SubName>

which calls subroutine SubName and inserts the results. (You can write subroutines of your own and keep them in cruser.pl.) You can use this Sub syntax wherever you can use the Field syntax used above. For instance, <If: Sub: SubName> will test if a subroutine returns a true value or not.

Finally, you can just jump straight into raw Perl:

 <PerlCode>$xxcounter++;
 $newshtml .= 'counter is currently at $xxcounter';</PerlCode>

(Note that to have something appear as part of the news item HTML, you have to add it to $newshtml, as in the example above.) You can use absolutely any valid Perl here. Of course, deleting files and causing other mischief can all be done in valid Perl. Because of this, before you can use the <PerlCode> feature, you have to enable it. To do so, edit cruser.pl. This setting is clearly labelled and is near the top of the file. If you enable the setting, just be careful that nobody unauthorized is able to get Administrator access to Coranto.

A FINAL EXAMPLE

One common request is to, rather than listing the date with every single news item, list all the news items for a particular day under a single date banner. Here's an example of how to do this. Of course, edit the HTML used to match your site's style.

 <If: Sub: isNewDate>
 <h1><Field: Day> <Field: Month_Name> <Field: Year></h1>
 </If>
 <p><b><Field: Subject></b> -- <small>Posted by
 <If: Field: UserField_Email>
 <a href="mailto:<Field: UserField_Email>"><Field: User></a>
 <If: Else>
 <Field: User>
 </If>
 at <Field: Hour>:<Field: Minute> <Field: AMPM></small><br>
 <Field: Text></p>

 Coranto Documentation