=head1 Programmer Reference - Creating a new v2 action

=head1 What is an "action"?

An "action" is simply a page that can be seen on the board. For example, some actions include:

=over

=item * The main board page.

=item * Viewing a forum.

=item * The who's online page.

=item * The emoticon editing page.

=back

An action can do anything you wish, within the realms of your creativity.

=head1 Creating a new action

Creating a new action is simple. All actions can be found in the I<Frontend/Web> directory. Each action has it's own .pm file. For example:

=over

=item mainpage.pm - the main board page.

=item viewforum.pm - viewing a forum.

=item whosonline.pm - the who's online page.

=item emoticons.pm - the emoticon editing page.

=back

To create a new action:

Create a new file in the Frontend/Web directory, with the name of the action as the filename, appended with ".pm". For example, if you were to create a new action that would stream an mp3 file to the user, you might call it I<mp3.pm>. 

Action names B<must be entirely lower case>, and can consist of only letters and numbers.

Of course, to work properly, an action needs to have some code in it's file. Here is the basic code that you must include in your action's file. You can simply copy and paste this into the file, if you wish:

=over

	#!/usr/bin/perl

	package Frontend::Web::Pages;
	use strict;

	sub actionname {
		my $self = shift;

		# Your code goes here
	}

	1;

=back

Make sure to change B<I<actionname>> in the code above to the actual name of your action. For example, if you named the file "mp3.pm", you would use "mp3":

=over

	#!/usr/bin/perl

	package Frontend::Web::Pages;
	use strict;

	sub mp3 {
	        my $self = shift;
	
	        # Your code goes here
	}

	1;

=back

That's it! You're now ready to add your own code to make your action do whatever you need.

=head1 Useful stuff

If you've tried the code above, you may notice that it doesn't actually work. It gives an Internal Server Error? That's because you haven't yet given v2 anything to print to the browser.

Normally, B<you cannot simply I<print> HTML directly to the browser!> To make it simple for the programmer, bbv2 will handle all the template header/footer creation and printing, authentication and all other aspects of the board. You simply need to provide it with the HTML to print I<between the header and footer of the template>.

There are 4 main ways to provide bbv2 with information to print:

=over

=item * I<return> the HTML from the main sub of your action. This will print the HTML you return between the header and footer of the template. You don't need to send HTTP headers. Here's an example:

=over

	#!/usr/bin/perl

	package Frontend::Web::Pages;
	use strict;

	sub showalink {
		my $self = shift;
	
		my $html = "<center> <a href=\"http://www.bbv2.com\">Click me!</a> </center>";
	
		return $html;
	}
	
	1;

=back

=item * I<print> the HTTP headers and HTML directly to the browser, and I<return 0> from the main sub of your action. Returning 0 from your sub will cause bbv2 B<not> to print the header and footer, but to simply exit. This is useful if you want your action to print something that is non-HTML - for example an image or a file, directly to the browser. Here's an example:

=over

	#!/usr/bin/perl

	package Frontend::Web::Pages;
	use strict;

	sub showalink {
		my $self = shift;
	
		print "Content-type:text/html\n\n";
		print "<a href=\"http://www.bbv2.com\">Click me!</a>";
		return 0;
	}
	
	1;

=back

=item * Use a I<redirect>. A redirect will not show any HTML to the user, but will simply redirect them to the specified URL. Here's an example:

=over

	#!/usr/bin/perl

	package Frontend::Web::Pages;
	use strict;

	sub redirectme {
		my $self = shift;

		$self->_redirect('http://www.bbv2.com');
	}

	1;

=back

=item * Use an I<interactivity>. bbv2 supplies functions to give the user a message, ask them to confirm if they wish to continue, or ask them to choose between two options. Here's an example of all 3:

=over

	#!/usr/bin/perl

	package Frontend::Web::Pages;
	use strict;

	sub mp3 {
		my $self = shift;
	
		# Ask the user if they would like to continue.
		# If they say YES, the script carries on to the lines below this function.
		# If they say NO, they're taken to the previous page.
	
		$self->_userconfirm('Would you like to continue?');
	
		# If we're here, they said YES.
		# So, let's ask them if they want the high quality mp3 or the low quality one.
	
		my $high_or_low = $self->_userask('What quality mp3 would you like?','High','Low');
	
		# We provided "High" and "Low" as second and third arguments above. 
		# $high_or_low will now be either 1 (for High) or 2 (for Low).
	
		if ($high_or_low == 1) {
			# High quality
			return "<a href=\"http://www.example.com/mp3_high_quality.mp3\">Click here for the mp3!</a>";
		}
		else {
			# Low quality
			return "<a href=\"http://www.example.com/mp3_low_quality.mp3\">Click here for the mp3!</a>";
		}
	
	}
	
	1;

=back

=back

=head1 Useful functions

There are many useful functions which bbv2 provides for your use immediately. If a function you need is available, it's always best to use the provided function rather than spending time coding it yourself.

Here are a few frequently-used functions:

=over

=item KickGuests - Shows an error to unregistered users, and only allows registerd (and logged in) users to view the current page. Here's an example:

=over

	#!/usr/bin/perl
	
	package Frontend::Web::Pages;
	use strict;
	
	sub mp3 {
		my $self = shift;
		$self->KickGuests();
	
		# If we're here, the user is registered and logged in.
	
		$self->_usermessage('Congratulations, you\'re registered!');
	}
	
	1;

=back

=item CheckAdmin - Shows an error to regular users and guests, and only allows I<admins> to view the current page. An example:

=over

	#!/usr/bin/perl
	
	package Frontend::Web::Pages;
	use strict;
	
	sub mp3 {
		my $self = shift;
		$self->CheckAdmin($self->{userdetails});
	
		# If we're here, the user is an admin.
	
		$self->_usermessage('Hello Admin!');
	}
	
	1;

=back

=item _param - Returns the specified CGI query param's value. For example:

=over

	#!/usr/bin/perl
	
	package Frontend::Web::Pages;
	use strict;
	
	sub showparam {
		my $self = shift;
	
		my $time = $self->_param('time');
	
		return "The time you entered was: $time";
	}
	
	1;
	

=back

=item DateTimeFromUnix - Returns the time in the user's time zone, in human-readable format. Here's an example:

=over

	#!/usr/bin/perl

	package Frontend::Web::Pages;
	use strict;
	
	sub showtime {
		my $self = shift;
		
		my $time = $self->_param('time');
		return "The epoch-time you entered, $time, in human readable format is: " . 
			 $self->DateTimeFromUnix($time, $self->{userdetails});
	}
	
	1;

=back

=back

Of course, for this to do anything useful, you first need a HTML form for the user to provide the number of seconds since the epoch:

=over

	#!/usr/bin/perl

	package Frontend::Web::Pages;
	use strict;

	sub entertime {
		my $self = shift;

		return qq~<form action="bbBoard.cgi" method="post">
			<input type=hidden name="a" value="showtime">
			Please enter the number of seconds since the epoch, for the time you want to view:<br><br>
			<input type=text name=time> <input type=submit value="View Time">
			</form>~;
	}
	
	1;

=back

If you've created these 2 actions (as Frontend/Web/showtime.pm and Frontend/Web/entertime.pm), you can now load I<http://www.example.com/bbBoard.cgi?a=entertime> in your browser, type in the number of seconds since the epoch (try I<1077777777>), and it'll show you the corresponding time. Well done, you just created your first working feature!

=head1 Adding to the Admin/Mod/User/Guest CP

Now you've completed your first feature. But nobody knows about it! People on your board will need a link to the feature to actually know it exists, and use it. The best area for a link to the feature is usually in one of the Control Panel/Areas.

To add your action to a Control Panel:

=over

=item 1. Open I<Backend/Func/ControlPanels.pm> in your favourite text editor.

=item 2. There are 4 different Control Panels: Admin CP, Mod CP, User CP and Guest CP. You need to decide which one you would like to add your action to. In this case, let's add it to the User CP.


You can find the entries for the User CP simply by using the I<find> feature in your text editor. Here's what to search for:

For the User CP, search for: B<0 =E<gt> {>

For the Mod CP, search for: B<1 =E<gt> {>

For the Admin CP, search for: B<2 =E<gt> {>

For the Guest CP, search for: B<3 =E<gt> {>

We want to add it to the User CP, so we search for: B<0 =E<gt> {>. We see something that looks like:

=over

        0 => {
            'myprofile' => [ 'Edit Profile','Change your profile.', " onClick=\"Do('myprofile')\" "],
            'calc' => [ 'Calculator', 'A calculator.', " onClick=\"Opencalc()\" "],
            'resetdst' => ['Reset DST','Clear daylight saving time.', " onClick=\"Do('resetdst')\" "],
            'setdst' => ['Set DST','Set daylight saving time.', " onClick=\"Do('setdst')\" "],

	[..etc..]

=back

=item 3. Let's add our action to the top there. We only need to add the I<entertime> action to the CP, as that's the only one the user will need to go directly to.

=over

        0 => {
	    'entertime' => [ 'Enter a Time','View an epoch time.', " onClick=\"Do('entertime')\" "],
            'myprofile' => [ 'Edit Profile','Change your profile.', " onClick=\"Do('myprofile')\" "],
            'calc' => [ 'Calculator', 'A calculator.', " onClick=\"Opencalc()\" "],
            'resetdst' => ['Reset DST','Clear daylight saving time.', " onClick=\"Do('resetdst')\" "],
            'setdst' => ['Set DST','Set daylight saving time.', " onClick=\"Do('setdst')\" "],

        [..etc..]

=back

The last option for the arrayref (including I<onClick> etc), is printed in the INPUT tag for the button. You can simply copy and paste the one above, replacing "entertime" with your own action's name, and the first 2 params with the button's name and a short description of the action, respectively.

=back

That's it! There are many more useful functions to be found in the Function Reference Manual (L<http://www.bbv2.com/manuals/func/>), for use in your own actions.