DCForum Developers Forum - Archives of articles for DCForum Hacks and more

Add your own modules and functionalities

Developing New DCForum Modules

By David S. Choi
DCScripts.com

Introduction

Adding a new functionality to DCForum is very simple in part due to its modular design. In this article we describe how you can integrate your hack seamlessly with DCForum. In general, all you need to do is create a new module that obays an input/output standard (descrbied below) and save it as new_module.pl file in your Lib directory. As an example, we show how we added the new Bookmark feature.

DCForum Variables

Before we dive into how DCForum works, we first need to describe few DCForum variables:

$r_in - A reference variable which points to %in hash. This variable contains the key-value pairs of the input variable from the browser. For example, $r_in->{'az'} is the value of the inputvariable of keyword "az", which correspond to a particular processing request.
$r_setup - A reference variable which points to a hash that contains the setup key-value pairs. For example,$r_setup->{'table_width'} contains the width of the tables set in the forum settings.
$heading - A string variable that contains HEADING text
$sub_heading - A string variable that contains SUBHEADING text
$menu_button - A string variable that contains menu icon
$html_output - A string variable that contains forum output

How DCForum Works

DCForum uses two program files to process all incoming requests: dcboard.cgi and dcadmin.cgi. dcboard.cgi handles the forumrequests while dcadmin.cgi handles all administrative requests. In this article, we discuss how you can add new functionality to dcboard.cgi.

dcboard.cgi is just a shell program that read in the input request variable "az". The input request is then passed to the appropriate .pl module in the Lib directory. For example, if the input request is "az=new_module", dcboard.cgi passes that request to new_module.pl.

The code that handles this "passing" of request is shown below:

174  if (-e "$password_file_dir/forumlock.lock") {
175     print_header();
176     print_header_end();
178     $heading = "Forum is currently offline";
179     $sub_heading = "Forum is currently offline for maintainance.
180              Please try again  later";
181  } 
182  elsif(-e "$cgilib/$r_in->{'az'}.pl") {     
183     require"$cgilib/$r_in->{'az'}.pl";
184     my $command = '($heading,$sub_heading,$html_output,$menu_button) =  '
185           . $r_in->{'az'} . '($r_in,$r_setup)';
186     eval($command);
187  }
188  else {
189      print_header();
190      print_header_end();
191      $heading = "ERROR";
192      $sub_heading = "$r_in->{'az'}.pl file can't be found!!!";
193      $html_output =  "Check and make sure         
194      $r_in->{'az'}.pl is in your Lib directory";
195  }

Lines 174-181 first checks to see if the forum is currently in shutdown mode. This is done by checking to see if forumlock.lock file exists in the User_info directory.

Lines 188-195 is a error message that is displayed to the browser if the .pl file doesn't exists in the Lib directory. If you didn't forget to upload all the .pl files, this error should never be a problem.

Lines 182-187 is the heart of dcboard.cgi that handles the incoming request and passes it to appropriate .pl file. First, the .pl file is included by the require statement in line 183. Second, the call to .pl file is constructed in lines 184-185. Finally, this command is executed by the eval function in line 186. The important thing to note is the syntax of $command string. It is contructed using the input variable $r_in->{'az'}, which is the value of keyword "az". For example, if the input request was "az= new_module", $r_in->{'az'} would be "new_module". In this case, $command string is given by:

$html_output = new_module($r_in,$r_setup);

Here, the function "new_module" is called with two input arguments: $r_in and $r_setup. In return, it sends back one argument: $html_output. In fact, any request is called with these same two input parameters and one output variable. So when you develop a new module, you must make sure that its input and output interface is preserved. This will be shown in the next section.

The new_module.pl File

The basic shell for the new module which we call new_module.pl is shown below:

1  sub new_module {
2     my ($r_in,$r_setup) = @_;
3     my $html_output;
4
5     # DO SOMETHING HERE
6
7  return $html_output;
8  }
9  1;

Line 2 reads in the input arguments. Line 3 localizes four variables which we will define in this new module. Line 4-6 is the main processing code. Here, all four output variables will be defined and constructed. Line 7 returns the resulting values to dcboard.cgi. Note line 9 - this "1;" is required by the "require" statement in dcboard.cgi. Hence, so long as your new module contains lines 1-3 and 7-9, you can create any new functionality for DCForum.

As an example, we show how bookmark feature is developed in the next section.

Example: Adding Bookmark Feature

Adding bookmark feature required two separate processes: adding bookmark and viewing/managing bookmark. The first function is implemented using add_bookmark.pl module and the latter by using my_bookmark.pl. In this article, we only discuss the add_bookmark.pl module. my_bookmark.pl is constructed in a similar way.

For adding topics to user's bookmark, we decided to add the "add bookmark" link directly on the topic page. Hence, we added following lines of code in function create_page in dcforumlib2.pl somewhere below the "Printer Friendly Page" code:

<a href="$boardurl?az=add_bookmark&om=$r_in->{'om'}&
forum=$forum&archive=$r_in->{'archive'}"><img 
src="$imgurl/bookmark.gif" align="bottom" border="0"><font
SIZE="1" FACE="$font_face_4" color="$font_color_4">Bookmark this topic 
(Registered users only)</font></a>

Upon "Updating Threads", "Bookmark this topic (Registered users only)" link now appears in each topic. Note that in addition to "az=add_bookmark", values for om, forum, and archive are also passed to dcboard.cgi. In order for us to bookmark the topic in question, we need to know which topic from what forum to add to bookmark. When the user clicks on this link, dcboard.cgi passes these variables to function add_bookmark (in add_bookmark.pl) via $r_in variable. The simplified listing of add_bookmark.pl is shown below.

  1 sub add_bookmark {
  2
  3 my ($r_in,$r_setup) = @_;
  4 require "$cgilib/dcforumlib2.pl";
  5 
  6 
  7 
  8 my $html_output;
  9
 10 # adding bookmark code
 11 # $html_output is created here
 12 return $html_output;
 13 }
 14 1;

(See the full listing of add_bookmark.pl).

It is evident that, similar to the new_module.pl, add_bookmark.pl includes the input (line 3) and output (line 12) code. Here, line 4 requires dcforumlib2.pl because add_bookmark uses a function in this library file. Lines 5-8 declears variables. Line 10-11 signify the actual processing code where $html_output is created. See the full listing of add_bookmark.pl.

Conclusion

In this article, developing new DCForum modules is described. It was shown that so long as the new module obays input/output standard, anyone can add new features to DCForum. An example was shown using bookmark feature.