Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

data cascade precedence not matching docs #915

Closed
mvolkmann opened this issue Feb 8, 2020 · 17 comments
Closed

data cascade precedence not matching docs #915

mvolkmann opened this issue Feb 8, 2020 · 17 comments

Comments

@mvolkmann
Copy link

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
Copy link
Author

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
Copy link
Member

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

@mvolkmann
Copy link
Author

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

@zachleat
Copy link
Member

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 zachleat reopened this Feb 24, 2020
@zachleat
Copy link
Member

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
Copy link
Contributor

samuelpath commented Mar 5, 2020

@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
Copy link
Member

zachleat commented Mar 5, 2020

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

samuelpath commented Mar 9, 2020

@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
Copy link
Author

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
Copy link
Contributor

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
Copy link
Contributor

paulshryock commented Mar 10, 2020

@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
Copy link
Member

zachleat commented Apr 7, 2020

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
Copy link
Member

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

@zachleat zachleat modified the milestones: Planning for Eleventy v1.0.0, Eleventy 1.0.0 Nov 22, 2020
@zachleat zachleat self-assigned this Sep 26, 2021
@zachleat
Copy link
Member

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 added a commit to 11ty/11ty-website that referenced this issue Sep 27, 2021
@zachleat
Copy link
Member

zachleat commented Oct 7, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants