resources

Introduction

It is easy enough to setup avatars in Xaraya for users and update the appropriate module templates for use. However, it can be time consuming for new developers or webmasters alike and an easy '10 minute' approach is now available in Xarigami.

This article provides steps on:

• how to add avatar options for your users including the ability to choose none, a selected avatar from your collection, their own uploaded avatar, a linking to a personalized avatar or a gravatar
• the custom roles avatar tag that can be used to place an avatar in your templates

The steps for the advanced user are simply :

1. Setup the avatar dynamic data properties - import the supplied roles user dynamic data properties found in the xardata directory of the Roles module
2. Adjust the dynamic data properties - to customize which  of the available avatar options you require, and the image selection path and upload paths for those avatar options
3. Displaly the avatars with the roles avatar tag in your templates to add avatars - or use existing modules that support these avatar options (eg Xarigami Roles, Xarigami Comments, Xarigami Xarbb)

Users will be able to select their preferred avatar by editing their user account Profile page and it will be displayed where provisioned for in your site (eg Roles view, comments, forum).

For those that would like more, detailed instructions follow.

Requirements

• Xarigami Core 1.5.1
• Roles version 1.1.7 or above

Currently Xarigami Core, Xarigami Comments and Xarigami XarBB automatically support these avatars using the custom tag. You can also easily add to your own templates using the block layout custom <xar:roles-avatar /> tag.

Steps

1. Setup the avatar dynamic data properties

1. Check that a roles dynamic data (DD) object does not already exist (may have roles DD properties already). If you are unsure, as Administrator go to the Dynamic Data - Manage Objects page, and look for a Roles object of Item type 0. If you have one there already you can either delete it (if there is nothing in it you need) or add the four required properties manually (details in the xml file - see  step 1.d below).
2. Import the roles user DD properties by going to Dynamic Data - Utilities - Import. 
   - Enter in the base directory where the xml file is: modules/roles/xardata and click on Refresh
   - Select roles-def-users.xml from the drop down selection
   - Click in Import Definition to import the DD property definitions from the file
3. On a successful import you will be returned to the Modifying Dynamic Data : Roles page in the Dynamic Data admin area.
4. Here you will find all the new DD properties you have just setup. Those not required can be removed, but the key ones for avatars are :
   
   1. avatar_type : provides options for the user to select which type of avatar they wish to use, if any. Depending on their selection here they may need to complete one of the following.
   2. avatar_select : provides an image list of a set of avatars provided on your site for a  user to select from
   3. avatar_url : provides the user with a field to enter a URL to their avatar
   4. avatar_upload : allows the user to upload their avatar
   
   If for some reason (from step a) you need to setup these DD properties manually, the details are in the xml file. All the above four DD properties must be added.
   
   Note that none of these four properties need be displayed in the user profile. They are only required on the input screen when a user edits their profile. Thus, you can check to ensure the 'status' of each of these is 'input only'.
5. You can adjust the order of your DD properties using the reorder arrows in the DD property listing. Keep the avatar related properties together, the first one of them as avatar_type.

2. Adjust the dynamic data properties

1. Avatar_type has 5 options by default: None, Selected Picture, My Picture (URL), My Picture (uploaded), and Gravatar. You can remove any of the ones you do not wish to support by removing them from the validation in the DD property. Be sure to keep the correct numeric id assigned to each option that you want to retain. eg None should always be zero (0), Selected Picture always 1, and so on.
2. Avatar_select is by default set to var/uploads/avatars. This is the directory where you can supply a list of avatars for your users to select from. The directory only need by Readable for your users. If it does not exist, you should create it. Alternatively you can use another directory but you must update the validation directory path in the DD property. Of course, you also need to supply some avatar images in that directory :) There are a lot of free sets found on the internet. The chosen avatar displays automatically in the page (uses the display=true option in the image list DD property validation).
3. avatar_url: does not need any specific setup. It requires the user to type in a url to their chosen avatar
4. avatar_upload is set by default to var/uploads/useravatars. This is the directory where your users can upload their own avatar. The directory needs to be writeable for users. Either ensure the directory exists and is writeable, or setup your own directory and update the validation directory path in the DD property.
5. Gravatar use requires that a user has an account setup and created a gravatar at http://gravatar.com
   
   

3. Display the avatar using the avatar tag or existing supported module

To display an avatar for any given user using this method, you need to use a module that supports these avatars such as Xarigami Comments or add the avatar using the avatar custom Block Layout tag.

1. Using a supported module such as Xarigami Comments - you can go to Xarigami Comments Modify Config tab for the module itself or override configuration if you have that activated and select "Use Avatars" from the selection drop down.
   
   If a user has selected an avatar in their account, it will display in any comments they make (currently only in Flat View).
2. Alternatively, you can  use the <xar:roles-avatar uid="$uid" size="50" /> custom block layout tag to add avatar display in your templates. This tag can be placed anywhere on a page where the user id is known.
   
   
   Usage options:
   1. uid - must be the correctly named variable in any given page where you use the tag. This directs the tag to display the avatar of the given user with user uid.
   2. size - optional parameter of avatar width in pixels. As we cannot assume every site has image module, or uploads and mime modules installed, this is currently a simple width parameter. By default the tag displays at 80 px wide.

You are now ready to allow users to select and use avatars on your site. They can set their avatar in their user account page by editing their Profile as illustrated in the first screen shot above.