search

locomotivecms / engine

A platform to create, publish and edit sites
http://www.locomotivecms.com
Other
2.31k stars 625 forks source link

Trouble Understanding Sections #1296

Open westonganger opened 5 years ago

westonganger commented 5 years ago

The Documentation for Sections is quite difficult to comprehend. I have some questions and concerns.

  1. Docs Sections JSON definition, What is the difference between presets, default, sections_content? To be honest they all seem very similar. If so can they possibly be merged in any way to simplify this somehow?
  2. Docs Sections JSON definition, The repetition of the settings key gets confusing. Maybe the section-wide settings key could be renamed to main_settings
  3. Docs sections, "Create a Section" should be merged to top of "Setup a Section"
  4. Docs section, "Display a Section", should be ordered Global, Standalone, Dropzone. Currently its Global, Dropzone, Standalone. Dropzone requires the most comprehension and knowledge so it should be explained last.
  5. When reading through other places of the documentation, whenever dropzone is mentioned in other places of the docs it should have a link to the dropzones explanation. As a newbie reading through I had no idea what this meant and thought that it was referring to Liquid Drops.
  6. Docs Sections JSON definition, a kitchen sink example for each type would be good. Specifically there is not a good example snippet for dropzones.
  7. Looks like the Javascript Events section needs to be updated to include the new SectionManager. I quite like the simplicity of the old style events and the description of it brings some clarity to whats happening under the hood within the Section Manager. Please leave the old Javascript events description on top, and then explain the Section Manager below that.
  8. Docs Section "Setup a Section", the doc for "Liquid Template" should come before the "JSON Definition". The reason for this is it adds some simple intro knowledge to clarify to what is deeply explained in the JSON Definition docs.
did commented 5 years ago
  1. They can't be merged because you've got 3 distinct ways of using sections in a site:
    • as a global section (like the header or the footer)
    • as a standalone section (see it as snippet on steroids)
    • as a section in dropzone

Sometimes, a section can be used both as a standalone section and in a dropzone. That's why we need different kind of settings, especially in Wagon.

  1. @DonKoko, @manuchap, did you have problems with that?

  2. Agreed

  3. Agreed

  4. Again agreed :-)

  5. Agreed

  6. Totally agreed. The SectionManager is very useful when you don't want to repeat yourself when you generate a new section.

  7. Yeah, not sure about this one but it makes sense.

DonKoko commented 5 years ago

Maybe it was a bit confusing the first time, but not anymore. For me its clear that its scoped to the parent, which is either the section or the block.

manuchap commented 5 years ago

Took me a while to wrap my head around sections, especially grasping arrays and objects. I'll post more sections examples in TGV (when if find the time :-) What I found confusing was how wagon renders data either from the page header or from the default settings in the json definition.

westonganger commented 5 years ago

1 - Ok I understand they may be different, but how do I tell which one is for which? Can we maybe update to dropzone_presets, default_content, existing_sections_content

9 - Add sections_content description from docs "Display a Section" into "JSON Definition"

did commented 5 years ago
  1. https://doc.locomotivecms.com/v4.0/docs/json-definition#section-settings
westonganger commented 5 years ago

6 - Looks good but I meant more like kitchen sink examples that highlight the difference between the 3 ways of using sections (global, standalone, and dropzone)

did commented 5 years ago
  1. https://doc.locomotivecms.com/v4.0/docs/events
did commented 5 years ago
  1. What do you suggest? (I re-read the https://doc.locomotivecms.com/v4.0/docs/how-to-display-sections and it looks clear to me).
westonganger commented 5 years ago

6 - Hmm maybe I was thinking to have a code snippet with tabs in it where the tab names are "Global", "Standalone", "Dropzone" where each one is showcased and you can click each tab and compare the differences. Similar to the snippet here for the field types https://doc.locomotivecms.com/v4.0/docs/json-definition#settings

westonganger commented 5 years ago

9 - The documentation is missing for the Section drop from the Liquid -> Drops page. Also there should also be a section.name method here