Joomla! 1.0 component tutorial - part 2: back-end
Part 2 of the component tutorial explaines all files creating backend interface for my sample JPortfSimple component:
  1. admin.jportfsimple.php
  2. admin.jportfsimple.html.php
  3. toolbar.jportfsimple.php
  4. toolbar.jportfsimple.html.php
  5. install.jportfsimple.php
  6. uninstall.jportfsimple.php
  7. jportfsimple.xml
which are placed in administrator/components/com_jportfsimple folder during installation.
Well, .xml file was explained earlier (see p. 4).

7. Backend

Similarly to frontend, one file is responsible for "logic" of the component (it's backend interface) - admin.jportfsimple.php, and second file is displaying the information (admin.jportfsimple.html.php).

admin.jportfsimple.php
  1. // no direct access
  2. defined('_VALID_MOS') or die('Direct Access to this location is not allowed.');
  3.  
  4. // ensure user has access to this function
  5. if (!($acl->acl_check( 'administration', 'edit', 'users', $my->usertype, 'components', 'all' )
  6.   | $acl->acl_check( 'administration', 'edit', 'users', $my->usertype, 'components', 'com_jportfsimple' ))) {
  7.   mosRedirect( 'index2.php', _NOT_AUTH );
  8. }
  9. global $mosConfig_live_site, $mosConfig_absolute_path, $mosConfig_lang, $mosConfig_list_limit;
  10.  
  11. // load .class.php and .html.php files for the component
  12. require_once( $mainframe->getPath( 'admin_html' ) );
  13. require_once( $mainframe->getPath( 'class' ) );
  14.  
  15. // get task and act from request
  16. $task   = trim( mosGetParam( $_REQUEST, 'task', '' ));
  17. $act   = trim( mosGetParam( $_REQUEST, 'act', '' ));
  18.  
  19. // get selected objects
  20. $id = josGetArrayInts( 'cid' );
  21.  
  22. // load language file
  23. if (file_exists( $mosConfig_absolute_path.'/components/com_jportfsimple/lang/'.$mosConfig_lang.'.php'))
  24.       include_once( $mosConfig_absolute_path.'/components/com_jportfsimple/lang/'.$mosConfig_lang.'.php');
  25.    else
  26.    if (file_exists( $mosConfig_absolute_path.'/components/com_jportfsimple/lang/english.php'))
  27.       include_once( $mosConfig_absolute_path.'/components/com_jportfsimple/lang/english.php');
  28.  
  29.   // get configuration parameters
  30.   $database->setQuery('SELECT * FROM #__jportfsimple_conf'  );
  31.   $conf_rows = $database -> loadObjectList();
  32.   if ($database -> getErrorNum()) {
  33.     echo $database -> stderr();
  34.     return false;
  35.   }
  36.   if ($conf_rows) {
  37.     $jpConf = $conf_rows[0];
  38.     $base_path = $jpConf->base_path;
  39.   }

First part of frontend file does the following:

lines 12 to 16 - acl check - does logged in user has access to the component ?

19 to 21 - loads the required class and backend html (admin.jportfsimple.html.php) files

23 to 28 - gets variables defining what to do ($act, $task) and with which object ($id)

30 to 35 - loads language file, default is english.php in com_jportfsimple/lang folder

37 to 47 - reads data from database table containing configuration parameters. They are stored in $jpConf object, and location of images in $base_path


Main backend "logic":

admin.jportfsimple.php
  1. switch( $act )
  2. {
  3.   case 'configure':
  4.   switch($task) {
  5.     case 'save':
  6.     Conf_save( $option );
  7.     break;
  8.     default:
  9.     Conf_list( $option );
  10.     break;
  11.   }
  12.   break;
  13.  
  14.   case 'categories':
  15.   switch ($task) {
  16.     case 'save' :
  17.       Cat_save( $option );
  18.       break;
  19.     case 'cancel' :
  20.       Cat_cancel( $option, $act);
  21.       break;
  22.     case 'edit' :
  23.         Cat_edit( $option, $id );
  24.       break;
  25.     case 'new' :
  26.       $id = '';
  27.       Cat_edit( $option, $id );
  28.       break;
  29.     case 'delete' :
  30.       Cat_del( $option, $id );
  31.       break;
  32.     case 'publish' :
  33.       Cat_publish( $option, '1', $id );
  34.       break;
  35.         case 'unpublish' :
  36.       Cat_publish( $option, '0', $id );
  37.       break;
  38.     case 'orderup':
  39.       ordercat( intval( $id[0] ), -1, $option, $act );
  40.       break;
  41.     case 'orderdown':
  42.       ordercat( intval( $id[0] ), 1, $option, $act );
  43.       break;
  44.      
  45.     default:
  46.       Cat_list($option);
  47.       break;
  48.    
  49.     }
  50.   break;
  51.    
  52.   case 'projects':
  53.   switch ( $task ) {
  54.     case 'save' :
  55.       Proj_save( $option );
  56.       break;
  57.     case 'cancel' :
  58.       Proj_cancel( $option, $act);
  59.       break;
  60.     case 'edit' :
  61.       Proj_edit( $option, $id );
  62.       break;
  63.     case 'new' :
  64.       $id = '';
  65.       Proj_edit( $option, $id );
  66.       break;
  67.     case 'delete' :
  68.       Proj_del( $option, $id );
  69.       break;
  70.     case 'publish' :
  71.       Proj_publish( $option, '1', $id );
  72.       break;
  73.     case 'unpublish' :
  74.       Proj_publish( $option, '0', $id );
  75.       break;
  76.     case 'orderup':
  77.       orderproj( intval( $id[0] ), -1, $option, $act );
  78.       break;
  79.     case 'orderdown':
  80.       orderproj( intval( $id[0] ), 1, $option, $act );
  81.       break;
  82.      
  83.     default:
  84.       Proj_list( $option );
  85.       break;
  86.   }
  87.   break;
  88.  
  89.  
  90. case 'info':
  91.   HTML_jportfsimple::Info( $option );
  92.   break;
  93.  
  94. default:
  95.  
  96. break;
  97. }

Variable $act get it's value from chosen menu. You remember this part of xml file:

  • <menu>jportfsimple</menu>
  •   <submenu>
  •     <menu act="categories">Categories</menu>
  •     <menu act="projects">Projects</menu>
  •     <menu act="configure">Configuration</menu>
  •     <menu act="info">About</menu>
  •   </submenu>

So for example, if Categories was clicked, $act would be 'categories', and then variable $task will be checked (line 64). Initially $task is empty, so the default action is performed: function Cat_list in line 95. Other functions are called when you click toolbar buttons.

Configuration saving function:

admin.jportfsimple.php
  1. /**
  2. * Configuration saving
  3. */
  4. function Conf_save( $option )
  5. {
  6.   global $database,$mosConfig_absolute_path, $jfiles;
  7.  
  8.   // no . in path, and must end in slash
  9.   if (!(strpos($_POST['base_path'],'..')===FALSE)) { $err2=_COM_JP_ERROR; $_POST['base_path']='images/stories/'; }
  10.   if (substr($_POST['base_path'],-1,1)!=='/') $_POST['base_path']=$_POST['base_path'].'/';
  11.  
  12.   $row = new jportfsimpleConf($database);

  14.   // bind it to the table
  15.   if (!$row -> bind($_POST)) {
  16.     echo "<script> alert('".$row->getError()."'); window.history.go(-1); </script>\n";
  17.     exit();
  18.   }
  19.   // store it in the db
  20.   if (!$row -> store()) {
  21.     echo "<script> alert('".$row->getError()."'); window.history.go(-1); </script>\n";
  22.     exit(); 
  23.   }
  24.  
  25.   mosRedirect( 'index2.php?option='.$option.'&act=configure', 'Configuration Saved'.$err2 );
  26. }

Function called after editing configuration parameters, when "Save" is clicked.

First some specific for this component checks - if base_path variable containes two dots, then it's changed to default one; if it does not end with slash, one is added.

Lines 159 to 172 - whichever object in Joomla! is being saved (from those defined in .class file) similar actions are performed:

  • new object is created (line 159)
  • bind - copies values from $_POST to the above object - if for example you have a field in a form with a name which is not in object's class, then this part will throw an error (line 162)
  • storing to database - here also an error may show up, if for example you added field to .class file, but you didn't update database table
  • if no errors, then component redirects to the page depending on act variable in mosRedirect function, with nice message "Configuration Saved"
Configuration listing function:

admin.jportfsimple.php
  1. /**
  2. * Configuration listing
  3. */
  4. function Conf_list( $option )
  5. {
  6.  
  7.   HTML_jportfsimple::Conf_list( $option );
  8.   HTML_jportfsimple::bottom();
  9. }

It just calls display function, since configuration data is already in $jpConf variable (see line 45).

Function publishing a category:

admin.jportfimple.php
  1. /**
  2. * Category publishing
  3. */
  4. function Cat_publish( $option, $publish=1 ,$cid )
  5. {
  6.   global $database, $my;
  7.   if (!is_array( $cid ) || count( $cid ) < 1) {
  8.     $action = $publish ? 'publish' : 'unpublish';
  9.     echo "<script> alert('Select an item to $action'); window.history.go(-1);</script>\n";
  10.     exit;
  11.   }
  12.   $cids = implode( ',', $cid );
  13.   $database->setQuery( 'UPDATE #__jportfsimple_categories SET published='.$publish.' WHERE id IN ('.$cids.')');
  14.  
  15.  
  16.   if (!$database->query()) {
  17.     echo "<script> alert('".$database->getErrorMsg()."'); window.history.go(-1); </script>\n";
  18.     exit();
  19.   }
  20.   mosRedirect( 'index2.php?option='.$option.'&act=categories' );
  21. }

First it checks if at least one category is checked (line 192), if not - it displays popup window with error message (this is one exeption of the rule to not use output commands in this file). Then it runs a query to update 'published' column in jos_jportfsimple_categories table (line 198), and if no errors (line 201) it redirects back to categories page.

Category saving function:

admin.jportfsimple.php
  1. /**
  2. * Category saving
  3. */
  4. function Cat_save( $option )
  5. {
  6.   global $database;
  7.   $row = new jportfsimpleCategories($database);
  8.   // bind it to the table
  9.   if (!$row -> bind($_POST)) {
  10.     echo "<script> alert('".$row->getError()."'); window.history.go(-1); </script>\n";
  11.     exit();
  12.   }
  13.   // store it in the db
  14.   if (!$row -> store()) {
  15.     echo "<script> alert('".$row->getError()."'); window.history.go(-1); </script>\n";
  16.     exit(); 
  17.   }
  18.   $row->updateOrder();
  19.   mosRedirect( 'index2.php?option='.$option.'&act=categories', 'Saved' );
  20. }

As you see, it's almost the same as configuration saving function earlier, just one additional function updating order of all categories (line 225).

Category deleting function:

admin.jportfsimple.php
  1. /**
  2. * Category deleting
  3. */
  4. function Cat_del( $option, $cid )
  5. {
  6.   global $database;
  7.   if (!is_array($cid) || count($cid) < 1) {
  8.     echo "<script> alert('Select an item to delete'); window.history.go(-1);</script>\n";
  9.     exit();
  10.   }
  11.   if (count($cid))
  12.   {
  13.     $ids = implode(',', $cid);
  14.     $database->setQuery('DELETE FROM #__jportfsimple_categories WHERE id IN ('.$ids.')');
  15.   }
  16.   if (!$database->query()) {
  17.     echo "<script> alert('".$database->getErrorMsg()."'); window.history.go(-1); </script>\n";
  18.   }
  19.   mosRedirect( 'index2.php?option='.$option.'&act=categories' );
  20. }

Similar to category publishing function, just different query is used (line 242).


Category editing function. As you perhaps noticed (line 72 and 76), the same function is used for creating new category and for editing existing one.

admin.jportfsimple.php
  1. /**
  2. * Category editing
  3. */
  4. function Cat_edit( $option, $uid )
  5. {
  6.   global $database;
  7.  
  8.   // build the html select list for ordering
  9.   $query = 'SELECT ordering AS value, cat_name AS text FROM #__jportfsimple_categories ORDER BY ordering';
  10.   $lists['ordering'] = mosAdminMenus::SpecificOrdering( $row, $uid, $query, 1 );
  11.  
  12.   $row = new jportfsimpleCategories($database);
  13.   if($uid){
  14.     $row -> load($uid[0]);
  15.   }
  16.  
  17.   HTML_jportfsimple::Cat_edit( $option, $row, $lists );
  18. }

Lines 258, 259 are needed only if you want to be able to change order of categories during editing. You would also need 'ordering' field in database table. Actual category editing part is in lines 261 to 266: first new object is needed ($row), then if it is in fact editing of an existing category ($uid is not empty) load function loads it from the database. Finally, edit page is displayed (line 266).

Cancellation of editing:

admin.jportfsimple.php
  1. /**
  2. * Category editing cancel
  3. */
  4. function Cat_cancel( $option, $act )
  5. {
  6.  
  7.   mosRedirect( 'index2.php?option='.$option.'&act='.$act );
  8. }

Just redirecting after pressing "Cancel".

Category listing:

admin.jportfsimple.php
  1. /**
  2. * Category listing
  3. */
  4. function Cat_list( $option )
  5. {
  6.   global $database, $mainframe, $mosConfig_absolute_path, $mosConfig_list_limit;
  7.  
  8.   $limit     = intval( $mainframe->getUserStateFromRequest( 'viewlistlimit', 'limit', $mosConfig_list_limit ) );
  9.   $limitstart = intval( $mainframe->getUserStateFromRequest( "view{$option}limitstart", 'limitstart', 0 ) );
  10.   require_once( $mosConfig_absolute_path . '/administrator/includes/pageNavigation.php' );
  11.  
  12.   $query = 'SELECT COUNT(*) FROM #__jportfsimple_categories';
  13.   $database->setQuery( $query );
  14.   $total = $database->loadResult();
  15.  
  16.   $pageNav = new mosPageNav( $total, $limitstart, $limit  );
  17.  
  18.   $database->setQuery('SELECT * FROM #__jportfsimple_categories ORDER BY ordering LIMIT '.$pageNav->limitstart.', '.$pageNav->limit );
  19.   $rows = $database -> loadObjectList();
  20.   if ($database -> getErrorNum()) {
  21.     echo $database -> stderr();
  22.     return false;
  23.   }
  24.  
  25.   HTML_jportfsimple::Cat_list( $option, $rows, $pageNav );
  26.   HTML_jportfsimple::bottom();
  27. }

Main function listing all categories.

Lines 285 to 287 - gets current page and number of categories per page, selected by user, and loads required class

289 to 291 - first query, loading just the total number of existing categories (SELECT COUNT), needed for pagination

293 - creates new $pageNav object

295 to 300 - second query, loading just the categories on current page

302, 303 - displaying functions are called


Project functions next are very similar to the above function dealing with categories.  I will list only main differences instead of full rest of the code.

In Proj_publish, Proj_save and Proj_del (project publishing, saving and deleting functions) redirecting function in last line goes to projects page:

admin.jportfsimple.php
  1. mosRedirect( 'index2.php?option='.$option.'&act=projects' );

Project editing function:

admin.jportfimple.php
  1. /**
  2. * Project editing
  3. */
  4. function Proj_edit( $option, $uid )
  5. {
  6.   global $database, $base_path;
  7.   $proj = new jportfsimpleProjects($database);
  8.   if($uid)
  9.   {
  10.     $proj -> load($uid[0]);
  11.   }
  12.   else $proj->date = date( 'Y-m-d H:i:s' ); // creation date, 2006-09-01 10:00:00
  13.  
  14.   $database->setQuery('SELECT * FROM #__jportfsimple_categories ORDER BY cat_name');
  15.   $rows = $database -> loadObjectList();
  16.   if ($database -> getErrorNum()) {
  17.     echo $database -> stderr();
  18.     return false;
  19.   }
  20.  
  21.   foreach ($rows as $row) { $urow2[]=$row->id; $urow[]=$row->cat_name; }
  22.    
  23.   $i=0; $j=0;  //$j  for Select category text in case of new item
  24.   if (!$uid)
  25.   {
  26.     $categories[$i] = mosHTML::makeOption( '0', _COM_JP_SEL_ALBUM );
  27.     $i++; $j=1;
  28.   }
  29.   if (count($rows)>0)
  30.     foreach ($urow as $row)
  31.     {
  32.       $categories[$i] = mosHTML::makeOption( $urow2[$i-$j], $urow[$i-$j]);
  33.       $i++;   
  34.     }
  35.   $size=1;
  36.  
  37.   $javascript = '';
  38.  
  39.   $category = mosHTML::selectList( $categories, 'catid', 'class="inputbox" size="'. $size .'" '. $javascript, 'value', 'text', $proj->catid );
  40.   $lists['category'] = $category;
  41.  
  42.   // build the html select list for ordering
  43.   $query = 'SELECT ordering AS value, name AS text '
  44.   . ' FROM #__jportfsimple_projects'
  45.   . ' WHERE catid = '.$proj->catid
  46.   . ' ORDER BY ordering';
  47.   $lists['ordering'] = mosAdminMenus::SpecificOrdering( $proj, $uid, $query, 1 );
  48.  
  49.   foreach ($rows as $c) { $c2[$c->id]=$c;  }
  50.  
  51.   HTML_jportfsimple::Proj_edit( $option, $proj, $base_path, $c2, $lists);
  52. }

Lines 376 to 380 - if editing existing project, load it's data, or set a creation date for new project

382 to 408 - this part is used to create a list of categories in HTML select form, for easier selecting a category the project should belong to, instead of entering a category name manually. The challenge here is to select a name, but return a category id. First it gets list of categories, then it creates a $categories array with HTML code for select function, with category id and a name (lines 389 - 402), finally it finishes HTML preparation. It uses functions from Joomla's mosHTML class.

410 to 415 - builds another HTML select list, this one for ordering of a project

419 - calles display function


Project listing function is also similar to category listing, added is the above code for creating HTML select function for filtering projects by a category.

Last two functions: ordercat and orderproj - are used whenever reorder arrow is clicked.

admin.jportfsimple.php
  1. /**
  2. * Category ordering
  3. */
  4. function ordercat( $uid, $inc, $option, $act )
  5. {
  6.   global $database;
  7.  
  8.   $row = new jportfsimpleCategories( $database );
  9.   $row->load( $uid );
  10.   $row->updateOrder();
  11.   $row->move( $inc, 'published >= 0' );
  12.   $row->updateOrder();
  13.    
  14.   mosRedirect( 'index2.php?option='. $option .'&act='. $act);
  15. }

This is nothing else like using internal Joomla function (updateOrder in this case) to reorder objects.


Now the display file - admin.jportfsimple.html.php - which displays the information provided by the "logic" file, earlier, or shows forms and input fields to enter new information.

All backed functions are members of HTML_jportfsimple class:

admin.jportfsimple.html.php
  1. // no direct access
  2. defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
  3.  
  4.  
  5. class HTML_jportfsimple{

Configuration listing function is an example of using tabs, and also editor:

admin.jportfsimple.html.php
  1. /**
  2. * Configuration listing
  3. */
  4. function Conf_list( $option )
  5. {
  6.   global $jpConf;
  7. ?>
  8.  
  9. <script language="javascript" type="text/javascript">
  10.         function submitbutton(pressbutton) {
  11.                 <?php getEditorContents( 'editor', 'description' ); ?>
  12.                 submitform( pressbutton );
  13.         }
  14. </script>
  15.  
  16. <script language="Javascript" src="js/dhtml.js"></script>
  17.  
  18. <table class="adminheading">
  19.     <tr>
  20.       <th><?php echo _COM_JP_CONFIG_INFO ?></th>
  21.     </tr>
  22. </table>
  23.  
  24. <table cellpadding="4" cellspacing="0" border="0" width="100%">
  25. <tr>
  26. <td width="5%" class="tabpadding"> </td>
  27. <td id="tab1" class="offtab" onClick="dhtml.cycleTab(this.id)">Settings</td>
  28. <td id="tab2" class="offtab" onClick="dhtml.cycleTab(this.id)">CSS</td>
  29. <td width="5%" class="tabpadding"> </td>
  30. </tr>
  31. </table>
  32.  
  33. <form action="index2.php" method="post" name="adminForm">
  34. <div id="page1" class="pagetext">
  35.  
  36. <table cellpadding="4" cellspacing="0" border="0" width="90%" class="adminlist">
  37. <tr>
  38.   <th class="title" width="10%"><?php echo _COM_JP_CONFIG_PARAMETER ?></th>
  39.   <th class="title" width="20%"><?php echo _COM_JP_CONFIG_VALUE ?></th>
  40.   <th class="title"><?php echo _COM_JP_CONFIG_DESCR ?></th>
  41. </tr>
  42.  
  43. <tr>
  44.   <td><?php echo _COM_JP_CONFIG_BASEPATH ?>    </td>
  45.   <td><input size="30" name="base_path" value="<?php echo $jpConf->base_path; ?>"> </td>
  46.   <td><?php echo _COM_JP_CONFIG_BASEPATH_DESCR ?> </td>
  47. </tr>
  48.  
  49. <tr>
  50.   <td><?php echo _COM_JP_CONFIG_TITLE ?>    </td>
  51.   <td><input size="30" name="title" value="<?php echo $jpConf->title; ?>"> </td>
  52.   <td><?php echo _COM_JP_CONFIG_TITLE_DESCR ?> </td>
  53. </tr>
  54.  
  55. <tr>
  56.   <td valign="top" ><?php echo _COM_JP_CONFIG_FRONT_DESCR ?>    </td>
  57.   <td  align="center" colspan="2">
  58.   <?php
  59.     editorArea( 'editor',  $jpConf->description , 'description', '600', '220', '60', '40' ) ;
  60.   ?>
  61.   </td>
  62. </tr>
  63. </table>
  64. </div>
  65.  
  66. <div id="page2" class="pagetext">
  67.  
  68. <table cellpadding="4" cellspacing="0" border="0" width="90%" class="adminlist">
  69.  
  70. <tr>
  71.   <th class="title" width="10%"><?php echo _COM_JP_CONFIG_PARAMETER ?></th>
  72.   <th class="title" width="20%"><?php echo _COM_JP_CONFIG_VALUE ?></th>
  73.   <th class="title"><?php echo _COM_JP_CONFIG_DESCR ?></th>
  74. </tr>
  75.  
  76. <tr>
  77.   <td valign="top" ><?php echo _COM_JP_CONFIG_CSS ?>    </td>
  78.   <td><input size="30" name="css_file" value="<?php echo $jpConf->css_file; ?>"> </td>
  79.   <td valign="top" ><?php echo _COM_JP_CONFIG_CSS_DESCR ?>    </td>
  80. </tr>
  81. </table>
  82. </div> 
  83.  
  84. <input type="hidden" name="option" value="<?php echo $option; ?>" />
  85. <input type="hidden" name="task" value="" />
  86. <?php if ($jpConf->id) { ?>
  87. <input type="hidden" name="id" value=<?php echo $jpConf->id ?> />
  88. <?php } ?>
  89. <input type="hidden" name="act" value="configure" />
  90. </form>
  91.  
  92. <script language="javascript" type="text/javascript">dhtml.cycleTab('tab1');</script>
  93.  
  94. <?php
  95. }

Lines 38 to 43 - are required for using WYSIWYG editor in a form (actually to get back the content of an editor). Editor is loaded in line 88. Notice the name of the editor field: 'editor' - if you'd like to use more than one editor, their names should be unique.

45 - this is needed for tabs. Their displayed names are defined in lines 56, 57, first open tab is defined in line 121, and then each tab content is displayed within a div. So here:

tab1 - name: Settings, div id=page1 (line 63, 93)

tab2 - name: CSS,  div id=page2 (line 95, 111)

As you see, each input field must have it's name, which must be the same as defined in class file, depending on object which is edited.

The "hidden" fields (lines 113 to 118) are used to pass other variables, like $option or $act, so the backend "knows" where to go after you press "Save". Variable $task is empty initially - it's value is assigned when actual button in pressed. Variable $id is needed so the right record is saved. In case of configuration there is always only 1 record.

Categories listing function:

admin.jportfsimple.html.php
  1. /**
  2. * Category listing
  3. */
  4. function Cat_list( $option, &$rows, &$pageNav )
  5. {
  6. ?>
  7.  
  8. <form action="index2.php" method="post" name="adminForm">
  9.  
  10. <table class="adminheading">
  11.     <tr>
  12.       <th><?php echo _COM_JP_ALBUMS_INFO ?></th>
  13.     </tr>
  14. </table>
  15.  
  16. <table cellpadding="4" cellspacing="0" border="0" width="100%" class="adminlist">
  17. <tr>
  18.   <th width="20"><input type="checkbox" name="toggle" value="" onclick="checkAll(<?php echo count($rows); ?>);" /></th>
  19.   <th class="title" width="20%"><?php echo _COM_JP_ALBUM_NAME ?></th>
  20.   <th class="title"><?php echo _COM_JP_ALBUM_PATH ?></th>
  21.   <th class="title"><?php echo _COM_JP_ALBUM_INFO ?></th>
  22.   <th width="5%"colspan="2" align="center"><?php echo _COM_JP_ORDER; ?></th>
  23.   <th width="7%"></th>
  24.   <th width="7%"><?php echo _COM_JP_CONFIG_PUBLISHED; ?> </th>
  25. </tr>
  26.  
  27. <?php
  28. if (count($rows)<1) echo '<tr><td colspan="8" ><center><b>'._COM_JP_NO_CAT.'</b></center></td></tr>';
  29.  
  30.   $k = 0;
  31.   for ($i=0, $n=count( $rows ); $i < $n; $i++)
  32.   {
  33.   $row = &$rows[$i];
  34.  
  35. ?>
  36. <tr class="<?php echo "row$k"; ?>">
  37.   <td><input type="checkbox" id="cb<?php echo $i;?>" name="cid[]" value="<?php echo $row->id; ?>" onclick="isChecked(this.checked);" /></td>
  38.   <td><a href="#edit" onclick="hideMainMenu();return listItemTask('cb<?php echo $i;?>','edit')"><?php echo $row->cat_name; ?></a></td>
  39.   <td><?php echo $row->cat_path; ?></td>
  40.   <td><?php echo substr($row->cat_info,0,30); ?></td>
  41.   <td>
  42.   <?php echo $pageNav->orderUpIcon( $i, 1 ); ?>
  43.   </td>
  44.   <td>
  45.   <?php echo $pageNav->orderDownIcon( $i, $n, 1 ); ?>
  46.   </td>
  47.   <td>
  48.   </td>
  49.   <td align="center">
  50. <?php
  51.   if ($row->published == "1") {
  52.   echo "<a href=\"javascript: void(0);\" onClick=\"return listItemTask('cb$i','unpublish')\"><img src=\"images/publish_g.png\" border=\"0\" /></a>";
  53.   } else {
  54.   echo "<a href=\"javascript: void(0);\" onClick=\"return listItemTask('cb$i','publish')\"><img src=\"images/publish_x.png\" border=\"0\" /></a>";
  55.   }
  56. ?>
  57.   </td>
  58. <?php $k = 1 - $k; ?>
  59. </tr>
  60.  
  61. <?php
  62.   }
  63. ?>
  64.  
  65. </table>
  66. <?php echo $pageNav->getListFooter(); ?>
  67.  
  68. <input type="hidden" name="option" value="<?php echo $option; ?>" />
  69. <input type="hidden" name="task" value="" />
  70. <input type="hidden" name="boxchecked" value="0" />
  71. <input type="hidden" name="hidemainmenu" value="0" />
  72. <input type="hidden" name="act" value="categories" />
  73. </form>
  74.  
  75. <?php
  76. }

Here or in any similar listing function, few blocks are used:

lines 141 to 150 - start of table, and column headers

153 - if no category defined yet, display warning
156 - loop through all categories
162 - checkbox for selecting categories
163 - displays category name with Javascript returning 'edit' value for $task variable
167, 170 - displays reordering icons
176 to 180 - displays 'published' or 'unpublished' icon
191 - displays select list - how many categories per page to display

Next function - category editing - is similar to configuration editing. Additionally it has Javascript doing basic field validation. It displays popup warning if category name or folder are not entered.

admin.jportfsimple.html.php
  1. <script language="javascript" type="text/javascript">
  2.         function submitbutton(pressbutton) {
  3.         var form = document.adminForm;
  4.       if (pressbutton == 'cancel') {
  5.         submitform( pressbutton );
  6.         return;
  7.       }
  8.  
  9.       // do fields validation
  10.       if (form.cat_name.value == ''){
  11.         alert( "Category must have a name" );
  12.       } else if (form.cat_path.value == ''){
  13.         alert( "You must select a category folder" );
  14.       } else {
  15.         <?php getEditorContents( 'editor', 'description' ); ?>
  16.         submitform( pressbutton );
  17.       }
  18.         }
  19. </script>


Project listing and project editing functions are similar to the above ones.

Last function is 'Info' which displays information about the component. It shows logo, short description and version as defined in language file constants (_COM_JP_DESC, _COM_JP_VER1) and then it includes HTML file from help folder.

admin.jportfsimple.html.php
  1. if (file_exists( $mosConfig_absolute_path.'/administrator/components/com_jportfsimple/help/'. $mosConfig_lang.'.html'))
  2.     include_once( $mosConfig_absolute_path.'/administrator/components/com_jportfsimple/help/'. $mosConfig_lang.'.html');
  3.   else
  4.   if (file_exists( $mosConfig_absolute_path.'/administrator/components/com_jportfsimple/help/english.html'))
  5.     include_once( $mosConfig_absolute_path.'/administrator/components/com_jportfsimple/help/english.html');

If information in other language is not available, it will show english.html by default. It could be done differently - whole information could be also entered in one constant in language file, but I found it easier to update this way.



8. Backend - toolbars

Toolbar is defined with help of two files:
  1. toolbar.jportfsimple.php
  2. toolbar.jportfsimple.html.php

toolbar.jportfsimple.php
  1. // no direct access
  2. defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
  3.  
  4. require_once( $mainframe->getPath( 'toolbar_html' ) );
  5. $task = mosGetParam( $_REQUEST, 'task', '' );
  6. $act = mosGetParam( $_REQUEST, 'act', '' );
  7.  
  8. switch ( $task ) {
  9.  
  10.     case 'edit':
  11.     case 'new':
  12.       menujportfsimple::EDIT_MENU();
  13.     break;
  14.    
  15.     default:
  16.     switch($act)
  17.     {
  18.       case "configure":
  19.       case "css":
  20.         menujportfsimple::CONFIGURE_MENU();
  21.       break;
  22.      
  23.       case "info":
  24.         menujportfsimple::INFO_MENU();
  25.       break;
  26.  
  27.       case "categories":
  28.       case "projects":
  29.         menujportfsimple::DEFAULT_MENU();
  30.       break;
  31.      
  32.       default:
  33.        
  34.       break;   
  35.     }
  36.     break;
  37.   }

Depending on $act and $task it calls certain menu function from menujportfsimple class, which displays the right toolbar.

toolbar.jportfsimple.html.php
  1. // no direct access
  2. defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
  3.  
  4.  
  5.  
  6. class menujportfsimple{
  7.  
  8.   function DEFAULT_MENU() {
  9.  
  10.     mosMenuBar::startTable();
  11.     mosMenuBar::publish('publish');
  12.     mosMenuBar::unpublish('unpublish');
  13.     mosMenuBar::divider();
  14.     mosMenuBar::addNew('new');
  15.     mosMenuBar::editList('edit', 'Edit');
  16.     mosMenuBar::deleteList( ' ', 'delete', 'Remove' );
  17.     mosMenuBar::divider();
  18.     mosMenuBar::endTable();
  19.     }
  20.  
  21.   function EDIT_MENU() {
  22.  
  23.     mosMenuBar::startTable();
  24.     mosMenuBar::cancel();
  25.     mosMenuBar::save('save');
  26.     mosMenuBar::endTable();
  27.   }
  28.  
  29.   function CONFIGURE_MENU() {
  30.  
  31.     mosMenuBar::startTable();
  32.     mosMenuBar::save('save');
  33.     mosMenuBar::endTable();
  34.   }
  35.  
  36.   function INFO_MENU() {
  37.  
  38.     mosMenuBar::startTable();
  39.     mosMenuBar::endTable();
  40.   }
  41. }

Each _MENU function uses startTable and endTable from mosMenuBar class at the beginning and at the end of a toolbar. Then it defines actual buttons using functions like: addNew, editList or save.



9. Backend - install, uninstall

Last two files contain functions which are run after installing or uninstalling a component.
  1. install.jportfsimple.php
  2. uninstall.jportfsimple.php
Both are almost identical, only the function name inside is different, and the constant used to display information.

install.jportfsimple.php
  1. // no direct access
  2. defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
  3.  
  4. function com_install() {
  5.   global $mosConfig_live_site, $mosConfig_absolute_path, $mosConfig_lang;
  6.   if (file_exists( $mosConfig_absolute_path."/components/com_jportfsimple/lang/". $mosConfig_lang.".php"))
  7.       include_once( $mosConfig_absolute_path."/components/com_jportfsimple/lang/". $mosConfig_lang.".php");
  8.    else
  9.    if (file_exists( $mosConfig_absolute_path."/components/com_jportfsimple/lang/english.php"))
  10.       include_once( $mosConfig_absolute_path."/components/com_jportfsimple/lang/english.php");
  11.    
  12.   echo _COM_JP_INFO_TOP;
  13.   echo _COM_JP_INSTALL1;
  14.  
  15.   echo _COM_JP_INFO_BOTTOM;
  16. }


10. Summary

In the above tutorial I tried to explain the structure and functions of sample component written for Joomla! CMS v. 1.0.12.