Modern Router

Overview: What does the Modern Router do?

The Modern Router was designed to generate clearer and more consistent SEF URLs. An interface was created to produce identical URL structures across different components. It does this by:

• using menu items as the basis for URL segments,
• using category hierarchies to form segments,
• optionally removing IDs,
• and appending unresolved parameters as query parameters.

The goal: clean URLs such as /gallery/images/my-image.html instead of complex query strings.

Requirements and Router Settings

Enabling the Modern Router

In Joomla! under System → Global Configuration → Site → Search Engine Optimisation (SEO), routing can be enabled using "Search Engine Friendly URLs". Optionally, the suffix (e.g. *.html) can be enabled using "Add Suffix to URL". Additionally, "Remove IDs from URLs" can be enabled in the component settings.

Important Structural Elements

• Menu items define the main URL segments.
• Categories provide additional optional segments to represent deeper structural nesting.
• Aliases determine how the final URL segments are displayed.

Step by step: How a SEF URL is generated in Joomla!

Main Menu Item (Root View)

The top-level menu item, for example Gallery with the alias gallery, generates the first URL segment: /gallery/.

Submenu Items

Together with a menu item for the image list, for example alias images, this becomes: /gallery/images/.

Categories

A category with the title "Landscapes" and the alias landscapes could add another segment.

Items (e.g. images, articles)

A detail view of an image with ID 1 and alias testimage would become for example:
/gallery/images/1-testimage.html.

What happens if no matching menu item exists?

If a menu item is missing, the router attempts to:

• generate fallback URL structures,
• append unresolved parameters as query parameters,
• or potentially produce 404 errors (stricter detection).

Result: URLs may appear longer or less clean, for example:

/component/joomgallery/image/5-bird?format=raw&type=detail&Itemid=5

What actually happened here?

The router attempted to find a menu item matching the image with ID: 5. Since no suitable menu item was found, the router chose to use the fallback URL for image URLs: /component/joomgallery/image. After this, it was able to successfully generate the segment for the specific image: 5-bird. All other parts of the URL could not be resolved by the router, so they were appended at the end as query parameters.

• Itemid is the parameter of the menu item used. In this case the router selected a randomly available menu item because it could not find a matching JoomGallery menu item. This random menu item is listed here.
• format the requested format is appended if "Add Suffix to URL" is not enabled in the Joomla! global configuration.
• type specifies which image type should be displayed.

Available Menu Items in JoomGallery

Another important element is how the relationships between the different possible view types and menu item types are defined. These relationships are fixed within the respective router. JoomGallery allows different routers to be selected in order to generate the desired URLs based on these relationships. JoomGallery provides the following routers with the following relationships by default:

Modern Router (Default)

• Gallery view
• Category view (nestable)
• Image list
• Single image
• Category list
• User: Panel
• User: Categories
• User: Category
• User: Images
• User: Image
• User: Upload

Modern Router (JG3 Variant)

• Gallery view
• Category view (nestable)
• Single image
• Image list
• Category list
• User: Panel
• User: Categories
• User: Category
• User: Images
• User: Image
• User: Upload

Guidelines for targeted URL design

Menu items are the key to clean URLs. Only with a well-structured and carefully planned menu item structure can you generate the desired URL structure. Some components, such as JoomGallery, create a set of menu items during installation that already produce good URLs for most use cases.

To generate your desired URLs, the correct menu items must therefore be created in combination with the appropriate router.

• Define a main menu item e.g. gallery, first segment
• Create submenu items e.g. images, categories.
• Structure categories with unique aliases: landscapes, portraits.
• Use clear, unique aliases for images e.g. testimage.
• Check router settings
• Test resulting URLs
• Minimise parameters by resolving them through menu items or category aliases.

Notes on aliases

For categories and especially images it is very important that unique aliases exist. This is particularly important when "Remove IDs from URLs" is enabled. The router's task is to determine the corresponding element (image or category) solely from the available segments. To do this it searches the database for the element with the corresponding alias. Ideally only one element exists with that alias. Let's look at an example:

index.php/gallery/images/5-airplane-2.html

This image was uploaded into a category in which an image with the alias airplane already existed. Therefore JoomGallery automatically appended -2 to the alias.

Modern Router – Default

The default router creates the complete image segment using the pattern ID-ALIAS, resulting in 5-airplane-2. When converting back, the router knows from the preceding segment that this is an image segment. It therefore needs to search for an image. In this case it is simple: a number appears before the first hyphen, which the router immediately interprets as the image ID.

If "Remove IDs from URLs" is enabled, the ID is omitted and the image segment is output using the pattern ALIAS. The router then searches the image table in the database for an image with the alias airplane-2. It selects the first search result it finds.
Problems
If "Remove IDs from URLs" is enabled, the following problems may occur:

• Alias not unique: If multiple images exist with the same alias, the router may select the wrong image during the search. As a result, the wrong image may be displayed or linked.
• Alias starting with a number: If the alias begins with a number followed by a hyphen, for example 2012-berlin, the router automatically interprets 2012 as the image ID. The image with ID=2012 will then be displayed or linked instead of the intended image with alias=2012-berlin.

Modern Router – JG3 Variant

This router works largely in the same way. However, here an image path is preceded by several category segments. These help the router locate the correct image because the search is restricted to a specific category. This reduces the risk of the wrong image being found.

Examples

 Component;View type;Item slug (article/image);Category structure;Output format;Menu structure

The query parameters component and view type are only used internally by the router and never produce a URL segment, meaning they are effectively "consumed" by the router. All other available query parameters are processed according to the principle described above. Any parameters that cannot be converted into segments are appended at the end of the URL as query parameters.

Example 1: JoomGallery (Modern Router – Default)

index.php?option=com_joomgallery&view=image&id=12:testimage&catid=2&format=html&Itemid=42

index.php/gallery/images/12-testimage.html?catid=2

• gallery → alias of the main menu item of type "Gallery View"
• images → alias of the menu item of type "Image List" as a child of gallery
• 12-testimage → item ID + alias
• ?catid=1 → parameter that could not be resolved through menu/category and is therefore appended as a query parameter.

In this example I deliberately kept the category as a query parameter, because this may occur with migrated JoomGallery content. The JG3 router behaved differently and required the category information. Content created directly in JG4 does not include this query parameter, so the resulting URL appears cleaner without "catid=2" at the end.

Example 2: JoomGallery (Modern Router – JG3 Variant)

index.php?option=com_joomgallery&view=image&id=12:testimage&catid=2&format=html&Itemid=42

index.php/gallery/nature/12-testimage.html

• gallery → alias of the main menu item of type "Gallery View"
• nature → alias of the category with ID 2
• 12-testimage → item ID + alias

Example 3: Articles (Modern Router)

index.php?option=com_content&view=article&id=23:minas-tirith&catid=66&Itemid=42

index.php/lotr-wiki/cities-in-middleearth/minas-tirith

• lotr-wiki → alias of the main menu item of type "Category Blog"
• cities-in-middleearth → alias of the category with ID 66
• minas-tirith → item alias (the setting "Remove ID" is enabled here)

Source: https://manual.joomla.org

Sources

• Pull Request JoomGallery (JG4) – Modern Router https://github.com/JoomGalleryfriends/JG4-dev/pull/265
• Joomla Documentation – New Routing System https://docs.joomla.org/J3.x:New_Routing_System/de
• Joomla – Supporting SEF URLs in Components https://docs.joomla.org/J3.x:Supporting_SEF_URLs_in_your_component/en
• Modern Router Notes https://quantumwarp.com/kb/articles/30-joomla/962-my-joomla-modern-router-notes
• Joomla Manual – Routing https://manual.joomla.org/docs/next/general-concepts/routing/