Source auth header and Frontity Query Options about api-reference

[michalczaplinski]

Based on our in-person conversation with @mburridge here are some more details about Frontity Options and their use case. I think that it can be useful to think about the Frontity Options as this:

Dynamic configuration that can be specified via query string but which does not form part of the canonical link

The important part here being the does not form part of the canonical link. That means that whatever is passed in the frontity_*** query is not going to be used to be matched by handlers or used to fetch data from WordPress. Its purpose is to allow dynamic configuration of Frontity like the configuration that Luis has specified above:

• Some of these "Frontity Query Options" will be used by the core, like for example:

  • frontity_name -> state.frontity.options.name: The name of the site you want to load.
  • frontity_public_path -> state.frontity.options.publicPath: The public path that you want to use (not ready yet, but it will exist).

• But packages can also make use of them, like for example:

  • frontity_source_auth -> state.frontity.options.sourceAuth: A authentication token for the source package.
  • frontity_comments_skip -> state.frontity.options.commentsSkip: A boolean to skip rendering the comments (it's not real, I've just made it up).

[luisherranz]

Great summary Michal 🙂

I'd like to add that we are looking for a name for the query parameters that start with frontity_. It's a new concept in Frontity, so I think it deserves its own name. We've used Frontity Query Options and I think it is good so we can stick to that.

The "Frontity Query Options" could have their own section in the docs. They work as described by Michal:

• Any query param in the URL that starts with frontity_ is a "Frontity Query Option".
• Those queries are reserved to "send special information to Frontity", not related to the URL that needs to be rendered (a post, a page, or whatever), but to the Frontity configuration.
• Those parameters are removed from the state.frontity.initialLink and state.router.link because they should not affect the content of what needs to be rendered (a post, a page, or whatever).
• Those parameters are added to state.frontity.options. Packages that use them will look for them there.
• The name of those parameters is converted to camelcase. The value is not transformed.
• Some of these "Frontity Query Options" will be used by the core, like for example:
  • frontity_name -> state.frontity.options.name: The name of the site you want to load.
  • frontity_public_path -> state.frontity.options.publicPath: The public path that you want to use (not ready yet, but it will exist).
• But packages can also make use of them, like for example:
  • frontity_source_auth -> state.frontity.options.sourceAuth: A authentication token for the source package.
  • frontity_comments_skip -> state.frontity.options.commentsSkip: A boolean to skip rendering the comments (it's not real, I've just made it up).

[mburridge]

Closed by #24 and frontity/docs#281