In #237 Alan wrote:
BTW on the Introduction page, Coding Features is in green text (which usually means Premium), but only some of the Coding Features are Premium
This is an issue of its own. Quite simply, when a page includes a <premium> tag, the index page and link which calls to it gets the "premHint" class.
I understand the intent but it's not valid.
The class gets added here during the creation of navigation links:
|
nav += newNaviItem( |
|
state.curScope + `/${func.replace(/^\d+|\s+/g, '')}.htm`, |
|
(m.name || func).replace(/^\d+\s*/, ''), getAddClass(m, state)); |
The getAddClass is here:
|
function getAddClass(m, state) { |
|
if (!m || typeof m.desc !== "string") return ''; |
|
const desc = unwrapDesc(m.desc, state); |
|
if (!desc) return ''; |
|
|
|
if (has(desc, "<deprecated")) return ' class="deprHint"'; |
|
if (has(desc, "<xfeature")) return ' class="xfeatHint"'; |
|
if (has(desc, "<premium")) return ' class="premHint"'; |
|
return ''; |
|
} |
Note how it determines deprecation and premium from the current text description - the presence of a <tag>.
So what Alan is pointing out is that in the Coding Features page, cfg.MUI and cfg.Transparent have the <premium> tag, which is caught by getAddClass, so the call to newNaviItem uses that to add a "premHint" class on the menu list in the Introduction.htm page that gets generated.
It's important to leave the <premium> tags on the descriptions.
It's important to leave the premHint class on other index pages. But not this one - as Alan says, it gives the impression that everything in that category is Premium, which isn't correct.
As an example of where this is a good feature, see the docs > Native > Premium page which shows a list of premium features.
Note an issue on that page (to be addressed separately) that a couple premium features don't have the premHint class simply because the detail pages don't have the <premium> tag. Note also the red "SetKioskMode" which is both a <premium> feature and <xfeature>. (Class "xfeatHint" gets returned first, so it's red.)
Proposal
Given the fairly static nature of this documentation set, I don't think it's unreasonable to hardcode a couple file/category names. This is already done in at least one place.
To address this specific issue I propose a change to the generateNavigators function to simply avoid adding a class name to the Coding Features page.
Only a couple lines of code change in generate-navs.js.
I'm providing a PR that implements this proposal :
const noClassFor = ['04 Coding Features'];
...
nav += newNaviItem(
state.curScope + `/${func.replace(/^\d+|\s+/g, '')}.htm`,
(m.name || func).replace(/^\d+\s*/, ''),
noClassFor.includes(m.name || func) ? '' : getAddClass(m, state) // <<
);
If there are other examples of navigation items that shouldn't get styled, the code easily allows for it.
In #237 Alan wrote:
This is an issue of its own. Quite simply, when a page includes a
<premium>tag, the index page and link which calls to it gets the"premHint"class.I understand the intent but it's not valid.
The class gets added here during the creation of navigation links:
Docs/files/generators/generate-navs.js
Lines 28 to 30 in b2b4b89
The getAddClass is here:
Docs/files/generators/util.js
Lines 126 to 135 in b2b4b89
Note how it determines deprecation and premium from the current text description - the presence of a
<tag>.So what Alan is pointing out is that in the Coding Features page, cfg.MUI and cfg.Transparent have the
<premium>tag, which is caught by getAddClass, so the call to newNaviItem uses that to add a "premHint" class on the menu list in the Introduction.htm page that gets generated.It's important to leave the
<premium>tags on the descriptions.It's important to leave the premHint class on other index pages. But not this one - as Alan says, it gives the impression that everything in that category is Premium, which isn't correct.
As an example of where this is a good feature, see the docs > Native > Premium page which shows a list of premium features.
Note an issue on that page (to be addressed separately) that a couple premium features don't have the premHint class simply because the detail pages don't have the
<premium>tag. Note also the red "SetKioskMode" which is both a<premium>feature and<xfeature>. (Class "xfeatHint" gets returned first, so it's red.)Proposal
Given the fairly static nature of this documentation set, I don't think it's unreasonable to hardcode a couple file/category names. This is already done in at least one place.
To address this specific issue I propose a change to the generateNavigators function to simply avoid adding a class name to the Coding Features page.
Only a couple lines of code change in generate-navs.js.
I'm providing a PR that implements this proposal :
If there are other examples of navigation items that shouldn't get styled, the code easily allows for it.