linkedin / linkedin/dustjs

Proposal for additional $ properties

Open
#761 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
2.9k
Forks
461
PR merge metrics
No merged PRs in 30d

Description

I don't want to submit a PR without some feedback about this first. Essentially, I'd like to add a handful of very useful $ properties.

Currently, we have `$idx` and `$len`. I'd like to add the following:

- `$first` - equals `true` during the first iteration, `false` otherwise
- `$last` - equals `true` during the last iteration, `false` otherwise
- `$count` - equals the current count of the iteration (1-based index)

I've come across a number of circumstances where the corresponding helpers are too verbose or don't work. Perhaps the biggest use case is being able to use the proposed properties with comparison helpers. Some examples:

```dust
{?$first}...{/$first} <-- first item only
{^$first}...{/$first} <-- everything except the first item

{?$last}...{/$last} <-- last item only
{^$last}...{/$last} <-- everything except the last item

{@eq key=$count value=4}{/eq} <-- a specific item
```

I realize Dust aims to use "less logic", but sometimes we don't have complete control over datasets (or we have to go out of our way to adapt them). These special properties add a huge convenience to Dust templates.

Here is a simple modification to [this section of the code](https://github.com/linkedin/dustjs/blob/master/lib/dust.js#L855-L867) that adds the propsed properties:

```js
if (len > 0) {
head = context.stack && context.stack.head || {};
head.$len = len;
for (i = 0; i < len; i++) {
head.$first = i === 0;
head.$last = i === len - 1;
head.$count = i + 1;
head.$idx = i;
chunk = body(chunk, context.push(elem[i], i, len));
}
head.$idx = undefined;
head.$len = undefined;
head.$first = undefined;
head.$last = undefined;
head.$count = undefined;
return chunk;
} else if (skip) {
return skip(this, context);
}
```

I haven't done extensive testing, but it's a pretty straight-forward addition that seems to work well. (Of course, it works properly in nested loops as well.)

FWIW, I'd also suggest the aliases `$index` and `$length` for consistency and legibility, but that's another discussion.

Interested to hear the developer's and the community's thoughts on this.

Re:
- #720
- https://github.com/linkedin/dustjs-helpers/issues/15
- https://github.com/linkedin/dustjs-helpers/issues/58
- http://stackoverflow.com/questions/14781217/in-dust-js-can-the-inital-value-of-idx-not-be-zero-based

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in lib/dust.js around lines 855-867, where loop properties such as $idx and $len are assigned. Review the related issues and existing loop behavior before deciding how the proposed $first, $last, and $count properties should work, including nested loops. Done means the behavior is agreed upon, implemented, and covered by tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.