Discussion Forum

oliver

Member

Registered: April 6, 2012

Posts: 8

Generated Route?

Anyone willing to break magic and tell me what's happening "behind the scenes" so I can utilize it?

I love this cms. It is big and powerful and scares me. I feel like I'm in Howl's castle. Thank you for your voodoo.

P.S. I'm learning php by going into cms backends and breaking things and trying to fix them so pretend you're talking to a small advanced child.

benplum

Administrator

Registered: March 30, 2012

Posts: 54

Re: Generated Route?

That's probably the best way to learn, just remember to use a fresh install when moving into production!

The generated route field type doesn't conjure any sort of black magic, it's just a simple way to build search engine friendly URLs for your module-driven routed templates.

Lets say you're building a news module and each story contains a date, title, story and image. Begin by setting up a new database table with the columns 'date', 'title', 'story', 'image' and finally 'route'. Now head to the admin and start creating your new module. At the form creation screen, set the 'route' field type to "Generated Route".

Enter the database column name of the content that should be used when generated the route, in this case it would be the story's title. Click "Save".
Now when you create a new Story the title you enter will be transformed into a URL-ready string stored in the 'route' column. For example, "Breaking News!" will become "breaking-news". The real heavy lifting is done by a the field type processor (core/admin/field-types/process/route.php) and the internal function $cms->urlify("String"). This new string can now be used by the News module to link to a detail page where you query for a particular story:

oliver

Member

Registered: April 6, 2012

Posts: 8

Re: Generated Route?

All hail benplum. Big Tree Clan is forever.

I've been poking around core and $commands sure gets around. May I ask exactly what it's doing in this instance? It's working, I just don't know why. Sure looks like black magic to me.

Thanks in advance, over-the-air hi-5!

benplum

Administrator

Registered: March 30, 2012

Posts: 54

Re: Generated Route?

The array $commands is used a lot, it's where any pieces of a URL that aren't used to find the current file in a routed template are stored. In the 'News' example above there are two files in the 'news' routed template folder:

default.php
details.php
If you were to request the URL 'http://www.example.com/news/' BigTree will render the file default.php. Requesting 'http://www.example.com/news/details/' will render details.php, with an empty $commands array. Adding your newly generated route to the URL, like 'http://www.example.com/news/details/breaking-news/', will still render details.php but the $commands array will now contain 'breaking-news' as the first item.

This covers the most standard usage, but you can also use $commands to define actions within a routed template.

oliver

Member

Registered: April 6, 2012

Posts: 8

Re: Generated Route?

This is awesome.

timbuckingham

Administrator

From: Baltimore, MD

Registered: April 2, 2012

Posts: 978

Re: Generated Route?

Just to clarify, http://www.example.com/news/details/breaking-news/ would render details.php with "breaking-news" as the first element of $bigtree["commands"].

If you want more information about the route you're currently at, you can also access $bigtree["path"] that has each URL piece included.  In http://www.example.com/news/details/breaking-news/ it would include "news", "details" and "breaking-news".

If you need to know the individual routes used to find the currently drawn file, you may use $bigtree["routed_path"] which would contain only "details".