Collapsable hierarchical tree

[kibertoad]

It would make navigating across hierarchical trees of complex entities with sub-entities more convenient if it was possible to collapse/expand each nesting level - something akin to this: https://www.w3schools.com/jquerymobile/tryit.asp?filename=tryjqmob_collapsible

[nknapp]

This wasn't possible in version 0.x, because there was no javascript-library included (and no engine to add javascript-libraries. In bootprint 1.x, this would be possible. However, including the complete bootstrap-javascript as well as jquery greatly increases the size of the generated HTML/CSS/JS, which is why I have removed the uglify-engine in version 2.0 (see the next-branch of the bootprint-project).

You could do it yourself for the moment, if you create a custom module for your purposes. Have a look at customize-engine-uglify.

customize and builder are the same thing.

[kibertoad]

@nknapp But given that HTMLs are going to be generated in the backend anyway, why does the size of generated artifacts matter? Also jquery and bootstrap could be linked from the CDN, thus avoiding any bump in size.

[nknapp]

The original purpose of bootprint was to generate a single HTML file with inline styles and send those by mail. Or even generate a PDF from the HTML. I am not sure if anybody uses it that way, but still, watching the output locally should not require an internet connection. I would not add CDN links to the core. And I do believe that size matters. The javascript has to be downloaded and parsed. That takes time, whether statically generated or not.

Do get me wrong. I would like to see some interactive features in the generated output. But it's not my top priority right now. There must be a way without adding megabytes of unused js code (don't know how much it actually was).

[igor-savin-ht]

@nknapp what is the business case behind such use? I wonder why would anyone schedule doc generation by email. We and other teams around use bootprint exclusively for documentation generation, and there user experience absolutely trumps size and net-independence. Would it be possible to include multiple templates with the lib so that everyone could use the output that suits his goals? We obviously can produce our own, but if something is maintained outside of upstream, it bitrots and is not very reusable.

[nknapp]

The original use... And I don't me "schedule". Just "generate". We use it on a public site as well now and we have it embedded in a grunt task and put other stuff around it.

Quesrion: are you using json-schema directly or openapi? If it's json-schema, could you have a look at the "next" branch and version 2.0.0-rc.3? I would be interested in whether it produces something better than version 1.x.

I have some thoughts about including a switch for activating such features, but for the moment I would propose the following:

If you are willing to implement those changes yourself, I give you and your colleagues access to the org on github. You can work in a branch (based in "next" preferably) and I will consult and support you as good as I can. When we have something usable, we can think about how to include this into "next" and then in "master"

[igor-savin-ht]

@nknapp Thanks for the clarification! We are using json-schema for model entity documentation and openapi for API endpoint documentation. I'll try out the next branch and compare the output, thanks.

I could take a shot at making the change - what would be your preferred solution and good places in code to start with implementing it?

[nknapp]

In the next branch there is a documentation of the partial-structure of this project. It can help you figure out where to add css-classes and add elements.

As a start, you could load the bootstrap-javascript and any library you need from a CDN. Create a new partial html-head-extra.hbs in handlebars/partials/base. That overrides the partial from the bootprint-base-package (which is the purpose of this partial, really).

You can use customize-engine-assets to include static assets (like images), but this engine this not well documented yet. I just see that this package is not published yet. That means, for the moment, we cannot use images or external fonts.

You can use customize-engine-uglify to include and minify multiple javascript-files that implement the actual collapse/expand.

The index.js would become

var path = require('path')

// Export function to create new config (builder is passed in from outside)
module.exports = function (builder) {
  return builder
    .registerEngine('uglify', require('customize-engine-uglify'))  // new: load uglify engine
    .load(require('bootprint-base'))
    .merge({
      'handlebars': {
        'partials': path.join(__dirname, 'handlebars/partials'),
        'helpers': require.resolve('./handlebars/helpers/index.js')
      },
      'less': {
        'main': [
          require.resolve('./less/theme.less'),
          require.resolve('./less/variables.less')
        ],
      },
      'uglify': {
        files: {
          'main.js': require.resolve('./javascript/main.js')  // new: generate main.js
        },
      }
    })
}

// Add "package" to be used by bootprint-doc-generator
module.exports.package = require('./package')

Then add javascript/main.js and start coding. The generated javascript is called bundle.js and is put next to the input-html. You can include it in the html-head-extra.hbs along with the other libraries.

---

This would be the initial setup that has to be done. I have no opinion yet about how the interface should look like, so I would say: Just start to implement something. I'll certainly give some comments when I see the changes.