Configuration Variable Redesign (#14008)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

plugins/configuration.rb

@@ -12,6 +12,8 @@ module Jekyll
       'device_class', 'icon', 'map', 'list', 'date', 'datetime'
     ]
 
+    MIN_DEFAULT_LENGTH = 30
+
     def initialize(tag_name, text, tokens)
       super
       @component, @platform = text.strip.split('.', 2)
@@ -55,13 +57,11 @@ module Jekyll
 
     def render_config_vars(vars:, component:, platform:, converter:, classes: nil, parent_type: nil)
       result = Array.new
-      result << "<dl class='#{classes}'>"
+      result << "<div class='#{classes}'>"
 
       result << vars.map do |key, attr|
         markup = Array.new
-        markup << "<dt><a class='title-link' name='#{slug(key)}' href='\##{slug(key)}'></a> #{key}</dt>"
+        markup << "<div class='config-vars-item'><div class='config-vars-label'><a name='#{slug(key)}' class='title-link' href='\##{slug(key)}'></a> <span class='config-vars-label-name'>#{key}</span>"
-        markup << "<dd>"
-        markup << "<p class='desc'>"
 
         if attr.key? 'type'
 
@@ -78,14 +78,23 @@ module Jekyll
               TYPES.include? attr['type']
           end
 
-          markup << "<span class='type'>(<span class='#{type_class(attr['type'])}'>"
+          markup << "<span class='config-vars-type'>#{type_link(attr['type'], component: component)}</span>"
-          markup << "#{type_link(attr['type'], component: component)}</span>)</span>"
         else
           # Type is missing, which is required (unless we are in a list or template)
           raise ArgumentError, "Configuration key '#{key}' is missing a type definition" \
             unless ['list', 'template'].include? parent_type
         end
 
+        defaultValue = ""
+        isDefault = false
+        if attr.key? 'default' and not attr['default'].to_s.empty? 
+          isDefault = true
+          defaultValue = converter.convert(attr['default'].to_s)
+        elsif attr['type'].to_s.include? 'boolean'
+          # If the type is a boolean, a default key is required
+          raise ArgumentError, "Configuration key '#{key}' is a boolean type and"\
+            " therefore, requires a default."
+        end
         
         if attr.key? 'required'
           # Check if required is a valid value
@@ -93,41 +102,48 @@ module Jekyll
             "true, false, inclusive or exclusive."\
             unless [true, false, 'inclusive', 'exclusive'].include? attr['required']
 
-          markup << "<span class='required'>(#{required_value(attr['required'])})</span>"
+          isTrue = attr['required'].to_s == 'true'
+          startSymbol = isTrue ? '' : '('
+          endSymbol = isTrue ? '' : ')'
+          showDefault = isDefault && (defaultValue.length <= MIN_DEFAULT_LENGTH)
+          shortDefaultValue = ""
+          if showDefault
+            shortDefaultValue = defaultValue
+            shortDefaultValue.slice!("<p>")
+            shortDefaultValue.slice!("</p>")
+            shortDefaultValue = shortDefaultValue.strip
+            shortDefaultValue = ", default: " + shortDefaultValue
+          end
+
+          markup << "<span class='config-vars-required'>#{startSymbol}<span class='#{attr['required'].to_s}'>#{required_value(attr['required'])}</span>#{shortDefaultValue}#{endSymbol}</span>"
         end
 
+        markup << "</div><div class='config-vars-description-and-children'>"
+
         if attr.key? 'description'
-          markup << "<span class='description'>#{converter.convert(attr['description'].to_s)}</span>"
+          markup << "<span class='config-vars-description'>#{converter.convert(attr['description'].to_s)}</span>"
         else
           # Description is missing
           raise ArgumentError, "Configuration key '#{key}' is missing a description."
         end
-        markup << "</p>"
 
-        if attr.key? 'default' and not attr['default'].to_s.empty?
+        if isDefault && defaultValue.length > MIN_DEFAULT_LENGTH
-          markup << "<p class='default'>\nDefault value: #{converter.convert(attr['default'].to_s)}</p>"
+          markup << "<div class='config-vars-default'>\nDefault: #{defaultValue}</div>"
-        elsif attr['type'].to_s.include? 'boolean'
-          # Is the type is a boolean, a default key is required
-          raise ArgumentError, "Configuration key '#{key}' is a boolean type and"\
-            " therefore, requires a default."
         end
-
+        markup << "</div>"
-        markup << "</dd>"
 
         # Check for nested configuration variables
         if attr.key? 'keys'
-          markup << "<dd>"
           markup << render_config_vars(
             vars: attr['keys'], component: component,
             platform: platform, converter: converter,
             classes: 'nested', parent_type: attr['type'])
-          markup << "</dd>"
         end
 
-        markup
+        markup << "</div>"
       end
 
-      result << "</dl>"
+      result << "</div>"
       result.join
     end
 

sass/custom/_paulus.scss

@@ -491,47 +491,82 @@ twitter-widget {
 
 // Configuration variables
 div.config-vars {
-  // Future re-design
+  padding-bottom: 16px;
-  // h3 {
-  //   border: 0;
-  //   border-top: 1px solid $primary-color;
-  //   padding-top: 1.4rem;
-  // }
 
-  dl {
+  .config-vars-item {
-    margin-bottom: 1.5em;
+    border-bottom: 1px solid #d9dbde;
+    padding-top: 16px;
+    padding-bottom: 16px;
+  }
 
-    &.nested {
+  .nested .config-vars-item:last-child {
-      border-left: 1px dotted $primary-color;
+    border: none
-      padding-left: 6px;
+  }
+
+  .config-vars-label {
+    padding-bottom: 4px;
+    position: relative;
+
+    > span {
+      padding-right: 4px;
     }
 
-    dt {
+    &:hover a.title-link::before {
-      font-weight: bold;
+      position: absolute;
+      top: 5px;
+      left: -25px;
+      padding-right: 40px;
+      font-family: "FontAwesome";
+      font-size: 15px;
+      color: #999;
+      content: "";
     }
+  }
 
-    dd {
+  .config-vars-label-name {
-      margin: 0 0 0.5em 1em;
+    font-weight: bold;
+    font-size: 16px; 
+    color: #222222bd;
+  }
 
-      p.desc {
+  .config-vars-type {
-        margin: 0;
+    color :#8792a2;
+    font-size: 13px;
+  }
 
-        span.type,
+  .config-vars-required {
-        span.required {
+    color :#8792a2;
-          font-style: italic;
+    font-size: 13px;
+    text-transform: lowercase;
 
-          &::after {
+    .true {
-            content: " "
+      color: #e56f4a;
-          }
+      text-transform: uppercase;
-        }
+      font-size: 11px;
-      }
-
-      p.default {
-        font-style: italic;
-        margin: 0;
-      }
     }
   }
+
+  .config-vars-description-and-children {
+    font-size: 14px;
+    color: #4f566b;
+  }
+
+  .config-vars-description p {
+    margin: 0;
+  }
+
+  .config-vars-default {
+    padding-top: 8px;
+
+    p {
+      margin: 0;
+      display: inline;
+    }
+  }
+
+  .nested {
+    margin-left: 48px;
+  }
 }
 
 code {