Mastering Joomla! 1.5 Extension and Framework Development phần 5 ppt

Chapter 7 [ 179 ] When we perform any modications to the user's session, unless we save the changes, the modications will last only until the session expires. User parameters are not used as a temporary store. To store temporary data we should use the session and the user state; we will see both in the next section. If we store temporary data in user parameters, we run the risk of saving the data accidently to the user's database record. A common design issue is the extension of the user beyond their predened attributes. There are three common ways of dealing with this: Add additional elds to the #__users table. Create a new table that maintains a one-to-one relationship with the #__users table. Use the user's parameters to store additional data. The rst option can cause some major problems. If several extensions choose this method, there is a chance that there will be a naming conict between elds. The second option is a good choice if the extra data is searchable, ordered, or used to modify results returned from the queries. To maintain the table successfully, we would have to create a plugin to deal with the events onAfterStoreUser and onAfterDeleteUser, explained in Chapter 6. The nal option is ideal if the extra data is not subject to searches, ordered, or used to restrict query results. We might implement these parameters in one of the three ways: Manually edit the parameters using the setParam() method. This is suitable if there are not many parameters or the user never modies the parameters using a form. Use JParameter as the basis to create a form in which users can modify the parameters. Allow the user to modify the parameters, via the user's component. To do this, we need to modify the users.xml le (for more information about editing XML, see Chapter 10). Before we begin, there is something we need to understand. A JUser object essentially has two sets of parameters, a RAW parameters string or array (params) and a JParameter object (_params). Both of these are loaded from the database when the user's session starts. If we modify either of them, the changes will be present only until the user's session ends. If we want to save the parameters to the database, as is normally the case, we can use the save() method. This will update the parameters based on the RAW parameters alone. • • • • • • Extension Design [ 180 ] When we use the setParam() method only the JParameter object is modied. It is because of this that we must update the RAW params attribute before saving. We must take extra care when saving changes to the user's parameters. Poor handling can result in loss of data. This example demonstrates how we can set the user's foo parameter and save the changes to the database: // get the user and add the foo parameter $user =& JFactory::getUser(); $user->setParam('foo', 'bar'); // update the raw user parameters $params =& $user->getParameters(); $user->set('params', $params->toString()); // save the changes to the database if (!$user->save()) { JError::raiseError('SOME_ERROR', JText::_('Failed to save user')); } Next we will explore parameters that a user can update via a form. We will begin by creating an XML le that denes the extra parameters. We will see the parameters in detail in the Appendix. The following XML denes two text parameters, myparameter and myotherparameter: <?xml version="1.0" encoding="utf-8"?> <metadata> <params> <param name="myparameter" type="text" default="example" label="My Parameter" description="An example user parameter" /> <param name="myotherparameter" type="text" default="example" label="My Other Parameter" description="An example user parameter" /> </params> </metadata> We can create form elements using this XML and the user's JParameter object. We can get a reference to the JParameter object using the getParameters() method: // get the user $user =& JFactory::getUser(); // get the user's parameters object $params =& $user->getParameters(); Chapter 7 [ 181 ] Once we have the parameters object, we can load the XML le and render the form elements using the render() method, as this example demonstrates: $params->loadSetupFile($pathToXML_File); echo $params->render('myparams'); A form eld is created for each parameter, all of which are treated as a form array. The parameter that we provide to the render() method is used to name the form array. If we do not provide the parameter, the default name 'params' is used. Our example will create two text inputs called myparams[myparameter] and myparams[myotherparameter]. This is a screenshot of how these parameters would appear: Alternatively we could use the JParameter renderToArray() method that returns an array of arrays that dene the different form elements. Creating a form to deal with extra parameters is only the beginning; we need to process submitted forms. In this example, we retrieve the parameters from the POST array (assuming that the form is submitted using the POST method), add them to the user's existing parameters, rebind them to the user object, and save the changes: // get the user object and the post array. $user =& JFactory::getUser(); $post = JRequest::get('post'); // get the existing parameters $params = $user->getParameters(); // add the parameters from the form submission $params->bind($post['myparams']); // update and save the user $user->set('params', $params->toString()); $user->save(); The last option we will explore is modifying the users.xml le. To do this, we will utilize the JSimpleXML parser. For a complete description of the JSimpleXML parser, please refer to Chapter 10. Extension Design [ 182 ] The rst thing we need to do is get hold of the XML le and parse the contents: // get a parser $parser =& JFactory::getXMLParser('Simple'); // define the path to the XML file $pathToXML_File = JPATH_ADMINISTRATOR.DS.'components'.DS.'com_users'. DS.'users.xml'; // parse the XML $parser->loadFile($pathToXML_File); In order to add new param tags to the XML, we need to navigate to the params tag: // get the root tag (install) $document =& $parser->document; // get the params tag $params =& $document->params[0]; We can now start adding to the XML using the addChild() method to add child param tags, and the addAttribute() method to set the necessary param tag attributes. This example adds the parameters myparameter and myotherparameter, both of which we dened in the previous example: // Add myparameter $myparameter =& $params->addChild('param'); // modify the myparameter attributes $myparameter->addAttribute('name', 'myparameter'); $myparameter->addAttribute('type', 'text'); $myparameter->addAttribute('label', 'My Parameter'); $myparameter->addAttribute('description', 'An example user parameter'); // Add myotherparameter $myotherparameter =& $params->addChild('param'); // modify the myotherparameter attributes $myotherparameter->addAttribute('name', 'myotherparameter'); $myotherparameter->addAttribute('type', 'text'); $myotherparameter->addAttribute('label', 'My Other Parameter'); $myotherparameter->addAttribute('description', 'An example user parameter'); Chapter 7 [ 183 ] Now that we have made the changes to the XML le, we need to save those changes to the users.xml le. We can do this using the JFile class: // create XML string $xmlString = '<?xml version="1.0" encoding="UTF-8" ?>'."\n"; $xmlString .= $document->toString(); // get the JFile class jimport('joomla.filesystem.file'); // save the changes if (!JFile::write($pathToXML_File, $xmlString)) { // handle failed file save } These alterations will enable users to modify myparameter and myotherparameter, when they use the user's component to modify their details. This screenshot depicts the resultant form with the changes: If one were to employ this technique, the best place to do so would probably be in a component installation le. It is also important to consider making a backup of the existing le, in case of any unexpected difculties. Modifying this le could also lead to problems if the le is ever updated, for example as part of an upgrade. However, it does mean that all of the user's details are editable from one central point. Extension Design [ 184 ] The Session When a user accesses Joomla!, a new session is created; this occurs even if the user is not logged in. Instead of accessing the $_SESSION hash, as we do in most PHP applications, we must use the global JSession object. When we access session data, we provide the value name and, optionally, the namespace. If we do not provide a namespace the default namespace, aptly named, default is assumed. In this example, we retrieve the value of default.example: $session =& JFactory::getSession(); $value = $session->get('example'); It is unusual when accessing the session in this way to use anything other than the default namespace. That is why the second parameter in the get() method is not the namespace, but the default value. In this example, we retrieve the value of default. example, returning a value of 1 if the value does not exist: $session =& JFactory::getSession(); $value = $session->get('example', 1); The last parameter is the namespace. This example demonstrates how to retrieve a value from a different namespace (someNamespace): $session =& JFactory::getSession(); $value = $session->get('example', 1, 'someNamespace'); In addition to retrieving values, we can also set them. In this example, we set the value of default.example and someNamespace.example: $session =& JFactory::getSession(); $session->set('example', 1); $session->set('example', 1, 'someNamespace'); You might be wondering why we tend to use the default namespace. Due to limitations of the namespace handling within the JSession class, we use a special area of the session known as the 'user-state'. The user-state is a JRegistry object that is stored in the session. The application accesses this object, which is located in default.registry. There are two application methods that we use, getUserState() and getUserStateFromRequest(). We'll start by exploring getUserState(). This example demonstrates how we can retrieve the value of session.counter, a counter that represents the number of requests a user has made: $mainframe->getUserState('session.counter'); Chapter 7 [ 185 ] Setting user-state values is very similar. This example demonstrates how we can set an alternative template for a user: $mainframe->setUserState('setTemplate', 'someSiteTemplate'); The getUserStateFromRequest() method is very similar to the getUserState() method, except that it checks the request values rst. This method is used extensively in Joomla!'s implementation of pagination. The method has three parameters, the key (a path), the name of the request, and a default value. This example retrieves the value of com_myextension.list. filter.order: $order = $mainframe- >getUserStateFromRequest('com_myextension.list.filter.order', 'filter_order', 'name'); The second parameter is especially important. If a request were made in which the query contained filter_order=owner, the value returned would be owner. It would also update the user-state to equal owner. This method is of particular interest when we want to allow a user to modify their state values. It is for this reason that the getUserStateFromRequest() method is used extensively in pagination. There is not a setUserStateFromRequest() method because when we execute the getUserStateFromRequest() method the value is updated. As a nal note, Joomla! session data is not always stored in the usual way. Joomla! uses session storage classes to allow alternative methods of data storage. These methods include the database, php-eaccelerator, and php-pecl-apc. We must install php-eaccelerator or php-pecl-apc on the server if we have to use them. There is a limitation of database session-storage. The session data size is limited to 65,535 characters. This can cause problems with extensions that require large amounts of session storage space. The Browser A useful source of information about the client is the browser. We can use the JBrowser class, located in joomla.environment.browser, to investigate the client browser. Browsers have features that enable them to behave in certain ways. For example, a browser may or may not support JavaScript. We can use the hasFeature() method to check for different features. Extension Design [ 186 ] This example checks for JavaScript support: $browser =& JBrowser::getInstance(); if ($browser->hasFeature('javascript')) { // the browser has JavaScript capabilities } This is a list of the different features we can check for when using the hasFeature() method: accesskey cite dom frames hdml homepage html iframes images java javascript optgroup rte tables utf wml xmlhttpreq Browsers also have quirks (peculiarities of behavior). We can use JBrowser to check for certain quirks in browsers. In this example, we check that the browser is happy to deal with popups: $browser =& JBrowser::getInstance(); if ($browser->hasQuirk('avoid_popup_windows')) { // the browser does not like popups } Generally, all browsers, except mobile browsers and old browsers, will deal with popups. • • • • • • • • • • • • • • • • • Chapter 7 [ 187 ] This is a list of the different quirks that we can check for using JBrowser: avoid_popup_windows break_disposition_lename break_disposition_header broken_multipart_form cache_same_url cache_ssl_downloads double_linebreak_textarea empty_le_input_value must_cache_forms no_lename_spaces no_hidden_overow_tables ow_gui_1.3 png_transparency scroll_tds scrollbar_in_way windowed_controls Both the quirks and features are hard-coded in Joomla!; they are not retrieved from the browser. This means that JBrowser will not detect popup blockers or other unexpected settings. This is a list of the browsers known to Joomla!: AvantGo BlackBerry Ericsson Fresco HotJava i-Mode Konqueror Links Lynx MML Motorola Mozilla • • • • • • • • • • • • • • • • • • • • • • • • • • • • Extension Design [ 188 ] MSIE Nokia Opera Palm Palmscape Up WAP Xiino There are a number of handy methods to determine which browser a user is using. This example demonstrates how we would output a formatted string representation of the user's browser: $browser =& JBrowser::getInstance(); $string = ucfirst($browser->getBrowser()).' '; $string .= $browser->getVersion().' ('; $string .= $browser->getPlatform().')'; This is an example of the value of $string: Mozilla 5.0 (win). We will now discuss three additional JBrowser methods that we can use to make our extensions more user friendly and secure. Imagine we want to prevent robots from viewing an extension. Robots are programs that systematically 'crawl' though a website indexing the content for use in search engines. We can check if a browser is a robot using the isRobot() method: $browser =& JBrowser::getInstance(); if ($browser->isRobot()) { JError::raiseError('403', JText::_('Robots are disallowed')); } When we use components, we can choose to modify the MIME type of a response. Before we do this, using JBrowser, we can check that the browser supports the MIME type. This example checks that the browser can handle the MIME type application/vnd.ms-excel (an MS Excel le) before displaying a certain link: $browser =& JBrowser::getInstance(); if ($browser->isViewable('application/vnd.ms-excel')) { echo '<a href="'.JRoute::_('index.php?option=com_myextension&format= raw&application=xls').'">Link to an XLS document</a>'; } • • • • • • • • [...]... the Joomla! framework is a common way to extend Joomla! beyond its intended scope We discussed in a previous chapter the use of plugins in lieu of library extensions If we want, we can use the same logic, JLoader, to create 'internal' libraries in any extension Making extensions easy to build is all part of the logic behind helper classes These static classes allow us to categorize functionality and. .. there is land full of imagery, multimedia, and the occasional unicorn If we want to give administrators full control over an extension, being able to modify an extension' s repository of assets is necessary Use the installer assets tag to take advantage of the Joomla! Media Manager [ 191 ] Rendering Output In Joomla!, there are several ways in which we can render output that make our lives easier and force... similar to the core class JFactory to further increase accessibility of global objects A JRegistry object handles the site settings and extension settings, stored in INI, XML, and PHP files We should consider the use of JRegistry before we create any settings files The user is a complex entity and how we handle it is very important We can extend users in various ways Whichever mechanism we choose, we should... our extensions [ 190 ] Chapter 7 We must always remember to use the global JSession object to handle sessions Directly accessing the $_SESSION variable can have some unexpected results Modifying our site to suit a browser may seem drastic, but when checking for features and quirks in the browser is as easy as one simple method, it makes sense Bulletproof extensions always consider the unexpected, and. .. one assets folder and create it in the frontend Of course, we do not have to do this; where we choose to create such a folder is entirely at the developer's discretion Summary There are restrictions as to what we can do in Joomla!, but there are many ways to achieve the same goal You should never feel restricted by conventional extension design, but you should always work with Joomla! and take advantage... hard-coded) [ 189 ] Extension Design We can copy files into any folder in the Media Manager using the media tag destination attribute If we want to add files to the root of the Media Manager, we need not include the destination attribute Alternatively, we can create a folder in our extensions called assets Many of the core extensions use this approach It prevents modification of the assets, and is ideal for... frame XHTML string Date Takes a date and formats it accordingly The date should always be UTC The offset is retrieved from the registry unless a custom offset is provided Date and time (UTC), supports RFC822, ISO8601, and Unix time stamps Date format; default is DATE_FORMAT_LC [offset] Returns date [format] Parameters Number of hours offset from UTC Date string [ 1 95 ] Rendering Output Tooltip Gets some... types, each of which represents handles a common field found used in the database Before we begin there are some important things that need to be in place The form must be called adminForm, and it must include two hidden fields, one called boxchecked with the default value 0 and one called task used to determine which task a controller will execute We'll use grid.id and grid.published as an example... legacy groups [ 2 05 ] Rendering Output Category Gets a drop-down selection box of different categories related to a specific section We can use categories outside of the content component in order to maintain categories for a different extension We do this by specifying a section value equal to that of the extension name, for example com_somecomponent List name section Section ID or extension name Initially... JFormValidator JavaScript class to the document and instantiates an object of this type in document.formvalidator This object can be used to aid the validation of forms Switcher Adds JavaScript that can be used to toggle between hidden and shown page elements This is specifically used in conjunction with the backend submenu For example, both the site configuration and system information areas in the backend . handles the site settings and extension settings, stored in INI, XML, and PHP les. We should consider the use of JRegistry before we create any settings les. The user is a complex entity and. limitation of database session-storage. The session data size is limited to 65, 5 35 characters. This can cause problems with extensions that require large amounts of session storage space. The Browser A. Mozilla 5. 0 (win). We will now discuss three additional JBrowser methods that we can use to make our extensions more user friendly and secure. Imagine we want to prevent robots from viewing an extension.