shinstrap repo

Module: template/publish

This is the primary export module for shinstrap. jsdoc looks for this file in the referenced template/ directory when specified as a template in jsdoc's config file.

shinstrap is a fork of ink-docstrap, and the bulk of this file remains untouched. shinstrap, like docstrap before it follows the patterns set down in jsdoc's default template. See jsdoc/templates/default/publish.js (no link because, ironically, jsdoc didn't comment their templates :) ).

In addition to docstrap's baseline of features, shinstrap primarily adds customization. The order and organization of default tags can be changed (from configuration settings), as well as new rules to allow for the rendering of custom tags. The menus for tutorials can likewise be customized.
shinstrap adds a few simple features to override the built-in templates even for complex reworks with a minimum amount of futzing. Full details should be available in the Usage.md document in this module's documentation (or in design/Usage.md) [Usage].

namespaces

view

templates

static attribs

Template File: partial.scaffolded.attribs.tmpl
Honors the following configuration settings:
Name Type Description
template.displayStyle string

One of buttons, badges or csl describing how the doclet's attribs should be displayed.

The "first" scaffolded partial template, this template controls the display of attributes. This partial is designed to fit in with the display layout of docstrap, attempting to provide a "terse" easy rendering of the attributes for an entity.

By default, this template is called from method.tmpl and members.tmpl.

static container

Template File: container.tmpl

The "root" level display template for jsdoc. container.tmpl marhalls and displays most of the doclets which have their own landing page. This includes modules, interfaces, classes, namespace, events, mixins, etc. displayed as <article>s. This template is broken into two sections in docstrap, an "overview" section and what I am calling the body.

Display of contents of the "overview" area are controlled in the customizeOutput area of the template's configuration by the specifier path:
"container:article:overview:..."
This specifier has three branches -- "class", "module-with-modules" and the default (every other case). This is a legacy of docstrap

The "body" portion of this template's display is controlled by the specifier path:
"container:article:body:default"

static details

Template File: details.tmpl

One of the three workhorse templates for jsdoc display. details.tmpl marshals and displays the details of a doclet. Specifically...
[ "properties", "version", "since", "inherits", "overrides", "implementations", "implements", "mixes", "deprecated", "author", "copyright", "license", "defaultvalue", "meta", "tutorials", "see", "todo" ]

static General

Template File: listing.scaffolded.general.tmpl
Honors the following configuration settings:
Name Type Default Description
entryWrapper string

The tag which the entire entry should be wrapped in. For situations where you want to wrap both the title and the contents. For example, when making a <details> entry or a <fieldset> entry.
entryWrapperAttributes string

The attributes which should be rendered for the entryWrapper. Only valid if entryWrapper has a value.
suppressTitle boolean

If true, no title will be generated. This causes title, titleCaption and titleAttributes to be ignored.
outerTitleWrapper string

The "outer" wrapper for the title (title only supports two "tiers" of wrappers).
outerTitleAttributes string

The attributes to associate with the outer title tag.
titleWrapper string

The tag to wrap the title in.
titleCaption string

A string with which to replace the normally auto-generated title text. (See module:template/publish.handleScaffolding)
titleContextPluralize object

Causes the title to be pluralized if the doclet is an array with more than one member. This object has two fields--singular and plural, the value for each is used as the title in their respective cases.
titleWrapperAttributes string

The attributes to associate with the title tag.
suppressValue boolean false

If true, no value will be display for this entry. This causes the various wrapper and use* descriptors to be ignored.
outermostWrapper string

listing.scaffolded.general.tmpl allows for up to three tiers of embedded html wrappers.
This is the outermost wrapper.
outermostWrapperAttributes string

The attributes to assign to the outermostWrapper.
outerWrapper string

The "second tier" or outer html wrapper for an entry value.
outerWrapperAttributes string

The attributes to assign to the outerWrapper.
wrapper string

If usePartial is not set, wrapper indicates the tag in which to wrap the value of this listing.
wrapperAttributes string

The attributes to associate with the wrapping tag.
usePartial string

The template to display the tag's value with.
usePartialOnField string

When usePartial is set, allows the specification of which field on the doclet to supply to the partial as its data.
usePerItemPartial string

In the event that the entry's value is an array, usePerItemPartial allows the specification of a partial template to be used on each value in this entry's value array. This setting is overridden by usePartial.
perItemMapPartial object

If set, this setting allows the specification of an object, where each field name in the object is an expression, which if it evaluates to true will cause this template to use as a partial the value of that field. Conditions are tested in order and used on a first found basis. If a "default" field is specified, it will be used in the event none of the other conditions evaluate to true. usePartial and usePerItemPartial both override this setting.
alternateHandler string
itemMarshalling array

:advanced: This is an array of view helpers and parameters to execute on each entry's value before rendering it. The format for each call is ["functionName", "param1", "param2", ...]. An arbitrary number of marshal calls may be made, and they will be executed in order (e.g. itemMarshalling: [ [ "linkto", "", "" ] ]). Param specifications are relative to the entry value itself (for brevity), so "" references the entry value itself, and "kind" would reference data.kind (for instance).
find object

:advanced:
validate object

:advanced:

This is the general case listing handler for shinstrap.

static KeyValue

Template File: listing.scaffolded.kv.tmpl
Honors the following configuration settings:
Name Type Description
titleWrapper string

The tag to wrap the title in.
titleCaption string

A string with which to replace the normally auto-generated title text. (See module:template/publish.handleScaffolding)
titleWrapperAttributes string

The attributes to associate with the title tag.
usePartial string

The template to display the tag's value with.
usePartialOnField string

When usePartial is set, allows the specification of which field on the doclet to supply to the partial as its data.
wrapper string

If usePartial is not set, wrapper indicates the tag in which to wrap the value of this listing.
wrapperAttributes string

The attributes to associate with the wrapping tag.

This template handles the display of key-value pairs. For instance,
Type: {Object}

static method

Template File: method.tmpl

One of the three workhorse templates for jsdoc display. method.tmpl marshals and displays the common features of javascript entites and is used for methods, classes (when not on their own landing page), typedefs, and events. This is a common template to leverage for complex custom tags as well. By default it displays...
[ "description", "augments", "type", "this", "params", "details", "requires", "fires", "listens", "listeners", "exceptions", "returns", "examples" ]

static source

Template File: source.tmpl

This template controls the presentation of source files by jsdoc (when "outputSourceFiles": true).

static tutorial

Template File: tutorial.tmpl

This template controls the presentation of tutorials by jsdoc.

methods

static publish(taffyData, opts, tutorials)

This is the primary entry point into docstrap (and shinstrap).

Parameters:
Name Type Description
taffyData TAFFY

See http://taffydb.com/.
opts object
tutorials Tutorial

static utils.addScopeToAttribs(_doclet)

This is a simple helper function which simple adds a doclet's scope to its attribs collection. This is normally done in publish by calling jsdoc/util/templateHelper.getAttribs but that helper function only adds scope attribs for doclets of specific kinds. For custom doclet types, we have this function.

Parameters:
Name Type Description
_doclet object

The doclet for which to accumulate attributes.

Stub marshalling function to build namespace links.

static utils.capitalize(_string)

This is a simple helper function to capitalize a string. It is currently not wired into the system, being "pre" deprecated ;).

Parameters:
Name Type Description
_string string

The string to capitalize

static utils.handleScaffolding(_tmpl, _doclet, _arrangement, _listing, _title)

This is the primary helper function for the new custom listing mechanism. All listings are now routed through this method and, in conjunction with listing.scaffolded.general.tmpl, the capabilities of the custom listing declarations are enabled.

Parameters:
Name Type Description
_tmpl object

The template object for which this function is doing the scaffolding
_doclet object

Doclet object being described
_arrangement object

Describes how the listing should be displayed
_listing string

The portion of the doclet being documented
_title string

The doclet title as understood in the current template. Not the title of the listing being documented.
Returns:

The rendered HTML for the doclet or doclet fragment passed in.

Type
string

static utils.marshalItemDisplay(_item, _marshallingRules, _view)

This is the handler function for the itemMarshalling rule. This function will interpret the arrangment and the marshalling rules in the context of the indicated _item to derive the appropriate parameters, invoke the indicated function and return the result to the calling template.

Parameters:
Name Type Description
_item object

The display item or doclet being marshalled.
_marshallingRules object

The marshalling rules which dictate the handling of this item's marshalling.
_view object

The template view which is handing the rendering of this listing.
Returns:

"marshalled" html representation for _item as indicated in the _marshallingRules.

Type
string

static utils.renderDoclet(_arrangement, _defaults, _docOrData)

The default rendering pattern for a sectioned/named renderer (template).

Parameters:
Name Type Description
_arrangement object

The rules array for the doclet/fragment being rendered.
_defaults array

The default array of entries which are expected/valide for this doclet.
_docOrData object | array | string

The doclet or fragment being rendered.
ToDo:

  • Once I'm satisfied, this function should probably replace all the renderer snippets.

static utils.resolveArrangement(_aSelectors)

This function resolves two sets of information for doclets of the specified selectors...

  1. It will determine the order which tags are intended to be displayed in the listing.
  2. It will generate the tags descriptor object for all tags.
    This information is derived from the conf settings passed into the publish module.
remarks

I debate here whether I should capture in the closure the entirety of conf.customizeOutput or if I should instead pass it in on the stack (which might also allow for some recursive/contextual resolution in the future)...

Parameters:
Name Type Description
_aSelectors Array

An array of selectors indicating for which context to resolve the arrangement information. The last (most specific) specifier in the array may be replaced by "default" (although because of the behavior for unrecognized specifiers, this is just a convention)
Returns:

An object consisting of two fields--An order field as an array of listings to be displayed, and a tags field containing any custom listing specifications for that section. If the specified path is not found, the default arrangment will be returned ({ order: [ "*" ] , tags: {} }). If the specified path exists, but the specific specifier does not (e.g. container:article:body:module-with-modules) this function will return the default arrangement for that path, as specified in the all keyword, if present.

{ order: [ "description", "notes", "remarks", "*" ], tags: {} }

Type
object
Example 
var arrangement = resolveArrangement([ "container", "article", "body", "default" ]);

static utils.scaffoldFromSpecifier(_tmpl, _doclet, _tagSpecifier)

This is a simple wrapper on module:template/publish.utils.handleScaffolding which will retrieve the rules for a listing from a specifier (and then call handleScaffolding with those rules for the specified listing).

Parameters:
Name Type Description
_tmpl object

The template object for which this function will be doing the scaffolding.
_doclet object

The doclet or fragment being rendered.
_tagSpecifier string

A colon-delimeted specifier to the rules which dictate the rendering pattern for the doclet.
Returns:

HTML for the doclet or doclet fragment passed in.

Type
string

inner buildNav(members)

Create the navigation sidebar.

Parameters:
Name Type Description
members object

The members that will be used to create the sidebar.

Properties
Name Type Description
classes array.<object>
externals array.<object>
globals array.<object>
mixins array.<object>
interfaces array.<object>
modules array.<object>
namespaces array.<object>
tutorials array.<object>
events array.<object>
Returns:

The HTML for the navigation sidebar.

Type
string