When thinking about the architecture of a Syntax site, remember that just because someone may want a list of documents or events, it doesn't mean that ginning up a module and plunking it on the main navigation is the right answer. It has a lot of drawbacks:
- Your site navigation is not dynamic. This starts to resemble the Bad Old Days of static HTML. Once you pick a term, you're stuck with it. Never underestimate the psychological comfort that is had by having the option to change something, even if it's a bad idea to do it.
- Your page title is similarly static. This further resembles the Bad Old Days. It helps to get a project out the door when you can say "if you don't like it, you can change it." Again, this is true even if you've done killer information architecture and selected culturally appropriate and tested terms.
- You have limited options for dynamic text on the main listing page. You can embed a section call within the template through
F1CMS::module() (more on the power of that later), but that requires modifying not only the list template but also creating a custom template for each hidden section so it doesn't start listing other content items. Plus it turns your Section Navigation admin area into a nest of hidden sections that aren't really sections but content items. You could introduce a datatype that will function in that capacity, but that creates its own complications. How do you decide where each item will be published? Will you build its own module just for display?
Fortunately a much better option exists. You'll still have to create a custom section template, but it will be a logical, functional, and non-hidden section.
Embed a Module in a Section
Create your module as you would like it to appear, and make sure that the links to sort and search are all to the current URL in a nice, portable manner (such as $_SERVER['REQUEST_URI'] or some such). Make sure you don't build out a completely functional page--build the list function as if it were going to appear in a standard section--because it will.
Now create a section template. Since you'll want most of the functionality, I usually start by copying private/templates/section.tpl to something like private/templates/section/my_module.tpl. Edit it, and look at all the code that loops through the grouping a section may use and calls the general module to display each.
You'll want to look at that call to the general module, because you're going to change that to read 'module'=>'my_module'. Then remove the loops for the grouping. Make sure the action is list or whatever you set the default action to.
Now go to Context (our name for the admin application) and create a section with the URL ID my_module. Fill out the section normally, even give it a nice default grouping if you like--it won't matter what it's set to, as you've made sure the template will ignore it. Save your changes, and don't forget to make it a child of _home.
Now go back to the public area and enter the URL /section/my_module/. Voila! Your nifty section title and descriptive text appear, followed by the list function you created in your module. Unless you coded it into your module, the datatype(s) you have associated with that module won't even need to be published to that section. They'll just appear the same as if you'd gone to /content/my_module/list/ but the URL is a little prettier and your administrators will be a whole lot happier.
Caveat: Your administrator can do much damage if they change the URL ID or delete the section. Unfortunately, there's no useful way to restrict access to it for anybody who has the permission to be editing sections in the first place. So you'll need a bit of training of your administrative users so they don't mess themselves up.
