What it is
Invision Community 4.2 introduces a powerful profile completion feature which can guide users into completing additional parts of their user profile following their registration. Your application can add additional steps that the administrator can enable for profile completion as well.
How to use
Upon creating a ProfileSteps extension, the class template will contain 9 methods.
/**
* Available Actions to complete steps
*
* @return array array( 'key' => 'lang_string' )
*/
public static function actions()
{
return array( ... );
}
The actions() method should return the available top-level actions that can be specified in the returned array as key => language string.
/**
* Available sub actions to complete steps
*
* @return array array( 'key' => 'lang_string' )
*/
public static function subActions()
{
return array( ... );
}
The subActions() method can be used to return the available sub-actions available. As an example, completing custom profile fields might be a top-level action, and then each custom profile field would be an available sub-action. The format of the array should be
array( 'action' => array( 'subaction_key' => 'subaction_language_string' ) )
/**
* Can the actions have multiple choices?
*
* @param string $action Action key (basic_profile, etc)
* @return boolean
*/
public static function actionMultipleChoice( $action )
{
return FALSE;
}
The actionMultipleChoice() method is designed to take the action key and determine if there are multiple choices available to the action. For example, linking social profiles does not carry with it multiple choices - you have either done it or you haven't. Supplying custom profile field information, however, will allow different values to be supplied. More often than not, you will simply want to return TRUE from this method.
/**
* Can be set as required?
*
* @return array
* @note This is intended for items which have their own independent settings and dedicated enable pages, such as MFA and Social Login integration
*/
public static function canBeRequired()
{
return array( 'action' );
}
As the note indicates, if your actions can be set as required, they should be returned as values in the array this method returns. Social login integration has its own configuration pages, so it cannot be set as required, however you can on the other hand require a user to supply their birthday, or to supply custom field details.
/**
* Has a specific step been completed?
*
* @param \IPS\Member\ProfileStep $step The step to check
* @param \IPS\Member|NULL $member The member to check, or NULL for currently logged in
* @return bool
*/
public function completed( \IPS\Member\ProfileStep $step, \IPS\Member $member = NULL )
{
return FALSE;
}
The completed() method is called to determine if a specified member has completed a profile step that has been set up, returning FALSE to indicate the step has not been completed or TRUE to indicate it has been completed. For birthday, as an example, if the member has a birthday set then the step would be considered completed.
/**
* Format Form Values
*
* @param array $values The values from the form
* @param \IPS\Member $member The member
* @param \IPS\Helpers\Form $form The form
* @return void
*/
public static function formatFormValues( $values, &$member, &$form )
{
}
When a member submits the profile completion form during their first visit, the formatFormValues() method is called in order to allow the ProfileSteps extension correctly format the submitted value. $member is passed by reference, so you can set $member->x properties, and save() will be called against the member automatically later, centrally. If any errors are encountered, you can set $form->error (or set an error on an individual form element) and return from the method.
/**
* Action URL
*
* @param string $action The action
* @param \IPS\Member|NULL $member The member, or NULL for currently logged in
* @return \IPS\Http\Url
*/
public function url( $action, \IPS\Member $member = NULL )
{
return \IPS\Http\Url::internal( ... );
}
If the user opts not to complete their profile and then later wishes to complete a step, the user will be sent to the url returned by url().
/**
* Post ACP Save
*
* @param \IPS\Member\ProfileStep $step The step
* @param array $values Form Values
* @return void
*/
public function postAcpSave( \IPS\Member\ProfileStep $step, array $values )
{
}
Your extension can take action following a changed profile completion step. For example, if a custom profile field is set as required then the custom profile fields ProfileSteps extension will set the required flag for the field.
/**
* Wizard Steps
*
* @param \IPS\Member $member Member or NULL for currently logged in member
* @return array
*/
public static function wizard( \IPS\Member $member = NULL )
{
return array( ... );
}
The wizard() method accepts one parameter (the member completing the wizard) and must return an array of callback functions to be added to the profile completion wizard. Generally speaking, each step should return a form with one or more form fields which will allow the member to complete the profile completion step.
An example to review is the profile completion step for custom profile fields.
/**
* Wizard Steps
*
* @param \IPS\Member $member Member or NULL for currently logged in member
* @return array
*/
public static function wizard( \IPS\Member $member = NULL )
{
$member = $member ?: \IPS\Member::loggedIn();
$wizards = array();
foreach( \IPS\Member\ProfileStep::loadAll() AS $step )
{
if ( $step->completion_act === 'profile_fields' AND ! $step->completed( $member ) )
{
$wizards[ $step->key ] = function( $data ) use ( $member, $step ) {
$form = new \IPS\Helpers\Form( 'profile_profile_fields_' . $step->id, 'profile_complete_next' );
foreach( $step->subcompletion_act as $item )
{
$id = \substr( $item, 12 );
$field = \IPS\core\ProfileFields\Field::load( $id );
$form->add( $field->buildHelper() );
}
if ( $values = $form->values() )
{
static::formatFormValues( $values, $member, $form );
$member->save();
return $values;
}
return $form->customTemplate( array( call_user_func_array( array( \IPS\Theme::i(), 'getTemplate' ), array( 'forms', 'core' ) ), 'profileCompleteTemplate' ), $step );
};
}
}
if ( count( $wizards ) )
{
return $wizards;
}
}
If the supplied member parameter is NULL, then we are working with the currently logged in member.
Next we loop over all of the profile completion steps and look for any that match this type, and that have not been completed. If we find one, we start a new wizard step (which is a callback function that accepts a single $data parameter). Within this callback function we start a new form, loop over any subactions (individual custom fields in this case) and add those form elements to the form, which we then output. As we do elsewhere, we also check if the form is submitted and if so, we save the submitted values.
Report Document