Update guide 3 to 4 needs Routing section

[tpow]

As discussed on discord, in v3, the documentation says "Another cool feature is that if the current route already contains the correct dictionary then you do not have to pass a second parameter... [if the route has @id parameter], you can just leave it out completely since the id key is already stored on the request object". The v4 documentation omits that and it doesn't seem to be automatically populating the id as it had previously.

@josephmancuso says

No we didn’t port that over
I removed some of the magic stuff from 3 to 4 to make things clearer
I had lots of people confused about that over the years
If anything that should be noted in the upgrade guide
If it’s missing

There's a section in the upgrade guide for Routes, but it has nothing in it.

Personally, I like the feature when it worked, but it was fiddly and somewhat confusingly described.

[tpow]

In case it will help anyone else, I wrote this little script to help me identify routes with potentially missing parameters in the templates. Save it and run it in your Masonite project directory. This will only run in a masonite v4 project.

#!/usr/bin/env python

# Find templates that use route helper and compare number of params to expected
# number based on the variables in the route url
# This is to help identify templates that may need params added for v4
# See https://github.com/MasoniteFramework/docs/issues/233

import argparse
import os
import sys

from wsgi import application

router = application.make("router")

# Defaults
verbose = False
default_path = "templates/"
ignored = ["base.html"]


def find_routes(s):
    """Look for route(...) in the string and return ..."""
    # This assumes that route() only appears in jinja output
    import re

    routeregex = re.compile(r"route\(([^\)]+)\)")
    routes = re.findall(routeregex, s)
    return routes


def route_split(s):
    """Split route name from params"""
    parts = s.split(",")
    s = eval(parts[0])
    if not isinstance(s, str):
        raise TypeError
    params = parts[1:]
    return s, params


def main(templates_path):
    """Parse templates and identify possible route problems"""
    for root, subdir, files in os.walk(templates_path):
        for name in files:
            if not name.endswith("html") or name in ignored:
                continue
            fpath = os.path.join(root, name)
            if verbose:
                print(f"__ {fpath}")

            with open(fpath) as f:
                for row in f:
                    if not "route(" in row:
                        continue
                    row = row.strip()
                    # print(row)
                    routes = find_routes(row)
                    for route in routes:
                        rname, params = route_split(route)
                        # print(f"   route: {rname}, params: {params}")
                        found = router.find_by_name(rname)
                        if not found:
                            if not verbose:
                                print(f"__ {fpath}")
                            print(f"   !!!! missing route {rname} in {row}")
                            continue

                        num_required_params = found.url.count("@")
                        num_optional_params = found.url.count("?")
                        if len(params) != num_required_params:
                            if not verbose:
                                print(f"__ {fpath}")
                            print(f"   URL: {found.url}")
                            if len(params) == (
                                num_required_params + num_optional_params
                            ):
                                print("   OK with optional params:", end="")
                            else:
                                print("   !!! FIXME params needed:", end="")
                            print(f" route({rname},{','.join(params)})")


if __name__ == "__main__":
    desc = "Find templates that may have missing parameters for routes"
    parser = argparse.ArgumentParser(description=desc)
    parser.add_argument(
        "-v", "--verbose",
        default=False,
        action="store_true",
        help="verbose output"
    )
    parser.add_argument(
        "templates_path",
        default=default_path,
        nargs="?",
        help="path to templates folder (default: %(default)s)",
    )
    args = parser.parse_args()

    if args.verbose:
        verbose = True
        print("Verbose output", file=sys.stderr)

    main(args.templates_path)