Extended Comments

To complete the trio of our extended-entities, we tackle extended-comments in this section.

Since we have already been through extended-folders, this part should seem familiar.
It extends the existing commenting functionality in Couch (as documentated at http://www.couchcms.com/docs/concepts/u ... ments.html) so I assume we have a registered template (blog.php) that is already configured to
a. accept submitted comments (via cms:process_comment used within a Couch form's success condition) and
b. list submitted comments using cms:comments tag

We'll call this template the 'target' template (as we'll be extending its comments).

Next we'll use another clonable template (lets name it blog-comments.php), define editable regions in it and register it the usual way and make sure it is available in the admin-panel. We'll call it the 'source' template (as it provides the editable regions that'll extend the target template).

Following is our sample source template (for our demo we are defining two editable regions in it, a 'checkbox' and a 'text'. These regions will eventually be borrowed by the comments in the target template i.e. blog.php)

With the two templates registered and ready, we can begin the process of extending the comments in the target template.
It is, just like with extended-folders, a two step process -
1. Enable the 'extended-comments' addon by uncommenting (i.e. removing the '//') from the following line in 'couch/addons/kfunctions.php' -

(we are assuming that you have already extracted and placed the 'extended' folder from the attached zip into 'couch/addons')

2. Make the following change to the target template (i.e. blog.php in our example). Assuming this was the template's original definition -
Before:

After:

As you can see, we have used the 'comment_masterpage' parameter to specify our source template's name.
IMP: make sure to visit the modified target template at this point as super-admin for the changes to picked up by Couch.

With the two above-mentioned changes, our target template is now ready to accept the additional fields.
Let us see now.

Unlike folders that we extended before, comments cannot be created from the admin-panel. They get created from the front-end through comment submission form placed in the target template.

As you'd know from the docs (http://www.couchcms.com/docs/concepts/u ... ments.html), the comment form expects inputs named k_author, k_email, k_link and k_comment. With the extended-comments addon activated, we can now add to this form the editable regions we defined in the source template as well.

Assuming our comment form is using the sample code given in the docs, folowing is an excerpt from the form body showing some regular inputs

We can add our 'extended' fields to the form as follows -

As you can see, the cms:input match their corresponding cms:editable regions we defined in the source template.
And that is the key - any cms:inputs with names matching the editable regions in source template will be persisted as part of the comment upon successful form submission.

The tag that does all the heavy-lifting while saving a comment, as you'd know, is
With extended-comments addon active, the cms:process_comment tag gets 'smarter' and recognizes the extending fields also.

Try submitting some comments and verify this.

One little problem you might face while adding cms:input fields manually, as we did above, is when there is no matching input type for an extending editable region e.g. 'relation' etc. (or even when it is too much hassle to craft an input that matches the editable region exactly)

To get around this we can piggy-back on DataBound Form. As you know, we can use a generic input of type 'bound' with DataBound Forms and that input automatically gets resolved to whatever editable region is defined with its name.

Let us make a little change to our comment submission form to turn it into a DataBound form
Before:

After:

As we know, it is the 'masterpage' parameter that transforms a form into a DBF. The 'k_template_comment_masterpage' variable we are using as its value is made available to us by Couch and always contains the value set as the 'comment_masterpage' parameter of the target template (i.e. this variable will resolve to 'blog-comments.php' in our example).
The 'mode' parameter needs always be set to 'create'.

And that is it. We can now use cms:input of type 'bound'. As a test, let us convert the 'checkbox' type named 'my_categories' into bound.
Before:

After:

The resulting form will look and work just the same as before.

If you are conversant with DataBound Forms, you might be wondering why we have not used the 'cms:db_persist_form' tag that conventionally accompanies all DBFs?

The answer is that the 'cms:process_comment' already present in the comment form now works exactly as 'cms:db_persist_form' (as mentioned, it has grown 'smarter' ).
So much so that it now also supports passing values directly into it as parameters, exactly how we can do with 'cms:db_persist_form' e.g. the following would always submit 'Penguin!' as the club field's value

Okay, so now we can get the values into our custom fields. How do we get them out?

Listing Extended Comments:
Displaying the values submitted through the extended fields requires no additional effort.
The cms:comments tag used to list submitted comments will make available the extended fields too.
For example, the following placed within the cms:comments loop will show the club and categories of the comments been shown -

In closing, as already mentioned, the extended_folders and extended_comments addons are not as sophisticated as extended_users. They serve only to add custom fields to folders/comments and to retrieve the values submitted using the extended fields. We cannot, for example, filter the folder/comments listings based on the extended fields (e.g. show only comments that have 'penguin' as the club). If your use-case demands such functionality, a normal clonable template coupled with DataBound Forms and Relations can be used to implement it.

With extended-entities covered, we can now see the other new features in this release.