Intro to Merge Templates

Status: 4 - In Work

Seq: 47

Author: Herb Bowie

Body:

In this adventure, I will offer a brief introduction to the use of Notenik merge templates.

Of course, Notenik can be used for a lot of different purposes, and you can do many of them without ever needing to learn the first thing about merge templates.

In general, though, whenever you would like to reformat some of the info you have in Notenik into some other layout, then you can use a merge template to get the job done.

Let me break this down into steps (many of which will be performed using your favorite text editor).

Step 1. Identify Where The Output Will Be Used

It can be used inside of Notenik (to reformat the Display tab), or somewhere outside of Notenik.

Step 2. Identify the Target Format

This could be HTML (for a web page, or for internal use within Notenik), or XML, or JSON, or CSV, or Markdown, or plain text, or any other format that can be expressed in a text file.

Step 3. Identify the Intended Scope

By which I mean, your merge template could be intended to:

If either of the latter two cases, you may wish to see your output in the form of a list of some sort.

Step 4. Apply the Target Format

Create a text file, using your favorite text editor, and load it with all the boilerplate you need for your target format.

For example, here’s a very simple sample web page written using HTML.

<!doctype html>
<html>
<head>
	<title>Our Simple HTML Page</title>
</head>

<body>
	Content goes here.
</body>
</html>

Save this in a text file, being sure to give the template file an extension appropriate for your intended output format — .html for HTML, and so forth.

Where you save this text file will depend on how you plan to use it. For example, if you’d like to reformat your Display tab, store it with the name display.html and save it inside of your collection folder. For other uses, it’s often best to store it in a templates folder inside of a factory folder.

Step 5. Fill in Your Notenik Fields

Figure out what fields should go where, and insert these using special delimiters.

For example, here’s our simple web page, now with a couple of Notenik fields filled in.

<!doctype html>
<html>
<head>
	<title>=$title$=</title>
</head>

<h1>=$title$=</h1>

<body>
	=$body$=
</body>
</html>

Note the following:

Step 6. Add Additional Formatting as Needed

This step can really be done in parallel with the prior step, as you insert each field.

For example, note that in the prior code example, I’ve placed the second occurrence of =$title$= between starting and ending h1 tags, so that it will be formatted as a level 1 heading.

Again, what sort of formatting code you use will depend on your desired output format, and on your own desires in terms of formatting.

Step 7. Add Variable Modifiers

Variable modifiers can be used to apply special formatting of one sort or another to the fields that you are inserting into your template.

Here’s an example of what I mean. I won’t repeat the entire code sample, just the fragment containing the Body field.

<body>
	=$body&w1o$=
</body>

Note the following:

These conversions will be performed by Notenik before inserting the field value into the output.

Which variable modifiers you need or want will depend on the types of fields you are using, the desired output format, and/or on your appearance preferences.

Step 8. Add Notenik Merge Commands

Merge Commands provide additional processing instructions for Notenik.

Here’s our example with a couple of the most basic and essential merge commands added.

<?nextrec?>
<!doctype html>
<html>
<head>
	<title>=$title$=</title>
</head>

<h1>=$title$=</h1>

<body>
	=$body&w1o$=
</body>
</html>
<?loop?>

Note the following:

Step 9. Consider Placement of the Output Command

The output command names an output file that will be the recipient of the code being generated by the template.

There are three possibilities here.

a. No Output Command

Your template will be used in a context (such as Notenik display, or Notenik sharing) for which the output is predetermined, or determined by user input outside of the merge template. In this case, no output command should be inserted into your template.

b. Output One File per Note

In this case the output command should follow the nextrec command, and should probably include one or more field’s values to form the name of the output file.

Here’s an example of what I mean (showing only a code fragment).

<?nextrec?>
<?output "=$title&f$=.html" ?>
<!doctype html>

Note the following:

c. Output a List

The scope of your template is intended to be a list of notes — not just a single note. In this case, the output command will be placed before the nextrec command, and the name and location of the intended output file will be coded as a constant within the output command, as in the following example.

<?output "list.html" ?>
<!doctype html>
<html>
<head>
	<title>My list of Notes</title>
</head>

<h1>My List of Notes</h1>

<body>
<?nextrec?>
	<h2>=$title$=</h2>

	=$body&w1o$=
<?loop?>
</body>
</html>

Step 10. Test and Tweak

At this point, it’s time to take your new merge template for a test drive, inspect its output, and then consider how you might fix/enhance the template to improve the output. This can be a one-and-done, or a series of small changes and tests until you are happy with the results.

And that’s about it! If you’ve been avoiding use of merge templates in Notenik for lack of knowledge, then hopefully this brief tutorial has been enough to get you started! As usual, refer to the Knowledge Base for more complete information.


Timestamp: 20250404200509

Date Added: 2025-04-04 13:05:09 -0700

Date Modified: 2025-04-15 15:43:41 -0700