RFC: Autocompletion in templates

Development RFCs
1

Hello,

As you may know, quite a long time ago I was working on templates DSL documentation available now in Foreman under /templates_doc. Although one can find this useful, when it comes to wrtiting a template it’s not so pleasant to check macros in the docs everytime one forgets which arguments they have or other small stuff. To help with this I’ve implemented [1] autocompletion for template editor, which uses the same docs to show tooltips and autofills. I’ve recorded how looks writing Host Statuses report template with enabled autocompletion:
autocomp

Current additions:

  • Basic autocompletion. After initial review only macros and properties are supported.
  • Parses /templates_doc to get macros/properties as snippets.
  • Shows related information about macro, – signature, short description, examples, return value, – as a tooltip.
  • Snippets also have default values set as per documentation.

Current issues:

  • This is more editor with autocompletion than IDE, so there is no object.suggestions pattern that would show what methods can be called on what objects, i.e. you cannot type @host. and get only the host methods. Current workaround is that properties are shown with prefixes, so one need to type prefix#property to get the snippet, e.g. Managed#name.
  • Doesn’t check if passed value type is valid.
  • Sometimes the related info is not being shown fully; probably the issue is in brace/ace that doesn’t consider user’s viewport for docTooltip.
  • Internal ApipieDSL.docs is used as a documentation to get the macros from. This means: the latest changes in code/docs, english (or default lang) only, default version. We can also use stored cache or or combinations.

RFCs:

  • Should we implement IDE-like behaviour based on return values?
    NOTE: probably will require lots of js code on client side.
  • How we can enhance visuals for autocompletion?
    NOTE: the question is more about what instead of actual how.
  • Should we restrict snippets and show only related ones for each kind of template, i.e. in report template editor show only macros from Reports section?
    NOTE: This can obviously reduce unrelated macros, but this needs review of all sections to ensure everything is properly scoped; probably will require some restructurations in the documentation.

All reviews, thoughts and suggestions are more than welcome to push the progress with it.

Please, feel free to write down them here or in the PR.

[1] - Fixes #32035 - Add DSL autocompletion in templates by ofedoren · Pull Request #8385 · theforeman/foreman · GitHub

6 Likes
2

Thanks @ofedoren, this is fantastic work bringing the templating engine to another level!

I played with the PR and here are few thoughts:

The main thing that is quite confusing is, is the list of keywords. These are typically things user won’t use such as stdin, assert_match and many other things that are disallowed in safemode. I think that limiting the autocompletion to just properties and macros would be a big win.

Another thing that I immediatelly experienced is typing outside of erb tag. E.g. when I edit kickstart file, adding more packages to %packages section is annoying (one word per line), when I hit enter to add a new line it selected the item from the autocompletion so I always have to press escape for every new entry. Maybe the autocompletion could pop-up on a special keys combination, like alt+enter or so. I guess we can’t guess the cursor context to know, when we want to activate the autocompletion…

I hope we can resolve these two main things in some way, I think the autocompletion is really cool.

1 Like
3

Hey all,

I’m going to continue to work on this and I’ve updated the PR [1]. If you interested, please review so we can enhance and merge this :slight_smile:

[1] - https://github.com/theforeman/foreman/pull/8385