[
https://issues.apache.org/jira/browse/SOLR-11584?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Hoss Man updated SOLR-11584:
----------------------------
Attachment: SOLR-11584_customjs.patch
bq. ... Since most people don't run the HTML conversion locally before
committing, they may not know if they got it wrong until after it's published.
...
As of SOLR-10934, we now have a tool box to help us reduce the risk of these
types of "structural" mistakes, because "build-pdf" now also builds a barebones
HTML5 version (w/o jekyll) that we can run anchor+link checking against. We
could also use it to run other forms of structural validation in the future
(see more comments on this below) and ultimately hook it in to precommit if we
don't trust people to run "ant build-pdf" after changing the ref-guide pages.
bq. IOW, it's fiddly, as they say - if someone doesn't get all the parts
exactly right, we could end up with a mess. ... I chatted with Hoss Man
offline about it, and he promised to take a look to see if there is a way to do
this via a macro, or some other way that's less easy to mess up.
There's definitely some options for making these less error-prone.
When cassandra first showed me what she had in mind, and her POC, my initial
impression was that an asciidoctor macro of some kind would be the way to go --
but the more i looked at the diff asciidoctor "block types" that already exist,
and the way asciidoctor's html5 output will directly map user defined "roles"
to CSS classes, i started realizing that the problem isn't really asciidoctor
-- it's bootstrap's lack of "bootstrapping" tabs/pills/buttons based on content.
So instead what i did was write some javascript to "bootstrap bootstrap" --
automatically generating the pills we want based on the tab-panes and a new
"tab-label" we define. If/when we decide we want to take advantage of other
dynamic bootstrap page features, similar custom javascript will be easy.
In a nutshell, instead of something like this...
{code}
ifdef::backend-html5[]
++++
<ul id="fooTabs" class="nav nav-pills">
<li class="active"><a href="#fooXXX" data-toggle="pill">XXX Label</a></li>
<li><a href="#fooYYY" data-toggle="pill">YYY Label</a></li>
</ul>
++++
endif::[]
[.tab-content]
--
[example.tab-pane.active#fooXXX]
====
*XXX Label*
blah blah blah blah blah blah blah blah ...
====
[example.tab-pane#fooYYY]
====
*YYY Label*
[source,text]
----
blah blah blah blah blah blah blah blah ...
----
====
--
{code}
All we have to do is write this...
{code}
[.dynamic-tabs]
--
[example.tab-pane#fooXXX]
====
[.tab-label]*XXX Label*
blah blah blah blah blah blah blah blah ...
====
[example.tab-pane#fooYYY]
====
[.tab-label]*YYY Label*
[source,text]
----
blah blah blah blah blah blah blah blah ...
----
====
--
{code}
...and custom javascript takes care of building up the "pill" links and giving
everything the CSS classes and data-\* attributes that bootstrap expects.
Since this all runs in javascript, it means that if javascript is disabled, the
html never includes the useless pill links.
A few things to note about this javascript that are all easily tweakable based
on the conventions we want:
* I used {{dynamic-tabs}} as the special CSS class the custom javascript looks
for, and when it finds it it adds the {{tab-content}} class that bootstrap
requires -- 2 reasons for this:
** this way there's less risk that our custom javascript accidently breaks
{{tab-content}} that exists in our jekyll header/footer
** this means we could (if we want) style this stuff differently depending on
wether javascript is disabled
* the code currently assumes we always want the force the *first* {{tab-pane}}
to be the active tab pane/pill
** i feel like as a matter of convention this is just a blanket good idea
** this code could be tweaked so it checks if any tab pane has a user specified
{{active}} class, then it automatically sets the corrisponding pill as active
(to meet bootstraps preconditions)
*** but if we want to do this we have to decide what the rules should be if a
user copy/pasts a tab-pane and there are 2 active ones (pick the first? pick
the last?)
*** the custom html validation code we have could always fail if it detects
this ... just a matter of writting that validation code
* the custom javascript assumes that every tab-pane have a custom id defined
** no real way to avoid that in order for the pills to work -- but we could
make the HTML hide any tab that's missing it to draw attention to it
** again: our custom html anchor+link checking code could start failing the
build if a {{tab-pane}} exists w/o an id
* the {{tab-label}} class is how the custom java code decides what text to put
in the auto-generated pill
** currently the code _removes_ the tab label from the tab-pane itself -- so
the text doesn't appear redundently when a tab is visible -- but there's no
reason we can't leave it in if people think it looks better
** the code also currently uses the _inner_ html of the label -- so in the case
if {{\*Some \_stuff\_\*}} the pill text won't be bold, but the word "stuff"
will be italics
*** i did this on the assmption that as a convention we'd want to use the bold
tag for most of these "labels" in the PDF, but don't want all the pills to be
bold
*** we could use any asciidoctor markup that supports a role annotation for
these labels, and copy the markup into the pill if we want -- we just need to
decide the convention
*** again: whatever convention we want, rules could be enforced by our custom
validation code (ie: "the tab-label role can only be assigned to bold tags
which are the first element of a tab-pane"
** the custom javascript is currently forgiving about tab panes that don't have
a {{tab-label}} in them anywhere and auto generates a label based on the
"number" of the tab
*** there's a nocommit example of this in the attached patch (generating a pill
with the text "# 2") just so folks can see what it looks like
*** not sure it's a good idea, but wanted to point out that it's possible
*** again: custom html validation could enforce every tab-pane has a tab-label
if we want that.
----
NOTE: the attached patch "overlaps" cassandra's previous patch but is not a
super set -- notably it includes all of her CSS changes & equivilent content
changes to stream-decorator-reference.adoc (although in my conversion i may
have messed up some -- there was some weirdness with a blurb of text inbtween
the tab-panes for 'daemon' / contunious push streaming that i think was in the
original patch?) but it does not include changes to the meta-docs or any other
source files (partly because a lot the meta-doc chaanges from cassandras patch
don't really apply with this new approach, and partly because i had issues
applying her patch because of the image file?)
> Ref Guide: support Bootstrap components like tabs and pills
> -----------------------------------------------------------
>
> Key: SOLR-11584
> URL: https://issues.apache.org/jira/browse/SOLR-11584
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Cassandra Targett
> Assignee: Cassandra Targett
> Priority: Minor
> Fix For: 7.2
>
> Attachments: SOLR-11584.patch, SOLR-11584_customjs.patch,
> refguide-tabs.png, tabbed_api_output_example.png
>
>
> The theme I initially copied as the basis for the new Ref Guide included a
> Bootstrap integration, which has the potential to provide us with a number of
> options, such as organizing some content on a page into tabs (to present the
> same information in multiple ways - such as Windows vs Unix commands, or
> hand-editing schema.xml/managed-schema vs Schema API examples).
> However, the way AsciiDoctor content is inserted into a Jekyll template made
> it difficult to know how to use some of Bootstrap's features. Particularly
> since we have to make sure whatever we put into the content comes out right
> in the PDF.
> I had a bit of a breakthrough on this, and feel confident we can make
> straightforward instructions for anyone who might want to add this feature to
> their content. A patch will follow shortly with more details but the summary
> is:
> * Add an AsciiDoctor passthrough block that includes the Bootstrap HTML code
> to create the tabs.
> ** This has an {{ifdef::backend-html5[]}} rule on it, so it will only be used
> if the output format is HTML. The PDF will ignore this section entirely.
> * Use AsciiDoctor's "role" support to name the proper class names, which
> AsciiDoctor will convert into the right {{<div>}} elements in the HTML.
> ** These will take multiple class names and a section ID, which is perfect
> for our needs.
> ** One caveat is the divs need to be properly nested, and must be defined on
> blocks so all the content is inserted into the tab boxes appropriately. This
> gets a little complicated because you can't nest blocks of the same type
> (yet), but I found two block types we aren't using otherwise.
> ** The PDF similarly ignores these classes and IDs because it doesn't know
> what to do with custom classes (but in the future these may be supported and
> we could define these in a special way if we want).
> * Modify some of the CSS to display the way we want since AsciiDoctor inserts
> some of its own classes between the defined classes and the inheritance needs
> to be set up right. Also the default styling for the blocks needs to be
> changed so it doesn't look strange.
> I'll include a patch with a sample file that has this working, plus detailed
> instructions in the metadocs. In the meantime, I've attached a screenshot
> that shows a small snippet from my testing.
> While the focus here is using tabs & pills, we will be able to use the same
> principles to support collapsing sections if that's preferred for
> presentation.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
