FluidInspectorConcept.md

Fluid Inspector Concept

Intention

To create a backend module (first as standalone, in time shipped with EXT:fluid, the adapter for TYPO3) which allows inspecting various aspects of Fluid - which paths apply, how and there they are overridden and other information helpful when debugging. As a secondary goal the package should provide approximately the same analysis features as EXT:builder currently contains in its backend module. Once standalone Fluid becomes a dependency of TYPO3, additional configuration becomes possible and this configuration can then also be inspected (examples of such new features include but are not limited to registering ViewHelper namespaces in TypoScript or overriding default argument values, all of which will be highly relevant to output in an inspection module such as this one).

Purpose

To provide utilities that let you inspect and debug the environment of Fluid rather than each template. An inspector showing all details about the Fluid setup, paths etc. will serve this purpose much better than the TypoScript Object Browser which is where the configuration parameters can be read, but do not relate in any meaningful way to the actual template resources. Fitting the module with a diff mechanism will further allow comparing templates that have been overridden to their originals - which among other things greatly helps when upgrading extensions that provide templates - for example EXT:news.

Files and Classes involved

The Fluid Inspector (EXT:fluid_inspector) will start as a separate extension but could in time be merged with EXT:template (core extension that provides the TypoScript Object Browser and other views dealing with TypoScript). The implementation itself will be MVC-based and as such use a simple controller and view - but will skip the usual model part in favour of simple filtering parameters (e.g. which extension scope to focus on, which template in paths to compare with when diff’ing and along those lines). Simple measures will be used to allow saving the active filters in user configuration (UC) meaning it can be stored across sessions and when switching page contexts, further easing tasks like fast visual comparison of setups of two pages by switching back and forth.

Interface sketch - setup browser

This will be the primary interface based around a tree-style output like mocked below. From this interface the user can jump directly to for example a filtered result or a diff comparison of two templates, or just gather knowledge about where template files can be found.

• Fluid Root
  • Extension A (?filter…)
    • Templates
      • Page
      • Content
      • News
    • Partials
      • SomeDir
      • SomePartial.html analyse/profile (?view=analysis)
        • Alternative formats: txt (?filter=…), json (?filter=…), xml (?filter=…)
        • Overridden by:
          • Extension B (?filter=…) Compare with original (?filter=…)
          • Extension C (?filter=…) Compare with original (?filter=…)
    • Layouts
    • Widgets
  • Extension B (?filter…)
    • Templates
      • Content
        • SomeAction.html analyse/profile (?view=analysis)
          • Overridden by:
            • Extension B (?filter=…) Unmodified, equal to original
            • Extension C (?filter=…) Compare with original (?filter=…)
  • Extension C (?filter=…)
    • Templates

Interface sketch - diff view

The diff view focuses on two main view components: a source code diff and a set of key metrics extracted from the Parser during a test parse. If for whatever reason the template cannot be parsed (which would happen if it for example requires a controller which assigns view variables) the metrics section is excluded and a message shown, individually so that if the original is parseable but the override is not, it will clearly show in this view.

Navigation is done exclusively by changing the compared file in the topmost selector. The diff can also be exported to a format compatible with git.

|````````````````````````````````````````````````````````|
|                   <select>[1]</select>     [save diff] |
|________________________________________________________|
|                            |                           |
| original source            | diff / override           |
|____________________________|___________________________|
|                            |                           |
| parser metrics, original   | metrics of override with  |
|                            | second metric being diff  |
|                            | from original value (+/-) |
|____________________________|___________________________|

[1] Is intended to be an indentation- and optgroup-based <select> field which displays only the templates, partials and layouts which actually exist in the override path - enabling quick navigation to view diff of all overridden files without hitting “duds” that are still vanilla version.

Interface sketch - analysis view

A metrics-based view similar to what EXT:builder provides, the purpose of this view is to allow the metrics analysis that gets used in the diff view, to also be used in this view as a full size component. This view then also allows viewing metrics of both overrides and originals, whereas the diff view only deals with files that are overridden.

Metrics results can be exported to a folder (uploads folder) using a unique identifier and compiled to a chronological sequence suitable for display in a graph detailing changes over time - as a rough profiling support designed to give quick hints about general optimising (but not analyse every aspect of each ViewHelper’s performance).

|````````````````````````````````````````````````````````|
| <select>[2]</select> <select>[3]</select>              |
|________________________________________________________|
|                                                        |
| Overrides: [original](?filter=…)                       |
| Overridden by: [Ext B](?filter=…), [Ext C](?filter=…)  |
|________________________________________________________|
|                                                        |
|                                                        |
|                    Metrics results                     |
|                                                        |
|________________________________________________________|
|                                                        |
|              <historyChart></historyChart>             |
|________________________________________________________|

[2] Is a selector allowing switching to another extension as filtered scope and display the same template as it exists in that extension. If the same template asset does not exist in that other extension, the view resets to an empty view and wait for user to select the template file from the [3] selector. [3] Is a selector allowing switching between all template, partial, layout assets of the currently selected extension (originals only, overrides not considered at all). However, if the currently selected template is overridden by or overrides the same template from another extension then quick links are shown to switch to that extension’s template asset.

Sounds pretty neat :)

a few additional ideas:

1. i know of some plugins in wordpress that attach version numbers to their templates, every time a template gets changed, the version number is increased. maybe we could provide an optional viewhelper to set a version number at the top of a file. This makes it easier to determine, if you need to update your template or not. For example, if you massively changed one overridden template the diff will show loads of changes of course, but if had the "version tag" in there and it's still the same you can immediatly see/understand that there's nothing to care/worry about. if the version number changed though, you know that you probably need to update your template as well.
   Code Example:

Original Template:

<f:templateVersion version="1.0.0" />
<f:for each="{pages}" as="page"> 
    ....
</f:for>

overriden Template:

<f:templateVersion version="0.4.0" />
<f:for each="{oldPagesVariable}" as="page"> 
    ....
</f:for>

1. The general overview in the backend is really neat, additionally it would be awesome to have an analog to <f:debug> to quickly get the gist of one specific execution of templates. Example:

...some template/partial/layout...
<f:analyzeEnvironment/>