data cascade precedence not matching docs

[mvolkmann]

The docs say that the precedence order for data in a template is:

• front matter in the template
• layouts used by the template
• template data files
• directory data files
• global data files

But it seems to me that layouts get the lowest precedence.
This GitHub repo. demonstrates what I'm seeing https://github.com/mvolkmann/11ty-demo

To Reproduce
Steps to reproduce the behavior:

1. Clone the repo.
2. npm install
3. npm start
4. Browse http://localhost:8080/level1/level2/demo/.

Note that the dog names displayed are those from _data/dogs.json, not those from _includes/layout.njk. However, we know the layout is getting used because we see "layout.njk header" at the top and "layout.njk header" at the bottom.
If we rename _data/dogs.json to _data/dogsx.json and refresh the browser then the names from the layout are displayed.

Expected behavior
The dog data in the layout should take precedence over every other definition of dogs except front matter in the demo.md file.

Environment:

• OS and Version: macOS 10.15.1
• Eleventy Version 0.10.0

[mvolkmann]

For example, consider the following directory structure. Each file is numbered to indicate its precedence in providing data using in dogs.md with 1 being the highest. Assume that dogs.md uses _includes/layout.njk. This shows the precedence I am experiencing, but the docs indicate that _includes/layout.njk should be 2.

• _includes
  • layout.njk (10)
• _data
  • dogs.js (8)
  • dogs.json (9)
• level1
  • level1.11tydata.js (6)
  • level1.11tydata.json (7)
  • level2
    • dogs.11tydata.js (2)
    • dogs.11tydata.json (3)
    • level2.11tydata.js (4)
    • level2.11tydata.json (5)
    • dogs.md (1)

[zachleat]

Aha, I noticed this too—thanks! Can you retest after the next beta is released?

[mvolkmann]

I'd be glad to do that! How can I be notified when a new beta is released?

[zachleat]

Good question! They show up here https://github.com/11ty/eleventy/releases and here https://www.npmjs.com/package/@11ty/eleventy

We also post them on Twitter, usually. Not sure of the subscription options for these though

[zachleat]

Reopening this as I’m rethinking how it should correctly work!

Prior to 0.11.0 the behavior was:

1. Front Matter Data in a Template
2. Template Data Files
3. Directory Data Files (and ascending Parent Directories)
4. Global Data Files
5. Front Matter Data in Layouts

The documentation incorrectly stated:

1. Front Matter Data in a Template
2. Front Matter Data in Layouts
3. Template Data Files
4. Directory Data Files (and ascending Parent Directories)
5. Global Data Files

But I don’t think either of those are correct. I think ideally it should be:

1. Front Matter Data in a Template
2. Template Data Files
3. Directory Data Files (and ascending Parent Directories)
4. Front Matter Data in Layouts
5. Global Data Files

Any thoughts here?

[samuelpath]

@zachleat, I'm trying to make sense of your last comment and question.

I'm putting aside the question regarding the documentation (data-cascade and data-computed), and only focusing on what was, is, and should be.

WAS (prior to 0.11.0)

1. Front Matter Data in a Template
2. Template Data Files
3. Directory Data Files (and ascending Parent Directories)
4. Global Data Files
5. Front Matter Data in Layouts

IDEALLY SHOULD BE (accoding to @zachleat)

1. Front Matter Data in a Template
2. Template Data Files
3. Directory Data Files (and ascending Parent Directories)
4. Front Matter Data in Layouts
5. Global Data Files

So the only difference between what was and what should be is that 4 and 5 should be inverted, right?

@zachleat, can you then explain why you think Front Matter Data in Layouts should take precedence over Global Data Files in the data cascade?

PS. You said what was and what should be but you didn't say what is. Could you clarify?

[zachleat]

Current behavior is:

    Front Matter Data in a Template
    Template Data Files
    Directory Data Files (and ascending Parent Directories)
    Global Data Files
    Front Matter Data in Layouts

Which I would classify as a hefty bug. The idea of the Data Cascade generally is that the closer you get to the content, the higher priority the items should be. The more templates a data file can affect, the lower priority they should be in the cascade. So, ideally:

1. Front Matter Data in a Template
2. Template Data Files
3. Directory Data Files (and ascending Parent Directories)
4. Global Data Files

Where should Front Matter Data in Layouts go? Last (current behavior) is definitely wrong. An argument could be made to slide it in at 1.5, 2.5, or 3.5 probably.

1.5 would match what the docs have said for a very long time and may be the least controversial. But 2.5 or 3.5 makes the most sense to me in the spirit of the Data Cascade.

[samuelpath]

You said:

1.5 would match what the docs have said for a very long time and may be the least controversial. But 2.5 or 3.5 makes the most sense to me in the spirit of the Data Cascade.

In my humble opinion, it would be better to implement what makes most sense to you (and most likely to other experienced static-site generators developers), rather than to stick with what the docs have said for a very long time and may be the least controversial.

Sticking with the least controversial option is most likely easier in the short-run, but for the long-term maintainability and development of this project, I would suggest that we dare implementing what makes most sense.

If you follow me on that, then we only have to decide between 2.5 and 3.5.

So we have these 2 options:

2. Template Data Files
---> Front Matter Data in Layouts ??
3. Directory Data Files (and ascending Parent Directories)
---> Front Matter Data in Layouts ??
4. Global Data Files

So the decision to be taken can be summed up with the following question:

What should take precedence between Front Matter Data in Layouts and Directory Data Files (and ascending Parent Directories)?

If both seem as logical, we can simply chose the one that would prove less controversial and would lead to less refactoring. Which one would it be in your opinion?

[paulshryock]

3.5 makes the most sense.

"It's been in the Docs for a long time" might be a solid justification if this project had multiple established major versions. Since it's pre-1.0, it feels totally acceptable to change this, and simply document the change.

[samuelpath]

@paulshryock : Can you explain why 3.5 makes the most sense to you?

Also, @mvolkmann : Since you initially opened this issue, your take on this could be useful. Do you have a strong opinion between 2.5 and 3.5, and if so, why?

[mvolkmann]

I would vote for 3.5. My reason is that layouts seem closer to “global” data than directory data files. I imagine most 11ty sites have a small number of layout files that are shared by many pages and have a larger number of directories that possibly want to provide data to a smaller subset of pages.

[samuelpath]

There seems to be a growing consensus on 3.5 (Directory Data Files taking precedence over Front Matter Data in Layouts).

@zachleat what's your take on this in light of the latest responses?

If you agree on 3.5, have you planned to implement the change yourself, or could you delegate this?

In case you'd be happy to delegate, I'd be happy to give it a try, and I would welcome some guidelines if you have any :).

[paulshryock]

@paulshryock : Can you explain why 3.5 makes the most sense to you?

I agree with these comments from @zachleat and @mvolkmann:

The idea of the Data Cascade generally is that the closer you get to the content, the higher priority the items should be. The more templates a data file can affect, the lower priority they should be in the cascade.

My reason is that layouts seem closer to “global” data than directory data files.

Layouts are lower priority ansd less specific than directory data and template data. Layouts are farther from the content, and can affect more templates across a range of directories.

[zachleat]

Unfortunately I am going to push this change into the 1.0 release, which seems both safer and more prudent here. 1.0 dev will start after 0.11.

[zachleat]

Definitely agree with the comments that it should go between 3 and 4 (aka 3.5)

[zachleat]

Shipping with Canary 45, the new order is:

# New in 1.0:

    Front Matter Data in Content/Templates
    Template Data Files
    Directory Data Files (and ascending Parent Directories)
    Front Matter Data in Layout Files
    Global Data Files

However, after a bit more research I don’t think it was clear what the previous behavior was on 0.11.0 -> 0.x, so I want to have that clearly documented here too:

# 0.11.0 to latest 0.x release

    Front Matter Data in Content/Templates
    Front Matter Data in Layout Files
    Template Data Files
    Directory Data Files (and ascending Parent Directories)
    Global Data Files

[zachleat]

Canary 45 ended up not being a thing. Instead, it shipped with 1.0.0-beta.1