[jira] [Commented] (SOLR-11584) Ref Guide: support Bootstrap components like tabs and pills

["Cassandra Targett (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-11584?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16234635#comment-16234635 ] 

Cassandra Targett commented on SOLR-11584:
------------------------------------------

The attached patch demonstrates how to do two types of content layout options: a) tabbed sections and b) content that's hidden behind a button. There are several things in this patch:

* An updated {{stream-decorator-reference.adoc}} file that uses tabs for every "Parameters" and "Syntax" section. There are 25 decorators on that page, so this shows what it might look like if a full page used this.
** This page also includes one example (in the section on the daemon stream decorator) of hiding content behind a button users need to click on to see the example - that specific example may not be the best use of that functionality, but I wanted to show another Bootstrap component that we could use relatively easily.
**  (As a side note, I started this to try to find a new way to organize & display all the streaming expressions in an easier-to-consume way. I suspect this isn't it, but since I started there, I finished there to demonstrate all its complexity on a large page).
* Updates to several CSS files to style tabs and buttons according to our style guidelines.
* Addition of documentation in {{meta-docs/jekyll.adoc}} to explain how to insert these types of sections in any page.
* Also, since I was playing with stuff, I added in a way to make a column-based TOC at the top of pages, as another option besides a long single list at the top or on the right side (use {{:page-tocclass: column}} to use it). This could be committed completely separately.

If you take a look at the docs I wrote on how to implement this, it requires a bit of knowledge of how Jekyll consumes Asciidoctor-converted content, how Asciidoctor deals with what it calls roles (which become CSS classes in the HTML), and how to nest different content block types into one another. 

IOW, it's fiddly, as they say - if someone doesn't get all the parts exactly right, we could end up with a mess. 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. I chatted with [~hossman] 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.

> 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: refguide-tabs.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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org