Export Patterns

This is a guide to create your own Export Patterns.  If you’re looking for a list of premade patterns, go to the Export Patterns Category.

Export Patterns allow DaleyKlippings to output data in custom formats which means that you can export your clippings to a wide variety of programs.  We will package many common Export Patterns with our installers.  Unlike import patterns, however, there will always be a new user with a new piece of software and the need for a new export pattern.

The Export Pattern logic was a major focus of the original DaleyKlippings design.  This section will explain how Export Patterns work and the various features available to a designer.

Basics

Export patterns are composed of three basic sections:

  • Header – This section is placed (once) at the top of the file
  • Body – This sections is repeated for each row in the user interface (generally speaking for each Highlight or Note)
  • Bottom – This section is placed (once) at the bottom of the file

There is also one special section that may not always be used:

  • Attached Notes – Because DaleyKlippings is capable of linking Notes and their associated Highlights, this field lets you customize the “Text” that is generated for combined (or “attached”) lines.

We will explain this section in more detail when we discuss the “Text” field below.

Inserting Fields

DaleyKlippings is built in Python and uses a lot of conventions from that world.  The first major convention is the way fields are inserted into Export Patterns.  Specificaly, if you want DaleyKlippings to insert data from the table, you format the field as:

?P<FiledName>

Where “FieldName” is replaced by the name of the field you want to use (e.g. “Author”).  Everything else in an Export Pattern is duplicated without modification in the export file.  There are eight fields available in DaleyKlipppings:

  • Book
  • Author
  • Page
  • Location
  • Date
  • Highlight
  • Note
  • Text

The first seven fields are found in the user interface and should need no further explanation.  However, the Highlight and Note fields are often empty so the Text field is the preferred strategy when designing Export Patterns.  Specifically, the Text field will automatically select among four possible values:

  • <Blank> – in the case of a bookmark
  • Highlight – for any line with a highlight that is not attached to a note
  • Note – for any line with a note that is not attached to a highlight
  • Attached Note Pattern – for any line that has a note attached to a highlight, we will substitute this entire pattern for the Text tag.  Normally, this pattern will include additional tags (specifically, Note and Highlight) with some extra text or formatting.

As we mentioned above, the Export Pattern window has a special “Attached Notes” box.  When a Note and Highlight are present on the same line, this box determines the format used in the Export.  This box is configured exactly the same as the Header, Body, and Bottom boxes, except that this field will not accept the “Text” field (it would loop forever if we let you do this).

Prefixes

In many cases, Export Pattern designers need to ensure that data in the fields do not violate certain conventions.  For example, if you are trying to export data into an XML file, you don’t want characters like <, >, and & in the text of the output since these characters could mess up your carefully designed XML structure.

Prefixes are our solution to that problem.  If you add a prefix to any field, it will apply a set of formatting restrictions to that field.  Prefixes can be combined to get a variety of interesting behaviors.  We currently offer several formatting prefixes:

  • XmlSafe – Replaces <, >, and & with their HTML (e.g. “&lt;”) equivalents.
  • CommaSafe – Replaces , with _
  • QuoteSafe – Replaces ” with ‘
  • TabSafe – Replaces <tab> characters with 5 <spaces>
  • CommaEscape (v0.5+) – Replaces , with \,
  • QuoteEscape (v0.5+) – Replaces ” with “”
  • Ellipsis### and Truncate###
    • These prefixes ensure that an output does not exceed a particular length.  They take any value from 0 to 999, but must be zero padded (e.g. truncating at 10 length would be Truncate010).
    • The only difference is that Ellipsis will replace the last three characters with “…” if it is forced to truncate a field.
    • If Ellipsis is called with a length of 3 or lower, it will behave like a Truncate.
  • EvernoteTag is a special prefix that enforces Evernote’s restriction on tags.  Specifically, it applies CommaSafe, then applies Ellipsis100, then (if the result is not empty) wraps the result in <tag> and </tag>.

You will see one other prefix in the built-in Evernote Pattern.  However, it is not fully support so it’s use is strongly discouraged.

  • (LIMITED PREFIX) The Span prefix was added so that all the data objects could be wrapped in HTML tags that would (in theory at least) help distinguish data from labels if (in the future) we ever were motivated to do so.
    • This prefix should be applied to a single field (e.g. SpanAuthor) and wraps the result in <span> HTML tags with a special title property,  title=”value_<field>” (e.g. title=”value_author”).
    • Because Span is corrupted by several other prefixes (QuoteSafe, Truncate, Ellipsis, etc.), we discourage the combination of Span with other prefixes.  To avoid corruption, however, we have coded a special exception for XmlSafeSpan (SpanXmlSafe before v0.4).
    • The combination of Span with any other prefix is UNSUPPORTED.  If you still choose to combine prefixes, Span must be the last prefix before the field value.  If you try to wrap prefixes inside of Span (e.g. SpanCommaSafeAuthor), the span will include the other prefixes in the title property, (e.g. title=”value_commasafeauthor”).

Prefixes are combined with the 7 standard fields (Book, Author, Page, Location, Date, Highlight, and Note) by including them as part of the field name.  For example:

  • ?P<CommaSafeAuthor>
  • ?P<Ellipsis100Book>
  • ?P<XmlSafeNote>

Text is a special case when it comes to prefixes.  Recall that Text outputs one of four values, <blank> (bookmark), Highlight, Note, or the Attached Notes pattern.  How does a prefix affect each of these fields:

  • Bookmarks always return <blank> so prefixes are not applied
  • A Highlight without a Note returns “PrefixesHighlight”
  • A Note without a Highlight returns “PrefixesNotes”
  • The Attached Notes Pattern is fully customizable by the designer so prefixes are not applied.

If a designer wants to apply Prefixes to Attached Notes, these prefixes should be included in the Attached Notes box.  For example:

# This is the body box
# 
# In our body, we include the XmlSafe prefix so the content 
# of Notes and Highlights don't mess up our HTML structure
# 
<div>?P<XmlSafeNote></div>
<div>?P<XmlSafeText></div>
# This is the attached notes box
# 
# If XmlSafe was applied to the content of this box, 
# it would have killed our <br/> tags.
# 
# If we wanted Attached Notes to be completely XmlSafe, we 
# would exclude the HTML tags from the Attached Notes box
# 
# However, we do want the fields to be XmlSafe so we wrap 
# Note and Highlight in that prefix
# 
?P<XmlSafeNote>
<br/><br/>
?P<XmlSafeHighlight>

or, for a CSV file,

# In our body, we include CommaSafeText to ensure Commas 
# don't break the CSV file
# 
... ,?P<CommaSafeNote>,?P<CommaSafeText>
# In this case, we want a completely CommaSafe Attached Notes field.
# 
# Note that no commas are included outside the CommaSafe calls 
# and we apply CommaSafe to the Highlight and Note fields
# 
My Note
?P<CommaSafeNote>
My Highlight
?P<CommaSafeHighlight>

Getting Started

The best way to get started is to check out the examples in our Export Patterns Category and the Export Patterns already included in DaleyKlippings.  If you continue to have trouble getting the output you want, we hope to have a forum up soon so that you can ask the community.

Your last option is to Contact Us and ask us to make the pattern you need.  In most cases, we will ask you to pay for this service (keep in mind that we do not charge for the software or for new Import Patterns).