Skocz do zawartości
Zaloguj się, aby obserwować  
Invisionize.eu

[Dokumentacja IPS4] Introduction to Comments

Polecane posty

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: 

 

Wyświetl pełny artykuł

Udostępnij ten post


Link to postu
Udostępnij na innych stronach

Bądź aktywny! Zaloguj się lub utwórz konto

Tylko zarejestrowani użytkownicy mogą komentować zawartość tej strony

Zaloguj się, aby obserwować  

  • Kto przegląda   0 użytkowników

    Brak zalogowanych użytkowników przeglądających tę stronę.

×

Ważne informacje

Kontynuując przeglądanie strony, wyrażasz zgodę na używanie przez nas plików cookies.