An ``action'' is simply a page that can be seen on the board. For example, some actions include:
An action can do anything you wish, within the realms of your creativity.
Creating a new action is simple. All actions can be found in the Frontend/Web directory. Each action has it's own .pm file. For example:
- mainpage.pm - the main board page.
-
- viewforum.pm - viewing a forum.
-
- whosonline.pm - the who's online page.
-
- emoticons.pm - the emoticon editing page.
-
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 mp3.pm.
Action names 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:
#!/usr/bin/perl
package Frontend::Web::Pages;
use strict;
sub actionname {
my $self = shift;
# Your code goes here
}
1;
Make sure to change 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'':
#!/usr/bin/perl
package Frontend::Web::Pages;
use strict;
sub mp3 {
my $self = shift;
# Your code goes here
}
1;
That's it! You're now ready to add your own code to make your action do whatever you need.
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, you cannot simply 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 between the header and footer of the template.
There are 4 main ways to provide bbv2 with information to print:
- 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:
#!/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;
- print the HTTP headers and HTML directly to the browser, and return 0 from the main sub of your action. Returning 0 from your sub will cause bbv2 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:
#!/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;
- Use a redirect. A redirect will not show any HTML to the user, but will simply redirect them to the specified URL. Here's an example:
#!/usr/bin/perl
package Frontend::Web::Pages;
use strict;
sub redirectme {
my $self = shift;
$self->_redirect('http://www.bbv2.com');
}
1;
- Use an 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:
#!/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;
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:
- KickGuests - Shows an error to unregistered users, and only allows registerd (and logged in) users to view the current page. Here's an example:
-
#!/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;
- CheckAdmin - Shows an error to regular users and guests, and only allows admins to view the current page. An example:
-
#!/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;
- _param - Returns the specified CGI query param's value. For example:
-
#!/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;
- DateTimeFromUnix - Returns the time in the user's time zone, in human-readable format. Here's an example:
-
#!/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;
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:
#!/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;
If you've created these 2 actions (as Frontend/Web/showtime.pm and Frontend/Web/entertime.pm), you can now load http://www.example.com/bbBoard.cgi?a=entertime in your browser, type in the number of seconds since the epoch (try 1077777777), and it'll show you the corresponding time. Well done, you just created your first working feature!
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:
- Open Backend/Func/ControlPanels.pm in your favourite text editor.
- 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 find feature in your text editor. Here's what to search for:
For the User CP, search for: 0 => {
For the Mod CP, search for: 1 => {
For the Admin CP, search for: 2 => {
For the Guest CP, search for: 3 => {
We want to add it to the User CP, so we search for: 0 => {. We see something that looks like:
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..]
- Let's add our action to the top there. We only need to add the entertime action to the CP, as that's the only one the user will need to go directly to.
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..]
The last option for the arrayref (including 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.
That's it! There are many more useful functions to be found in the Function Reference Manual (http://www.bbv2.com/manuals/func/), for use in your own actions.
|
