Template library
Troubleshooting templates
Newscoop's administration interface has a built-in Preview option on the article edit page which also shows template parsing errors, if there are any. When you browse your publication in the preview window, you can see error messages for all parts of your publication.
At the bottom of the preview window you can see error messages from the template parser.
The lower frame on this page displays any parsing errors, which can be very useful for debugging templates. It immediately narrows down possible errors to the specific main or included template. It also displays the line and type of error.
The error messages are not always precise. The point where the parser encounters an error may only be a reflection of a problem coming from further up in the template. If the message shown by the parse error frame is not useful to find the problem, you'll have to find an alternate way to locate it.
For example, in some situations, checking the source of the generated HTML page helps. It may be that the content you expect to be shown somewhere doesn't appear on the page, but it's in the HTML source. This obviously shows that the problem is not in Newscoop but somewhere in HTML or CSS. The opposite is also true; if the source contains all the <div> and <li> tags that it should but their content is empty, you can be sure that Newscoop isn't working like it should.
There are lots of very handy tools out there in browsers nowadays. You can use them to easily parse your HTML code and find an error. For example, Firebug (from http://getfirebug.com) is an extension to Firefox. All you need to do is search for it in the Firefox Add-ons Manager and click to install it. Chrome, Safari, Firefox, Opera, and even Internet Explorer all come with their own individual suites of powerful developer tools built in now.
The usage is pretty easy - open, inspect element, find error:
But what is really good is that you can debug your jQuery templates with it. Just adding a few lines of code to your JavaScript will provide Console feedback:
console.log ("Here are the date links:\r\n");
...
console.log (link + "\r\n");
There's almost the same tool in Chrome, which can be found in the menu under Tools -> Developer tools, or simply right-click on the selection and choose 'Inspect Element':
Another debugging strategy may be inserting temporary tags for printing the values of Newscoop variables.
The following code checks the values of variables in the registration process. It doesn't make any sense to use on a live site, but it may be useful for debugging purposes:
<h2>Add new subscription</h2>
{{* debug user add/edit/subscribe *}}
<h5>Edit_user_action:</h5>
<p>Edit user action defined: {{ if $gimme->edit_user_action->defined }}defined{{ else }}not defined{{/if}}</p>
<p>Edit user action error: {{ if $gimme->edit_user_action->is_error }}is_error, code: {{ $gimme->edit_user_action->error_code }}, message: {{ $gimme->edit_user_action->error_message }}{{ else }}not error{{/if}}</p>
<p>Edit user action ok: {{ if $gimme->edit_user_action->ok }}ok{{ else }}not ok{{/if}}</p>
<p>edit user action type: {{ $gimme->edit_user_action->type }}</p>
<h5>Edit_subscription_action:</h5>
<p>Subs action defined: {{ if $gimme->edit_subscription_action->defined }}defined{{ else }}not defined{{/if}}</p>
<p>Subs action error: {{ if $gimme->edit_subscription_action->is_error }}is_error, code: {{ $gimme->edit_subscription_action->error_code }}, message: {{ $gimme->edit_subscription_action->error_message }}{{ else }}not error{{/if}}</p>
<p>Subs action ok: {{ if $gimme->edit_subscription_action->ok }}ok{{ else }}not ok{{/if}}</p>
<p>Subs action {{ if $gimme->edit_subscription_action->is_trial }}is_trial{{ else }}not trial{{/if}}</p>
<p>subs action {{ if $gimme->edit_subscription_action->is_paid }}is_paid{{ else }}not paid{{/if}}</p>
{{* end debugging *}}
This would output:
Similarly, you can use this temporary outputs wherever you feel you need to check what's really happening. For example, inside a list to check how values of list index and list count change with every new iteration:-
{{ list_articles }}
<div class="post wrap">
<p>Current list index: {{ $gimme->current_list->index }}, list count: {{ $gimme->current_list->count }}</p>
<h2 class="post-title"><a href="{{ uri options="article" }}" rel="bookmark" title="{{ $gimme->article->name }}">{{ if ! $gimme->article->content_accessible }}* {{ /if }}{{ $gimme->article->name }}</a></h2>
</div>
{{ /list_articles }}
Here we put a temporary <p> tag with values of index and count above every title, and the result would be like this screenshot:
Or, you may want to check the values of parameters forwarded to a page. You can do this at the template's very beginning:
<p>Language: {{ $gimme->language->name }}<br />
Issue: {{ $gimme->issue->name }} <br />
Section: {{ $gimme->section->name }}<br />
Article no: {{ $gimme->article->number }}<br />
Topic active? {{ if $gimme->topic->defined }}yes{{ else }}no{{ /if }}
</p>
{{ include file="set_thejournal/_tpl/top.tpl" }}
The output displays the values of the parameters, so you can check if everything is OK:
Most common errors / problems
- Missing a closing element for {{ if }} statements - this especially happens when several 'if' clauses are nested. You can simplify your expression by using {{ elseif }}; that will reduce the need for nesting 'if's
- Missing list closing element - this also happens more often when using lists inside lists
- Wrong syntax inside an 'article list' constraints option. Because there are a lot of possible options, always consult the template reference at the end of this book for options and their correct formatting
- Syntax errors in general - again, the safest way to avoid errors is to always consult the template reference
- Context problems - these are harder to discover because they don't produce parse errors in the preview window. To discover context-related value problems, try inserting temporary tags to output the values of variables. Do it at the beginning of the template, then do it again after an action was performed. This way, you can see what really happens with those variables.
Where to go for more help
There are a few places you can turn for troubleshooting assistance on your templates. The first place to look is the Newscoop support forum, which you can find at http://forum.sourcefabric.org
Sourcefabric also offers paid support. As the maintainer of Newscoop (and its largest code contributor), Sourcefabric can provide a broad and deep body of knowledge to our clients. For example, we can help troubleshoot your templates or installation, or we can create custom templates for you. You can find more details about Sourcefabric's services on the website: http://www.sourcefabric.org/en/newscoop/newscooppro/