FOray: Extending FOray

Contents

• Introduction

Introduction

The purpose of this page is to assist those who may wish to extend FOray’s capabilities. For documentation of the standard FOray extensions, see FOray Extensions.

There are a variety of reasons why some might want to extend FOray. Some may wish to extend it for proprietary reasons. Others may have needs that are too unusual to try to support in a standard product. FOray’s licensing supports both of these, and we think its technical design supports them also. Of course, if you develop an extension of general interest, we hope that you will consider contributing it to the project so that others can benefit as well. If you have developed something of general use and choose not to contribute it, you run the risk that someone else will develop and contribute a similar solution, thus essentially wasting your effort. There is a saying in the open-source community that “software wants to be free,” and it is true. By “free” is meant unencumbered (as opposed to gratis). There is nothing morally wrong with a proprietary solution, but it seems inevitably to lead to a need for an open-source counterpart, not so much usually for cost reasons as for availability. The open-source community is built around the idea that cooperation and cost-sharing ultimately leads to a more efficient and responsive development model than most commercial software vendors are able to deliver.

One of the primary design goals for FOray has been to make it as extensible as possible. The modular nature of its design was created specificially so that comparable components could be swapped in and out or run in parallel as needed.

Extending FOray’s core means extending one or more of its core modules, FO Tree, Area Tree, Layout, or Renderer. (This does not minimize the importance of the other modules, but simply highlights that they exist primarily in support of these.)

Of the four core modules, the easiest to discuss is Renderer. If you understand the Area Tree and know how to create the desired output format, it should be a fairly straightforward task to create a new Renderer or extend an existing one.

Creating a new Layout system requires creating a specialized subclass of LayoutStrategy which can drive the layout process. A solid understanding of the FO Tree and Area Tree data structures will be key ingredients to success.

Adding new classes to the Area Tree is feasible, but must be done with care. Probably the easiest way to proceed is to find a similar function that already exists and mimic it.

Finally, if your solution requires changes to the FO Tree, you will need to create a org.foray.fotree.Namespace instance to handle the parsing of the custom item(s). The Namespace must then be registered with the FOraySession after FOraySession has been instantiated.