Documentation

End-User Instructions

To install this package:

  1. Install through the standard Add Functionality page
  2. Add a "wall" to the profile page
    1. Go to a profile (via, e.g., Members -> [your username])
    2. Edit page
    3. Add 'Concrete Wall' block
    4. Configure it as a wall and with a larger number (e.g. 30) max postings
    5. Save and publish
  3. Add an "activity feed" to your homepage, or another landing page
    1. Go to the page
    2. Edit page
    3. Add 'Concrete Wall' block
    4. Configure it as an activity feed and with a smaller number (e.g. 5) max postings
    5. Save and publish
  4. Install or upgrade add-ons that support the wall, and let activities begin to be populated. Alternatively, you can look at the developer instructions to easily make the modifications yourself.

Developer Instructions

A demonstration package which has been modified to work with lerteco_wall is available for download. It is a modified version of the 'Likes This' block from Andrew Embler. It will install normally and, if lerteco_wall is installed, send posts to lerteco_wall when users like a page. The relevant changes are in blocks/likes_this/controller.php and start at line 9 and line 80. There are only 5 lines of code, including the closing brace for an if statement. Reading the likes_this package may help you follow the explanation below better.

The wall model is based on the idea of a posting type and a posting.

A posting type describes the type of posting that can be added to a wall. Each package (and the core) must set up (register) its own posting types. Posting types can be enabled/disabled by the admin and describe:

  • The package (or core) that will make the posting
  • The type of posting (as described by a name, like "Likes" and a code, like "like_add")
    The code must be unique within your package and is used for referencing the type when adding a new notification or updating the type. For consistency, the code should loosely be in the format of noun_verb. ie, "forum_post_add" or "forum_post_delete" or "friend_new".
  • The template used to display the notification (you'll see that a notification only includes an array of data, and shouldn't include much text).

    The template and the posting array will be run through a special method and then run through vsprintf, which means that you can use the standard sprintf syntax. It's recommended that you use numbered placeholders (see Argument Swapping) in case you want to change the template in the future. Additionally, there are (so far) two custom type specifiers (which you must use in the numbered placeholder format):
    * %[place]$u for users. You only need to pass a uID in the data, and lerteco_wall will create a link with the proper URL and usename.
    * %[place]$p for pages. Similary, you only need to pass a pageID in the data, and lerteco_wall will create a link with the proper URL and page name.
    When expanding these two type specifiers, lerteco_wall will look for elements named wall_user or wall_page, respectively, and pass a userinfo object or a page object named 'userinfo' or 'page', respectively. The rendered version of these elements will be used instead of the default text. This would allow, for example, for the user hover functionality that is on concrete5.org.

    To produce a posting template for items other than pages and users, the developer will be responsible for creating the full text (and HTML) and using the standard sprintf string type. For example, a forum posting (which includes an a-name) might have the template "said something cool about %1$s" while the passed-in post data is "<a href='$postURL'>$postTitle</a>".

    The rendered template text will be placed after the the name of the user who did the action. Thus, a template should be something like, "added a new blog entry How to Use The Wall'". The username will be in 3rd person and you can use tense as appropriate (e.g., "James likes a page" sounds better than "James liked a page", despite the fact that "James posts a blog entry" sounds awkward).
  • Template example data is part of the type and allows the admin to see how the template will render. It should be in the same format as the posting data.
  • Share With refers to a constant in PostingType: 1 will make all postings of the type private to only the user's friends, and 2 will make the postings public to whoever can view the block (which the site owner can lock down with standard c5 permissions).

A package can register as many posting types as appropriate (added a blog entry, commented on a blog entry, liked a blog entry, had a record number of posts this week, etc -- though you probably wouldn't want to add types for editing or deleting -- think of what users want to know about).

A posting represents the instance of the activity and describes:

  • Which type of posting it is
  • The user that did the action
  • The arbitrary data that you pass in. This is an array and depends on what the template will display. In many cases it will be a single value (such as a page id), in which case you can pass the value and lerteco_wall will put it into an array for you. However, your template might be something like 'responded to a comment by [previous commenter] on [blog entry name]'.
  • The posting date is stored automatically

In principle, you will register the posting type once (probably on installation) and reference the type code when sending a posting. However, since lerteco_wall might not have been installed when your package was installed, and it would be complicated for you to check if lerteco_wall is available, if you've previously registered, and, if not, register, you should try to register your type each time you create a posting. lerteco_wall will take care of ensuring that each type is only registered once (and, in fact, will update the name, template, or template example data if you've changed it).

A single method is available in the package controller which allows you to register and create a posting in one call. The likes_this package has the following lines added:

// these are the values that you would use to register the type. We set up this variable for the sake of clean code
protected $posting_type = array('likes_this_block', 'page_like', 'Likes', 'likes %1$p', 1, 2);

// we try to load the lerteco_wall package and then check if it's available
$wall = Loader::package('lerteco_wall');
if (is_object($wall)) {
//it's installed. now we call the single method which creates the posting and, if necessary, the posting type
$wall->postAndPossiblyRegister($u->getUserID(), $page->getCollectionID(), $this->posting_type);
}

If you don't want to use the single helper method, you should create a new instance of either PostingType or Posting and call the relevant methods.

Any questions or suggestions can be discussed here.

 

Privacy

Privacy is obviously a concern. Clearly, though, there are many activities on a site which are already public. For example, the public can already view which users "like" a page or have posted to the forum. Given that, consolidating these activities into a feed should not be viewed too negatively from a privacy standpoint. Additionally, privacy is addressed through:

  1. A site administrator can configure which types of postings are enabled and disabled. For example, "like"ing a page or posting a blog entry might both be enabled, while buying an item from the store would not.
  2. Different types of postings are set to either be shared with the public or with the users' friends. A purchase activity might only be seen by friends while creating a blog entry would be seen by the public. This setting affects the activity feed (e.g. the short list on the homepage) and the user's wall.