diff --git a/Resources/doc/usage.rst b/Resources/doc/usage.rst index cb04cc9..06dbb6a 100644 --- a/Resources/doc/usage.rst +++ b/Resources/doc/usage.rst @@ -76,6 +76,98 @@ Then within your JavaScript development you can use: Routing.setRoutingData(routes); Routing.generate('rep_log_list'); +Exposing Routes +--------------- + +.. important:: + + Before generating URIs for routes in JavaScript, you must expose the routes. Routes are not automatically available in the frontend; they need to be explicitly marked for exposure using one of the methods below. Without exposing routes, the ``Routing.generate()`` method will not work. + +There are several ways to expose routes: + +**1. Using Route Options:** + + Add ``options: ['expose' => true]`` to your route definition. + + **With attributes:** + + .. code-block:: php + + #[Route(path: '/foo/{id}/bar', name: 'my_route', options: ['expose' => true])] + + **With YAML:** + + .. code-block:: yaml + + my_route: + path: /foo/{id}/bar + options: + expose: true + +**2. Configuration in config.yml:** + + Configure a list of routes to expose: + + .. code-block:: yaml + + fos_js_routing: + routes_to_expose: [route_1, route_2] + + You can use regular expressions to match multiple routes: + + .. code-block:: yaml + + fos_js_routing: + routes_to_expose: ['^api_.*'] + +**3. Preventing Exposure:** + + To explicitly prevent a route from being exposed, set ``expose: false``: + + .. code-block:: yaml + + my_secret_route: + path: /admin + options: + expose: false + +For internationalized routes (e.g., with JMSI18nRoutingBundle), ensure the exposed routes match the locale-prefixed names or use patterns. + +**4. Exposing Routes in API Platform:** + + If you are using `API Platform`_, you can expose routes using the configuration method with regular expressions, or by setting options on specific operations. + + **Using Configuration:** + + .. code-block:: yaml + + fos_js_routing: + routes_to_expose: ['api_.*'] + + This will expose all routes starting with 'api_'. You can use more specific patterns like ``['api_jobs_.*', 'api_types_.*']``. + + **Using Operation Options:** + + For specific operations, add ``'expose' => true`` to the options: + + .. code-block:: php + + #[ApiResource( + operations: [ + new GetCollection( + options: ['expose' => true] + ) + ] + )] + class MyEntity {} + + To find the exact route names generated by API Platform, use the command: + + .. code-block:: bash + + bin/console debug:router + +.. _`API Platform`: https://api-platform.com/ Generating URIs ---------------