Customizing your MVC Routes

One of the best things about using Agility in your .NET website, is that you have full control over how and when Agility will render a page.

In a typical setup, there is an Agility wildcard route setup in the RouteConfig.cs file of the MVC project. 

//Agility Wildcard Route for Default Page Routing
routes.MapRoute("Agility", "{*sitemapPath}", 
    new { controller = "Agility", action = "RenderPage" }, 
    new { isAgilityPath = new Agility.Web.Mvc.AgilityRouteConstraint() });

This will register Agility.Web to check each incoming URL and match it to a page as defined in Agility and subsequently loop through each Content Zone and render each Module within it.

Mixing Agility and Custom Routing

Within your MVC project, you can have as many routes as you see fit. You can have the Agility wildcard route in addition to any number of other routes. You can customize the order in which the routes are evaluated as well so you can have the Agility wildcard route last to only pickup routes that aren't already defined.

//Custom Route 
routes.MapRoute(
     name: "Default",
     url: "{controller}/{action}/{id}",
     defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional }
);

//Agility Wildcard Route for Default Page Routing
routes.MapRoute("Agility", "{*sitemapPath}", 
     new { controller = "Agility", action = "RenderPage" },
     new { isAgilityPath = new Agility.Web.Mvc.AgilityRouteConstraint() });

You don't even need to have the Agility wildcard route in place if you don't want it. This means, you can take an existing, mature website that may have numerous static routes defined in the RouteConfig.cs and decide that you don't want Agility to do any routing and instead only be responsible for rendering partial content on your existing pages.

Using Agility to Render Partial Content on Existing Custom (non Agility) Pages

You may have some existing pages that are not powered by Agility and rather than converting the whole page's functionality to be a Module or a series of Modules, you have the freedom to keep that existing page and its route in-place and have Agility only control part of that page. You can do this by pro-grammatically rendering the content of an Agility page within the layout of an existing .cshtml (Razor) page.

Setting up Partial Rendering

1. Configure your Routing - Ensure the Agility wildcard route is moved in the RouteConfig.cs so it is evaluated AFTER your custom route. You need to ensure that your custom routes are evaluated before falling back on Agility routing. If Agility wildcard routing is not required at all, this route can be removed entirely (warning: this will likely mean that editors cannot create new pages in Agility without your code somehow handling the routing and/or rendering for these pages).

2. Create a Child Controller ActionResult - You'll need a Controller and an ActionResult to be able to pro-grammatically render an Agility page. Add the following code:

   [ChildActionOnly]
   public ActionResult RenderPartialPage(string path)
   {
          return new AgilityViewActionResult(path);
   }
   

3. Add Code to Execute the Child Controller ActionResult - In your custom page, add the following code in your .cshtml file where you want the content of the rendered page to appear:

   <div class="agility-page-content">
          @Html.Action(
                  "RenderPartialPage", 
                  "AgilityPartial", 
                  new { path = "~/page-path-to-render-inline" } 
           )
   </div>
   

4. Optional: Create a new Agility Page Template to use for Inner Pages - By default, when you render an Agility page it will try to render the full page layout including the master page. This may result in your custom page loading its own header/footer and your inner page also loading a header/footer. To workaround this, it is recommended to create a specific Agility Page Template that does NOT render the full master layout and only its own markup and that of its child modules. Create a new Page Template, add your respective module zones and be sure to add the following within your template code at the top of the file:

   @{ 
          Layout = null;
   }
   

   Next, create a page in your page tree that uses this new template you've just created. Add some content so you can test it appropriately.

5. Test Functionality - You should now be able to make a request to your custom routed page, and watch as it renders an Agility page inline within your template.