[pelican_comment_system] Adds Quickstart guide + default theme

pelican_comment_system/Readme.md

@@ -21,10 +21,10 @@ Bernhard Scheirle  | <http://bernhard.scheirle.de> | <https://github.com/Scheirl
 
 ## Instructions
 
+ - [Quickstart Guide](doc/quickstart.md)
  - [Installation and basic usage](doc/installation.md)
  - [Avatars and identicons](doc/avatars.md)
  - [Comment Atom feed](doc/feed.md)
- - [Comment form (AKA, never gather metadata)](doc/form.md)
  
 ## Requirements
 
@@ -32,9 +32,7 @@ Pelican 3.4 or newer is required.
 
 To create identicons, the Python Image Library is needed. Therefore you either need PIL **or** Pillow (recommended).
 
-#### Install Pillow
-
-Install Pillow via:
+**Install Pillow via:**
 
     pip install Pillow
 

pelican_comment_system/doc/avatars.md

@@ -3,7 +3,7 @@ To activate the avatars and [identicons](https://en.wikipedia.org/wiki/Identicon
 
 ##### Example
 ```python
-PELICAN_COMMENT_SYSTEM_IDENTICON_DATA = ('author')
+PELICAN_COMMENT_SYSTEM_IDENTICON_DATA = ('author',)
 ```
 Now every comment with the same author tag will be treated as if written from the same person. And therefore have the same avatar/identicon. Of cause you can modify this tuple so other metadata are checked.
 

pelican_comment_system/doc/form.md

@@ -1,89 +0,0 @@
-# Comment Form (AKA, never gather metadata)
-
-Add a form that allows your visitors to easily write comments.
-
-But more importantly, on submission the form generates a `mailto:` link.
-
-The resulting email contains a valid Markdown block. Now you only have to copy this block to a new file, obviating the need to gather the metadata (such as date, author, replyto) yourself.
-
-#### Reply button
-
-Add the following in the comment for-loop in your article.html template so your visitors can reply to a comment.
-
-```html
-<button onclick="reply('{{comment.slug | urlencode}}');">Reply</button>
-```
-
-#### Form
-
-A basic form so your visitors can write comments.
-
-```html
-<form role="form" id="commentForm" action="#">
-	<input name="Name" type="text" id="commentForm_inputName" placeholder="Enter your name or synonym">
-	<textarea name="Text" id="commentForm_inputText" rows="10" style="resize:vertical;" placeholder="Your comment"></textarea>
-	<button type="submit" id="commentForm_button">Post via email</button>
-	<input name="replyto" type="hidden" id="commentForm_replyto">
-</form>
-```
-
-You may want to add a button to reset the `replyto` field.
-
-#### Javascript
-
-To generate the `mailto:` link and set the `replyto` field, there is some Javascript required.
-
-```javascript
-<script type="text/javascript">
-	function reply(id)
-	{
-		id = decodeURIComponent(id);
-		$('#commentForm_replyto').val(id);
-	}
-
-	$(document).ready(function() {
-		function generateMailToLink()
-		{
-			var user = 'your_user_name'; //user@domain = your email address
-			var domain = 'your_email_provider';
-			var subject = 'Comment for \'{{ article.slug }}\'' ;
-
-			var d = new Date();
-			var body = ''
-				+ 'Hey,\nI posted a new comment on ' + document.URL + '\n\nGreetings ' + $("#commentForm_inputName").val() + '\n\n\n'
-				+ 'Raw comment data:\n'
-				+ '----------------------------------------\n'
-				+ 'date: ' + d.getFullYear() + '-' + (d.getMonth()+1) + '-' + d.getDate() + ' ' + d.getHours() + ':' + d.getMinutes() + '\n'
-				+ 'author: ' + $("#commentForm_inputName").val() + '\n';
-
-			var replyto = $('#commentForm_replyto').val();
-			if (replyto.length != 0)
-			{
-				body += 'replyto: ' + replyto + '\n'
-			}
-
-			body += '\n'
-				+ $("#commentForm_inputText").val() + '\n'
-				+ '----------------------------------------\n';
-
-			var link = 'mailto:' + user + '@' + domain + '?subject='
-				+ encodeURIComponent(subject)
-				+ "&body="
-				+ encodeURIComponent(body);
-			return link;
-		}
-
-
-		$('#commentForm').on("submit",
-			function( event )
-			{
-				event.preventDefault();
-				$(location).attr('href', generateMailToLink());
-			}
-		);
-	});
-</script>
-```
-(jQuery is required for this script.)
-
-Don't forget to set the variables `user` and `domain`.

pelican_comment_system/doc/installation.md

@@ -1,9 +1,7 @@
 # Installation
 
-Activate the plugin by adding it to your `pelicanconf.py`:
+Activate the plugin by adding it to your `pelicanconf.py`: (See also [How to use plugins](https://github.com/getpelican/pelican-plugins/tree/master/#how-to-use-plugins))
 
-	PLUGIN_PATH = ['/path/to/pelican-plugins']
-	PLUGINS = ['pelican_comment_system']
 	PELICAN_COMMENT_SYSTEM = True
 
 Then, modify your `article.html` theme as follows below.
@@ -115,3 +113,5 @@ Attribute  | Description
 	<p>There are no comments yet.<p>
 {% endif %}
 ```
+
+For a more complex / extensive example have a look at [theme/template/pcs/comments.html](../theme/template/pcs/comments.html)

pelican_comment_system/doc/quickstart.md

@@ -0,0 +1,32 @@
+# Quickstart Guide (with Comment form)
+
+This guide shows you how to setup the plugin for basic usage.
+The default theme has an comment form included.
+This form allows your visitors to easily write comments and send them to you via email [1].
+
+1. Merge the `./theme` folder with your own theme folder, or copy the files manually
+	```
+	mkdir -p [yourtheme]/template/pcs
+	mkdir -p [yourtheme]/static/js
+	cp ./theme/template/pcs/comments.html [yourtheme]/template/pcs/comments.html
+	cp ./theme/static/js/comments.js      [yourtheme]/static/js/comments.html
+	```
+
+2. Modify your `article.html` template:
+	1. Add `{% import 'pcs/comments.html' as pcs with context %}` to the top
+	2. Add `{{ pcs.comments_quickstart("emailuser", "example.com") }}` where you want your comments (e.g. below `{{ article.content }}`)  
+	"emailuser@example.com" will be the e-mail address used for the `mailto:` link [1]
+
+3. Enable the plugin: `pelicanconf.py` (See also [How to use plugins](https://github.com/getpelican/pelican-plugins/tree/master/#how-to-use-plugins))
+	```
+	PELICAN_COMMENT_SYSTEM = True
+	PELICAN_COMMENT_SYSTEM_IDENTICON_DATA = ('author',)
+	```
+
+## Notes
+ * Instead of using `pcs.comments_quickstart` you can also use the other macros available in `comments.html`.
+   They are a bit more flexible and may generate "better" html output e.g.:
+    * Don't force load jQuery
+    * No inline css
+
+[1] The comment form generates a `mailto:` link on submisson. The resulting email contains a valid Markdown block. Now you only have to copy this block to a new file, obviating the need to gather the metadata (such as date, author, replyto) yourself.

pelican_comment_system/theme/static/js/comments.js

@@ -0,0 +1,76 @@
+//requires jquery
+var CommentSystem = {
+	email_user:   "not set",
+	email_domain: "not set",
+	display_replyto_html: function(comment_content, article_slug, author) {return ''},
+
+	cancelReply: function() {
+		$('#commentForm_replyto').val("");
+		$('#pcs-comment-form-display-replyto').hide();
+	},
+
+	setReply: function(slug, author) {
+		slug   = decodeURIComponent(slug);
+		author = decodeURIComponent(author);
+
+		$('html, body').animate({ scrollTop: $("#pcs-comment-form").offset().top }, 1000);
+
+		$('#pcs-comment-form-input-replyto').val(slug);
+
+		var jquery_escaped_id = slug.replace('.', '\\.')
+		var commentContent = $('#comment-' + jquery_escaped_id + ' .pcs-comment-content:first').text().trim()
+
+		$('#pcs-comment-form-display-replyto').html(this.display_replyto_html(commentContent, slug, author));
+		$('#pcs-comment-form-display-replyto').show();
+	},
+
+	getMailtoLink: function(slug) {
+		var subject = 'Comment for \'' + slug + '\'' ;
+
+		var now = new Date();
+		tzo = -now.getTimezoneOffset(),
+		dif = tzo >= 0 ? '+' : '-',
+		pad = function(num) {
+			norm = Math.abs(Math.floor(num));
+			return (norm < 10 ? '0' : '') + norm;
+		};
+		var body = ''
+		+ 'Hey,\nI posted a new comment on ' + document.URL + '\n\nGreetings ' + $("#pcs-comment-form-input-name").val() + '\n\n\n'
+			+ 'Raw comment data:\n'
+			+ '----------------------------------------\n'
+			+ 'email: \n' // just that I don't forget to write it down
+			+ 'date: ' + now.getFullYear()
+					+ '-' + pad(now.getMonth()+1)
+					+ '-' + pad(now.getDate())
+					+ 'T' + pad(now.getHours())
+					+ ':' + pad(now.getMinutes())
+					+ dif + pad(tzo / 60)
+					+ ':' + pad(tzo % 60) +'\n'
+			+ 'author: ' + $("#pcs-comment-form-input-name").val() + '\n';
+
+		var replyto = $('#pcs-comment-form-input-replyto').val();
+		if (replyto.length != 0)
+		{
+			body += 'replyto: ' + replyto + '\n'
+		}
+
+		var url = $("#pcs-comment-form-input-website").val();
+		if (url.length != 0)
+		{
+			if(url.substr(0,7) != 'http://' && url.substr(0,8) != 'https://'){
+				url = 'http://' + url;
+			}
+			body += 'website: ' + url + '\n';
+		}
+		body += '\n'
+			+ $("#pcs-comment-form-input-textarea").val() + '\n'
+			+ '----------------------------------------\n';
+
+		var link = 'mailto:' + this.email_user + '@' + this.email_domain + '?subject='
+			+ encodeURIComponent(subject)
+			+ "&body="
+			+ encodeURIComponent(body);
+		console.log(link)
+		return link;
+	}
+}

pelican_comment_system/theme/template/pcs/comments.html

@@ -0,0 +1,162 @@
+{% macro comments_styles() %}
+{% if PELICAN_COMMENT_SYSTEM %}
+{# NOTE:
+ # Instead of using this macro copy these styles in your main css file
+ # This marco is only here to allow a quickstart with nice styles
+ #}
+<style>
+#pcs-comment-form input,
+#pcs-comment-form textarea {
+	width: 100%;
+}
+#pcs-comment-form-display-replyto {
+	border: solid 1px black;
+	padding: 2px;
+}
+#pcs-comment-form-display-replyto p {
+	margin-top: 0.5em;
+	margin-bottom: 0.5em;
+}
+#pcs-comments ul {
+	list-style: none;
+}
+#pcs-comments .comment-left {
+	display: table-cell;
+	padding-right: 10px;
+}
+#pcs-comments .comment-body {
+	display: table-cell;
+	vertical-align: top;
+	width: 100%;
+}
+</style>
+{% endif %}
+{% endmacro %}
+
+{% macro comments_form() %}
+{% if PELICAN_COMMENT_SYSTEM %}
+<section>
+	<form id="pcs-comment-form" action="#">
+		<legend>Add a Comment</legend>
+		<input type="hidden" id="pcs-comment-form-input-replyto">
+		<fieldset>
+			<label for="pcs-comment-form-input-name">Name</label>
+			<input  id="pcs-comment-form-input-name" type="text" placeholder="Enter your name or nickname" />
+		</fieldset>
+		<fieldset>
+			<label for="pcs-comment-form-input-website">Website</label>
+			<input  id="pcs-comment-form-input-website" type="text" placeholder="Enter your website (optional)" />
+		</fieldset>
+		<fieldset>
+			<label   for="pcs-comment-form-input-textarea">Your Comment</label>
+			<textarea id="pcs-comment-form-input-textarea" rows="5" style="resize:vertical;" placeholder="Your comment"></textarea>
+			<p>You can use the <a href="https://en.wikipedia.org/wiki/Markdown">Markdown</a> syntax to format your comment.</p>
+			<div style="display: none; " id="pcs-comment-form-display-replyto"></div>
+		</fieldset>
+
+		<button type="submit"
+				id="pcs-comment-form-button-submit"
+				{# Piwik Track click on comment button
+				onclick="javascript:_paq.push(['trackEvent', 'comment', '{{ article.title }}', document.getElementById('pcs-comment-form-input-textarea').value]);" #}
+				>Post via email</button>
+
+		{% if PELICAN_COMMENT_SYSTEM_FEED and article %}
+			<a href="{{ SITEURL }}/{{ PELICAN_COMMENT_SYSTEM_FEED|format(article.slug) }}">
+				Comment Atom Feed
+			</a>
+		{% endif %}
+	</form>
+</section>
+{% endif %}
+{% endmacro %}
+
+{% macro comments_with_form() %}
+{% if PELICAN_COMMENT_SYSTEM %}
+<section id="pcs-comments">
+	<header>
+		<h2>Comments</h2>
+		<hr/>
+	</header>
+	{% if article.comments %}
+		<ul>
+		{% for comment in article.comments recursive %}
+			<li id="comment-{{comment.slug}}">
+				<div class="comment-left">
+					<img    src="{{ SITEURL }}/{{ comment.avatar }}"
+							alt="Avatar"
+							height="{{ PELICAN_COMMENT_SYSTEM_IDENTICON_SIZE }}"
+							width="{{ PELICAN_COMMENT_SYSTEM_IDENTICON_SIZE }}">
+				</div>
+				<div class="comment-body">
+					<div style="float:right;">
+						<a role="button" href="{{ SITEURL }}/{{ article.url }}#comment-{{comment.slug}}" rel="bookmark" title="Permalink to this comment">Permalink</a>
+						<button onclick="CommentSystem.setReply('{{comment.slug | urlencode}}', '{{comment.author | urlencode}}');">Reply</button>
+					</div>
+					<h4>
+						{% if comment.metadata['website'] %}
+							<a href="{{comment.metadata['website']}}">{{ comment.author }}</a>
+						{% else %}
+							{{ comment.author }}
+						{% endif %}
+					</h4>
+					<p>
+						Posted on
+						<time datetime="{{ comment.date.isoformat() }}" title="{{ comment.date.isoformat() }}">{{ comment.locale_date }}</time>
+					</p>
+					<div class="pcs-comment-content" {# class used as id in comments.js#}>
+						{{ comment.content }}
+					</div>
+					{% if comment.replies %}
+						<hr>
+						<ul>
+							{{ loop(comment.replies) }}
+						</ul>
+					{% endif %}
+				</div>
+			</li>
+		{% endfor %}
+		</ul>
+	{% else %}
+		<p>There are no comments yet.</p>
+	{% endif %}
+	{{ comments_form() }}
+</section>
+{% endif %}
+{% endmacro %}
+
+
+{% macro comments_js(user, domain, includeJquery=True) %}
+{% if PELICAN_COMMENT_SYSTEM %}
+	{% if includeJquery %}
+		<script type="text/javascript" src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
+	{% endif %}
+	<script type="text/javascript" src="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/js/comments.js"></script>
+	<script type="text/javascript">
+		$(document).ready(function() {
+			CommentSystem.email_user   = "{{ user }}";
+			CommentSystem.email_domain = "{{ domain }}";
+			CommentSystem.display_replyto_html = function(comment_content, article_slug, author) { 
+				return ''
+					+ '<button style="float:right;" onclick="CommentSystem.cancelReply(); return false;" title="Cancel the reply">'
+					+ 	'×'
+					+ '</button>'
+					+ '<p>This comment will be posted as a reply to \'<a title="'+comment_content+'" href="#comment-'+article_slug+'">'+author+'</a>\'</p>';
+			};
+
+			$('#pcs-comment-form').on("submit",
+				function( event )
+				{
+					event.preventDefault();
+					$(location).attr('href', CommentSystem.getMailtoLink("{{ article.slug }}"));
+				}
+			);
+		});
+	</script>
+{% endif %}
+{% endmacro %}
+
+{% macro comments_quickstart(user, domain) %}
+	{{ comments_styles() }}
+	{{ comments_with_form() }}
+	{{ comments_js(user, domain) }}
+{% endmacro %}