Re-structuring

[jasonvarga]

This PR contains a bunch of improvements to Structure-related areas.

Overview

Structures have been split into Navigation and Collection Structures.

Structures themselves still technically exist, but are more of an abstract code level thing.

Navigation

Navigation (or Navs) are now the things you were creating up until now.

A navigation is a type of structure that lives in your content/navigation directory. It's just a bunch of links and/or references to entries. Previously, you'd have a structure and you'd choose "navigation" as it's purpose. It replaces "Structures" in the CP sidebar.

Collection Structures

Associating a structure with a collection was one of the biggest areas of confusion.

Now, instead of needing to create a structure and link that structure from the collection, you can simply opt to have a collection "be organized into a structure".

The structure will be stored in the collection's YAML file:

# content/collections/pages.yaml
title: Pages
route: '{parent_uri}/{slug}'
blueprints:
  - page
structure:
  max_depth: 4
  tree:
    -
      entry: id-of-home
    -
      entry: id-of-blog-page

In the control panel, you will be able to easily toggle between the tree view and the table view.

Collection Ordering

Now that's simpler to define the structure of your entries, we've merged the concept of "ordering" into the structure.

Being orderable and being structured is basically the same thing. You're just dragging and dropping entries into the order you want. The only difference is that a structure lets you nest them.

So now instead of an explicit orderable: true item in your collection, you just enable the structure, and set max_depth: 0.

This removes the need for the current entry_order array in the collection's yaml file. If at some point you want to change from a linear order to a nested one, you can just increase the max depth.

In terms of UX, when you have a structure with a max depth of 1, you will get the existing table list view with drag handles.

Structure Root

The expects_root and root: some-id on a structure was also confusing.

The expects_root setting was there to control the UI, especially in the case where your structure didn't have any pages in it yet.
We had a separate root to prevent you from adding child pages to it.

Now, the "root" page is just simply part of the tree, and root is a boolean that defines whether the first item should be considered the root.

root: true
tree:
  -
    entry: home-page
  -
    entry: blog-page

This prevents you from needing to move the root in and out of the tree when you change the expects_root setting.

Redirects

You were already able to add redirect: somewhere to an entry to have a redirect be triggered when you visit its url. Now, the actual URL will be its target. ie. when you do {{ url }} in the front-end, you'll get the redirected URL.

This also means that if you use the entry query builder (or a feature that uses it under the hood), then there may be more than one entry with the same url. Not necessarily a problem, just something to be aware of.

Collection Structure Links

Piggybacking off redirects, this is how you'd create redirects and links within a collection's structure. A redirect would simply be another actual entry. It would just have a redirect variable in it.

When you click the "create entry" button in a collection, you'll get a "Link" option, as if it were one of your blueprints. This will give you the create entry screen with a title and redirect field.

If you create an entry_link blueprint, you can override these fields.

Collection Tag and Links

By default, link entries (any entries with a redirect value) will be excluded from the collection tag. You can include them by adding the links="true" (or redirects="true") parameter.

Permissions

Permissions are now attached to navs, instead of structures.

The existing reorder {collection} entries permission will be used to control whether the tree can be edited.

Control Panel "Nav"

We've changed Statamic\Facades\Nav to now deal with these new navs.

The existing Nav class which let you add items to the CP's sidebar has been moved to Statamic\Facades\CP\Nav.

Breaking changes

These are obviously breaking changes, so we will provide a way for you to get updated without you having to do it all manually.

Closes #1094

[jackmcdade]

A few bugaroos 🐛

• Turning on orderable on a new collection will throw missing tree errors when you try to save
• Picking an entry in the Redirect Fieldtype will show the ID instead of the title
• Redirect fieldtype's dropdown isn't wide enough to show the words "First Child"
• Tree view's "Create Entry" button should say "Create..." or use the new btn-group style with a dropdown because it wasn't clear that was a Create Link option until you see it there.
• You can Add Child Link to an entry in a Navigation but like above it wasn't clear you could add link to an entry from the Add Link button.

[chrisbjr]

Hi @jasonvarga already getting errors after this was merged :) is there a way to migrate to this re-structure automatically like you mentioned?