diff --git a/source/modules/helpers/theme_helpers.js b/source/modules/helpers/theme_helpers.js index 71107af..bd82bfc 100644 --- a/source/modules/helpers/theme_helpers.js +++ b/source/modules/helpers/theme_helpers.js @@ -19,6 +19,8 @@ module.exports = (dust) => { // // Outputs one or more classes that should be applied to the element. // + // Attributes: none + // // Examples: // // {@bodyClass/} @@ -50,6 +52,11 @@ module.exports = (dust) => { // // Outputs the post content. If no post is specified, the current post context will be used. // + // Attributes: + // + // - editable - must appear exactly one time in every post template. Used to tell Postleaf which + // content block is editable. + // // Examples: // // {@content/} @@ -79,6 +86,11 @@ module.exports = (dust) => { // // Generates a URL for a dynamic image. // + // Attributes: + // + // - src* - the URL of the image to process. + // - See dynamic_images.js:processImages() for a complete list of attributes. + // // Examples: // // {@dynamicImage src="/uploads/2017/03/image.jpg" width="100"/} @@ -94,6 +106,15 @@ module.exports = (dust) => { // // Generates an excerpt. If no content is specified, the current post context will be used. // + // Attributes: + // + // - content - a string of HTML content to obtain the excerpt from. If omitted, the current post + // context will be used. + // - paragraphs - the number of paragraphs to use in the excerpt. + // - words - the number of max number of words to return in the excerpt. + // - tags - a comma-separated list of HTML tags to allow. If omitted, a default list list of tags + // suitable for an excerpt will be used. + // // Examples: // // {@excerpt/} @@ -134,6 +155,8 @@ module.exports = (dust) => { // // Outputs required foot data. // + // Attributes: none + // // Examples: // // {@foot/} @@ -176,6 +199,8 @@ module.exports = (dust) => { // // Gets all admin menu items. // + // Attributes: none + // // Examples: // // {@getAdminMenu} @@ -200,6 +225,16 @@ module.exports = (dust) => { // // Gets one or more authors. // + // Attributes: + // + // - id - the id of a single author to fetch. + // - email - the email of a single author to fetch. + // - username - the username of a single author to fetch. + // - sortBy - the property to sort results by (id, name, email, username, createdAt). + // - sortOrder - the sort order (asc for ascending, desc for descending). + // - count - the maximum number of items to return. + // - offset - the offset from which to return items. + // // Examples: // // {@getAuthors count="10" offset="0" sortBy="name" sortOrder="desc"} @@ -264,6 +299,13 @@ module.exports = (dust) => { // purposes, including finding an image to display as a visual excerpt or parsing elements or // attributes. If no content is specified, the current post context will be used. // + // Attributes: + // + // - content - the HTML content to parse. If omitted, the current post context will be used. + // - selector - The CSS selector to use. + // - count - The max number of elements to return. + // - offset - The offset from which to return elements. + // // Examples: // // {@getElements content="

...

" selector="img" count="1" offset="0"} @@ -303,6 +345,11 @@ module.exports = (dust) => { // // Gets the next post. If no post is specified, the current post context will be used. // + // Attributes: + // + // - post - the target post object. If omitted, the current post context will be used. + // - previous - set to true to return the previous post instead of the next post. + // // Examples: // // {@getNextPost} @@ -349,6 +396,15 @@ module.exports = (dust) => { // // Gets one or more posts. // + // Attributes: + // + // - id - the id of a single post to fetch. + // - slug - the slug of a single post to fetch. + // - sortBy - the property to sort results by (id, slug, title, createdAt). + // - sortOrder - the sort order. Use asc for ascending or desc for descending. + // - count - the maximum number of items to return. + // - offset - the offset from which to return items. + // // Examples: // // {@getPosts count="10" offset="0" sortBy="name" sortOrder="desc"} @@ -422,6 +478,12 @@ module.exports = (dust) => { // Gets posts that are related to the source post. If no post is specified, the current post // context will be used. // + // Attributes: + // + // - post - the target post object. + // - count - the max number of items to return. + // - offset - the offset from which to return items. + // // Examples: // // {@getRelatedPosts} @@ -482,6 +544,14 @@ module.exports = (dust) => { // // Gets one or more tags. // + // Attributes: + // - id - the id of a single tag to fetch. + // - slug - the slug of a single tag to fetch. + // - sortBy - the property to sort results by (id, slug, name, createdAt). + // - sortOrder - the sort order. Use asc for ascending or desc for descending. + // - count - the maximum number of items to return. + // - offset - the offset from which to return items. + // // Examples: // // {@getTags slug="favorites"} @@ -544,6 +614,12 @@ module.exports = (dust) => { // // Outputs required head data. // + // Attributes: + // + // - jsonLD - set to false to disable JSON-LD output. + // - openGraph - set to false to disable OpenGraph output. + // - twitterCard - set to false to disable Twitter Card output. + // // Examples: // // {@head/} @@ -645,6 +721,8 @@ module.exports = (dust) => { // // Gets the site's navigation. // + // Attributes: none + // // Examples: // // {@navigation} @@ -680,6 +758,10 @@ module.exports = (dust) => { // Outputs one or more classes that should be applied to posts in your theme. If no post is // specified, the current post context will be used. // + // Attributes: + // + // - the target post object. + // // Examples: // // {@postClass/} @@ -716,7 +798,15 @@ module.exports = (dust) => { // Posts can be filtered by any of the available flags using a `true` or `false` value. If an // argument is omitted, the flag will be ignored. // - // The special flag `isPublic` can be used to filter by posts that are publicly visible. + // Attributes: + // + // - author - set to a username to only count posts from that author. + // - tag - set to a tag slug to only count posts with that tag. + // - status - set to draft, published, pending, or rejected to only count posts with that status. + // - isFeatured - set to true to only count featured posts. + // - isPage - set to true to only count pages. + // - isSticky - set to true to only count sticky posts. + // - isPublic - set to true to only count posts that are publicly visible. // // Examples: // @@ -767,8 +857,12 @@ module.exports = (dust) => { }; // - // Determines if a post is publicly visible (i.e. published but not scheduled). If no post is - // specified, the current post context will be used. + // Determines if a post is publicly visible (i.e. published but not scheduled). + // + // Attributes: + // + // - post – the target post object. If no post is specified, the current post context will be + // used. // // Examples: // @@ -807,6 +901,11 @@ module.exports = (dust) => { // Returns the approximate number of minutes to read the specified content. If no content is // specified, the current post context will be used. // + // Attributes: + // + // - content - the content to use to estimate the reading time. + // - wordsPerMinute - the number of words per minute to base the calculation on (default 225). + // // Examples: // // {@readingTime/} diff --git a/source/modules/helpers/utility_helpers.js b/source/modules/helpers/utility_helpers.js index 65295ba..ce190da 100644 --- a/source/modules/helpers/utility_helpers.js +++ b/source/modules/helpers/utility_helpers.js @@ -43,17 +43,23 @@ module.exports = (dust) => { ////////////////////////////////////////////////////////////////////////////////////////////////// // - // Outputs a date in the specified format. If date isn't specified, the current time will be used. - // If format isn't specified, 'YYYY-MM-DD HH:mm:ss' will be used. If timeZone isn't specified, - // the time zone from settings will be used. + // Outputs a date/time in the specified format. // - // Format can be any format supported by Moment.js: https://momentjs.com/docs/#/displaying/ + // Attributes: + // + // - date - the date to output. If omitted, the current date and time will be used. + // - format - the format to use to output the date. Format can be any format supported by + // Moment.js (https://momentjs.com/docs/#/displaying/). If omitted, 'YYYY-MM-DD HH:mm:ss' will + // be used. + // - relative - Set to true to output a relative date (e.g. "7 days ago"). + // - timeZone - the time zone to convert the date to. If omitted, the time zone configured in + // settings will be used. // // Examples: // - // {@date date=publishedAt format="YYYY-MM-DD"/} ==> 2017-01-02 - // {@date date="2017-01-02 12:00:00" format="ddd, hA"/} ==> Sun, 3PM - // {@date date=publishedAt format="relative"/} ==> 3 days ago + // {@date date=publishedAt format="YYYY-MM-DD"/} + // {@date date="2017-01-02 12:00:00" format="ddd, hA"/} + // {@date date=publishedAt format="relative"/} // dust.helpers.date = (chunk, context, bodies, params) => { const I18n = context.options.locals.I18n; @@ -77,10 +83,23 @@ module.exports = (dust) => { // // Compares two dates. // + // Attributes: + // + // - key - The first date to compare. + // - value - The second date to compare. + // - operand - The type of comparison to perform. Can be <, <=, >, >=, between, or = (default). + // // Examples: // - // {@dateCompare key=publishedAt operand="<" value="now"}...{/dateCompare} - // {@dateCompare key=publishedAt operand="between" start="2016-01-01" end="2016-12-31"}...{/dateCompare} + // {@dateCompare key=publishedAt operand="<" value="now"} + // Date is in the past. + // {:else} + // Date is in the future. + // {/dateCompare} + // + // {@dateCompare key=publishedAt operand="between" start="2016-01-01" end="2016-12-31"} + // ... + // {/dateCompare} // // Notes: // @@ -132,7 +151,11 @@ module.exports = (dust) => { }; // - // Formats a size in bytes. + // Formats bytes into a more readable format. + // + // Attributes: + // + // - bytes - the target size in bytes. // // Examples: // @@ -150,6 +173,13 @@ module.exports = (dust) => { // // Formats a number. // + // Attributes: + // + // - number - the target number. + // - places - number of decimal places to use (default 0). + // - decimal - the decimal separator (default .). + // - thousands - the thousands separator (default ,). + // // Examples: // // {@formatNumber number="25000"/} @@ -176,6 +206,15 @@ module.exports = (dust) => { // Formats a URL based on the specified arguments. If no arguments are set, only the hostname will // be displayed. // + // Attributes: + // + // - url - the URL to format. + // - protocol - set to true to show the protocol, e.g. https:// (default false). + // - hostname - set to true to output the hostname (default true). + // - path - set to true to output the path (default false). + // - search - set to true to output the query (search) string, e.g. ?page=2 (default false). + // - hash - set to true to output the hash, e.g. #hash (default false). + // // Examples: // // {@formatUrl url="https://example.com/"/} @@ -206,6 +245,13 @@ module.exports = (dust) => { // // Outputs a localized language term. // + // Attributes: + // + // - term - the key of the desired language term. + // - type - the type of key. Can be term (default), symbol, or meta. + // - [placeholders] - If a term has a [placeholder], you can set its value by adding an attribute + // with the same name as the placeholder. + // // Examples: // // {@i18n term="term"/} @@ -247,9 +293,18 @@ module.exports = (dust) => { // // Checks an array or a CSV string for the given value. // + // Attributes: + // + // - key - the key to check for. + // - value - the values to check. Can be an array or a comma-separated string. + // // Examples: // - // {@in key=User.role value="editor,contributor,admin"}...{:else}...{/in} + // {@in key=User.role value="editor,contributor,admin"} + // Key is in value + // {:else} + // Key is not in value + // {/in} // dust.helpers.in = (chunk, context, bodies, params) => { let key = context.resolve(params.key); @@ -277,6 +332,13 @@ module.exports = (dust) => { // // Returns a plural or non-plural string based on a number. // + // Attributes: + // + // - count - the target count. + // - none - the output when count is zero. + // - one - the output when count is one. + // - many - the output when count is greater than one. Use % as a placeholder for count. + // // Examples: // // {@plural count="2" none="No posts" one="One post" many="% posts"/} @@ -293,6 +355,8 @@ module.exports = (dust) => { // // Outputs the current Postleaf version number. // + // Attributes: none + // // Examples: // // {@postleafVersion/} @@ -304,9 +368,16 @@ module.exports = (dust) => { // // Truncates text after a certain number of characters or words. // + // Attributes: + // + // - text - the text to truncate. + // - chars - the max number of characters to output (default 140). Only used if words isn't set. + // - words - the max number of words to output. + // - append - optional string to append if the text is longer than the max (default …) + // // Examples: // - // {@truncateWords text="Lorem ipsum..." chars="140" append="…"/} + // {@truncateWords text="Lorem ipsum..." chars="140"/} // {@truncateWords text="Lorem ipsum..." words="20" append="…"/} // dust.helpers.truncateWords = (chunk, context, bodies, params) => { @@ -339,7 +410,31 @@ module.exports = (dust) => { }; // - // Generates a URL. + // Generates a URL. You should always use this helper when outputting URLs. This is the only way + // to guarantees that URLs will be correct when themes, settings, or environmental variables + // change. + // + // Attributes: + // + // - type – the type of URL to generate (default raw). + // - admin – generates a URL to the admin panel. + // - api – generates a URL to the API. + // - author – generates a URL to an author page. Set the page attribute to link to a specific + // page. + // - blog – generates a link to the blog. The blog URL will not be the same as the homepage if + // a custom homepage is used. Set the page attribute to link to a specific page. + // - feed – generates a feed URL. Set the format attribute to json or rss (default) to change + // the feed format. + // - post – generates a post URL. The slug attribute is required for this type of URL. + // - raw – generates a raw URL to the website. + // - search – generates a URL to a search page. Set the page attribute to link to a specific + // page. Set the search attribute to set a search query. + // - tag – generates a link to a tag page. The slug attribute is required for this type of URL. + // Set the page attribute to link to a specific page. + // - path – a path to append to the URL. Only supported for raw, admin, api, and theme types. + // - absolute – set to true to output an absolute URL. + // - query – a query string to append to the URL. + // - hash – a hash to append to the URL. // // Examples: // @@ -366,11 +461,26 @@ module.exports = (dust) => { // // Compares two URLs. Compares against the current URL if `to` is not set. // + // Attributes: + // + // - to - a URL. + // - url - a URL to compare against. + // // Examples: // - // {@urlCompare url="/path/to/compare"/}...{/urlCompare} - // {@urlCompare url="/path/to/compare" to="/another/path"}...{/urlCompare} - // {@urlCompare url="/path/to/compare"/}...{:else}...{/urlCompare} + // {@urlCompare url="/path/to/compare"/} + // ... + // {/urlCompare} + // + // {@urlCompare url="/path/to/compare" to="/another/path"} + // ... + // {/urlCompare} + // + // {@urlCompare url="/path/to/compare"/} + // ... + // {:else} + // ... + // {/urlCompare} // dust.helpers.urlCompare = (chunk, context, bodies, params) => { const locals = context.options.locals;