0.18.0 Migration Guide
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.
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.
OrchidSourceDoc is considered to be in beta for 0.18.x, it must be enabled via the
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.
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.
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
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.
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.
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.
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:
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
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
getCollections() without having to hold it in the Generator class itself, and it can also be injected into
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.
Previously, Collections grouped Pages together under a
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
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
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.