Examing Joomsport (DAY 1) : Entry Point of Controller and Manifest & JRequast::getVar

Joomsport is an extension developed by BearDev, from Russia.

From the perspective of pro-installation

Component File Structure and Function

The entry point of the component is joomsport.php. Its routine is essentially similar to the sample in the tutorial of Joomla! about creating component(see refs at the end). The differences reside in the piece:

$seasid = JRequest::getVar( 'seasid', 0, '', 'int' );
$sid = JRequest::getVar( 'sid', 0, '', 'int' );
if($seasid && !$sid)
{
	JRequest::setVar( 'sid', $seasid );
}

// Perform the Request task
$controller->execute(JRequest::getVar('task', null, 'default', 'cmd'));

The joomsport does not use getVar() method, instead of getWord().  According to the official document of JRequest:

/**
	 * Fetches and returns a given filtered variable. The word
	 * filter only allows the characters [A-Za-z_]. This is currently
	 * only a proxy function for getVar().
	 *
	 * See getVar() for more in-depth documentation on the parameters.
	 *
	 * @static
	 * @param	string	$name		Variable name
	 * @param	string	$default	Default value if the variable does not exist
	 * @param	string	$hash		Where the var should come from (POST, GET, FILES, COOKIE, METHOD)
	 * @return	string	Requested variable
	 * @since	1.5
	 */
	function getWord($name, $default = '', $hash = 'default')
	{
		return JRequest::getVar($name, $default, $hash, 'word');
	}

/**
	 * Fetches and returns a given variable.
	 *
	 * The default behaviour is fetching variables depending on the
	 * current request method: GET and HEAD will result in returning
	 * an entry from $_GET, POST and PUT will result in returning an
	 * entry from $_POST.
	 *
	 * You can force the source by setting the $hash parameter:
	 *
	 *   post		$_POST
	 *   get		$_GET
	 *   files		$_FILES
	 *   cookie		$_COOKIE
	 *   env		$_ENV
	 *   server		$_SERVER
	 *   method		via current $_SERVER['REQUEST_METHOD']
	 *   default	$_REQUEST
	 *
	 * @static
	 * @param	string	$name		Variable name
	 * @param	string	$default	Default value if the variable does not exist
	 * @param	string	$hash		Where the var should come from (POST, GET, FILES, COOKIE, METHOD)
	 * @param	string	$type		Return type for the variable, for valid values see {@link JFilterInput::clean()}
	 * @param	int		$mask		Filter mask for the variable
	 * @return	mixed	Requested variable
	 * @since	1.5
	 */
	function getVar($name, $default = null, $hash = 'default', $type = 'none', $mask = 0)
	{
		// Ensure hash and type are uppercase
		$hash = strtoupper( $hash );
		if ($hash === 'METHOD') {
			$hash = strtoupper( $_SERVER['REQUEST_METHOD'] );
		}
		$type	= strtoupper( $type );
		$sig	= $hash.$type.$mask;

		// Get the input hash
		switch ($hash)
		{
			case 'GET' :
				$input = &$_GET;
				break;
			case 'POST' :
				$input = &$_POST;
				break;
			case 'FILES' :
				$input = &$_FILES;
				break;
			case 'COOKIE' :
				$input = &$_COOKIE;
				break;
			case 'ENV'    :
				$input = &$_ENV;
				break;
			case 'SERVER'    :
				$input = &$_SERVER;
				break;
			default:
				$input = &$_REQUEST;
				$hash = 'REQUEST';
				break;
		}

		if (isset($GLOBALS['_JREQUEST'][$name]['SET.'.$hash]) && ($GLOBALS['_JREQUEST'][$name]['SET.'.$hash] === true)) {
			// Get the variable from the input hash
			$var = (isset($input[$name]) && $input[$name] !== null) ? $input[$name] : $default;
			$var = JRequest::_cleanVar($var, $mask, $type);
		}
		elseif (!isset($GLOBALS['_JREQUEST'][$name][$sig]))
		{
			if (isset($input[$name]) && $input[$name] !== null) {
				// Get the variable from the input hash and clean it
				$var = JRequest::_cleanVar($input[$name], $mask, $type);

				// Handle magic quotes compatability
				if (get_magic_quotes_gpc() && ($var != $default) && ($hash != 'FILES')) {
					$var = JRequest::_stripSlashesRecursive( $var );
				}

				$GLOBALS['_JREQUEST'][$name][$sig] = $var;
			}
			elseif ($default !== null) {
				// Clean the default value
				$var = JRequest::_cleanVar($default, $mask, $type);
			}
			else {
				$var = $default;
			}
		} else {
			$var = $GLOBALS['_JREQUEST'][$name][$sig];
		}

		return $var;
	}

The above two blocks explain the difference between the two methods, getWord is just using getVar, and it only return the paremeter that with literal name. The joomsport.php load the controller class, and then tackle with the parameters: seasid and sid, the logic is: if seasid is valid but not sid, then assgn sid to the seasid value. This process can be regarded as a kind of validation. But for this moment, we don't know the meaning of the two parameters. 

The official tutorials figure out a guide line of how to create a component, and after reading that, use the theories & principles to exam joomsport, we can sum up:

From the perspective of pre-installation

Now take a look at  joomsport.xml, it is the so-called manifeast file in Joomla!. Comparing it with the online  manifest sample, find out the counterparts for each section in joomsport.xml, and we can copy the comments from sample file, to make the functions more clear: 

<?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5">
	<name>JoomSport</name>
	<creationDate>May 2011</creationDate>
	<author>BearDev</author>
	<authorEmail>beardev@beardev.com</authorEmail>
	<authorUrl>www.beardev.com</authorUrl>
	<version>1.1.4</version>
	<description>JoomSport. Create your own league.</description>
	
	<!-- Custom Install Script to execute -->
	<!-- Note: This will be copied from the root of the installation package to the administrator directory automatically -->
	<installfile>install.joomsport.php</installfile>
	
	<!-- Install Database Section -->
	<install>
		<sql>
			<file charset="utf8" driver="mysql">install.sql</file>
		</sql>
	</install>	
	
	<!-- Site Main File Copy Section -->
	<files>
		<filename>joomsport.php</filename>
		<filename>index.html</filename>
		<filename>bl_lang.php</filename>
		<filename>controller.php</filename>
		<filename>router.php</filename>
		<folder>css</folder>	
		<folder>images</folder>
		<folder>js</folder>
		<folder>views</folder>
		<folder>includes</folder>
		<folder>controllers</folder>
		<folder>templates</folder>
		<folder>libs</folder>
	</files>
	
	<!-- Site Main Language File Copy Section -->
	<languages>
		<language tag="en-GB">Language/FE/en-GB.com_joomsport.ini</language>
		<language tag="fr-FR">Language/FE/fr-FR.com_joomsport.ini</language>
		<language tag="it-IT">Language/FE/it-IT.com_joomsport.ini</language>
		<language tag="el-GR">Language/FE/el-GR.com_joomsport.ini</language>
		<language tag="es-ES">Language/FE/es-ES.com_joomsport.ini</language>
	</languages>
	
	<!-- What is it for? -->
	<!-- Runs on install/uninstall/update; New in 1.6 -->
	<scriptfile>install.php</scriptfile> 	

	<administration>
	
		<!-- Administration Menu Section -->
		<!-- Name to display at the component menu. Should be the same as the extension commercial name -->
		<menu img="components/com_joomsport/img/beardev.gif" alt="JoomSport/JoomSport">COM_JOOMSPORT</menu>
		
		<submenu>
			<!-- Note that all & must be escaped to & for the file to be valid XML and be parsed by the installer -->
			<!-- Instead of link you can specify individual link attributes -->
			<menu task="tour_list" img="components/com_joomsport/img/tourn16.png">TOURNAMENT</menu>
			<menu task="season_list" img="components/com_joomsport/img/season16.png">SEASON</menu>
			<menu task="team_list" img="components/com_joomsport/img/team16.png">TEAMS</menu>
			<menu task="matchday_list" img="components/com_joomsport/img/match16.png">MATCHDAY</menu>
			<menu task="player_list" img="components/com_joomsport/img/players16.png">PLAYERS</menu>
			<menu task="pos_list" img="components/com_joomsport/img/players16.png">POSITIONS</menu>
			<menu task="event_list" img="components/com_joomsport/img/events16.png">EVENTS</menu>
			<menu task="group_list" img="components/com_joomsport/img/group16.png">GROUPS</menu>
			<menu task="moder_list" img="components/com_joomsport/img/moder16.png">MODERATORS</menu> 
			<menu task="fields_list" img="components/com_joomsport/img/additional16.png">EXTRAFIELDS</menu>
			<menu task="languages" img="components/com_joomsport/img/config16.png">LANGUAGES</menu>		
			<menu task="config" img="components/com_joomsport/img/config16.png">CONFIGURATION</menu>
			<menu task="help" img="components/com_joomsport/img/about16.png">HELP</menu>
			<menu task="about" img="components/com_joomsport/img/about16.png">ABOUT</menu>
		</submenu>
		
		<!-- Administration Main File Copy Section -->
		<!-- Note the folder attribute: This attribute describes the folder
				to copy FROM in the package to install therefore files copied
				in this section are copied from /admin/ in the package -->
		<files>
			
			<folder>img</folder>
	
			<filename>index.html</filename>
			<filename>admin.joomsport.html.php</filename>
			<filename>admin.joomsport.php</filename>
			<filename>language.joomsport.php</filename>
			<filename>admin.joomsport.class.php</filename>
			<filename>toolbar.joomsport.php</filename>
			<filename>toolbar.joomsport.html.php</filename>
			<filename>jbl_about.php</filename>
			<filename>jbl_help.php</filename>
			<filename>install.sql</filename>

			<folder>elements</folder>
			<folder>fields</folder>
			<folder>bearleague</folder>
			<folder>Language</folder>
			<folder>color_piker</folder>
		</files>
		
		<!-- Administration Language File Copy Section -->
		<languages>
			<language tag="en-GB">Language/BE/en-GB.com_joomsport.ini</language>
			<language tag="fr-FR">Language/BE/fr-FR.com_joomsport.ini</language>
			<language tag="it-IT">Language/BE/it-IT.com_joomsport.ini</language>
			<language tag="el-GR">Language/BE/el-GR.com_joomsport.ini</language>
			<language tag="es-ES">Language/BE/es-ES.com_joomsport.ini</language>
			<language tag="en-GB">Language/en-GB/en-GB.com_joomsport.menu.ini</language>
			<language tag="fr-FR">Language/fr-FR/fr-FR.com_joomsport.menu.ini</language>
			<language tag="it-IT">Language/it-IT/it-IT.com_joomsport.menu.ini</language>
			<language tag="el-GR">Language/el-GR/el-GR.com_joomsport.menu.ini</language>
			<language tag="es-ES">Language/es-ES/es-ES.com_joomsport.menu.ini</language>
			<language tag="en-GB">Language/en-GB/en-GB.com_joomsport.sys.ini</language>
			<language tag="fr-FR">Language/fr-FR/fr-FR.com_joomsport.sys.ini</language>
			<language tag="it-IT">Language/it-IT/it-IT.com_joomsport.sys.ini</language>
			<language tag="el-GR">Language/el-GR/el-GR.com_joomsport.sys.ini</language>
			<language tag="es-ES">Language/es-ES/es-ES.com_joomsport.sys.ini</language>
		</languages>
	</administration>
</install>

One new section is  scriptfile element, it is for 1.6 version. For 1.5 version, I think we can just ignore it. And please note that joomsport doesn't create an uninstall sql file, which is not a good pratice.

How does Joomla! interprate the Menu Part In Administration ? 

The menu section in the manifeast result in the menu of joomsport under component, as shown:

 

And now let's take a look at how Joomla! realize that menu according to the XML file, go to open directory:/administrator/modules/mod_menu/helper.php, scroll down to 'Components SubMenu':

...
		/*
		 * Components SubMenu
		 */
		if ($editAllComponents)
		{
			$menu->addChild(new JMenuNode(JText::_('Components')), true);

			$query = 'SELECT *' .
				' FROM #__components' .
				' WHERE '.$db->NameQuote( 'option' ).' <> "com_frontpage"' .
				' AND '.$db->NameQuote( 'option' ).' <> "com_media"' .
				' AND enabled = 1' .
				' ORDER BY ordering, name';
			$db->setQuery($query);
			$comps = $db->loadObjectList(); // component list
			$subs = array(); // sub menus
			$langs = array(); // additional language files to load

			// first pass to collect sub-menu items
...

we can ignore the other code for a while, and focus on the SQL query, this query implies that the data of menu is stored in tablejos_components, and the fieldenabled is a key criteria to filter the records. So open phpMyAdmin and browse this table, pick out all the records pervers to joomsport by executing: 

SELECT * 
FROM  `jos_components` 
WHERE id >=35
AND id <=49
LIMIT 0 , 30

The relation can be figured out:

 

For all sub menu items, the value of  admin_menu_link field is produced by appending task option to  link's value of parent menu item.

And if you want to hide some menu item, just set its record's  enabled field to0.

refs:

http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1

http://docs.joomla.org/Components:xml_installfile

http://docs.joomla.org/Manifest_files