JENKINS-38670 update docs, add support for JS in handlebars templates

This is a bit anathema to using handlebars but we're more or less stuck with it: provide a way for a BuildCardExtention to contribute JS to the build card, allowing for richer build cards. Also switched an appendTo() to an append() which during testing did an evaluation of the JS but only when it was in progress - this would result in build cards being hidden if the build is in progress. jQuery docs say these are equivalent, but they are liars.
jenkinsci · Jun 13, 2017 · 48410da · 48410da
1 parent c12811d
commit 48410da
Show file tree

Hide file tree

Showing 5 changed files with 66 additions and 3 deletions.
diff --git a/.../java/au/com/centrumsystems/hudson/plugin/buildpipeline/extension/BuildCardExtension.java b/.../java/au/com/centrumsystems/hudson/plugin/buildpipeline/extension/BuildCardExtension.java
@@ -61,6 +61,26 @@
 import java.util.logging.Logger;
 
 /**
+ * <p>
+ *   This class is an extension point for a plugin to provide their own behavior for the 'build cards'
+ *   that show up in the build pipeline plugin.
+ * </p>
+ *
+ * <p>
+ *   This base class encapsulates the logic for how builds can be re-run and how the upstream build is
+ *   found, allowing subclasses to override this behavior.
+ * </p>
+ *
+ * <p>
+ *   In addition, this class also defines the look-and-feel of the build cards so that they can be overridden.
+ *   These are defined in the following .jelly files:
+ * </p>
+ *
+ * <ul>
+ *    <li>buildCardTemplate.jelly</li>
+ *    <li>buildCardHelpers.jelly</li>
+ * </ul>
+ *
  * @author dalvizu
  */
 public abstract class BuildCardExtension
@@ -272,6 +292,7 @@ protected int triggerBuild(final AbstractProject<?, ?> triggerProject, final Abs
      */
     protected List<AbstractBuildParameters> retrieveUpstreamProjectTriggerConfig(final AbstractProject<?, ?> project,
                                                                                final AbstractBuild<?, ?> upstreamBuild) {
+        LOGGER.fine("Looking for triggers in the upstream project: " + upstreamBuild.getProject().getFullName());
         final DescribableList<Publisher, Descriptor<Publisher>> upstreamProjectPublishersList =
                 upstreamBuild.getProject().getPublishersList();
 
@@ -290,6 +311,8 @@ protected List<AbstractBuildParameters> retrieveUpstreamProjectTriggerConfig(fin
                 LOGGER.warning("Upstream project had a Manual Trigger for projects [" + downstreamProjectsNames
                         + "], but that did not include our project [" + project.getFullName() + "]");
             }
+        } else {
+            LOGGER.fine("No manual trigger found");
         }
 
         final BuildTrigger autoTrigger = upstreamProjectPublishersList.get(BuildTrigger.class);

diff --git a/...n/resources/au/com/centrumsystems/hudson/plugin/buildpipeline/BuildPipelineView/bpp.jelly b/...n/resources/au/com/centrumsystems/hudson/plugin/buildpipeline/BuildPipelineView/bpp.jelly
@@ -35,6 +35,11 @@
         var projectCardTemplateSource = jQuery("#project-card-template").html();
         var buildPipeline = new BuildPipeline(buildPipelineViewProxy, Handlebars.compile(buildCardTemplateSource), Handlebars.compile(projectCardTemplateSource), ${from.getRefreshFrequencyInMillis()});
     </script>
+
+    <st:include page="buildCardHelpers.jelly"
+                from="${from.getBuildCard()}"
+                it="${from}"/>
+
     <form method="post" action="gridBuilder/build" id="triggerPipelineForm" class="no-json"/>
     <form method="post" name="pipelineViewForm" action="manualExecution" id="manualExecutionForm">
 
@@ -129,7 +134,6 @@
                                             // generate build-card
                                             var buildData = ${build.asJSON()};
                                             jQuery("#build-${build.getId()}").append(buildPipeline.buildCardTemplate(buildData));
-
                                             // add build proxy to proxies for future use
                                             buildPipeline.buildProxies[${build.getId()}] = <st:bind value="${build}" />;
                                             <j:if test="${build.getStatus() == 'BUILDING'}">

diff --git a/...umsystems/hudson/plugin/buildpipeline/extension/BuildCardExtension/buildCardHelpers.jelly b/...umsystems/hudson/plugin/buildpipeline/extension/BuildCardExtension/buildCardHelpers.jelly
@@ -0,0 +1,22 @@
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form" xmlns:i="jelly:fmt">
+    <!--
+        This file is included once in the build pipeline file - it is intended to allow a BuildCardExtension to contribute
+        any 'global' scripts or assets to the build pipeline. This includes the ability to add a Handlebars helper
+        (if you really, really must be using JS in a handlebars template).
+
+        By default we just include helpers to append script tags to your build card
+    -->
+    <![CDATA[
+
+    <script type="text/javascript">
+        Handlebars.registerHelper('startScript', function() {
+            return new Handlebars.SafeString("<scr" + "ipt>");
+        });
+
+        Handlebars.registerHelper('endScript', function() {
+            return new Handlebars.SafeString("</scr" + "ipt>");
+        });
+    </script>
+
+    ]]>
+</j:jelly>
diff --git a/...msystems/hudson/plugin/buildpipeline/extension/BuildCardExtension/buildCardTemplate.jelly b/...msystems/hudson/plugin/buildpipeline/extension/BuildCardExtension/buildCardTemplate.jelly
@@ -1,4 +1,19 @@
 <j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form" xmlns:i="jelly:fmt">
+{{!--
+
+    This is a handlebars template compiled in bpp.jelly - it allows is used to template build cards. This form is passed
+    a JSON object which is a `au.com.centrumsystems.hudson.plugin.buildpipeline.BuildForm` turned into a JsonObject
+    through `BuildJSONBuilder`
+
+    This class has two stapler variables implicitly available: the `it` object referring to the `BuildPipelineView` object,
+    and the `from` object referring to the implementing `BuildCardExtension` object (e.g. `StandardBuildCard`)
+
+    Note that including JavaScript is a bit anathema to handlebars templating - if you really must add dynamic behavior
+    to a template, do that using handlebars helpers. Helpers can be attached in `buildCardHelpers.jelly`
+
+    See http://handlebarsjs.com/expressions.html#helpers
+
+--}}
 <div class="build-card rounded {{build.status}} {{#if project.disabled}}disabled{{/if}}">
     <div class="header">
         <a href="${rootURL}/{{build.url}}" title="{{project.name}}">
@@ -140,5 +155,4 @@
         {{/if}}
     </div>
 </div>
-
 </j:jelly>
diff --git a/src/main/webapp/js/build-pipeline.js b/src/main/webapp/js/build-pipeline.js
@@ -56,7 +56,7 @@ BuildPipeline.prototype = {
 	updateBuildCardFromJSON : function(buildAsJSON, fadeIn) {
 		var buildPipeline = this;
 		jQuery("#build-" + buildAsJSON.id).empty();
-		jQuery(buildPipeline.buildCardTemplate(buildAsJSON)).hide().appendTo("#build-" + buildAsJSON.id).fadeIn(fadeIn ? 1000 : 0);
+		jQuery("#build-" + buildAsJSON.id).hide().append(buildPipeline.buildCardTemplate(buildAsJSON)).fadeIn(fadeIn ? 1000 : 0);
 	},
 	updateProjectCardFromJSON : function(projectAsJSON, fadeIn) {
 		var buildPipeline = this;