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 will look something like this: 

<?php
        # Freemed-YiRC (C)2000-2007 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); 
$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_startwindow($SCRIPT_NAME);

fy_winprn("CENTER","","<B>View System Time</B>"); 
fy_winprn("CENTER","","<BR>");

$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")
{
        fy_winprn("CENTER","","<BR>");
        fy_winprn("CENTER","","<a href=\"clock_settings.php\">Edit Settings</a>");
}

fy_winprn("CENTER","","<BR>");
fy_winback("","main.php");

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

?>

In essence, this script does the following:

  • 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
    • - Provides project name and copyright information, including licenseing information
    • - 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.
    • - Includes the Freemed-YiRC system variables and primary functions.
    • - Performs security checks on cookies.
    • - Creates a database connection.
    • - Checks to ensure we have the property security permission to run this script.
    • - Checks to see if we have any other permissions.
    • - Displays starting HTML code
    • - Creates a Freemed-YiRC menu screen with title and navigation icons
      • - 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.
    • - Retrieves the time display format setting
    • - Displays the time according to this setting
    • - If the user has the edit permission, provide a link to an Edit Settings page.
  • 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
    • - Ends the Freemed-YiRC menu window.
    • - Displays ending HTML code.
    • - Ends the PHP script.


Example PHP Script #2

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

<?php
        # Freemed-YiRC (C)2000-2007 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);

$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_starthtml("Freemed-YiRC", "");
fy_startwindow($SCRIPT_NAME);

fy_winprn("CENTER","","<b>View System Time<br />Edit Settings</b>");
fy_winprn("CENTER","","<br />");

if ($fy_edit!="X")
{
        # ---Start Form---
        echo "<tr><td>";
        echo "<form action=\"clock_settings.php?fy_edit=X\" name=\"form\" method=\"post\">";
        echo "</td></tr>\n";

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

        echo "<tr><td>\n";
        echo "Format: ";
        echo "<select name=\"gr_clock_time_type\">\n";
        if ($fy_time_setting=="standard") {$fy_sel="SELECTED";} else {$fy_sel="";}
        echo "<option value=\"standard\" $fy_sel>AM/PM Format</option>\n";
        if ($fy_time_setting=="military") {$fy_sel="SELECTED";} else {$fy_sel="";}
        echo "<option value=\"military\" $fy_sel>24-Hour Military Format</option>\n";
        echo "</select>\n";
        echo "</tr></td>\n";

        # ---Submit & Reset---
        echo "<tr><td align=\"center\">";
        echo "<input type=\"submit\" value=\"Update\">";
        echo "</td></tr>\n";
        # ---End Form---
        echo "<tr><td>";
        echo "</form>";
        echo "</td></tr>\n";

        fy_winprn("CENTER","","<br />");
        fy_wincancel("","clock.php");
} else {         $sql = "UPDATE fy_clock_settings SET clock_time_type=\"".$gr_clock_time_type."\"";
        $result_set=fy_execsql($fydb_type, $fydb_name, $conn, $sql);

        fy_winprn("CENTER","","Clock Settings Updated!");

        fy_winprn("CENTER","","<br />");
        fy_winback("","clock.php");
}

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

?>

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.


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 and 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!!!

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