Embed Privatemsg pages

This page explains how to embed certain pages of Privatemsg into your website. Be sure only to use code suitable for your respective version of Drupal.

You should know some things about Drupal administration (for example, how to create new blocks) and some PHP knowledge if you want to further customize the given examples.

Warning: While these examples say that you can put this in a custom block through the User Interface, it is heavily suggested to create a custom module instead to embed PHP code into your site. Also, these examples are untested and might not work properly.

Privatemsg for Drupal 6

Display list of latest 5 messages in a block

Create a new block with the PHP Filter and put the following code into it:

global $user;

// Generate the query to load the messages.
// Replace 'inbox' with 'sent' to display sent messages or 'list' to display all messages.
$query = _privatemsg_assemble_query('list', $user, 'inbox');

// Load 5 messages/threads. Replace 5 if you want to display a different amount of messages.
$result = db_query_range($query['query'], 0, 5);
$list = array();
while ($thread = db_fetch_array($result)) {
  // Generate a link with the subject as title that points to the view message page.
  $list[] = l($thread['subject'], 'messages/view/'. $thread['thread_id']);
}
// Display list as a themed item_list.
echo theme('item_list', $list);

Display a list of unread messages.

Put the following code into a custom module (If you don't have one, you need to create it: http://drupal.org/node/206753). This tells the query builder of Privatemsg to only include new messages when you pass the argument "unread" to it.

function yourmodule_privatemsg_sql_list_alter(&$fragments, $account, $argument) {
  if ($argument == 'unread') {
    $fragments['where'][] = 'pmi.is_new = 1';
  }
}

In a second step, you have to embed the list with the unread argument into your website. As an example, you could use the above example to display it in a block and simply replace "inbox" with "unread".

You can customize almost every query that Privatemsg uses to load information, see http://blog.worldempire.ch/api/group/sql/1 for more information.

Display a form to send a new private message

There are two possible ways to do this, depending on your use case:

Use the existing Privatemsg form

This is useful if you simply want to display this form in a block or another non-default place. Place the following code into a new block or wherever you want it:

// The module_load_include() is necessary when using 6.x-2.x
// module_load_include('pages.inc','privatemsg');
echo drupal_get_form('privatemsg_new');

You can further customize this by adding default recipients and/or a default subject.

// The first argument can be a list of user objects the message should be sent to. These are just default values and it is possibel to change them as a user.
// Example: Send to the user with uid 1.
$recipients = array(user_load(1));
// The second argument sets the default subject.
$subject = 'Again, this is just a default that can be changed';
echo drupal_get_form('privatemsg_new', $recipients, $subject);

Note: If you display this in a block, you probably need to theme the form with CSS and/or a theme function to make it narrower.

Use a custom form and the Privatemsg API functions

A possible use case for this would be a contact form to send messages to a specific user like the site admin. First you have to create your form with Drupal FAPI (see http://api.drupal.org/api/group/form_api/6) and validate it as usually. In your submit function, you can use the privatemsg_new_thread() API function to start a new thread:

The following example sends a message to user 1 with a hardcoded subject.

function your_form_name_submit($form, &$form_state) {
  // Send message to user 1.
  $recipients = array(user_load(1));
  // Define the subject of the thread
  $subject = 'Message sent through contact form';
  // We assume the fapi element with the message text is called "body".
  $body = $form_state['values']['body'];
  
  // Send the message.
  $return = privatemsg_new_thread($recipients, $subject, $body);
  
  // Check return value to see if the message has been sent.
  if ($return['success']) {
    // Message has been sent, display confirmation message.
    drupal_set_message(t('Message has been sent.'));
  }
  else {
    // Display possible errors...
    foreach ($return['messages']['error'] as $error) {
      drupal_set_message($error, 'error');
    }
  }
  // Display warnings, these might occur even if the message has been sent successfully.
  foreach ($return['messages']['warning'] as $warning) {
    drupal_set_message($warning, 'warning');
  }
}

Privatemsg for Drupal 7

Display list of latest 5 messages in a block

global $user;

// Generate the query to load the messages.
// Replace 'inbox' with 'sent' to display sent messages or 'list' to display all messages.
$query = _privatemsg_assemble_query('list', $user, 'inbox');

// Load 5 messages/threads. Replace 5 if you want to display a different amount of messages.

$list = array();
$count=0;
foreach ($query->execute() as $thread) {
  if ($count <=5) {
    // Generate a link with the subject as title that points to the view message page.
    // $list[] = l($thread->subject, 'messages/view/'. $thread->thread_id);
    // take a look at $thread to see if what you needed is already there, so you can bypass other theming functions (you probably shouldnt)

    // proper solution:
    $theme_variables=array('thread' => (array)$thread);
    $subject=theme('privatemsg_list_field__subject', $theme_variables);
    $list_parts[]=$subject['data'];
    $list_parts[]=t('from');
    $participants=theme('privatemsg_list_field__participants', $theme_variables);
    $list_parts[]=$participants['data'];
    $last_updated=theme('privatemsg_list_field__last_updated', $theme_variables);
    $list_parts[]=$last_updated['data'];
    $list[] = implode(' ',$list_parts);
    $count++;
  } else {
    break;
  }
}

// Display list as a themed item_list.

print theme('item_list', array('items'=>$list));

Display a list of unread messages.

Extending the above example; you have to modify the query returned from _privatemsg_assemble_query() to include only unread messages like this:

$query = _privatemsg_assemble_query('list', $user, 'inbox');
$query->condition('pmi.is_new', 1);

Render the send message form with preset recipient

For Drupal 7 user, you can render the form in block as follow.

  module_load_include('pages.inc','privatemsg');
  $recipients = array(user_load($uid));
  $subject = 'Again, this is just a default that can be changed';
  print drupal_get_form('privatemsg_new', $recipients, $subject);

Please open bug reports if an example does not work or create a support request if you have a privatemsg related question here: http://drupal.org/node/add/project-issue/privatemsg