Jot

From MODx Wiki

Jump to: navigation, search

 MODx Snippet 

Jot v1.0
Author 
Armand "bS" Pondman
MODx Versions 
>= 0.9.2
Last Updated 
11/3/2006
Jot is a snippet for MODx and gives your site users the opportunity to enter feedback on your articles. Add comments to articles, create guestbooks, you can even use multiple instances on the same page. Jot is the reincarnation of the former Replix snippet.

View this demo site to see Jot in action.

[edit]

Downloads

Download the latest version of Jot from MODx repository.

[edit]

Description

[edit]

Features

  • Add comments to any (part of your) document
  • Supports multiple instances on one page
  • Database support
  • Unlimited custom fields (separate for each instance)
  • Pagination
  • Sorting
  • Subscriptions
    Let users subscribe to each comment source so they can receive email notifications on new posts
  • Moderation
    • Publish/Unpublish
    • Delete/Edit/View
    • Email notifications
      Receive notifications on new comments (unpublished, containing bad words, or all content)
      Send notification to document author when new comment is added
  • Access control
    • can view / post / moderate
    • trusted users
  • Anti-spam
    • Captcha/Veriword validation
    • Post delay
    • Double post elimination
    • Bad language filter
      Specify bad words and take specific action (do nothing, unpublish, reject)
  • Control output by using placeholders
  • Enhanced templating (PHx enabled - not required)
[edit]

Installation

[edit]

New installation

  1. Download and extract the archive.
  2. Create a directory called "jot" in your [MODx Directory]/assets/snippets directory
  3. FTP or copy the files into [MODx Directory]/assets/snippets/jot
  4. Create a new snippet in the manager called "Jot" and copy/paste the contents of jot.snippet.txt into the code field.
[edit]

Upgrade from previous version

  1. Download and extract the archive.
  2. Backup and delete the contents of [MODx Directory]/assets/snippets/jot
  3. Copy the files into [MODx Directory]/assets/snippets/jot
  4. Update the "Jot" snippet in the manager and copy/paste the contents of jot.snippet.txt into the code field.
[edit]

Usage

  • [!Jot? &subscribe=`1` &pagination=`10`!]

or 

  • [[Jot? &subscribe=`1` &pagination=`10`]]

Depending on your page cache settings.

[edit]

Parameters

parameter optional value description
&action yes
  • default (form & comments)
  • count-comments
  • count-subscriptions
  • comments
  • form
Controls what to display
&docid yes (docid as integer) Link instance to this document, defaults to parent document id.
&tagid yes (tagid as string [A-Za-z0-9]) Extra tag to use when two instances use the same docid.
&subscribe yes
  • 0 (default)
  • 1
  • 0 = disable subscriptions.
  • 1 = enable subscriptions.
&moderated yes
  • 0 (default)
  • 1
  • 0 = new comments will be published
  • 1 = new comments will be unpublished
    a moderator/manager user can review before publishing.
&notify yes
  • 0
  • 1 (default)
  • 2

Notify moderators specified by &canmoderate by email

  • 0 = do not notify
  • 1 = notify on new unpublished reply
  • 2 = notify on every new reply
&subjectSubscribe yes (string) Subject for subscription notification email.
&subjectModerate yes (string) Subject for moderator notification email.
&captcha yes
  • 0 (default)
  • 1
  • 2
  • 0 = disable captcha when posting.
  • 1 = enable captcha when posting.
  • 2 = enable captcha when posting, but disable it for logged in users.
&badwords yes (comma delimited list of words not allowed in post) best practise is to create a chunk with bad words seperated by a comma and call Jot like: 
&badwords=`{{MyBadwordsChunk}}`
to allow central administration of your badwords list.

Use the &bw parameter to specify the required action on detection.

&bw yes
  • 0
  • 1 (default)
  • 2
When a word specified by &badwords is detected:
  • 0 = do nothing.
  • 1 = do not publish the comment.
  • 2 = reject the comment.
&customfields yes (comma seperated list of extra form fieldnames) Using this command will save the specified fields when posting.

defaults to "name, email".

&authorid yes (id of source author) defaults to author value for the current document.
&title yes (title of source) defaults to longtitle value for the current document.

used for subject when left empty.

&css yes
  • 0
  • 1 (default)
  • 0 = do not auto-include jot stylesheet in header
  • 1 = auto-include jot stylesheet in header
&cssFile yes (relative path from modx root to CSS file) default to location of the included jot.css
&sortby yes (comma seperated sort string) syntax:

fieldname:a (for ascending) or fieldname:d (for descending) defaults to "createdon:d".

&numdir yes
  • 0
  • 1 (default)
  • 0 = first comment lowest number.
  • 1 = first comment highest number.
&validate yes (comma seperated validate string) syntax: fieldname:message(:validation)

if a field name is entered in validate it automatically becomes a required field. if validation is omitted it assumes "required". other validations are:

  • number
  • email
  • custom regular expression

examples:

  • required field:
    • "MyRequiredField:This field is required!"
  • to validate an email field:
    • "MyEmailField:Not a valid e-mail address.:email"
  • to validate a number:
    • "MyNumberField:Not a number.:number"
  • to validate an hyphen seperated US phonenumber by using custom regular expression:
    • "MyPhoneField:Not a valid phonenumber:^[2-9]\d{2}-\d{3}-\d{4}$"
  • Combinations of multiple validations:
    • "MyRequiredField:This field is required!,MyEmailField:Not a valid e-mail address.:email,MyNumberField:Not a number.:number"


defaults to "content:You forgot to enter a comment."


&guestname yes (string) The anonymous authorname to use when none is specified.

defaults to: anonymous.

&postdelay yes (seconds as integer) number of seconds there must be between posts from the same user.

Enter 0 to disable, defaults to: 15.

&pagination yes (number of comments per page)
  • 0 = disable, show all comments on one page (default)
  • 1 > enable paging with specified number.
&placeholders yes
  • 0
  • 1
  • 0 = no placeholders are created (default)
  • 1 = placeholders are created for every debug value (see &debug parameter)
    • if no tagid is specified the placeholders are created like this:
      [+jot.html.form+]
    • if the tagid is specified the placeholders are created like this: 
      [+jot.html.form.tagid+]
&output yes
  • 0
  • 1
  • 0 = hide output (can be used in combination with &placeholder parameter)
  • 1 = show output (default)
&debug yes
  • 0
  • 1
  • 0 = disable output of jot "hidden" variables. (default)
  • 1 = enable output of jot "hidden" variables.
&trusted yes (comma delimitted web groups) Comma delimitted web groups that are trusted and have their comments

published by default when &moderated is set 1. Badwords also does not apply for trusted webgroups. Manager users are always trusted.

&canpost yes (comma delimitted web groups) Comma delimitted web groups that can post comments.

Leave blank for public posting.

&canview yes (comma delimitted web groups) Comma delimitted web groups that can view comments.

Leave blank for public viewing.

&canedit yes (comma delimitted web groups) Comma delimitted web groups that can edit their OWN comments.

Leave blank for no editing by users.

&canmoderate yes (comma delimitted web groups) Comma delimitted web groups that can moderate comments.

Leave blank for no webuser moderation (=moderation by using manager account).

&notifyAuthor yes
  • 0 (Default)
  • 1
Send the author of the document an email notification when someone posts a comment (v 1.1.3+)
&subjectAuthor yes (string) Subject for author notification email (v 1.1.3+)
[edit]

Template parameters

parameter optional description
&tplForm yes Template (HTML) for user form.
&tplComments yes Template (HTML) for comment. This templates gets repeated for each comment.
&tplModerate yes Template (HTML) for moderation block. This templates gets included once (top) in comment view
&tplNav yes Template (HTML) for navigation bar. This templates gets included twice (top and bottom) in default comment view.
&tplSubscribe yes Template (HTML) for subscriptions block. This templates gets included once (top) in comment view
&tplNotify yes Template (TXT) for notification email for subscribers.
&tplNotifyModerator yes Template (TXT) for notification email for moderators.
&tplNotifyAuthor yes Template (TXT) for notification email for author (v 1.1.3+)
&cssRowAlt yes CSS style classname for alternate row.
&cssRowMe yes CSS style classname for current user row.
&cssRowAuthor yes CSS style classname for author row.
[edit]

Examples

Feel free to add your own examples to the list.

[edit]

simple

  • allow subscriptions
  • paginated: 10 comments per page 
[[Jot? &subscribe=`1` &pagination=`10`]]
[edit]

simple: alternate sorting

  • allow subscription.
  • paginated: 10 comments per page.
  • comments are sorted starting with the oldest post first. 
[[Jot? &subscribe=`1` &pagination=`10` &sortby=`createdon:a`]]
[edit]

moderated

  • allow subscriptions
  • paginated: 10 comments per page
  • new posts are unpublished and need to be published by a moderator (in this case a manager user)
  • a manager account won't receive notifications. You have to create a webgroup with a webuser that acts as the moderator. 
[[Jot? &subscribe=`1` &pagination=`10` &moderated=`1`]]
[edit]

moderated: trusted

  • allow subscriptions
  • paginated: 10 comments per page
  • new posts are unpublished and need to be published by a moderator (in this case a manager user)
  • new posts by users that are member of the "Trusted Users" webgroup will be published. 
[[Jot? &subscribe=`1` &pagination=`10` &moderated=`1` &trusted=`Trusted Users`]]
[edit]

anti-spam: automatic

  • paginated: 10 comments per page
  • captcha validation for everyone
  • if a bad word is detected the post will be rejected
  • the badwordlist is a chunk containing words seperated by a comma 
[[Jot? &pagination=`10` &captcha=`1` &badwords=`{{myBadwordList}}` &bw=`2`]]
[edit]

anti-spam: moderated

  • paginated: 10 comments per page
  • captcha validation for everyone
  • if a bad word is detected the post will be unpublished and a notify will be send out to the moderators.
  • webusers in the "Jot Moderators" webgroup can moderate comments
  • the badwordlist is a chunk containing words seperated by a comma 
[[Jot? &pagination=`10` &captcha=`1` &canmoderate=`Jot Moderators` &badwords=`{{myBadwordList}}` &bw=`1`]]
[edit]

Tips & Tricks

[edit]

Best practise for including comments

The best practise for comment-enabling your documents is to create a chunk for each type of Jot call you will use. Include each chunk in a template and link it to your articles. Try to avoid direct jot calls in the content field of a document (even if it's a chunk).

[edit]

Extended MODx templating

Jot uses an internal template handler that includes the functionality of the PHx plugin available from the repository. For more details on the modifiers check its description here.

Note: Jot does not require that the PHx plugin is installed. If not installed PHx functionality will still be available, but for the Jot templates only.

[edit]

Active identity

When logged in as both web- and manager user your webuser identity will over-rule your manager identity but your permissions will be the same. When logged in as a manager user you will always have moderator options.

[edit]

Custom fields

The custom fields you specify with &customfields will have to be added to your form chunk manually. The default templates holds an example of how a guest form looks (added fields here are: name and email)

NOTE: Be sure to prefix custom. to custom field. ie. [+comment.custom.customfieldname.url+]

[edit]

Bad words

Bad words are checked on all input, including custom fields.

[edit]

URL/Link generation

All generated links by Jot will preserve the current querystring and only the variables specific for the Jot instance are altered if necessary. This ensures that the current page state (that could be altered by other snippets on the same page) is preserved.

[edit]

Layout Ideas

To change the way jot outputs your forms including where moderator comments and actual comments appear use your call as normal 

[[Jot? &placeholders=`1` &output=`0` &pagination=`10` &captcha=`1` &canmoderate=`Jot Moderators` &badwords=`{{myBadwordList}}` &bw=`1`]]
Please note: You need to set 
&placeholders=`1` &output=`0`

Then, you can add these placeholders calls in your page where the Jot call is. 

[+jot.html.navigation+] - First. places the navigation on the page
[+jot.html.comments+] - Second. places the comment of the page
[+jot.html.moderate+] - Third. places moderated info on the page
[+jot.html.form+] - Fourth. places the form on the page

You can change the order as you see fit, the example has the comments first then the form is last but you could have. 

[+jot.html.form+] - First. places the form on the page
[+jot.html.comments+] - Second. places the comment of the page
[+jot.html.moderate+] - Third. places moderated info on the page
[+jot.html.navigation+] - Fourth. places the navigation on the page
Retrieved from "http://wiki.modxcms.com/index.php/Jot"
Personal tools