Config Editor: Enhance Description Flyout

Description

the parameter label (from ) should be displayed in the description flyout as well, as first line in bold, in a separated <p>.

below this a DIV with the description provided. this should be a DIV not a SPAN because it can contain blocklevel HTML markup, e.g. <p>, <ul> etc.

we should test this in one parameter description in the sample app.

Activity

Show:
Stefan Seifert
October 15, 2014, 9:19 AM

i've created for supporting a separate file for parameter properties. putting this on hold until we've decided and implemented WCMIO-18.

Stefan Seifert
October 14, 2014, 11:03 PM

my proposal would be to put this in the classpath near to the class defining the parameters. the abstract parameter provider implementation reading the constant class can look for such an optional XML file as well and read the additional properties (a bit tricky because this breaks the immutable concept of defined parameters, perhaps we add an intelligent clone-and-merge-custom-props methods for this). i can enhance the core implementation to support this.

if we store this additional property data in XML it is sensible to to use XHTML for rich markup instead of a type of markdown syntax. it's easy to ensure at least XML-validness in an editor, mixing XML and markdown is not really elegant. and there are too many different flavors of markdown syntax out there.

or if we want to use markdown we should use another format for storing the additional properties. java properties file? will get clumsy to edit as well with a lot of rich text and parameters in it.

Igor Sechyn
October 14, 2014, 11:28 AM

on possibility would be to have a separate XML file attached to the class holding the advanced parameter definitions nicely supporting XML with embedded HTML, it would be parsed once on startup. this solves all concerns but the i18n problem.

sounds good to me. where would you put the xml files? under resources in the corresponding project and reference them in the properties of the parameter? is config core bundle then responsible for parsing the xml files, whenever a new parameter provider is registered, before parameters are added to the collection?

Could wiki markup be an alternative?

Stefan Seifert
October 14, 2014, 9:22 AM

hmm, yes, that's not nice. but parameter descriptions may become very verbose, and my need special formatting like bullets, tables, inline links etc. in the past we had a lot of complex parameters that could not be explained with a single line or two of text. and on of our goals is to eliminate the need for separate parameter documentation in wiki, docbook or whatever which is always a maintenance burden.

i18n is a problem. in the past we only documented parameters in one language, so this was not a problem. inserting a lot of HTML code in a string in parameter definition class is another problem, quite ugly. on possibility would be to have a separate XML file attached to the class holding the advanced parameter definitions nicely supporting XML with embedded HTML, it would be parsed once on startup. this solves all concerns but the i18n problem.

having the sparate XML file would always be optional, you can decide to put the advanced parameter options either as properties in the class or in the XML file. allowing referencing i18n keys in the XML file allows translatable keys (even multiple ones mixed with HTML elements not part of the i18n keys). so if a project wants to invest the effort to translate even HTML-formatted parameter descriptions it would be possible. projects that cannot afford this just enter the description directly.

Igor Sechyn
October 13, 2014, 10:03 PM

below this a DIV with the description provided. this should be a DIV not a SPAN because it can contain blocklevel HTML markup, e.g. <p>, <ul> etc.

so the markup should be defined in the description property of the parameter, if i understand it correctly. I have implemented it this way at the very beginning, but removed it, because it could be error prone, writing markup as a string. furthermore, what happens, if the description needs to be localized? should markup be inserted into an i18n resource, this could be very tedious, when maintaing i18n resources in a json file.

Won't Fix

Assignee

Unassigned

Reporter

Stefan Seifert

Labels

None

Components

Priority

Trivial