When authoring content using FPM, we maintain a separation of content from presentation . FTD comes with a few “kernel” UI components, using them one can create any design or presentation. But using them directly is not recommended when authoring content.
For this reason themes should be designed as separate FPM package that are to be used by content packages as a dependency. The content packages should not use FTD kernel components, instead they should only use components defined by the one or more themes they depend on.
Each package in FPM exposes a bunch of “modules” (ftd documents in a package), and each of those modules exposes some “symbols”, e.g. record definitions, variables, and components defined in that module.
The set of modules and symbols is called the package interface of that package.
Say there is a package for creating resume. Say it exposes components like:
-- resume.me: Amit {bold: Upadhyay} total-experience: 18 years -- resume.degree: BTech, Mechanical Engineering university: IIT-Bombay graduation: 2003 -- resume.job: CEO company: FifthTry, Inc industry: Developer Tools start-date: 2020-August --- resume.role: CEO start-date: 2020-August
This theme has defined a module named resume and resume exposes .me,
.degree, .job and so on.
Any theme that implements this interface must implement components with same name.
The main goal for themes is for them to be interchangeable. Since a theme for a blog can not be interchanged with a theme for resume or a book, we aim interchangeable-ity at “package interface” level.
Every theme must target a well-known package-interface. Once a PI, package interface, has been picked, the theme must implement all the modules and symbols of that PI.
In future the fact that a theme implements some PI would be declared in the
FPM.ftd file for that theme:
-- import fpm: -- fpm.package: foo.github.io/some-theme implements: fpm.dev/resume
implements: is not yet implemented.
Once it is implemented, FPM will ensure that all the modules and symbols exported by fpm.dev/resume have corresponding compatible counterparts in foo.github.io/some-theme, else it will fail to build the package.
Similarly, in future, when adding the dependency of some-theme, a FPM.ftd
will be able to declare it is expecting it to implement some PI:
-- import fpm: -- fpm.package: amitu.github.io/resume -- fpm.dependency: foo.github.io/some-theme implements: fpm.dev/resume
Here amitu.github.io/resume is a FPM package that depends on
foo.github.io/some-theme. But since it has explicitly declared this dependency
implements fpm.dev/resume, only the modules and symbols exported by
fpm.dev/resume would be available on foo.github.io/some-theme.
The idea is that
a theme package may implement more than what is specified in the packages it implements.
A theme can provide extra modules or symbols. But since amitu.github.io/resume has imported foo.github.io/some-theme as fpm.dev/resume, when processing amitu.github.io/resume, only the fpm.dev/resume modules and symbols would be available, not the extra ones found on foo.github.io/some-theme.
If amitu.github.io/resume was interested in all the modules and symbols exported
by foo.github.io/some-theme, they can chose to not specify the implements:
directive in the FPM.ftd file.