Configuration Variable Redesign (#14008)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>
This commit is contained in:
Zack Arnett 2020-07-16 15:52:30 -05:00 committed by GitHub
parent 6a9ed4f342
commit 671dcbdf40
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 102 additions and 51 deletions

View File

@ -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 << "<dd>"
markup << "<p class='desc'>"
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>"
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 << "#{type_link(attr['type'], component: component)}</span>)</span>"
markup << "<span class='config-vars-type'>#{type_link(attr['type'], component: component)}</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?
markup << "<p class='default'>\nDefault value: #{converter.convert(attr['default'].to_s)}</p>"
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."
if isDefault && defaultValue.length > MIN_DEFAULT_LENGTH
markup << "<div class='config-vars-default'>\nDefault: #{defaultValue}</div>"
end
markup << "</dd>"
markup << "</div>"
# 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

View File

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