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.
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.
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
diagnose
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
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.
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 classesThe 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
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.
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 itemId
s. This allows features like the Admin Panel to display the itemId
s 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.