Jump to content

Community

  • We are moving our Documentation to our new Guides area.

    As articles are moved they will be deleted. Please start following the new guides. We look forward to publishing all our new guides soon!

  • Sign in to follow this  

    Introduction to Comments (*)


    Charles

    Requirements

    The Model
    Skeleton
    namespace IPS\yourApp;

    class _Comment extends \IPS\Content\Comment
    {
    

    /**
    * @brief [ActiveRecord] Multiton Store */

         protected static $multitons;
    

    /**
    * @brief Default Values */

         protected static $defaultValues = NULL;
    

    /**
    * @brief [Content\Comment] Item Class */

         public static $itemClass = 'IPS\yourApp\YourClass';
    

    /**
    * @brief [ActiveRecord] Database Table */

         public static $databaseTable = 'yourapp_comments';
    

    /**
    * @brief [ActiveRecord] Database Prefix */

         public static $databasePrefix = ‘comment_';
    

    /**
    * @brief Title */

         public static $title = ‘thing_comments’;
    

    /**
    * @brief Database Column Map */

         public static $databaseColumnMap = array(
    

    );

    'item'
    'author'
    'author_name'
    'content'
    'date'
    'ip_address'
    
    => 'fid',
    => 'mid',
    => 'author',
    => 'text',
    => 'date',
    => 'ip_address',
    

    61

    }

    Introduction

    Just like Content Items themselves, Comments also need a model which follow the Active Record design pattern.

    The inheritance is similar to Content Items (though \IPS\Content\Comment is instead of \IPS\Content\Item, though both extend \IPS\Content. The required properties are the same as Content Items, with the addition of $itemClass.

    The elements required for $databaseColumnMap are:

    • item should be the column that contains the ID number of the item the column belongs

      to.

    • author, like for item, should be the column that contains the ID number of the user who

      posted the comment.

    • content should be the column that contains the actual comment text.

    • date should be the column that contains the timestamp of when the comment was

      posted.

    • ip_address should be the column that contains the IP address of the user who posted

      the comment.
      The optional elements are:

    • author_name is optional, but if specified should be the column to contain the username

      of the user who posted the comment.

    • first should be a column that contains a boolean value indicating if this is the first

      comment on the item.

      Available Methods

      In addition to those provided by \IPS\Patterns\ActiveRecord (which work exactly the same as for Content Item models) a number of additional methods are available:

      url( $action=NULL )
      

      Gets the URL directly to that comment (will automatically work out the correct page number and anchor). Unlike for Content Items, this method is already defined for you.

      item()

      Returns the \IPS\Content\Item object of the item the comment belongs to.

      author()
      truncated(
      bool $oneLine=FALSE ) canView(...)
      canEdit(...)
      canDelete(...)
      modPermission(...)
      modAction(...)

      All behave the same as content items.

      isFirst()

      Returns a boolean value indicating if this is the first comment on the item. 62

    isIgnored( \IPS\Member $member=NULL )
    Returns a boolean value indicating if this comment should be ignored by $member (currently logged in member for NULL).

    dateLine()

    Returns a string that can be used in templates saying something along the lines “Posted 2 days ago”.

    html()

    Returns the HTML to display the comment (in it’s template).

    Optional Properties

    A number of optional properties can be specified:

    static $commentTemplate
    

    A callback specifying the template used to display the comment (a standard template is used by default).

    static $formTemplate
    

    A callback specifying the template used to display the form for posting the comment (a standard template is used by default).

    static $incrementPostCount
    

    A boolean value controlling if post counts should be incremented for comments of this type.

    static $formLangPrefix
    

    Behaves the same as for content items allowing you to change the language strings used on the submission form.

    Changes to make to Content Item model

    Add a new property to your Content Item model:

         public static $commentClass = ‘IPS\yourapp\YourClass';
    

    If your Content Item requires a first comment - for example, IP.Board topics need at least 1 post, so this is true for topics, but IP.Downloads files are posted with no comments to start with, so it is not true for files - add an additional property:

         protected static $firstCommentRequired = TRUE;
    

    Add new elements to $databaseColumnMap:

    63

    Element

    Description

    Required?

    num_comments

    The number of comments

    Yes

    last_comment

    Unix timestamp of when last comment was made

    No

    last_comment_by

    ID of member who made last comment

    No

    last_comment_name

    Username of the member who made the last comment

    No

    Create an EditorLocations extension

    To display the comment text editor, it will automatically look for an editor extension using the $application and $module properties of your content item, so you’ll need to create an editor extension that matches that.

    Displaying

    You can display the comments however you like, however, to ensure that the JavaScript features such as AJAX replying and editing works, you must apply certain attributes.

    Here is example markup:

    <div data-controller='core.commentFeed' data-feedID='messages-
    {$item->id}'>
    
         <br>
         {{if $item->commentPageCount() > 1}}
    
              {$item->pagination()|raw}
    
              <br><br><br>
         {{endif}}
    
         <div data-role='commentFeed'>
              {{foreach $item->comments() as $comment}}
    
                   {$comment->html()|raw}
              {{endforeach}}
    
         </div>
         <div data-role='replyArea'>
    
              {$item->commentForm()|raw}
         </div>
    

    </div>

    These methods will use generic templates. To customise the template used, add either or both of these methods to your Comment model (the values shown here are their default values):

    /**
    * @brief [Content\Comment] Comment Template */

         public static $commentTemplate = array( array( 'global',
    'core', 'front' ), 'commentContainer' );
    

    64

    /**
    * @brief [Content\Comment] Form Template */

         public static $formTemplate = array( array( 'forms', 'core',
    'front' ), 'commentTemplate' );
    

    65

    Content Item Changes

    Additional properties and methods in \IPS\Content\Item static $commentsPerPage

    Controls the number of comments per page. Defaults to 25.

    commentPageCount()

    Returns the number of pages of comments.

    commentPagination()

    Returns the HTML for pagination links

    comments( int $limit=NULL, int $offset=NULL, string $order=‘date’, string $orderDirection=‘asc’, \IPS\Member $member=NULL )
    Returns either an \IPS\Content\Comment object (if $limit is 1) or an array of comments. See phpdocs for full details.

    commentForm()

    Returns the HTML for the reply form.

    lastCommentPageUrl()

    Returns the URL for the last page of comments.

    canComment()

    Returns a boolean value indicating if the member logged in can comment.

    Behaviour Changes

    stats() will now return an additional element including the number of comments.

    66

    Searching Introduction

    Comments can be included in search results and the activity stream alongside content items.

    Other Requirements

    Searching must be implemented on the content items.

    Behaviour that changes once implemented

    Comments will be indexed and included in search results and the activity stream. The index will automatically be updated when comments are created, edited, moved, hidden, etc. and works automatically with both the MySQL index and Sphinx.

    Additional methods available once implemented

    None.

    How to implement

    1. Add an interface:

    implements \IPS\Content\Searchable

    67

    Reports Introduction

    Comments can be reported to moderators.

    Other Requirements

    None.

    Behaviour that changes once implemented

    A “Report” button will automatically appear next to the comment for members that can report the comment.

    Additional methods available once implemented

    canReport( [$member] )

    Checks if the member (either the given member or the currently logged in member) can report the content, taking into consideration if their group is allowed to submit reports, if they can view the content, if they are the author and if they have already reported that item.

    report( $reportContent )

    Submits a report.

    How to implement

    1. Add an interface:

         implements \IPS\Content\ReportCenter
    

    2. Add a new properties to define a CSS class name to represent your content item when viewing reports.

         public static $icon = 'icon';
    

    68

    Edit History Introduction

    Comments can log who has edited the comment and the changes that have been made.

    Other Requirements

    None.

    Behaviour that changes once implemented

    When editing, the details of the edit will be logged and displayed on the comment. The exact behaviour depends on the site’s configuration.

    Additional methods available once implemented editLine()

    Returns the “Edited x days ago by User” line to display next to the comment.

    editHistory( bool $staff )

    Returns an Iterator with the edit history.

    How to implement

    1. Add an interface:

    implements \IPS\Content\EditHistory 2. Add the following elements to $databaseColumnMap

    Element

    Description

    Required?

    edit_time

    Unix timestamp of when edit was made

    Yes

    edit_show

    Boolean indicating if edit message should show

    Yes

    edit_member_name

    Username of member making the edit

    Yes

    edit_reason

    Reason for the edit

    No, but recommended

    edit_member_id

    ID of member making the edit

    No

    69

    Hiding / Approving Introduction

    Comments can be hidden to non-staff members. This can be used to require staff approval before comments can be viewed, and as a way for staff members to hide undesirable comments.

    Other Requirements Requirements:

    None.

    Optional:

    Moderator permissions

    Behaviour that changes once implemented

    • loadAndCheckPerms(...) will now throw an OutOfRange exception if a hidden content item is loaded and the currently logged in user does not have permission to view is hidden content.

    • Hidden comments will only show to users who have permission to view hidden comments.

    • Users with appropriate moderator permission will see buttons to hide/unhide in comments.

    • Users who are set to have all new content moderated will have their comments hidden until it is manually approved.

      Additional methods available once implemented

      hidden()

      Returns a number indicating the hidden state:
      -1 means the content is hidden, but was previously unhidden.
      0 means the content is unhidden (default, normal status).
      1 means the content is hidden and was marked hidden at the time of posting.

      canHide( \IPS\Member $member=NULL )
      Returns a boolean value indicating if $member (currently logged in member if NULL) can hide the item. Takes into consideration if it is already locked.

      canUnhide( \IPS\Member $member=NULL )
      Returns a boolean value indicating if $member (currently logged in member if NULL) can unhide the item. Takes into consideration if it is already locked.

      A new method is also available in the content item class: 70

    canViewHiddenComments( \IPS\Member $member=NULL )
    Returns a boolean value indicating if $member (currently logged in member if NULL) can view hidden comments on the item.

    How to implement

    1. Add an interface:

           implements \IPS\Content\Hideable
      
    2. Add either a hidden or an approved element to $databaseColumnMap pointing to

      the column in the database which contains the status of the content.

    3. Optionally,youcanalsoaddaunapproved_commentselementtothe $databaseColumnMap in the content item class pointing to the column containing the number of comments pending approval.

    4. If a user is configured to have their content approved, their comments will be hidden by default automatically. You may want to override the method that handles this so, for example you can make certain nodes have all comments posted to items within them require approval. To do this, override the moderateNewComments(...) method in the content item class - for example:

         public static function moderateNewComments( \IPS\Member
    $member )
    
         {
              if ( $this->item()->container()->bitoptions[‘moderation’]
    
    and !static::modPermission( 'unhide', $member, $this->item()-
    >container() ) )
    
              {
                   return TRUE;
    

    }

              return parent::moderateNewComments( $member );
         }
    

    Element

    Value if unhidden (normal, default)

    Value if hidden (was previously unhidden)

    Value if pending approval

    hidden

    0

    -1

    1

    approved

    1

    -1

    0

    71

    Reputation Introduction

    Users can “like” or give reputation on comments. A member’s total reputation displays on their profile.

    Other Requirements

    None.

    Behaviour that changes once implemented

    Reputation buttons will automatically appear next to comments.

    Additional methods available once implemented reputation()

    Returns an integer indicating the current reputation for the item.

    canGiveReputation( int $type, \IPS\Member $member=NULL )
    Returns a boolean value indicating if $member (currently logged in member if NULL) can give $type (1 for positive, -1 for negative) reputation on the comment.

    giveReputation( $type, \IPS\Member $member=NULL )
    Gives reputation on the comment. Will throw DomainException if $member is not allowed to give reputation on the comment.

    repGiven( \IPS\Member $member=NULL )
    Returns an integer (1 for positive, -1 for negative, 0 for no reputation given) indicating what reputation $member (currently logged in member if NULL) has given to the comment.

    How to implement

    1. Add an interface:

         implements \IPS\Content\Reputation
    

    2. Addapropertyspecifyingakeytodistinguishreputationgivenonthistypeofcontent item as opposed to another. It can be anything you like, though convention is to use the name of the column in your database table (with prefix) which stores the ID.

         public static $reputationType = ‘comment_id’;
    

    72

    Following Introduction

    Members can follow content items and receive a notification when new comments are posted in it.

    Other Requirements

    The content items must be followable.

    Behaviour that changes once implemented

    After posting a new comment, members who are following the content item it was posted in will receive a notification. If the comment needs to be approved by a moderator, the notifications will be delayed until the comment has been approved.

    Additional methods available once implemented
    These methods are available to the content item class, not the comment class:

    followers( int $privacy=3, array $frequencyTypes=array( ‘immediate’, ‘daily’, ‘weekly ), array $limit=array( 0, 25 ), string $order=‘name’ )
    Returns an \IPS\Db\Select object which can be iterated on to get details about which members are following the item. See phpDocs for available options. $privacy is a bitwise value using the \IPS\Content\FOLLOW_* constants - the default value, 3, includes public and anonymous follows.

    How to implement

    1. Addafollowbuttononthepagewhereyourcontentitemcanbeviewed:

    {template="follow" app="core" group="global" params=“'yourApp', ‘YourContentItemClass’, $item->id, $item->followers()->count( TRUE )"}
 

     

    Example: 

     

    Sign in to follow this  


    User Feedback

    Recommended Comments

    There are no comments to display.


×
×
  • Create New...