Improve deprecated attribute or nested component visibility

[Matthbo]

[tnleeuw]

Is the deprecation-text, that explains why a property is deprecated / what to use instead still a hover-tooltip?

I think this would be much clearer if that text would not be a tooltip, but instead just be part of the description of the item. Then users don't have to know there's such a thing as a tooltip and can read this along with the text.

The drawback of the tooltip is that it is not obvious that it's there as explanation, and since there already is an explanation of the property one does not expect that there's another explanation available too.

[Matthbo]

Sergi and I have discussed this last week during our WUIDS, this is now consistent with the Properties page and we like to try this first. If it's still too unclear we might need to change the design for both occurrences instead of doing it one by one inconsistently.

[tnleeuw]

If this is the properties-page that you meant, I did not see any hover-info there for deprecation warnings:

https://reference.frankframework.org/#/properties

But perhaps you were referring to another page?

[Matthbo]

If this is the properties-page that you meant, I did not see any hover-info there for deprecation warnings:

reference.frankframework.org#/properties

But perhaps you were referring to another page?

On the properties page

Multiple flags can show here

[tnleeuw]

I (finally) see now that I have to hover the mouse over the little icon to the left of the property name.

This is a little bit better, but still not very clear to me. Especially for the XML attributes, where the tooltip gives important information and not just says "Deprecated", I think that for me this change still misses the point of discoverability.

You don't expect that information to be there, since you already expect to see all information in the next column.

In the descriptions of properties that is not as much of an issue since they are documented differently and the tooltip mostly doesn't offer real new information.

Anyway, that's my opinion on it.

[nielsm5]

We build the deprecation rule as follows:

https://github.com/frankframework/frankframework/blob/8ce84a9e9cbe2534ec9f7be8837efe83589293b5/core/src/main/java/org/frankframework/configuration/digester/ValidateAttributeRule.java#L209-L219

[philipsens]

I (finally) see now that I have to hover the mouse over the little icon to the left of the property name.

This is a little bit better, but still not very clear to me. Especially for the XML attributes, where the tooltip gives important information and not just says "Deprecated", I think that for me this change still misses the point of discoverability.

You don't expect that information to be there, since you already expect to see all information in the next column.

In the descriptions of properties that is not as much of an issue since they are documented differently and the tooltip mostly doesn't offer real new information.

Anyway, that's my opinion on it.

We chose this option, because it doesn't clutter the page or alter the way of reading the documentation.

Other options are:

• A banner above the property
• Separate section dedicated to "deprecated properties"
• A extra row beneath the description, like the options row

[evandongen]

I think this implementation misses the point (if I understand the reference to Properties correctly). The issue that caused this was because it's not clear at first sight how you can use (for example) EhCache. If the reason and alternatives for striked through attributes are still hidden, I'm not sure what we'll gain with this.

[philipsens]

I think this implementation misses the point (if I understand the reference to Properties correctly). The issue that caused this was because it's not clear at first sight how you can use (for example) EhCache. If the reason and alternatives for striked through attributes are still hidden, I'm not sure what we'll gain with this.

Good example.

We might have to do a WUIDS for this... I was thinking of doing something like this:

---

valueNamespaceDefs -> use value after v10.2
namespace definitions for valuexpath. must be in the form of a comma or space separated list of prefix=namespaceuri definitions

---

But there won't be a lot of space, so that's why I shortened it.

Also, I was looking through the example you gave (EhCache) and I can't seem to fiend the key and value properties. Am I looking wrong?

[evandongen]

I think this implementation misses the point (if I understand the reference to Properties correctly). The issue that caused this was because it's not clear at first sight how you can use (for example) EhCache. If the reason and alternatives for striked through attributes are still hidden, I'm not sure what we'll gain with this.

Good example.

We might have to do a WUIDS for this... I was thinking of doing something like this:

valueNamespaceDefs -> use value after v10.2 namespace definitions for valuexpath. must be in the form of a comma or space separated list of prefix=namespaceuri definitions

But there won't be a lot of space, so that's why I shortened it.

Also, I was looking through the example you gave (EhCache) and I can't seem to fiend the key and value properties. Am I looking wrong?

You aren't, those are @ff.parameter annotations on the AbstractCacheAdapter (the parent class) which aren't shown right now. Check #492 for that issue.

But, you say we need to do a wuids for this issue - I thought that was already done, resulting in this PR :-D

[tnleeuw]

I (finally) see now that I have to hover the mouse over the little icon to the left of the property name.
This is a little bit better, but still not very clear to me. Especially for the XML attributes, where the tooltip gives important information and not just says "Deprecated", I think that for me this change still misses the point of discoverability.
You don't expect that information to be there, since you already expect to see all information in the next column.
In the descriptions of properties that is not as much of an issue since they are documented differently and the tooltip mostly doesn't offer real new information.
Anyway, that's my opinion on it.

We chose this option, because it doesn't clutter the page or alter the way of reading the documentation.

Other options are:

• A banner above the property
• Separate section dedicated to "deprecated properties"
• A extra row beneath the description, like the options row

I thought it would be easiest to just add this as an extra paragraph in the same table-cell as the description of the attribute (or property).
Then it is inline, directly visible, and no extra tables / rows / etc.

[philipsens]

But, you say we need to do a wuids for this issue - I thought that was already done, resulting in this PR :-D

Yes we thought it was a really easy solution and a quick fix, but since you are giving feedback and there is some new information, we could reconsider. So everybody is happy :)

I thought it would be easiest to just add this as an extra paragraph in the same table-cell as the description of the attribute (or property). Then it is inline, directly visible, and no extra tables / rows / etc.

Ah yes, I meant the same when i said extra row. It is just that I don't want to draw a lot of extra attention to it. People should read it when it is relevant, so it shouldn't be to "loud"

Current situation:

Proposed solution:

(with or without 'Deprecated:')

Or maybe as note/quote:

This way it still differs from the description, but looks like an extra note.

I'll have to discuss with @Matthbo what's best.

[philipsens]

We build the deprecation rule as follows:

frankframework/frankframework@8ce84a9/core/src/main/java/org/frankframework/configuration/digester/ValidateAttributeRule.java#L209-L219

This doesn't show the "please use xxx"

[philipsens]

This will be our conclusion:

[Matthbo]

It now looks like this