Actions

Difference between revisions of "Creating a profile plugin"

From Joomla! Documentation

m (Missing curly bracket in the example code)
(Completing the example with missing information and correcting a few things that made the installation manager throw installation errors)
Line 13: Line 13:
 
  profile5.php
 
  profile5.php
 
  profile5.xml
 
  profile5.xml
 +
en-GB.plg_user_profile5.ini
 +
en-GB.plg_user_profile5.sys.ini
 
  /profiles/profile.xml
 
  /profiles/profile.xml
  
Line 21: Line 23:
 
<!-- $Id: profile.xml 16723 2010-05-04 01:37:00Z eddieajau $ -->
 
<!-- $Id: profile.xml 16723 2010-05-04 01:37:00Z eddieajau $ -->
 
<form>
 
<form>
<fields name="profile">
+
<fields name="profile5">
<fieldset name="profile"
+
<fieldset name="profile5"
label="PLG_USER_PROFILE_SLIDER_LABEL"
+
label="PLG_USER_PROFILE5_SLIDER_LABEL"
 
>
 
>
 
<field
 
<field
Line 29: Line 31:
 
type="text"
 
type="text"
 
id="something"
 
id="something"
description="PLG_USER_PROFILE_FIELD_SOMETHING_DESC"
+
description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
 
filter="string"
 
filter="string"
label="PLG_USER_PROFILE_FIELD_SOMETHING_LABEL"
+
label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
message="PLG_USER_PROFILE_FIELD_SOMETHING_MESSAGE"
+
message="PLG_USER_PROFILE5_FIELD_SOMETHING_MESSAGE"
 
size="30"
 
size="30"
 
/>
 
/>
Line 197: Line 199:
 
  <?xml version="1.0" encoding="utf-8"?>
 
  <?xml version="1.0" encoding="utf-8"?>
 
<!-- $Id:  -->
 
<!-- $Id:  -->
  <install version="1.6" type="plugin" group="user">
+
  <extension version="1.6" type="plugin" group="user">
 
<name>plg_user_profile5</name>
 
<name>plg_user_profile5</name>
 
<author>Joomla! Project</author>
 
<author>Joomla! Project</author>
Line 206: Line 208:
 
<authorUrl>www.joomla.org</authorUrl>
 
<authorUrl>www.joomla.org</authorUrl>
 
<version>1.6.0</version>
 
<version>1.6.0</version>
<description>PLG_USER_PROFILE_XML_DESCRIPTION</description>
+
<description>PLG_USER_PROFILE5_XML_DESCRIPTION</description>
  
 
<files>
 
<files>
Line 215: Line 217:
  
 
<languages>
 
<languages>
<language tag="en-GB">en-GB.plg_user_profile.ini</language>
+
<language tag="en-GB">en-GB.plg_user_profile5.ini</language>
<language tag="en-GB">en-GB.plg_user_profile.sys.ini</language>
+
<language tag="en-GB">en-GB.plg_user_profile5.sys.ini</language>
 
</languages>
 
</languages>
  
Line 224: Line 226:
 
<fieldset name="basic">
 
<fieldset name="basic">
 
<field name="register-require-user" type="spacer"
 
<field name="register-require-user" type="spacer"
label="PLG_USER_PROFILE_FIELD_NAME_REGISTER_REQUIRE_USER"
+
label="PLG_USER_PROFILE5_FIELD_NAME_REGISTER_REQUIRE_USER"
 
/>
 
/>
  
 
<field name="register-something" type="list"
 
<field name="register-something" type="list"
description="PLG_USER_PROFILE_FIELD_SOMETHING_DESC"
+
description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
label="PLG_USER_PROFILE_FIELD_SOMETHING_LABEL"
+
label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
 
>
 
>
 
<option value="2">JOPTION_REQUIRED</option>
 
<option value="2">JOPTION_REQUIRED</option>
Line 237: Line 239:
  
 
<field name="profile-require-user" type="spacer"
 
<field name="profile-require-user" type="spacer"
label="PLG_USER_PROFILE_FIELD_NAME_PROFILE_REQUIRE_USER"
+
label="PLG_USER_PROFILE5_FIELD_NAME_PROFILE_REQUIRE_USER"
 
/>
 
/>
  
 
<field name="profile-require_something" type="list"
 
<field name="profile-require_something" type="list"
description="PLG_USER_PROFILE_FIELD_SOMETHING_DESC"
+
description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
label="PLG_USER_PROFILE_FIELD_SOMETHING_LABEL"
+
label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
 
>
 
>
 
<option value="2">JOPTION_REQUIRED</option>
 
<option value="2">JOPTION_REQUIRED</option>
Line 253: Line 255:
 
</fields>
 
</fields>
 
</config>
 
</config>
  </install>
+
  </extension>
 
  </source>
 
  </source>
 +
 +
en-GB.plg_user_profile5.ini
 +
 +
; $Id: en-GB.plg_user_profile.ini 19353 2010-11-05 07:57:29Z infograf768 $
 +
; Joomla! Project
 +
; Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.
 +
; License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
 +
; Note : All ini files need to be saved as UTF-8
 +
 +
PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"
 +
PLG_USER_PROFILE5="User - Profile 5"
 +
PLG_USER_PROFILE5_SLIDER_LABEL="User Profile 5"
 +
PLG_USER_PROFILE5_FIELD_NAME_REGISTER_REQUIRE_USER="User profile fields for registration and administrator user profile 5 forms"
 +
PLG_USER_PROFILE5_FIELD_NAME_PROFILE_REQUIRE_USER="User profile fields for profile 5 edit form"
 +
PLG_USER_PROFILE5_FIELD_SOMETHING_DESC="Choose an option for the something filed"
 +
PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL="Something!"
 +
PLG_USER_PROFILE5_FIELD_SOMETHING_MESSAGE="A Message for something!"
 +
PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"
 +
 +
en-GB.plg_user_profile5.sys.ini
 +
 +
; $Id: en-GB.plg_user_profile.sys.ini 17052 2010-05-14 14:05:58Z infograf768 $
 +
; Joomla! Project
 +
; Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.
 +
; License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
 +
; Note : All ini files need to be saved as UTF-8
 +
 +
PLG_USER_PROFILE5="User - Profile 5 "
 +
PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"
  
 
By installing profile5 you can add new fields in addition to the ones in profile. You can also control which view levels see those fields.
 
By installing profile5 you can add new fields in addition to the ones in profile. You can also control which view levels see those fields.

Revision as of 14:49, 28 December 2010

Profile plugin is a new extension in Joomla! 1.6. It allows the addition of supplemental fields in the registration and profile forms of the com_user front end and in the user create/edit form in the back end.

A simple example plugin is included in the basic Joomla! installation as a proof of concept. Much more complex plugins are possible.

The example plugin takes advantage of on the onContentPrepareForm and onUserAfterSave events.

Multiple profile plugins may be included and will be rendered in sequence.

This page shows an example of a second plugin, named profile5. It adds a single field called something.

This is the file structure

profile5.php
profile5.xml
en-GB.plg_user_profile5.ini
en-GB.plg_user_profile5.sys.ini
/profiles/profile.xml

The supplemental fields are created with xml file in the profiles folder.

<?xml version="1.0" encoding="utf-8"?>
        <!-- $Id: profile.xml 16723 2010-05-04 01:37:00Z eddieajau $ -->
<form>
        <fields name="profile5">
                <fieldset name="profile5"
                        label="PLG_USER_PROFILE5_SLIDER_LABEL"
                >
                        <field
                                name="something"
                                type="text"
                                id="something"
                                description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
                                filter="string"
                                label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
                                message="PLG_USER_PROFILE5_FIELD_SOMETHING_MESSAGE"
                                size="30"
                        />
 
 
                </fieldset>
        </fields>
</form>


profile5.php

 <?php
 /**
  * @version            $Id: profile.php 17685 2010-06-14 21:46:46Z dextercowley $
  * @copyright  Copyright (C) 2005 - 2010 Open Source Matters, Inc. All rights reserved.
  * @license            GNU General Public License version 2 or later; see LICENSE.txt
  */
 
 defined('JPATH_BASE') or die;
 
  /**
   * An example custom profile plugin.
   *
   * @package           Joomla.Plugins
   * @subpackage        user.profile
   * @version           1.6
   */
  class plgUserProfile5 extends JPlugin
  {
        /**
         * @param       string  The context for the data
         * @param       int             The user id
         * @param       object
         * @return      boolean
         * @since       1.6
         */
        function onContentPrepareData($context, $data)
        {
                // Check we are manipulating a valid form.
                if (!in_array($context, array('com_users.profile', 'com_users.registration'))) {
                        return true;
                }
 
                $userId = isset($data->id) ? $data->id : 0;
 
                // Load the profile data from the database.
                $db = &JFactory::getDbo();
                $db->setQuery(
                        'SELECT profile_key, profile_value FROM #__user_profiles' .
                        ' WHERE user_id = '.(int) $userId .
                        ' ORDER BY ordering'
                );
                $results = $db->loadRowList();
 
                // Check for a database error.
                if ($db->getErrorNum()) {
                        $this->_subject->setError($db->getErrorMsg());
                        return false;
                }
 
                // Merge the profile data.
                $data->profile = array();
                foreach ($results as $v) {
                        $k = str_replace('profile.', '', $v[0]);
                        $data->profile[$k] = $v[1];
                }
 
                return true;
        }
 
        /**
         * @param       JForm   The form to be altered.
         * @param       array   The associated data for the form.
         * @return      boolean
         * @since       1.6
         */
        function onContentPrepareForm($form, $data)
        {
                // Load user_profile plugin language
                $lang = JFactory::getLanguage();
                $lang->load('plg_user_profile', JPATH_ADMINISTRATOR);
 
                if (!($form instanceof JForm)) {
                        $this->_subject->setError('JERROR_NOT_A_FORM');
                        return false;
                }
                // Check we are manipulating a valid form.
                if (!in_array($form->getName(), array('com_users.profile', 'com_users.registration','com_users.user'))) {
                        return true;
                }
                if ($form->getName()=='com_users.profile')
                {
                        // Add the profile fields to the form.
                        JForm::addFormPath(dirname(__FILE__).'/profiles');
                        $form->loadFile('profile', false);
 
                        // Toggle whether the something field is required.
                        if ($this->params->get('profile-require_something', 1) > 0) {
                                $form->setFieldAttribute('something', 'required', $this->params->get('profile-require_something') == 2, 'profile');
                        } else {
                                $form->removeField('something', 'profile');
                        }
                }
 
                //In this example, we treat the frontend registration and the back end user create or edit as the same. 
                elseif ($form->getName()=='com_users.registration' || $form->getName()=='com_users.user' )
                {               
                        // Add the registration fields to the form.
                        JForm::addFormPath(dirname(__FILE__).'/profiles');
                        $form->loadFile('profile', false);
 
                        // Toggle whether the something field is required.
                        if ($this->params->get('register-require_something', 1) > 0) {
                                $form->setFieldAttribute('something', 'required', $this->params->get('register-require_something') == 2, 'profile');
                        } else {
                                $form->removeField('something', 'profile');
                        }
                }                       
        }
 
        function onUserAfterSave($data, $isNew, $result, $error)
        {
                $userId = JArrayHelper::getValue($data, 'id', 0, 'int');
 
                if ($userId && $result && isset($data['profile']) && (count($data['profile'])))
                {
                        try
                        {
                                $db = &JFactory::getDbo();
                                $db->setQuery('DELETE FROM #__user_profiles WHERE user_id = '.$userId);
                                if (!$db->query()) {
                                        throw new Exception($db->getErrorMsg());
                                }
 
                                $tuples = array();
                                $order  = 1;
                                foreach ($data['profile'] as $k => $v) {
                                        $tuples[] = '('.$userId.', '.$db->quote('profile.'.$k).', '.$db->quote($v).', '.$order++.')';
                                }
 
                                $db->setQuery('INSERT INTO #__user_profiles VALUES '.implode(', ', $tuples));
                                if (!$db->query()) {
                                        throw new Exception($db->getErrorMsg());
                                }
                        }
                        catch (JException $e) {
                                $this->_subject->setError($e->getMessage());
                                return false;
                        }
                }
 
                return true;
        }
 }


Profile5.xml controls whether the field is required, disabled or optional in the forms. Since profile5.php says to treat backend create/edit the same as registration only two sets of options are required, register and profile.

 <?xml version="1.0" encoding="utf-8"?>
        <!-- $Id:  -->
 <extension version="1.6" type="plugin" group="user">
        <name>plg_user_profile5</name>
        <author>Joomla! Project</author>
        <creationDate>January 2008</creationDate>
        <copyright>(C) 2005 - 2010 Open Source Matters. All rights reserved.</copyright>
        <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
        <authorEmail>admin@joomla.org</authorEmail>
        <authorUrl>www.joomla.org</authorUrl>
        <version>1.6.0</version>
        <description>PLG_USER_PROFILE5_XML_DESCRIPTION</description>
 
        <files>
                <filename plugin="profile5">profile5.php</filename>
                <filename>index.html</filename>
                <folder>profiles</folder>
        </files>
 
        <languages>
                <language tag="en-GB">en-GB.plg_user_profile5.ini</language>
                <language tag="en-GB">en-GB.plg_user_profile5.sys.ini</language>
        </languages>
 
        <config>
                <fields name="params">
 
                        <fieldset name="basic">
                                <field name="register-require-user" type="spacer"
                                        label="PLG_USER_PROFILE5_FIELD_NAME_REGISTER_REQUIRE_USER"
                                />
 
                                <field name="register-something" type="list"
                                        description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
                                        label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
                                >
                                        <option value="2">JOPTION_REQUIRED</option>
                                        <option value="1">JOPTION_OPTIONAL</option>
                                        <option value="0">JDISABLED</option>
                                </field>
 
                                <field name="profile-require-user" type="spacer"
                                        label="PLG_USER_PROFILE5_FIELD_NAME_PROFILE_REQUIRE_USER"
                                />
 
                                <field name="profile-require_something" type="list"
                                        description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
                                        label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
                                >
                                        <option value="2">JOPTION_REQUIRED</option>
                                        <option value="1">JOPTION_OPTIONAL</option>
                                        <option value="0">JDISABLED</option>
                                </field>
 
                        </fieldset>
 
                </fields>
        </config>
 </extension>

en-GB.plg_user_profile5.ini

; $Id: en-GB.plg_user_profile.ini 19353 2010-11-05 07:57:29Z infograf768 $
; Joomla! Project
; Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.
; License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
; Note : All ini files need to be saved as UTF-8

PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"
PLG_USER_PROFILE5="User - Profile 5"
PLG_USER_PROFILE5_SLIDER_LABEL="User Profile 5"
PLG_USER_PROFILE5_FIELD_NAME_REGISTER_REQUIRE_USER="User profile fields for registration and administrator user profile 5 forms"
PLG_USER_PROFILE5_FIELD_NAME_PROFILE_REQUIRE_USER="User profile fields for profile 5 edit form"
PLG_USER_PROFILE5_FIELD_SOMETHING_DESC="Choose an option for the something filed"
PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL="Something!"
PLG_USER_PROFILE5_FIELD_SOMETHING_MESSAGE="A Message for something!"
PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"

en-GB.plg_user_profile5.sys.ini

; $Id: en-GB.plg_user_profile.sys.ini 17052 2010-05-14 14:05:58Z infograf768 $
; Joomla! Project
; Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.
; License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
; Note : All ini files need to be saved as UTF-8

PLG_USER_PROFILE5="User - Profile 5 "
PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"

By installing profile5 you can add new fields in addition to the ones in profile. You can also control which view levels see those fields. Alternatively, you can write a more complex common plugin with varying controls for different groups.