diff --git a/packages/docs/src/pages/qwikcity/routing/default-index.mdx b/packages/docs/src/pages/qwikcity/routing/default-index.mdx index 3bd05fb3b6a..092aa903d62 100644 --- a/packages/docs/src/pages/qwikcity/routing/default-index.mdx +++ b/packages/docs/src/pages/qwikcity/routing/default-index.mdx @@ -10,14 +10,14 @@ Sometimes the route component gets too complex, and placing the whole implementa ``` - src/ - routes/ - - index.tsx # http://server/ + - index.tsx # https://example.com/ - some/ - - index.tsx # http://server/some + - index.tsx # https://server/some - path/ - - index.tsx # http://server/some/path - - _other_component.tsx # this file is ignored and not mapped to any URL. + - index.tsx # https://example.com/some/path + - _other_component.tsx # this file is ignored and not mapped to any URL because of the leading underscore. ``` ### `_` prefix -From time to time, there is a need to place files into the `src/routes` folder without them showing up on any route. In such a case use the `_` prefix to let Qwik City knows that the file is private and should not be exposed on any route. +Occasionally, there is a need to place files into the `src/routes` folder without them showing up on any route. In this case, use the `_` prefix to let Qwik City know that the file is private and should not be exposed. diff --git a/packages/docs/src/pages/qwikcity/routing/overview.mdx b/packages/docs/src/pages/qwikcity/routing/overview.mdx index 94aefefced0..a8faa1d9af3 100644 --- a/packages/docs/src/pages/qwikcity/routing/overview.mdx +++ b/packages/docs/src/pages/qwikcity/routing/overview.mdx @@ -8,18 +8,18 @@ Routing is a way to map public URLs for a site to specific components declared i ## Basic routing -In its simplest form, the URL the user sees `http://server/some/path`, will be mapped to the `some/path` component in the `src/routes` folder. +In the Qwik City router, folders map to paths. For example, if the user sees `https://example.com/some/path`, the component exported at `src/routes/some/path` (either `.mdx` or `.tsx`) will be shown. ``` - src/ - routes/ - some/ - - path.tsx # http://server/some/path + - path.tsx # https://example.com/some/path ``` ## Implementing a Component -To return HTML for a specific route you will need to implement a component. For `.tsx` file the component must be exported as `default`. (Alternatively, you can use `.mdx` extension discussed [later](/qwikcity/content/mdx).) +To return HTML for a specific route you will need to implement a component. For `.tsx` files the component must be exported as `default`. Alternatively, you can use `.mdx` extension discussed [later](/qwikcity/content/mdx). ```typescript @@ -34,11 +34,11 @@ export default component$(() => { ### `_` prefix -From time to time, there is a need to place files into the `src/routes` folder without them showing up on any route. In such a case use the `_` prefix to let Qwik City knows that the file is private and should not be exposed on any route. +Occasionally, there is a need to place files into the `src/routes` folder without them showing up on any route. In this case, use the `_` prefix to let Qwik City know that the file is private and should not be exposed. ## `@qwik-city-plan` -The route information is stored in files. This is great for developer ergonomics but not useful for creating bundles and chunks. In addition, in some environments, such as edge functions, there is no file system that can be accessed. For this reason, it is necessary to serialize the route information into a single file. This is done through the `@qwik-city-plan` import. +Qwik City stores route information in files on disk. This is great for developer ergonomics but not useful for creating bundles and chunks. Additionally, in some environments - such as edge functions - there is no file system that can be accessed. For this reason, it is necessary to serialize the route information into a single file. This is done through the `@qwik-city-plan` import. ```typescript import cityPlan from '@qwik-city-plan'; @@ -55,4 +55,4 @@ Qwik City also supports: - [Nested layouts](/qwikcity/layout/overview) - [Menus](/qwikcity/content/menu) -These are discussed later. \ No newline at end of file +These are discussed later. diff --git a/packages/docs/src/pages/qwikcity/routing/pathless.mdx b/packages/docs/src/pages/qwikcity/routing/pathless.mdx index 076f81f82d1..94946f02ab1 100644 --- a/packages/docs/src/pages/qwikcity/routing/pathless.mdx +++ b/packages/docs/src/pages/qwikcity/routing/pathless.mdx @@ -11,7 +11,7 @@ At times components get so complex that using `index.ts` is not enough, and they - routes/ - some/ - path/ - - _complex-component/ # Notice the `_` prefix - - index.tsx # http://server/some/path (`_complex-component` is not used.) - - _other_component.tsx # this file is ignored and not mapped to any URL. + - _complex-component/ # Notice the underscore prefix + - index.tsx # https://example.com/some/path (the _complex-component folder is ignored) + - _other_component.tsx # this file is ignored and not mapped to any URL because of the leading underscore. ``` diff --git a/packages/docs/src/pages/qwikcity/routing/route-parameters.mdx b/packages/docs/src/pages/qwikcity/routing/route-parameters.mdx new file mode 100644 index 00000000000..1e1fcf0b753 --- /dev/null +++ b/packages/docs/src/pages/qwikcity/routing/route-parameters.mdx @@ -0,0 +1,45 @@ +--- +title: Qwik City - Route Parameters +--- + +# Qwik City - Route Parameters + +Route Parameters are parts of the URLs that are extracted into parameters. + +Imagine that you have a page with the following URLs where `[skuId]` can be any of the thousands of products that you have in your database. It would be impractical to create a route for each product. Instead, we need to define a Route Parameter (a part of the URL) that will be used to extract the `[skuId]`. + +- `https://example.com/sku/[skuId]` + - Will match: `https://example.com/sku/1234` + - Will match: `https://example.com/sku/xyz-567` +- `http://example.com/sku/[skuId]/details` + - Will match: `https://example.com/sku/1234/details` + +``` +- src/ + - routes/ + - sku/ + - [skuId]/ + - index.js # https://example.com/sku/1234 + - details.js # https://example.com/sku/1234/details +``` + + +## Retrieving the Route Parameter from the URL + +Once we have `[skuId]` in the URL, we need a way to retrieve it. This can be done by using `useLocation()` API. + +```typescript +import { useLocation } from '@builder.io/qwik-city'; + +export default component$(() => { + const location = useLocation(); + + return ( + +

SKU

+

Pathname: {location.pathname}

+

Sku Id: {location.params.skuId}

+ + ); +}); +``` diff --git a/packages/docs/src/pages/qwikcity/routing/slugs.mdx b/packages/docs/src/pages/qwikcity/routing/slugs.mdx deleted file mode 100644 index 85c5c742a61..00000000000 --- a/packages/docs/src/pages/qwikcity/routing/slugs.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Qwik City - Routing ---- - -# Qwik City - Slugs - -Slugs are parts of the URLs that are extracted into parameters. - -Imagine that you have a page with the following URLs where `[skuId]` can be any of the thousands of products that you have in your database. It would be impractical to create a route for each product. Instead, we need to define a slug (a part of the URL) that will be used to extract the `[skuId]`. - -- `http://server/sku/[skuId]` - - Example: `http://server/sku/1234` - - Example: `http://server/sku/xyz-567` -- `http://server/sku/[skuId]/details` - - Example: `http://server/sku/1234/details` - -``` -- src/ - - routes/ - - sku/ - - [skuId]/ - - index.js # http://server/sku/1234 - - details.js # http://server/sku/1234/details -``` - - -## Retrieving the slug from the URL - -Once we have `[skuId]` in the URL, we need a way to retrieve it. This can be done by using `useLocation()` API. - -```typescript -import { useLocation } from '@builder.io/qwik-city'; - -export default component$(() => { - const location = useLocation(); - - return ( - -

SKU

-

pathname: {location.pathname}

-

skuId: {location.params.skuId}

- - ); -}); -``` \ No newline at end of file