Support "try it out" requests to the server

README.md

@@ -32,6 +32,8 @@ Name           | Description
 `style`        | LESS or CSS to control the layout and style of the document using the variables from below. Can be a path to your own file or one of the following presets: `default`. May be an array of paths and/or presets.
 `template`     | Jade template to render HTML. Can be a path to your own file or one of the following presets: `default`.
 `variables`    | LESS variables that control theme colors, fonts, and spacing. Can be a path to your own file or one of the following presets: `default`, `flatly`, `slate`, `cyborg`. May be an array of paths and/or presets.
+`forms`        | Whether to generate form fields for trying out the API (default is `false`).
+`forms-base-uri` | The base URI to prepend to relative action URIs when trying out the API. Default is `auto`, meaning the full URI is calculated from the HOST keyword in the API Blueprint document or when that isn't present, from the host serving the documentation.
 
 **Note**: When using this theme programmatically, these options are cased like you would expect in Javascript: `--theme-full-width` becomes `options.themeFullWidth`.
 

src/main.coffee

@@ -317,11 +317,35 @@ modifyUriTemplate = (templateUri, parameters, colorize) ->
     uri
   , []).join('').replace(/\/+/g, '/')
 
-decorate = (api, md, slugCache, verbose) ->
+makeFullUriTemplate = (uriTemplate, baseUri) ->
+  # Change comma-separated params into individual params
+  while result = /\{([#&\?\+]?)([^,\}]+),/g.exec uriTemplate
+    operator = (if result[1] is '?' then '&' else result[1])
+    uriTemplate = uriTemplate.substring(0, result.index) +
+      '{' +
+      result[1] +
+      result[2] +
+      '}{' +
+      operator +
+      uriTemplate.substring(result.index + result[0].length)
+
+  # Prepend the baseUri if needed
+  if baseUri and uriTemplate.indexOf('://') is -1
+    if baseUri.charAt(baseUri.length-1) is '/'
+      baseUri = baseUri.substring 0, baseUri.length-1
+    if uriTemplate.charAt(0) isnt '/'
+      uriTemplate = '/' + uriTemplate
+    uriTemplate = baseUri + uriTemplate
+
+  return uriTemplate
+
+decorate = (api, md, slugCache, options) ->
   # Decorate an API Blueprint AST with various pieces of information that
   # will be useful for the theme. Anything that would significantly
   # complicate the Jade template should probably live here instead!
 
+  verbose = options.verbose
+
   # Use the slug caching mechanism
   slugify = slug.bind slug, slugCache
 
@@ -394,23 +418,36 @@ decorate = (api, md, slugCache, verbose) ->
 
         action.parameters = newParams.reverse()
 
+        uriTemplate = (action.attributes or {}).uriTemplate or
+          resource.uriTemplate or ''
+
+        for parameter in action.parameters
+          regex = new RegExp(
+            "\\{\\*#{parameter.name}\\}|\\{[#&\\?\\+]?#{parameter.name}\\*\\}")
+          parameter.explode = regex.test uriTemplate
+
         # Set up the action's template URI
-        action.uriTemplate = modifyUriTemplate(
-          (action.attributes or {}).uriTemplate or resource.uriTemplate or '',
-          action.parameters)
+        action.uriTemplate = modifyUriTemplate uriTemplate, action.parameters
 
-        action.colorizedUriTemplate = modifyUriTemplate(
-          (action.attributes or {}).uriTemplate or resource.uriTemplate or '',
+        action.colorizedUriTemplate = modifyUriTemplate(uriTemplate,
           action.parameters, true)
 
+        host = options.themeFormsBaseUri
+        if host is 'auto'
+          host = api.host
+        action.fullUriTemplate = makeFullUriTemplate action.uriTemplate, host
+
         # Examples have a content section only if they have a
         # description, headers, body, or schema.
-        action.hasRequest = false
+        action.requestCount = 0
+        action.hasBody = action.method == 'PUT' or action.method == 'POST'
         for example in action.examples or []
           for name in ['requests', 'responses']
             for item in example[name] or []
-              if name is 'requests' and not action.hasRequest
-                action.hasRequest = true
+              if name is 'requests'
+                ++action.requestCount
+                if not action.hasBody and item.body
+                  action.hasBody = true
 
               # If there is no schema, but there are MSON attributes, then try
               # to generate the schema. This will fail sometimes.
@@ -475,6 +512,12 @@ exports.getConfig = ->
     description: 'Layout style name or path to custom stylesheet'},
     {name: 'emoji', description: 'Enable support for emoticons',
     boolean: true, default: true}
+    {name: 'forms',
+    description: 'Generate form fields for trying out the API',
+    boolean: true, default: false},
+    {name: 'forms-base-uri',
+    description: 'A base URI to use for trying out the API',
+    default: 'auto'}
   ]
 
 # Render the blueprint with the given options using Jade and LESS
@@ -496,6 +539,8 @@ exports.render = (input, options, done) ->
   options.themeTemplate ?= 'default'
   options.themeCondenseNav ?= true
   options.themeFullWidth ?= false
+  options.themeForms ?= false
+  options.themeFormsBaseUri ?= 'auto'
 
   # Transform built-in layout names to paths
   if options.themeTemplate is 'default'
@@ -527,7 +572,7 @@ exports.render = (input, options, done) ->
   md.renderer.rules.code_block = md.renderer.rules.fence
 
   benchmark.start 'decorate'
-  decorate input, md, slugCache, options.verbose
+  decorate input, md, slugCache, options
   benchmark.end 'decorate'
 
   benchmark.start 'css-total'
@@ -541,6 +586,7 @@ exports.render = (input, options, done) ->
       condenseNav: options.themeCondenseNav
       css: css
       fullWidth: options.themeFullWidth
+      forms: options.themeForms
       date: moment
       hash: (value) ->
         crypto.createHash('md5').update(value.toString()).digest('hex')

styles/layout-default.less

@@ -121,6 +121,7 @@ pre {
     border: 1px solid @code-block-border-color;
     border-radius: @border-radius;
     overflow: auto;
+    max-height: 50em;
 
     code {
         color: @code-block-text-color;
@@ -139,6 +140,34 @@ code {
     border-radius: 3px;
 }
 
+input.parameter, select.parameter, select.request {
+    width: 200px;
+}
+
+textarea.body {
+    width: 300px;
+    height: 100px;
+}
+
+button.tryit {
+    padding: 1px 4px;
+    font: inherit;
+    margin: 12px 0 12px 150px;
+}
+
+.spinner {
+    margin-left: 4px;
+    display: none;
+}
+
+.response {
+    display: none;
+}
+
+.click-to-fill {
+    cursor: pointer;
+}
+
 ul, ol {
   padding-left: 2em;
 }
@@ -389,6 +418,10 @@ nav {
     max-height: 0;
     overflow: hidden;
     transition: max-height 0.3s ease-in-out;
+
+    dd {
+        overflow: auto;
+    }
 }
 
 /* Layout classes */

templates/index.jade

@@ -5,6 +5,7 @@ include mixins.jade
 html
     head
         meta(charset="utf-8")
+        meta(http-equiv="X-UA-Compatible", content="IE=edge")
         title= self.api.name || 'API Documentation'
         link(rel="stylesheet", href="https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css")
         style!= self.css