Jot
Jot is a snippet for Evo 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.
Description
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)
Installation
New installation
- Download and extract the archive.
- Create a directory called "jot" in your "[Evo Directory]/assets/snippets" directory
- FTP or copy the files into "[Evo Directory]/assets/snippets/jot"
- Create a new snippet in the manager called "Jot" and copy / paste the contents of "jot.snippet.txt" into the code field.
Upgrade from previous version
- Download and extract the archive.
- Backup and delete the contents of "[Evo Directory]/assets/snippets/jot"
- Copy the files into "[Evo Directory]/assets/snippets/jot"
- Update the "Jot" snippet in the manager and copy / paste the contents of "jot.snippet.txt" into the code field.
Usage
[!Jot? &subscribe=`1` &pagination=`10`!]
or
[[Jot? &subscribe=`1` &pagination=`10`]]
Depending on your page cache settings.
Parameters
Parameter | Optional | Value | Description |
---|---|---|---|
&action | yes |
|
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 |
|
|
&moderated | yes |
|
|
¬ify | yes |
|
Notify moderators specified by &canmoderate by email
|
&subjectSubscribe | yes | (string) | Subject for subscription notification email. |
&subjectModerate | yes | (string) | Subject for moderator notification email. |
&captcha | yes |
|
|
&badwords | yes | (comma delimited list of words not allowed in post) | best practice is to create a chunk with bad words separated 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 |
|
When a word specified by &badwords is detected:
|
&customfields | yes | (comma separated list of extra form fieldnames) | Using this command will save the specified fields when posting.
defaults to "name,email". (Note: Be sure not to have spaces in comma separated list of custom fields in the Jot call.) |
&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 |
|
|
&cssFile | yes | (relative path from Evo root to CSS file) | default to location of the included jot.css |
&sortby | yes | (comma separated sort string) | syntax:
fieldname:a (for ascending) or fieldname:d (for descending) defaults to "createdon:d". |
&numdir | yes |
|
|
&validate | yes | (comma separated 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:
examples:
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) |
|
&placeholders | yes |
|
|
&output | yes |
|
|
&debug | yes |
|
|
&trusted | yes | (comma delimited web groups) | Comma delimited 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 delimited web groups) | Comma delimited web groups that can post comments.
Leave blank for public posting. |
&canview | yes | (comma delimited web groups) | Comma delimited web groups that can view comments.
Leave blank for public viewing. |
&canedit | yes | (comma delimited web groups) | Comma delimited web groups that can edit their OWN comments.
Leave blank for no editing by users. |
&canmoderate | yes | (comma delimited web groups) | Comma delimited web groups that can moderate comments.
Leave blank for no webuser moderation (=moderation by using manager account). |
¬ifyAuthor | yes |
|
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+) |
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. |
If you are using templates, create a chunk in Evo, you can get the default templates from the "jot/template" directory
Examples
Feel free to add your own examples to the list.
Simple
- allow subscriptions
- paginated: 10 comments per page
[[Jot? &subscribe=`1` &pagination=`10`]]
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`]]
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.
- but a manager will receive notifications if
- you use Jot 1.1.3+
- the manager is the document's author and
- you provide
¬ifyAuthor=`1`
[[Jot? &subscribe=`1` &pagination=`10` &moderated=`1`]]
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`]]
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 separated by a comma
[[Jot? &pagination=`10` &captcha=`1` &badwords=`{{myBadwordList}}` &bw=`2`]]
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 separated by a comma
[[Jot? &pagination=`10` &captcha=`1` &canmoderate=`Jot Moderators` &badwords=`{{myBadwordList}}` &bw=`1`]]
Tips & Tricks
Best practice for including comments
The best practice 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).
Extended 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.
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.
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+]
Bad words
Bad words are checked on all input, including custom fields.
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.
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
Suggest an edit to this page.