Module Programming Guide: FMYiRC V1.00

From FMYiRCWiki

Jump to: navigation, search

Module Programming Guide: Freemed-YiRC V1.00


Contents


Summary

This document is intended to give a developer an understanding of how Freemed-YiRC modules work and how to create one from scratch.


Module SQL File

The first step in creating a new Freemed-YiRC module is to create a text file called module_XXX.sql, where XXX is a very short (one word?) description of the module. This file will contain SQL statements which will tell Freemed-YiRC how to utilize the new module. This text file should be placed into the DB/mysql directory of your Freemed-YiRC installation.

For example, let's say we're going to create a new module in Freemed-YiRC which does one thing, show the current system time. For the purpose of this guide, let's call this new module Clock. So, our module SQL file should be called module_clock.sql.

Module Record - DB Table fy_modules

The first line in your module SQL file should be the module creation line. This is an SQL record in the Freemed-YiRC table fy_modules. This table is made up of the following fields:

  • mod_fullname - The module's full name. This is also what will appear on menus, so please name accordingly.
  • mod_abbr - This is a very short abbreviation (FIVE CHARACTER MAXIMUM, preferably two or three!) for the module. No two Freemed-YiRC modules should ever have the same module abbreviation. Please ensure when creating a new module, even if you have no intention on releasing that module, that it does not have the same module abbreviation as any other module listed in the Freemed-YiRC Modules Index!!!
  • mod_type - This can be set to one of three types:
    • "User" - This indicates a menu option will appear on a user's main menu, providing the user has the proper permission (see mod_secdbperm).
    • "Group" - This indicates a menu option will appear on a group menu, providing the group is set up to use this module (after module installation of course) AND the user has the proper permission.
    • BLANK - If the module type is blank, no link will appear on any menu.
  • mod_status - Indicates if the module is enabled or not for the system to use. Can be one of two values:
    • "Active" - Module is enabled (you should always set this to Active in your module SQL file)
    • "Inactive" - Module is not enabled.
  • mod_mainscript - This is the PHP script which will be launched when the menu option for this module is clicked on. It is recommended to always include a question mark here, as if this is a group menu option, an argument specifying which group will always be appended. i.e., "clock.php?"
  • mod_secdbperm - This is the Security Database permission required in order for a user to be able to see this menu option appear. You will specify the Security Database permissions for your new module after the fy_modules SQL statement.
  • mod_serveronly - This is depricated.
  • mod_description - This is a text description of your module. While the length of this field is not constrained, it is recommended this be limited to two to four sentences.


So, for our example clock program, let's use the following field values:

  • mod_fullname - "View System Time"
  • mod_abbr - "CLK"
  • mod_type - "User"
  • mod_status - "Active"
  • mod_mainscript - "clock.php?"
  • mod_secdbperm - "clock" (Described in detail in the next section)
  • mod_description - "A program to allow users to view the current system time."

Our SQL statement would hence look like this: 

INSERT INTO fy_modules (mod_fullname, mod_abbr, mod_type, mod_status, mod_mainscript, mod_secdbperm, mod_description) VALUES ('View System Time', 'CLK', 'User', 'Active', 'clock.php?', 'clock', 'A program to allow users to view the current system time.');


Security Permissions - DB Table fy_secdb_perms

The next section of your module SQL file should list all applicable Security Database permissions for this new module. Typically a module has at least two security permissions, one for Access (read-only) and one for Edit. If your module is more complex, you may have more. You can use security permissions to greatly tailor your module to different users.

Typically a simple naming convention is used for Security Database permissions. You should always begin your modules security permissions with the same word which was used in your module SQL file. i.e., the XXX portion in module_XXX.sql. Your first Access permission typically is just this word, _access isn't necessary. However your other permissions should have a short description attached. The Edit permission is typically XXX_edit, an Administration permission may be XXX_admin, etc...

Security Database permissions should ALWAYS be in all lower-case!

These security permissions are stored in the fy_secdb_perms database table. This table is made up of the following fields:

  • perm_module - This is the module abbreviation of your module. This should EXACTLY match what you used for the mod_abbr field in the fy_modules table (i.e, the SQL statement we just created for this module). This is how these permissions are linked to the module.
  • perm_name - This is the name of the permission (i.e., XXX, XXX_edit, XXX_admin, etc...).
  • perm_descr - A short description of the permission. Typically Access, Edit, or Admin will suffice, unless this permission is more exotic.
  • perm_helptext - This is the help text for this permission. This should fully describe what this permission is used for, especially if it is more exotic than simply Access', Edit, or Admin.

For our clock example, we will use two permissions: clock and clock_edit. clock_edit will allow a user to edit any module settings we wish to create (although typically clock_admin could be used for this purpose too).

Based on this information, we would create two SQL statements: 

INSERT INTO fy_secdb_perms (perm_module, perm_name, perm_descr, perm_helptext) VALUES ('CLK', 'clock', 'Access', 'This permission allows a user to access the Clock module.');
INSERT INTO fy_secdb_perms (perm_module, perm_name, perm_descr, perm_helptext) VALUES ('CLK', 'clock_edit', 'Edit', 'This permission allows a user to edit settings in the Clock module.');


The Security Database - DB Table fy_secdb

Freemed-YiRC was not originally built to be a modular system. While the system is now much more modular in nature, there are still some legacy portions of the system which need tweaking. One of these portions is the Security Database. While we have defined the Security Database permissions in the previous section, we must now actually create a field in the DB table fy_secdb for each security permission we create.

This is basically using an SQL ALTER TABLE statement to modify fy_secdb and add our fields. You should ALWAYS use a field type of char(1)!!!

The formatting of the SQL statement is as follows. One statement per Security Database permission:

ALTER TABLE fy_secdb ADD PERMNAME char(1);

Where PERMNAME is your Security Database permission name.

For our clock example, we would do the following: 

ALTER TABLE fy_secdb ADD clock char(1);
ALTER TABLE fy_secdb ADD clock_edit char(1);


HELP! DB Table fy_help

Next up in the module SQL file are help entries. While the Freemed-YiRC Wiki can be used for this purpose, it is extremely helpful to at least provide a minimum level of help in case an agency does not have Internet access, or has configured their Freemed-YiRC installation to not use the Freemed-YiRC Wiki.

The Freemed-YiRC help system is set up for each of your PHP scripts. Each script can have one help entry. When the user clicks on the Freemed-YiRC help icon (the question mark "?" in the upper-right hand corner of your Freemed-YiRC menu) for a given page, the system returns any help text associated with that page.

The DB table for Freemed-YiRC help is fy_help. There are only two fields:

  • scriptname - The name of the PHP script this help text applies to.
  • helptext - The actual help text. This may be as simple, or as complex, as you wish it to be. You may use HTML formatting here. You may even reference images here and provide external links. However, care and caution should be exercised when providing links outside of the Freemed-YiRC system. Please keep in mind that a user may not have Internet access!!!

For our clock example let us assume there will only be two PHP scripts involved:

  • clock.php - The primary page
  • clock_settings.php - The settings administration page

With this in mind, we could do the following: 

INSERT INTO fy_help (scriptname, helptext) VALUES ('clock.php', 'This page shows the current Freemed-YiRC system time.  This is the same time the timecard system uses, so set your clocks to this!!!');
INSERT INTO fy_help (scriptname, helptext) VALUES ('clock_settings.php', 'This page allows you to edit the clock settings.  This is pretty easy, as there is only one settings... you can choose between standard AM/PM time or 24-hour, <i>military</i>, time.');


New Module DB Tables

Next up we are ready to create any DB tables for our new module. It's quite possible that the module may not have any. Most likely a functional module will have at least one, if not many. Now is the time create them... The specifics of SQL table creation is beyond the scope of this document.

All table names should be prefixed with fy_, then contain the name of the module. Then append an underscore (_) to this and add descriptive text.

For our clock example, we will have one DB table. This table will contain one field which will indicate in what format the time should be displayed. We will call our table fy_clock_settings.

With this in mind, our SQL for this table creation may look like: 

create table fy_clock_settings (
ID int unsigned not null auto_increment,
clock_time_type char(8),
PRIMARY KEY (ID)
);


Filler Records

Finally in our module SQL file we may want to load our tables with filler records. Maybe we want to initialize a settings table, fill any reference tables with data, etc... This is typically done via the SQL INSERT command. If you will have many filler records for multiple tables, please group them together with blank lines between records for different tables.

For our clock example, we will have one filler record. This will create a record in our fy_clock_settings table to indicate the default clock time display setting as standard (as opposed to military).

Our SQL for this filler record may look like: 

INSERT INTO fy_clock_settings (clock_time_type) VALUES ('standard');


Implementation

Congratulations! You now have what you need to tell Freemed-YiRC about your new module. So now what? If done correctly you should have a file in your DB/mysql directory of your Freemed-YiRC installation.

To implement this new module, you simply dump the contents of your text file into your database. This can be done via the command-line by issuing the following command (from the DB/mysql directory). This assumes your Freemed-YiRC database name is the default of freemed_yirc:

mysql freemed_yirc < module_XXX.sql

For our clock example, we would use the following command: 

mysql freemed_yirc < module_clock.sql


Full Example

For our clock example, we should have a file created in the DB/mysql directory of your Freemed-YiRC installation named module_clock.sql which looks something like this: 

INSERT INTO fy_modules (mod_fullname, mod_abbr, mod_type, mod_status, mod_mainscript, mod_secdbperm, mod_description) VALUES ('View System Time', 'CLK', 'User', 'Active', 'clock.php?', 'clock', 'A program to allow users to view the current system time.');

INSERT INTO fy_secdb_perms (perm_module, perm_name, perm_descr, perm_helptext) VALUES ('CLK', 'clock', 'Access', 'This permission allows a user to access the Clock module.');
INSERT INTO fy_secdb_perms (perm_module, perm_name, perm_descr, perm_helptext) VALUES ('CLK', 'clock_edit', 'Edit', 'This permission allows a user to edit settings in the Clock module.');

ALTER TABLE fy_secdb ADD clock char(1);
ALTER TABLE fy_secdb ADD clock_edit char(1);

INSERT INTO fy_help (scriptname, helptext) VALUES ('clock.php', 'This page shows the current Freemed-YiRC system time.  This is the same time the timecard system uses, so set your clocks to this!!!');
INSERT INTO fy_help (scriptname, helptext) VALUES ('clock_settings.php', 'This page allows you to edit the clock settings.  This is pretty easy, as there is only one settings... you can choose between standard AM/PM time or 24-hour, <i>military</i>, time.');

create table fy_clock_settings (
     ID int unsigned not null auto_increment,
     clock_time_type char(8),
     PRIMARY KEY (ID)
);

INSERT INTO fy_clock_settings (clock_time_type) VALUES ('standard');

To implement this module, execute the following from the command-line on your server: 

mysql freemed_yirc < module_clock.sql

Module PHP Code

The next step is actually creating your module PHP source code files. While the internals of PHP and Freemed-YiRC programming are beyond the scope of this document, there are a few things you need to know in order to make your scripts as friendly to others as possible.


Script Naming

All Freemed-YiRC PHP scripts are placed in the primary Freemed-YiRC directory. This is due to the fact that Freemed-YiRC started off as a small project and eventually got very large. Hence, it's necessary to follow some simple rules to ensure that your module's PHP scripts don't clash with those of other modules.

Please name all of your PHP scripts starting with the module name. The same module name as was used in your module SQL file, Security Database permissions, and any database tables created. Add an underscore character (_) and then descriptive text. Your primary script may simply be the module name for simplicity.


Example PHP Script #1

Our first example will focus on our new clock module. Our script (clock.php) will look something like this: 

<?php
        # Freemed-YiRC (C)2000-2011 Joe Thielen - Licensed under the GNU GPL V2
        # *_-=MODULE=-_*: View System Time (CLK)

include "freemed_yirc-vars.inc";
include "freemed_yirc-funcs.inc";

fy_cookiecheck($cookie_user);
fy_resetcookie($cookie_user, $cookie_id, $fy_cookietime);

$cookie_user = $_COOKIE['cookie_user'];
$cookie_id = $_COOKIE['cookie_id'];
$fydb_host = $_COOKIE['fydb_host'];

$conn=fy_makeconn($fydb_type, $fydb_host, $fydb_user, $fydb_name);
if (fy_secdbcheck($conn, $fydb_type, $fydb_name, $cookie_id, "clock")==1) {fy_autologout($cookie_user);exit;};
if (fy_secdbcheck($conn, $fydb_type, $fydb_name, $cookie_id, "clock_edit")==0) {$perm_edit="X";} else {$perm_edit="";}

fy_starthtml("Freemed-YiRC", "");
$fy_window_back="main.php";
fy_startwindow($SCRIPT_NAME, $fy_window_back);

fy_winprn("CENTER","","<b>View System Time</b>");
fy2_html_winblank();

$fy_time_setting=fy2_sql_lookup("fy_clock_settings", "clock_time_type", "1=1");

if ($fy_time_setting=="standard")
{
        fy_winprn("CENTER","",date("h:iA"));
} else {
        fy_winprn("CENTER","",date("H:i:s"));
}

if ($perm_edit=="X")
{
        fy2_html_winblank();
        fy2_html_winlink("CENTER","","clock_settings.php", "Edit Settings");
}

fy2_html_winblank();
fy_winback("", $fy_window_back);

fy_endwindow("User: $cookie_user");
fy_endhtml();

?>

Script Break Down

HEADER

Things that should be included in the start of nearly all Freemed-YiRC PHP source code files.

  • - Identifies the script as a PHP soure code file 
<?php
  • - Provides project name and copyright information, including licenseing information 
        # Freemed-YiRC (C)2000-2011 Joe Thielen - Licensed under the GNU GPL V2
  • - Provides the module name to which this script belongs to. This text should match what's in fy_modules in the mod_fullname and mod_abbr fields. 
        # *_-=MODULE=-_*: View System Time (CLK)
  • - Includes the Freemed-YiRC system variables and primary functions. 
include "freemed_yirc-vars.inc";
include "freemed_yirc-funcs.inc";
  • - Performs security checks on cookies. 
fy_cookiecheck($cookie_user);
fy_resetcookie($cookie_user, $cookie_id, $fy_cookietime);
  • - Imports necessary environmental variables 
$cookie_user = $_COOKIE['cookie_user'];
$cookie_id = $_COOKIE['cookie_id'];
$fydb_host = $_COOKIE['fydb_host'];
  • - Creates a database connection. 
$conn=fy_makeconn($fydb_type, $fydb_host, $fydb_user, $fydb_name);
  • - Checks to ensure we have the property security permission to run this script. 
if (fy_secdbcheck($conn, $fydb_type, $fydb_name, $cookie_id, "clock")==1) {fy_autologout($cookie_user);exit;};
  • - Checks to see if we have any other permissions. 
if (fy_secdbcheck($conn, $fydb_type, $fydb_name, $cookie_id, "clock_edit")==0) {$perm_edit="X";} else {$perm_edit="";}
  • - Displays starting HTML code 
fy_starthtml("Freemed-YiRC", "");
  • - Creates a Freemed-YiRC menu screen with title and navigation icons 
$fy_window_back="main.php";
fy_startwindow($SCRIPT_NAME, $fy_window_back);
  • - Everything in the Freemed-YiRC menu is in an HTML table. It's important to understand this. The basic PHP echo command is worthless, unless you always use the HTML table elements before and after each statement.
MODULE SPECIFIC CODE

The functionality you wish to implement

  • - Displays the menu header text in bold, followed by a blank line. 
fy_winprn("CENTER","","<b>View System Time</b>");
fy2_html_winblank();
  • - Retrieves the time display format setting 
$fy_time_setting=fy2_sql_lookup("fy_clock_settings", "clock_time_type", "1=1");
  • - Displays the time according to this setting 
if ($fy_time_setting=="standard")
{
        fy_winprn("CENTER","",date("h:iA"));
} else {
        fy_winprn("CENTER","",date("H:i:s"));
}
  • - If the user has the edit permission, provide a link to an Edit Settings page. 
if ($perm_edit=="X")
{
        fy2_html_winblank();
        fy2_html_winlink("CENTER","","clock_settings.php", "Edit Settings");
}
FOOTER

Things that should be included at the end of nearly all Freemed-YiRC PHP source code files.

  • - Provides a link back to the main menu 
fy2_html_winblank();
fy_winback("", $fy_window_back);
  • - Ends the Freemed-YiRC menu window. 
fy_endwindow("User: $cookie_user");
  • - Displays ending HTML code. 
fy_endhtml();
  • - Ends the PHP script. 
?>

Example PHP Script #2

Our second example will focus on our new clock module's Edit Settings functionality. Our script (clock_settings.php) will look something like this: 

<?php
        # Freemed-YiRC (C)2000-2011 Joe Thielen - Licensed under the GNU GPL V2
        # *_-=MODULE=-_*: View System Time (CLK)

include "freemed_yirc-vars.inc";
include "freemed_yirc-funcs.inc";

fy_cookiecheck($cookie_user);
fy_resetcookie($cookie_user, $cookie_id, $fy_cookietime);

$cookie_user = $_COOKIE['cookie_user'];
$cookie_id = $_COOKIE['cookie_id'];
$fydb_host = $_COOKIE['fydb_host'];
# Imported Vars
$fy_edit = strtoupper(substr(stripslashes($_REQUEST['fy_edit']),0,1));

$conn=fy_makeconn($fydb_type, $fydb_host, $fydb_user, $fydb_name);
if (fy_secdbcheck($conn, $fydb_type, $fydb_name, $cookie_id, "clock_edit")==1) {fy_autologout($cookie_user);exit;};

$fy_window_back="clock.php";
$fy_title="View System Time<br />Edit Settings";

if ($fy_edit=="X")
{
        $gr_clock_time_type = strtolower(substr(stripslashes($_POST['gr_clock_time_type']),0,8));

        # UNIV SQL INSERT/UPDATE/SMART
        $fy2_su_mode="UPDATE";
        $fy2_su_table="fy_clock_settings";
        $fy2_su_fieldsvals="clock_time_type=".$gr_clock_time_type;
        $fy2_su_smartfields="1=1";
        fy2_sql_univ($fy2_su_mode, $fy2_su_table, $fy2_su_fieldsvals, $fy2_su_smartfields);

        # FMYiRC QUICKPAGE DISPLAY
        $fy2_hq_title=$fy_title;
        $fy2_hq_message="<i>Clock Settings Updated!</i>";
        $fy2_hq_back="";
        $fy2_hq_meta=$fy_window_back;
        $fy2_hq_meta_length=1;
        fy2_html_quickpage($fy2_hq_title, $fy2_hq_message, $fy2_hq_back, $fy2_hq_meta, $fy2_hq_meta_length);

        exit;
}

fy_starthtml("Freemed-YiRC", "");
fy_startwindow($SCRIPT_NAME, $fy_window_back);

fy_winprn("CENTER","","<b>".$fy_title."</b>");
fy2_html_winblank();

# START FORM
$fy2_f_action="clock_settings.php?fy_edit=X";
$fy2_f_name="form";
$fy2_f_append="";
fy2_form($fy2_f_action, $fy2_f_name, 0, $fy2_f_append);

# Get the current time setting
$fy_time_setting=fy2_sql_lookup("fy_clock_settings", "clock_time_type", "1=1");

# FORM SELECT
$fy2_fs_title="Format:";
$fy2_fs_title_split=0;
$fy2_fs_title_align="CENTER";
$fy2_fs_select_align="LEFT";
$fy2_fs_name="gr_clock_time_type";
$fy2_fs_default_value=$fy_time_setting;
$fy2_fs_optionvals="standard=AM/PM|military=24-Hour Military Format";
$fy2_fs_append="";
fy2_form_select($fy2_fs_title, $fy2_fs_title_split, $fy2_fs_title_align, $fy2_fs_select_align, $fy2_fs_name, $fy2_fs_default_value, $fy2_fs_optionvals, $fy2_fs_append);

# FORM END
$fy2_fe_colspan=1;
$fy2_fe_button="Submit";
fy2_form_end($fy2_fe_colspan, $fy2_fe_button); 

fy2_html_winblank();
fy_wincancel("", $fy_window_back);

fy_endwindow("User: $cookie_user");
fy_endhtml();

?>

Script Break Down

We'll only focus on the differences from the first script.

This script performs two tasks:

  • Display a form which allows the user to change the time display format.
  • Update the setting if applicable.

This script can be greatly improved upon. However, for the purpose of an example it displays the very basics of how a fully functional module is created.

HEADER
  • We're grabbing on additional variable from the environment. However, since it's specific to this script, we pre-pend it with a comment: 
# Imported Vars
$fy_edit = strtoupper(substr(stripslashes($_REQUEST['fy_edit']),0,1));
MODULE SPECIFIC CODE
  • Variables to re-use... since we're going to re-use these variables, we create them before continuing:

$fy_window_back="clock.php"; $fy_title="View System Time
Edit Settings";

  • This script can actually be run in two very different ways. If we have submitted the form, then the $fy_edit variable is set to X. 
if ($fy_edit=="X")
{
  • Next, we're going to get the contents of the variable $gr_clock_time_type, which we will see in a bit is the variable in the form we have submitted
    • In order to help avoid SQL Injection and/or buffer overflow attacks, as well as remove any potentially automatically added slashes, we use the stripslashes() and substr() functions. Since we know the returned variable will never be more than 8 characters (earlier we created an SQL DB field clock_time_type in the fy_clock_settings DB table which we specified is limited to 8 characters), we tell substr() to limit it to 8 characters. 
     $gr_clock_time_type = strtolower(substr(stripslashes($_POST['gr_clock_time_type']),0,8));
  • Then we update the fy_clock_settings DB table. For this task, we use the FMYiRC Universal SQL Function, fy2_sql_univ(), for updating the record.
    • The 1=1 in the $fy2_su_smartfields variable tells the function to update ALL records in the fy_clock_settings DB table. Since we expect to only have one, this is sufficient. 
        # UNIV SQL INSERT/UPDATE/SMART
        $fy2_su_mode="UPDATE";
        $fy2_su_table="fy_clock_settings";
        $fy2_su_fieldsvals="clock_time_type=".$gr_clock_time_type;
        $fy2_su_smartfields="1=1";
        fy2_sql_univ($fy2_su_mode, $fy2_su_table, $fy2_su_fieldsvals, $fy2_su_smartfields);
  • After performing our intended task, we want to print a quick message to the screen indicating so. Instead of going through the process of sending the individual items to the screen (starting/stopping HTML/FMYiRC Window, title, etc...), we can do all of this with the fy2_html_quickpage() function! 
        # FMYiRC QUICKPAGE DISPLAY
        $fy2_hq_title=$fy_title;
        $fy2_hq_message="<i>Clock Settings Updated!</i>";
        $fy2_hq_back="";
        $fy2_hq_meta=$fy_window_back;
        $fy2_hq_meta_length=1;
        fy2_html_quickpage($fy2_hq_title, $fy2_hq_message, $fy2_hq_back, $fy2_hq_meta, $fy2_hq_meta_length);
  • Now that our task is done and we've notified the user so, we want to stop script execution. 
        exit;
  • Finally, we want to end our if statement code: 
}
  • The above contents of the if statement were to fulfill one part of our code. The other part of our code is to actually show the form we'll use to present the user with the choice of what data will be put into the fy_clock_settings DB table.
  • We display our starting html, FMYiRC window, and title as normal. The only differences here are that for the window title, we've already defined it in the $fy_title variable, since it's used twice in this script... the same for $fy_window_back. 
fy_starthtml("Freemed-YiRC", "");
fy_startwindow($SCRIPT_NAME, $fy_window_back);

fy_winprn("CENTER","","<b>".$fy_title."</b>");
fy2_html_winblank();
  • Now we want to start an HTML form, for this we'll use the FMYiRC fy2_form() function: 
# START FORM
$fy2_f_action="clock_settings.php?fy_edit=X";
$fy2_f_name="form";
$fy2_f_append="";
fy2_form($fy2_f_action, $fy2_f_name, 0, $fy2_f_append);
  • Next we look up the current value of the clock_time_type DB field from the fy_clock_settings DB table, so we can present this to the user as the default option. 
# Get the current time setting
$fy_time_setting=fy2_sql_lookup("fy_clock_settings", "clock_time_type", "1=1");
  • Now we present the user with an HTML SELECT (drop-down) input, using the FMYiRC fy2_form_select function. 
# FORM SELECT
$fy2_fs_title="Format:";
$fy2_fs_title_split=0;
$fy2_fs_title_align="CENTER";
$fy2_fs_select_align="LEFT";
$fy2_fs_name="gr_clock_time_type";
$fy2_fs_default_value=$fy_time_setting;
$fy2_fs_optionvals="standard=AM/PM|military=24-Hour Military Format";
$fy2_fs_append="";
fy2_form_select($fy2_fs_title, $fy2_fs_title_split, $fy2_fs_title_align, $fy2_fs_select_align, $fy2_fs_name, $fy2_fs_default_value, $fy2_fs_optionvals, $fy2_fs_append);
  • Then we end our form, using the fy2_form_end function 
# FORM END
$fy2_fe_colspan=1;
$fy2_fe_button="Submit";
fy2_form_end($fy2_fe_colspan, $fy2_fe_button);

Implementation

For the purpose of implementing this code, if you've already followed the Implementation steps in the Module SQL file section, then all you need to do is ensure that the your PHP scripts are located in your primary Freemed-YiRC directory.

For our example there should be two scripts:

  • clock.php
  • clock_settings.php

Allowing Users Access

The final step to allowing users access to the new module is to give them the proper Security Database permissions. If you proceed to modify a given users permissions in the Security Database, you should now see a new section for your new module, along with the Security Database permissions you specified.

You must go through each and every user you wish to have this access and apply these permissions.


Example Process

For our example module, you should have a new section in the Security Database titled View System Time which has two permissions: Access and Edit. If you click the help link next to each of these you should see the help text you specified in the module SQL file. Give yourself ONLY Access permission and hit Update. Return to your main menu. You should now have a new menu option on your menu, View System Time. Click it. It should simply display the time. The time will not update, it is static as of the time the script was run. Otherwise you should only see a BACK link. Click it. Now go back into the Security Database and give yourself Edit permission for your module. Return to your main menu and click on View System Time. You should now see a link for Edit Settings. Click it. You should see a drop down list for Format. The options should be AM/PM Format and 24-Hour Military Format. It should already be set to AM/PM Format. Change it to 24-Hour Military Format and hit the Update button. You should see a message stating Clock Settings Updated!. Hit the Back link. You should now see the time in 24-hour format.

Your first module is functional!


Allowing Group Access

If your module uses menu entries for group menus, then you must go into the Group Database and Modify each group you wish to have access to add this new module. The new module should appear in the list of modules at the bottom of the Modify screen.

Remember, for group menu items, BOTH the group AND the user must have access before the menu option will show up!!!


Adding Module/Help/Documentation Info To The Freemed-YiRC Wiki

If you intend on making your new module available for others to use or would like to make use of the help features on the Freemed-YiRC Wiki, there are several steps which need to be completed. This is highly recommended as it has the potential for community input. What does this mean? It means that others who use your module may be willing to provide additional documentation for your module... by means of additional text, hints & tricks, and/or other helpful information for others to use. This is the purpose of this wiki, and nearly every other wiki in existence.


Adding Module/Permission Documentation

Module Help/Documentation

The first Freemed-YiRC wiki article you create should be the module's main wiki page. This is important, if for nothing else than putting a claim on your module abbreviation so that others will not use it in the future. It is a core tenant of Freemed-YiRC that each module have a unique module abbreviation! When you create a new Freemed-YiRC module, you should always first check the Freemed-YiRC wiki Modules Index to determine if the module abbreviation you wish to use is available or not. If not, please choose a different, unique, abbreviation! Then claim that abbreviation by creating a page for the new module.

  • First, log into Freemed-YiRC and go into User Administration.
  • Choose a user then click Modify in the Security Permissions column.
  • Find the section for your module.
  • Click the help link to the right of the module name heading (the question mark in square brackets).
  • Clicking this will open a new window and, depending on how your Freemed-YiRC is set up, it will either bring up the internal help screen for that module or it will take you directly to the Freemed-YiRC wiki page for that module.
    • If it brings up the internal help screen, there should be a link to the Freemed-YiRC wiki, click that.
  • Unless there is already a wiki page created for your module, the wiki should present you with a blank article and give you a link to edit it.
  • Unless you have created a wiki page for modules before, it is suggested you copy and paste and existing module wiki page and edit it with the appropriate information.
    • A good example to copy from would be the Contact Database Module Page. Click edit at the top and then copy the page text/code.
    • Go back to your blank module page, click edit and then paste the code.
    • Modify the page to be appropriate to your module.
      • At the very minimum, you should have:
        • The page title as the first line (the line surrounded by the big element tags).
        • The Table Of Contents (TOC surrounded by underscores).
        • The Summary section which explains what your module is for.
        • The Other Modules This Module Interacts With. If your module is truly standalone, then simply state None in that section.
        • The Module History section. At minimum it should contain the date the module was created (month and year is fine), and the module author's name. Creating a wiki article for the author and linking to that article is recommended, but not required. Creating a page for the author would allow people to see other modules by this module author.
        • One or more index links as the very last line. Required is the Category:Modules link. If the module is fairly complicated and may have many wiki pages about it (i.e., permissions, script help pages, and/or other assorted documentation), then another index can be created specifically for this modules documentation. For example, since the Contact Database is a very large module, it has it's own index titled Category:Module-CON, where CON is the module abbreviation for the Contact Database. Your module index should follow this same format, i.e., Category:Module-XXX, where XXX is your module abbreviation. Your module abbreviation was specified in the record you created in the fy_modules database table. Your module abbreviation will be in the mod_abbr field of the fy_modules database table. MODULE ABBREVIATIONS ARE ALWAYS UPPER-CASE!


Module Permission Help/Documentation

The next thing you need to do is to create a wiki page for each of the Security Database permissions your module has created. This is usually somewhat easier than the above step because, in theory, you've already created the description of each permission when you created the records for the fy_secdb_perms database table. The pertinent information is in the perm_helptext database field. You'll simply be setting up a new page for each permission by copying and pasting the page text from an existing module permission wiki page, then copying and pasting the text from the perm_helptext field in the fy_secdb_perms database table into this new page.

  • In the same page in Freemed-YiRC as in the above section, the Security Permissions portion of the User Administration module, click on the question mark in square brackets to the right of the first permission for your module.
  • Unless there is already a page for this security permission, you should be presented with a blank article and a link to edit it. Do so (click edit).
  • Open a new window and find an existing module permission and click edit to see the wiki text for that page.
    • A good example page to start from would be the E-Mail - Access permission page. Copy the text from this page (after clicking edit), then close the window for this article.
  • Paste the contents of the existing module permission page to your new module permission page (which should be blank).
  • Edit the first line, which should be the article title header, which should be surrounded by the big element tags. The format for this line should be consistent: 
    • <big>'''Freemed-YiRC: ''MODULE_NAME-MODULE_PERMISSION_NAME_SHORT_DESCR (MODULE_PERMISSION_NAME)'' Security Permission Help Page'''</big>
    • Where:
      • MODULE_NAME = The name of your module, this should be the text that's in the fy_modules database table record for the module in the mod_fullname field.
      • MODULE_NAME-MODULE_PERMISSION_DESCR = The module permission description text that's in the fy_secdb_perms database table record for the module permission in the perm_descr field.
      • MODULE_PERMISSION_NAME = The module permission name text that's in the fy_secdb_perms database table record for the module permission in the perm_name field.
  • The body text of the wiki page should contain what's in the perm_helptext field in the fy_secdb_perms database table record.
    • This is the just bare minimum required text. You can feel free to make this page contain as much information as you wish in addition to the perm_helptext text.
  • The last line(s) of the wiki page text should contain links to one or more documentation indexes.
    • At the very minimum there must be a link to the Category:Permissions index.
    • If you created an index specific to this module in the modules main help page (created in the previous step), then add a link to that index as well. Again, the format for the link should be similar to Category:Module-MODULE_ABBR.

Repeat these steps for each and every security permission in your module

Adding Menu Specific Documentation

On every single menu/script/page of your module there is a question mark/help link in the upper-right hand corner of the Freemed-YiRC window. When a user clicks on this a new window will open and either show the contents of the help text (if it has been created) contained in the Freemed-YiRC internal help system (with a link to the wiki), or it will direct the user to the Freemed-YiRC wiki page for that specific menu. If the Freemed-YiRC wiki page does not already exist, it can be created.

Not every single menu/script/page requires help text. However, it is recommended that at least the main page of your module has a help page, even if that page just contains a link re-directing a user to the main module help page page you created previously. It is up to you to decide if a given module script/page needs its own help page and to provide the text for that page.

Again, the process for creating the help page for that menu/script/page is similar to the above previous steps. Find an existing help page from the Menus Documentation Index list and copy and paste the contents into your new page (look at the E-Mail Main Menu page for an example). Then edit the contents accordingly. Please follow the same rough format to keep the page consistent with other menu help pages. Ensure that that the last line contains a link to the Category:Menus index so that your menu help page will be indexed properly.

Adding Additional Documentation

You may create as many wiki articles as you see fit (with reasonable limits) in the Freemed-YiRC wiki for your module. If you wish to create additional pages above and beyond what has been described in the above sections, you need to take one item into consideration: how will users find the article? The simple solution is make sure you link to that page from one of the above pages. The primary way to do this is to provide a link on the module help page and/or the main script menu help page. If users can't find your documentation, will it ever help anyone?

A big recommendation, regardless of the size of your module, is to create a Technical Information article for your module. This page should contain a description of the database tables your module uses (if applicable), and possibly a list of the file names of the module scripts. For an example of this, check out the Contact Database Technical Information wiki page. This is helpful, especially in terms of database tables, as it provides other developers an idea of how your data links are set up... not just for internal module usage, but for links to other data sources in the Freemed-YiRC system (i.e., other modules' database tables).

I recommend the Astah (formerly called Jude) software package for creating database table diagrams. The community version is free. It's written in Java so it can be used with many common operating systems (Linux, Windows, MacOS, etc...). In the past I've also used the Umbrello UML Modeller software. However, Umbrello is mostly limited to Linux (unless KDE software is installed on Windows and/or Mac). Both have their pros and cons, but I moved to Astah (formerly Jude) because of it can be used on multiple different operating systems.

Other software can be used as well, including Microsoft Visio, SmartDraw, etc... however these software packages are not free. Also keep in mind that consistency is a big goal for the Freemed-YiRC wiki, and all diagrams to date have been created with either Jude or Umbrello.

Additional Reading

Retrieved from "http://www.freemed-yirc.com/freemed-yirc/wiki/index.php/Module_Programming_Guide:_FMYiRC_V1.00"
Personal tools