About FASTN Themes

When authoring content using FASTN, we maintain a {ds.highlight: 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 FASTN 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.

Package Interface
Each package in FASTN 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.

{ds.highlight: 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

-- 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.

Interchangeable Theme
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.

{ds.highlight: 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 `FASTN.ftd` file for that theme:

-- import fastn:

-- fastn.package: foo.github.io/some-theme
implements: fastn.dev/resume

-- import fastn:

-- fastn.package: foo.github.io/some-theme
implements: fastn.dev/resume

{ds.highlight: implements: is not yet implemented.} Once it is implemented, FASTN will ensure that all the modules and symbols exported by fastn.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 FASTN.ftd will be able to declare it is expecting it to implement some PI:

-- import fastn:

-- fastn.package: amitu.github.io/resume
-- fastn.dependency: foo.github.io/some-theme
implements: fastn.dev/resume

-- import fastn:

-- fastn.package: amitu.github.io/resume
-- fastn.dependency: foo.github.io/some-theme
implements: fastn.dev/resume

Here amitu.github.io/resume is a FASTN package that depends on foo.github.io/some-theme. But since it has explicitly declared this dependency implements fastn.dev/resume, only the modules and symbols exported by fastn.dev/resume would be available on foo.github.io/some-theme.

The idea is that {ds.highlight: 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 fastn.dev/resume, when processing amitu.github.io/resume, only the fastn.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 FASTN.ftd file.