Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jenkinsci/bootstrap5-api-plugin

Jenkins plug-in that provides Bootstrap 5 (https://getbootstrap.com)
https://github.com/jenkinsci/bootstrap5-api-plugin

api-plugin jenkins-plugin

Last synced: 3 months ago
JSON representation

Jenkins plug-in that provides Bootstrap 5 (https://getbootstrap.com)

Awesome Lists containing this project

README 

          
:tip-caption: :bulb:

:imagesdir: etc/images



= Bootstrap 5 Jenkins Plugin



image:https://ci.jenkins.io/job/Plugins/job/bootstrap5-api-plugin/job/main/badge/icon?subject=Jenkins%20CI[Jenkins, link=https://ci.jenkins.io/job/Plugins/job/bootstrap5-api-plugin/job/main/]

image:https://github.com/jenkinsci/bootstrap5-api-plugin/workflows/GitHub%20CI/badge.svg[GitHub Actions, link=https://github.com/jenkinsci/bootstrap5-api-plugin/actions]

image:https://img.shields.io/github/issues-pr/jenkinsci/bootstrap5-api-plugin.svg[GitHub pull requests, link=https://github.com/jenkinsci/bootstrap5-api-plugin/pulls]



Provides https://getbootstrap.com/[Bootstrap 5] for Jenkins Plugins. Bootstrap is -- according to their self-perception --

the world’s most popular front-end component library to build responsive, mobile-first projects on the web. It is

an open source toolkit for developing with HTML, CSS, and JS. Developers can quickly prototype their ideas or

build entire apps with their Sass variables and mixins, responsive grid system, extensive prebuilt components,

and powerful plugins.



This plugin bundles the latest release and corresponding Jenkins UI elements.

Note that the Bootstrap release build has been adapted to integrate well with the existing Jenkins styles. For

more details please see `bootstrap-custom-build.scss`. The build process uses `npm` to actually rebuild Bootstrap from

sources and `maven` to bundle everything as a Jenkins plugin.



== Visualizing the media breakpoints



You can see the available breakpoints by including the following HTML snippet in your view:



[source,xml]

----



    


        xxxl

        xxl

        xl

        lg

        md

        sm

        xs

    




----



== How to use the plugin



In order to use this JS library, add a maven dependency to your pom:



[source,xml]

----



  io.jenkins.plugins

  bootstrap5-api

  [latest version]



----



=== Grid layout



The first thing to decide is, which elements should be shown on a plugin page and how much space each element

should occupy. Typically, all visible components are mapped on the available space using a simple grid.

In a Jenkins view we have a fixed header and footer and a navigation bar on the left

(20 percent of the horizontal space). The rest of a screen can be used by

a details view. In order to simplify the distribution of elements in that remaining space we use

https://getbootstrap.com/docs/5.1/layout/grid/[Bootstrap's grid system].



.Jenkins layout with a details view that contains a grid system

[#img-grid]

image::grid.png[Grid layout in Jenkins]



That means, a view is split into 12 columns and and arbitrary number of rows. This grid system is simple to use

(but complex enough to also support fancy screen layouts) - I won't go into

details here, please refer to the https://getbootstrap.com/docs/5.1/layout/grid/[Bootstrap documentation]

for details.



For the forensics detail view we use a simple grid of two rows and two columns. Since the number of columns always is 12

we need to create two "fat" columns that fill 6 of the standard columns. In order to create such a view in our plugin we

need to create a view given as a jelly file and a corresponding Java view model object. A view with this layout

is shown in the following snippet:



[source,xml,linenums]

.index.jelly

----



   <1>

    

    

       <2>

      
 <3>



        
 <4>

          
 <5>

            Content of column 1 in row 1

          


          
 <6>

            Content of column 2 in row 1

          


        



        
 <7>

          
 <8>

            Content of row 2

          


        



      


    

  



----

<1> Enable the property `nogrid` so we can use the bootstrap built-in grid (and not the Jenkins grid). Otherwise the layout will break.

<2> Import Bootstrap 5: Importing of JS and CSS components is done using the adjunct concept,

which is the preferred way of referencing static resources within Jenkins' Stapler Web framework.

<3> The whole view will be placed into a fluid container that fills up the whole screen (100% width).

<4> A new row of the view is specified with class `row`. The additional class `py-3` defines the padding to use for

this row, see https://getbootstrap.com/docs/5.2/utilities/spacing/[Bootstrap Spacing] for more details.

<5> Since Bootstrap automatically splits up a row into 12 equal sized columns we define here

that the first column should occupy 6 of these 12 columns. You can also leave off the detailed numbers, then Bootstrap will

automatically distribute the content in the available space. Just be aware that this not what you want in most of the times.

<6> The second column uses the remaining space, i.e. 6 of the 12 columns.

<7> The second row uses the same layout as row 1.

<8> There is only one column for row 1, it will fill the whole available space.



You can also specify different column layouts for one row, based on the actual visible size of the screen.

This helps to improve the layout for larger screens. In the warnings plugin you will find

an example: on small devices, there is one card visible that shows one pie chart in a carousel. If you are

opening the same page on a larger device, then two of the pie charts are shown side by side and the carousel is hidden.



[#cards]

=== Cards



When presenting information of a plugin as a block, typically plain text elements are shown. This will normally result

in some kind of boring web pages. In order to create a more appealing interface, it makes sense to present such information

in a card, that has a border, a header, an icon, and so on. In order to create such a

https://getbootstrap.com/docs/5.2/components/card/[Bootstrap card] a small jelly tag has been provided by the new

https://github.com/jenkinsci/bootstrap5-api-plugin[Bootstrap plugin] that simplifies this task for a plugin.

Such a card can be easily created in a jelly view in the following way:



[source,xml,linenums]

----



  Content of the card



----



In <> examples of such cards are shown. The cards in the upper row contain pie charts that show the

distribution of the number of authors and commits in the whole repository. The card at the bottom shows the detail

information in a DataTable. The visualization is not limited to charts or tables, you can

show any kind of HTML content in there. You can show any icon of your

plugin in these cards, but it is recommended to use one of the existing https://fontawesome.com[Font Awesome] icons

to get a consistent look and feel in Jenkins' plugin ecosystem.



.Bootstraps cards in Jenkins plugins

[#img-card]

image::card.png[Card examples]



Note that the size of the cards is determined by the grid configuration, see section <>.



You can find several examples of Jenkins views that use jQuery in the

https://github.com/jenkinsci/warnings-ng-plugin[Warnings Next Generation plugin]

and in the https://github.com/jenkinsci/forensics-api-plugin[Forensics plugin].