The user object

The user object represents a Liquid Site user.

• domainadmin
  Checks whether the user has administration priviledges over the domain.
• email
  Returns the user email.
• groups
  Returns a list of the groups to which the user belongs.
• groupAdd(name)
  Adds the user to the specified group.
• groupRemove(name)
  Removes the user from the specified group.
• isGroup(name)
  Checks if the user is member of a named group.
• login
  Returns the user login username.
• realName
  Returns the user real name.
• save()
  Saves all the modifications to a user.
• sendEmailVerification(subject, text, replaceText)
  Sends an email verification request to the user.
• setEmail(email)
  Modifies the user email.
• setLogin(login)
  Modifies the user login username (only new users).
• setPassword(password)
  Modifies the user password.
• setRealName(name)
  Modifies the user real name.
• superuser
  Returns the superuser flag for the user.
• verifyEmail(key)
  Verifies the user email address and unlocks this user.

domainadmin

Checks whether the user has administration priviledges over the domain.

Syntax:

domainadmin → boolean

Returns:

True if the user has administration priviledges over the domain, false otherwise.

Example:

This code checks if a user has administration priviledges:

<#assign user = liquidsite.findUser("liquidsite").lock>
<#if user.domainadmin>

email

Returns the user email.

Syntax:

email → string

Returns:

The user email.

Example:

This code outputs the email of a user:

<#assign user = liquidsite.findUser("liquidsite").lock>
<p>The user email is ${user.email}</p>

groups

Returns a list of the groups to which the user belongs.

Syntax:

groups → sequence of string

Returns:

A list of the groups to which the user belongs.

Example:

This code loops through a user groups:

<#assign user = liquidsite.findUser("liquidsite").lock>
<#list user.groups>

groupAdd

Adds the user to the specified group. The user will only be added if the group exists and is public. Furthermore, the change is not saved until the save() method is called.

Syntax:

groupAdd(name) → nothing

Parameters:

• name -- the string containing the group name

Example:

This code adds a group "Newslist" from the current user:

${liquidsite.user.groupAdd("Newslist")}
<#assign result = liquidsite.user.save()>

groupRemove

Removes the user from the specified group. The user will only be removed if the group exists and is public. Furthermore, the change is not saved until the save() method is called.

Syntax:

groupRemove(name) → nothing

Parameters:

• name -- the string containing the group name

Example:

This code removes a group "Newslist" from the current user:

${liquidsite.user.groupRemove("Newslist")}
<#assign result = liquidsite.user.save()>

isGroup

Checks if the user is member of a named group.

Syntax:

isGroup(name) → boolean

Parameters:

• name -- the string containing the group name

Returns:

True if the user belongs to the named group, false otherwise.

Example:

This code checks if a user belongs to a certain group:

<#assign user = liquidsite.findUser("liquidsite").lock>
<#if user.isGroup("editors")>

login

Returns the user login username.

Syntax:

login → string

Returns:

The user login username.

Example:

This code outputs the login of a user:

<#assign user = liquidsite.findUser("liquidsite").lock>
<p>The user login is ${user.login}</p>

realName

Returns the user real name.

Syntax:

realName → string

Returns:

The user real name.

Example:

This code outputs the real name of a user:

<#assign user = liquidsite.findUser("liquidsite").lock>
<p>The user realName is ${user.realName}</p>

save

Saves all the modifications to a user. This method will write all the changes to the database if security permits.

New users can be saved by non-logged in users. Existing users can be saved by themselves. A logged in user with administrator privileges can save any other user, including themselves. Superusers cannot be modified at all by this method.

Syntax:

save() → boolean

Example:

This code creates a new user "bob":

<#assign user = liquidsite.findUser("bob")>
${user.setLogin("bob")}
${user.setPassword("secret")}
${user.setRealName("Robert")}
${user.setEmail("info@liquidsite.net")}
<#assign result = user.save()>

setEmail

Modifies the user email address. The change is not saved until the save() method is called.

Syntax:

setEmail(email) → nothing

Parameters:

• email -- the string containing the new email address

Example:

This code modifies the current user email address:

${liquidsite.user.setEmail("info@liquidsite.net")}
<#assign result = liquidsite.user.save()>

setLogin

Modifies the login username. This method can only be called for new users that have not yet been saved. It is not possible to change login username once a user has been saved. The new user is not saved until the save() method is called.

Syntax:

setLogin(login) → nothing

Parameters:

• login -- the string containing the login name

Example:

This code creates a new user "bob":

<#assign user = liquidsite.findUser("bob")>
${user.setLogin("bob")}
${user.setPassword("secret")}
${user.setRealName("Robert")}
${user.setEmail("info@liquidsite.net")}
<#assign result = user.save()>

setPassword

Modifies the user password. The change is not saved until the save() method is called.

Syntax:

setPassword(password) → nothing

Parameters:

• password -- the string containing the new password

Example:

This code modifies the password for the current user:

${liquidsite.user.setPassword("secret")}
<#assign result = liquidsite.user.save()>

setRealName

Modifies the user real name. The change is not saved until the save() method is called.

Syntax:

setRealName(name) → nothing

Parameters:

• name -- the string containing the new user real name

Example:

This code modifies the name for the current user:

${liquidsite.user.setRealName("Bobby")}
<#assign result = liquidsite.user.save()>

superuser

Returns the superuser flag for the user.

Syntax:

superuser → boolean

Returns:

True if the user is superuser, false otherwise.

Example:

This code checks if a user is superuser:

<#assign user = liquidsite.findUser("liquidsite")>
<#if user.superuser>

sendEmailVerification

Sends an email verification request to the user. The request email will only be sent if the user exists, has an email address set and has not been modified. A verfication key will be inserted into the email subject and text where a specified replacement text matches. The secret validation key is only sent to the user in email and cannot be retrieved in any other way for security reasons.

This method is used for password recovery, as it would be unsecure to allow changes to users that cannot in some way authorize themselves. By sending a validation key to the user by email, it will only be possible to change the password if the user was able to read their email. When the user provides the validation key from the email, this user object can be unlocked with the verifyEmail(key) method.

Syntax:

sendEmailVerification(subject, text, replaceText) → boolean

Parameters:

• subject -- the string containing the email subject text (and possibly text for replacement)
• text -- the string containing the email body text (and text for replacement)
• replaceText -- the string containing the text pattern to replace with the generated validation key

Returns:

True if the email was sent, or false otherwise.

Example:

This code sends an email verification mail:

<#assign user = liquidsite.findUser("bob")>
<#assign subject = "Validation Key">
<#assign text = "Validation Key:  ####">
<#assign result = user.sendEmailVerification(subject, text, "####")>

verifyEmail

Verifies the user email address and unlocks this user. The verification is done by comparing a previously sent key with the specified one. If the two keys match, the user email is considered verified and this user object is unlocked for save operations by an anonymous user.

This method is used for password recovery, as it would be unsecure to allow changes to users that cannot in some way authorize themselves. By sending a validation key to the user by email, it will only be possible to change the password if the user was able to read their email. The validation key to enter for a user is created and sent with the sendEmailVerification(subject, text, replaceText) method.

Syntax:

verifyEmail(key) → boolean

Parameters:

• key -- the string containing the validation key from the user

Returns:

True if the email was verified, or false otherwise.

Example:

This code uses a verification key to unlock a user and modify the password:

<#assign user = liquidsite.findUser("bob")>
<#if user.verifyEmail(liquidsite.request.param.key)>
  ${user.setPassword("secret")}
  <#if user.save()>
    Password changed
  <#else>
    Failed to save user
  </#if>
<#else>
  Invalid validation key, email couldn't be verified
</#if>