Support Produced by OmniGraffle 7.5 test 2017-09-15 03:22:04 +0000 phone/email/twitter +1 206-523-4152 or 800-315-OMNI

OmniOutliner export plug-in development

Introduction

OmniOutliner 4 comes with the built-in ability to export to a few fine file formats. But thanks to the magic of XML and XSLT, you can create your own export plug-ins and export your outlines to any kind of text- or XML-based format. If you enable OmniOutliner’s Pro feature set, you’ll have access to using external export plugins. This guide should get you on your way.

XSLT is a language that turns one XML document (such as an OmniOutliner outline) into another document, in some other kind of XML or text format (such as XHTML, SVG, TEX, or even, say, BulletML). If you understand the XML structure of an OmniOutliner document and you know some XSLT, you can use Apple Xcode to build an export option that will appear in OmniOutliner’s Export dialog.

Instructions (Xcode 6.3)

Create a new Project

  1. Start Xcode.
  2. Select File ‣ New Project….
  3. Select OS X ‣ Framework & Library ‣ Bundle.
  4. Enter a name for your plugin and change the Bundle Extension to ooxsl.
  5. Click Next and pick a directory in which to put the project.

Configure the Target for your plug-in

  1. With the project selected, select the Build Phases tab.
  2. Delete the Compile Sources and Link Binary With Libraries build phases.

Add your stylesheet

  1. If you have a pre-existing stylesheet then you can use Files ‣ Add Files to “Project”….
  2. If you’re starting from scratch select File ‣ New ‣ File.
    • Select OS X ‣ Other ‣ Empty.
    • Pick a file name for your stylesheet and give it a .xsl file extension.
  3. In both cases, make sure that the file gets added to the Target as well as the project. Select the XSL file entry in the sidebar and the Target Membership in the right pane should show a check mark. Additionally, selecting the Copy Bundle Resources build phase in your target should list the XSL file.

Configure the plug-in settings

  1. Expand the Supporting Files folder in the sidebar and select the Project-Info.plist file.
  2. The value for ‘Executable file’ must remain empty, or OmniOutliner will not load the plug-in. Alternatively, you can delete that key/value pair entirely.
  3. At the top level of the Info.plist, create an ‘OFRegistrations’ dictionary and an ‘OFRequiredSoftwareVersions’ dictionary.
  4. Under ‘OFRegistrations’, create an ‘OOXSLPlugin’ dictionary.
  5. Inside the ‘OOXSLPlugin’ dictionary can be any number of XSL transformation specification dictionaries. That is, one .ooxsl plug-in can provide multiple transformations. The names of these dictionaries are what appears in the Export dialog, so name them accordingly. If you’re creating a plug-in that creates a common format (like HTML), then specify the format name first followed by some description of your version, like so:

    A common case would be to provide both an import and export transform. Note that there are currently limitations on making import transforms that make it harder to add them, but the key point here is that the plug-in–to–transform mapping is one-to-many. - HTML (No Styles) - XML (Docbook)

Each of the XSL transformation dictionaries can contain the following keys. Unless otherwise specified, the value of each key is a string. Keys indicated with the warning sign ⚠️ are required; see the note on each item for more information.

  • source ⚠️

    • The input format for the transformation. For export transformations, the starting format is the OmniOutliner 3 XML format. Thus, this is typically com.omnigroup.omnioutliner.oo3.
  • result ⚠️

    • The output format for the transformation. For example, if you are producing HTML, it might be -//W3C//DTD XHTML 1.0 Transitional//EN
  • fileExtension ⚠️

    • The file extension to use when producing a plain file output. This is used when the source document has no attachments. This currently has no meaning for import transforms. For HTML export, this would probably be ‘html’ or ‘htm’.
  • index

    • The interior file name used when producing a directory output. This is used when the source document has file attachments. This currently has no meaning for import transforms. For HTML export, this would probably be index.html.
  • directoryExtension

    • The file extension to use when producing a directory output. This is used when the source document has file attachments. This currently has no meaning for import transforms. For HTML export, this would probably be htmld.
  • subDirectoryPath

    • A path to where the file should be written out to. Multi paths like test/test/foo are supported.
  • zipExportedFile

    • Defaults to false. Setting this to true will zip up the exported files.
  • stylesheet ⚠️

    • The name of the main XSL stylesheet to use when performing this transformation. Note that the bundle can contain other helper XSL files that the main stylesheet includes to provide utilities. The actual style sheet is expected to reside in the Resources directory of the plug-in.

    • The value for this key is given a .xsl extension, so if the value is ‘main’, then your bundle must have a ‘main.xsl’ file.

    • Also, advanced users can localize the XSL file itself (so you could provide a different main XSL file for each language). The one that is used depends on the user’s current language setting. If you do this, be aware that any utility XSL files need to be duplicated in each language directory or the language variants need to include them with relative paths (../en.lproj/utility.xsl)

  • templateFile

    • Name of a file to use as a template. The template will be loaded and attachments and other generated files will be added to the template. Existing files of the same name will be deleted before adding the newly generated ones.
  • OOXSLStylesheets (dictionary)

    • This is optional and is only really needed when you want to export to multiple files. Create an entry for each file to output. Below are the supported dictionary keys for each entry.
  • parameters (dictionary)

    • The parameters dictionary can be used to set up default XSL parameter values that can be used in your stylesheet to implement configurable behavior.

    • Be aware that the parameter values are XPath expressions, not simple strings. Thus if you say something like my_parameter = my_value you are really saying that ‘my_parameter’ is to be set to an element named ‘my_value’. Thus, you very often need to quote your values: my_parameter = "my_value"

  • attachmentFileNames (array)

    • This lists additional files that should be extracted from the ooxsl plug-in’s Resources directory and copied into the output when the transformation is performed. Note that this promotes regular source files to directory output files (the ‘directoryExtension’ and ‘index’ keys are used).

    • It is important to note that this key is required to copy the files across; we don’t simply copy all the resources across since you might have included utility XSL files, Localizable.strings files or NIB files (in the future).

  • helpLocation (array of strings)

    • An optional array of strings that specify the location of the help for this plug-in. All but the last entry are treated as menu item names. The last entry is treated as a URL. At launch time, OmniOutliner collects all the help locations for all installed plug-ins and dynamically generates entries under the Help menu.

    • For example, if you write a set of exporter plug-ins for your special format, you might set ‘thelp helpLocation’ key for each of them to (Export, MyFormat, Help.html). This builds a menu tree Export ‣ MyFormat ‣ PluginName for each plug-in with the leaf menu item opening the URL indicated by the last item in the ‘helpLocation’ array.

    • Each of the menu entries (except the last item) is localized first by looking in your plug-in’s Localizable.strings file. If that doesn’t contain a localized version, the main application’s PluginHelpItems.strings is consulted. This allows the application to vend localizations for common cases like ‘Import’ and ‘Export’.

    • The final entry in the ‘helpLocation’ may be a fully specified URL or it may be a file name (like Help.html). If the URL is fully specified (in this case, meaning it has a scheme of any type), it is used unaltered. But, if it is a plain file name, the localized variant of that file name in your plug-in bundle is used.

  • dateFormat

    • This defaults to using the string date format %Y-%m-%d %H:%M:%S %z, but some formats prefer other date representations.

    • This key can be set to unix to emit date elements that contain the number of sections since the Unix epoch (Jan 1 1970). It can also be set to ‘palm’ to use the Palm epoch (Jan 1 1904).

    • Finally, it can be set to formatted to apply the date format in the column itself. Since this option is lossy, OmniOutliner refuses to load documents that have a oo-date-format processing instruction (see below) with this value.

    • When this is set to palm or unix, a processing instruction is written into the resulting XML stream that records this fact so that further processors of the file can adjust their behavior: <?oo-date-format (palm|unix|formatted)?>

  • debugTransformationInput

    • This is intended as a temporary debugging feature for use while developing stylesheets for importing into OmniOutliner. This is a path to which OmniOutliner writes out the XML that is given as input to your XSL transform. You can use this to verify that you are getting exactly what you expect (which might be slightly different from the on-disk representation of the OmniOutliner file).
  • debugTransformationResults

    • This is intended as a temporary debugging feature for use while developing stylesheets for importing into OmniOutliner. The value of the key is a file path to write the output of the XSL transform to.
  • writeAttachments (bool)

    • This defaults to true. If set to false, no attachments will be copied to the output.
  • attachmentDirectoryPath

    • The sub directory in which to write any attachments.
  • filterAttachmentsUsingTypes (array)

    • Only output attachments of given types, for example, “image” or “com.adobe.pdf”.
  • writeAllAttachmentInfo (boolean)

    • If set, this causes the element to write information that could normally be obtained by examining the contents of the attachment (but which may be difficult for the exporter to do itself).

    • All attachment types have a ‘type’ attribute written that provides a hint about how OmniOutliner renders the cell contents. The current legal values are ‘link’ (a URL to an external resource), ‘image’ (a inline image whose data is contained in a file in the OO3 file wrapper) or ‘movie (a movie, or sound, whose data is contained in a file in the OO3 file wrapper).

    • More values for the ‘type’ attribute may be added in the future, so the best behavior is to fall back to the ‘link’ behavior if you don’t understand the given type.

    • Additionally, image and movie attachment types have ‘height’ and ‘width’ parameters written.

    • Movie attachments have a ‘controller’ value written (set to “yes” or “no”) that specifies whether the QuickTime movie controls are visible on the movie. For now, this is always “yes”, but in the future it might not be. Also note that the reported size for the movie contains the size needed for the controls.

  • writeFormattedNumbers (boolean)

    • If set, this causes OmniOutliner to write number values according to the format specified in their column. This is intended to ease to burden of exporting via XSL. Setting this key causes the <?oo-formatted-numbers?> processing instruction to be written. OmniOutliner refuses to load files with this processing instruction since this formatting is lossy in general.

    • Note that ‘number’ values include both plain number columns and duration columns.

  • additionalColorSpaceName

    • Cocoa supports many color spaces, and OmniOutliner tries to preserve this colorspace information accurately. Of particular interest to XSL export are the ‘catalog’ colorspaces. These are named colors that are hard (or impossible) to interpret in XSL. This key may be set to another Cocoa colorspace name to request that OmniOutliner write attributes for another colorspace by converting each color to this colorspace.

    • The available colorspace names are as follows:

      • NSCalibratedWhiteColorSpace
      • NSCalibratedBlackColorSpace
      • NSCalibratedRGBColorSpace
      • NSDeviceWhiteColorSpace
      • NSDeviceBlackColorSpace
      • NSDeviceRGBColorSpace
      • NSDeviceCMYKColorSpace
  • writeSummaryValues (boolean)

    • Defaults to YES. If set, values are written for cells for a column with a summary defined and a item with children. This is what most exporters need, but the ‘default’ exporter used for saving in the application does NOT write these values. This allows the file to have a minimal change for a leaf value change rather than having all the ancestor cells get updated too. Instead, a element is written in the file.

When you’re done, your plist should look something like this:

OmniOutliner 4 plugin plist

For more examples of Info.plist entries, you can examine the plug-ins shipped inside OmniOutliner. Control-click the application icon in Finder and select Show Package Contents. Navigate to Contents ‣ PlugIns to view the list of included plugins. Inside each you will find a Contents ‣ Info.plist that you can examine and compare to your work.

Build the target

Select Build > Build.

Add your plug-in to OmniOutliner’s bundle search path

With OmniOutliner 4, you can double-click the .ooxsl file and it will be installed to the correct location within the application sandbox container. Make sure you’ve enabled the Pro feature set in order to access your new export options from the File > Export window.

Notes

Debugging

Check your console.log file for any errors that OmniOutliner may emit when your plug-in gets loaded.

Misc. notes

The XSL library used in OmniOutliner 4 is libxslt which is supplied with Mac OS X 10.3.9 and later.

Last Modified: Jul 15, 2020

Can we help?

support@omnigroup.com
+1 206-523-4152 or 800-315-OMNI

Was this article helpful?

Still need help?

support@omnigroup.com
+1 206-523-4152 or 800-315-OMNI