End-User Changes

There are several breaking changes in this release, and some features have been deprecated. This guide will describe the process of migrating away from deprecated APIs to their replacements, and for updating breaking changes.

Unified Source Code Documentation

The current behavior for Javadoc, Groovydoc, Kotlindoc, and Swiftdoc has been deprecated, and will be removed in version 0.19.0. All of these plugins have been re-implemented under the common OrchidSourceDoc interface, and are more flexible, more maintainable, and are all configured in the same manner.

Since OrchidSourceDoc is considered to be in beta for 0.18.x, it must be enabled via the --experimentalSourceDoc CLI flag. Without this flag, the current behaviour remains unchanged, and your site will not break. You must update your docs before upgrading to 0.19.0, which will be released no earlier than February 2020.

Dynamic queries for pages has been removed

If you were using "queries" for locating pages, such as findAll('tag=one'), this has been removed in 0.18.0. You should instead create custom Taxonomy archives for the pages you wish to match in this manner, and then use the collections created by that plugins to locate those pages.

For backward-compatibility, you may replace function calls like findAll('tag=one') in your templates with index.queryPages('tag=one'). This method may be removed in a future version of Orchid, so you should work to migrate toward taxonomies as described above, but it will provide you with the expected functionality until then. Using the new Diagnosis Mode mode can help you find offending cases of findAll('tag=one')-like calls which need to be migrated.

Updates to Copper theme

Orchid's own docs have been redesigned with the Copper theme as its base, and numerous changes have been applied to that theme. Most notably, if you were using the homepage with the copperTiles component, you will need to re-create that with the Tiles set up as menu items, rather than the ad-hoc structure used previously. See the configuration used here for how to recreate your homepage as a Menu. The previous functionality has been deprecated and will be removed in 0.19.0.

There have been various other changes to the theme's design and options, but the rest should be backward-compatible.

Updates to theme search

Previously, the scripts needed for client-side search were added to the BsDoc, Editorial, and FutureImperfect themes automatically. This functionality has been deprecated and will be removed in 0.19.0, as search should be added through the OrchidSearch meta-components.

In addition, the useSidebarSearch property has been removed from the BsDoc theme, so the search field is always visible, just like the other themes.

API Changes

The following are changes to internal APIs and patterns of Orchid plugins. The rest of this page is only relevant if you are developing custom plugins. Also note that the changes listed below may not be exhaustive; it is just a high-level overview of the kinds of changes made to Orchid's internals. If your plugins no longer compile with version 0.18.0, you might be better off just reaching out on Gitter or opening an issue, where I can help you figure out how to fix the problem more specifically.

OrchidContext passed to classes

The following changes are only relevant if you develop custom plugins. The API of many of Orchid's "extensible" classes have been changed. Most notably, the OrchidContext class is now typically passed to these classes' when they are used, instead of expecting that it would be injected in their constructor if needed. In most cases, you should be able to simply follow the compiler errors to fix these changes.

The following classes are impacted:

• OrchidMenuFactory
• OrchidPublisher
• TemplateTag
• TemplateFunction
• OrchidComponent
• OrchidCommand
• OrchidTask

Generator Models

There are some bigger changes regarding Generators and Collections, which may take a bit more work to address. Now, instead of a OrchidGenerator returning a List<OrchidPage> from startIndexing(), it should return an instance of OrchidGenerator.Model, which effectively wraps List<OrchidPage>. That same model is then passed to getCollections() instead of List<OrchidPage>. This allows a Generator to pass data from the startIndexing() call to getCollections() without having to hold it in the Generator class itself, and it can also be injected into OrchidMenuFactory, OrchidComponent, etc.

Because of this, Generators should no longer hold any state, and they should not be configured as singletons. Any state that was previously contained in the Generator class should now be contained in the Model class. The model should be accessed not through constructor injection, but by using the context.resolve(ModelClass.java) method. Constructor injection of the Model will fail since it is not bound to the DI container in an OrchidModule, but is added dynamically after the Generator has been indexed.

Refined Collections

Previously, Collections grouped Pages together under a collectionType and collectionId, but from there the page's itemId used to locate specific pages in a collection was done dynamically. Orchid could not statically determine if a given itemId matched a page, and could not tell the user the itemId that would select a specific page.

Now, pages strongly define their itemIds. This allows features like the Admin Panel to display the itemIds for each page, and also generate the anchor() function that would match a given page as viewed in that admin panel. As such, if you are creating custom OrchidPage classes, you will need to determine which properties of that class are it's IDs. This also reduces the need for custom OrchidCollection classes.

As part of this change, the concept of "global collections" has been removed. Previously, these were used to parse some kind of dynamic query string and search all indexed pages for pages which match that query. This kind of functionality has been completely removed as it was determined to be something of an anti-pattern. Moving forward, you should structure your collections such that pages are already grouped in more meaningful collections that reduces the need for complex, dynamic queries. Users can then perform filtering of these smaller collections if they need a more specific subset of those pages, or create custom TemplateFuntions to handle that kind of query logic.