docs: qwik-cty docs fix ups (#1002)

QwikDev · Aug 10, 2022 · 33eac19 · 33eac19
1 parent 84fc87b
commit 33eac19
Show file tree

Hide file tree

Showing 16 changed files with 193 additions and 155 deletions.
diff --git a/packages/docs/src/routes/qwikcity/api/use-content/index.mdx b/packages/docs/src/routes/qwikcity/api/use-content/index.mdx
@@ -4,7 +4,7 @@ title: Qwik City - useContent()
 
 # Qwik City - `useContent()`
 
-Use `useContent()` function retrieves the nearest content information for the current route. The returned object includes:
+The `useContent()` function retrieves the nearest content information for the current route. The returned object includes:
 
 ```ts
 headings: ContentHeading[] | undefined;

diff --git a/packages/docs/src/routes/qwikcity/api/use-document-head/index.mdx b/packages/docs/src/routes/qwikcity/api/use-document-head/index.mdx
@@ -4,9 +4,9 @@ title: Qwik City - useDocumentHead()
 
 # Qwik City - `useDocumentHead()`
 
-Use `useDocumentHead()` to retrieve the document head metadata.
+Use the `useDocumentHead()` function to retrieve the document head metadata.
 
-`useDocumentHead()` retrieves `DocumentHead` object that will allow you to:
+`useDocumentHead()` retrieves a `DocumentHead` object that will allow you to:
 
 - update the `title` in `<head>`.
 - update the `meta` tags in `<head>`.

diff --git a/packages/docs/src/routes/qwikcity/api/use-location/index.mdx b/packages/docs/src/routes/qwikcity/api/use-location/index.mdx
@@ -4,7 +4,16 @@ title: Qwik City - useLocation()
 
 # Qwik City - `useLocation()`
 
-Use `useLocation()` to retrieve the current location (URL).
+Use the `useLocation()` function to retrieve a `RouteLocation` object for the current location.
+
+```tsx
+export interface RouteLocation {
+  readonly params: RouteParams; // Record<string,string>
+  readonly href: string;
+  readonly pathname: string;
+  readonly query: Record<string, string>;
+}
+```
 
 The return value of `useLocation()` is similar to `document.location`, but it is safe to use on the server where there is no global `location` object.
 

diff --git a/packages/docs/src/routes/qwikcity/content/component/index.mdx b/packages/docs/src/routes/qwikcity/content/component/index.mdx
@@ -28,7 +28,8 @@ export default component$(() => {
 
 ## Importing other components
 
-You can build complex views by composing multiple components within each other. To do that import other components like so: `import Heading from './path/to/component/heading';` to use it in the current component.
+You can build complex views by composing multiple components within each other. To do that import other components into your index.tsx file.
+
 ```
 - src/
   - components/
@@ -37,10 +38,10 @@ You can build complex views by composing multiple components within each other.
     - some/           
       - path/
         - index.tsx              # https://example.com/some/path
-        - _sub_component.tsx
+        - sub_component.tsx
 ```
 
-Inside `index.tsx` you can create a component that is exported as `default` export. Content is created by writing a template with [JSX](https://reactjs.org/docs/introducing-jsx.html)-Syntax. Every component-Function returns the template that should be rendered on the screen. If you want to learn more about the component anatomy, please see [components documentation](/docs/components/overview).
+Inside `index.tsx` you can create a component that is exported as `default` export. Content is created by writing a template with [JSX](https://reactjs.org/docs/introducing-jsx.html)-Syntax. Every component-function returns the template that should be rendered on the screen. If you want to learn more about the component anatomy, please see [components documentation](/docs/components/overview).
 The following component will be rendered at `https://example.com/some/path` according to the directory-structure, we have set up above. 
 
 ```typescript

diff --git a/packages/docs/src/routes/qwikcity/content/mdx/index.mdx b/packages/docs/src/routes/qwikcity/content/mdx/index.mdx
@@ -7,6 +7,7 @@ title: Qwik City - MDX
 An alternative way to author content is using `.mdx` files ([Markdown JSX](https://mdxjs.com/)). These files are authored as Markdown, but they are compiled down to Qwik components. In addition to Markdown syntax, `.mdx` files can also refer to other components.
 
 Let's assume you have your routes set up like this:
+
 ```
 - src/
   - routes/
@@ -67,4 +68,8 @@ export const Counter = component$(() => {
     </button>
   );
 });
-```
+```
+
+**Note**: A key difference with Qwik City and many current metaframeworks is directory-based routing. Every route needs to be defined as `a-directory/index.(tsx,ts,js,jsx,md,mdx)`.
+
+In other metaframeworks you're used to `about.mdx` will render a route `http://example.com/about`. However, this will not work in Qwik City. You must rename the file to `about/index.mdx` for Qwik City to know to render it.
diff --git a/packages/docs/src/routes/qwikcity/content/menu/index.mdx b/packages/docs/src/routes/qwikcity/content/menu/index.mdx
@@ -4,10 +4,10 @@ title: Qwik City - Menu
 
 # Qwik City - Menu
 
-Menus allow you to describe the site navigation structure in a simple declarative way. Menus come in two parts:
+Menus allow you to describe the site navigation structure in a simple declarative way. Menus come in two steps:
 
-1. A `menu.md` file that contains the menu structure for the directory it's in.
-2. A `useContent()` function that can be used to retrieve the menu structure in a template to be used for rendering.
+1. Defining a `menu.md` file that contains the menu structure for the directory it's in.
+2. Using the `useContent()` function to retrieve the menu structure in a template for rendering. [Read more here](/qwikcity/api/use-content)
 
 ## File Structure
 

diff --git a/packages/docs/src/routes/qwikcity/endpoint/overview/index.mdx b/packages/docs/src/routes/qwikcity/endpoint/overview/index.mdx
diff --git a/packages/docs/src/routes/qwikcity/menu.md b/packages/docs/src/routes/qwikcity/menu.md
@@ -10,8 +10,12 @@
 
 - [Overview](routing/overview/index.mdx)
 - [Index](routing/default-index/index.mdx)
-- [Route Parameters](routing/route-parameters/index.mdx)
 - [Pathless Dirs](routing/pathless/index.mdx)
+- [Route Parameters](routing/route-parameters/index.mdx)
+- [Retrieving Data](endpoint/data/index.mdx)
+- [Modifying Data](endpoint/modify/index.mdx)
+- [Redirects](endpoint/redirects/index.mdx)
+- [Error Responses](endpoint/error-responses/index.mdx)
 
 ## Layout
 
@@ -26,13 +30,6 @@
 - [MDX](content/mdx/index.mdx)
 - [Menu](content/menu/index.mdx)
 
-## Data Endpoints
-
-- [Overview](endpoint/overview/index.mdx)
-- [Retrieving Data](endpoint/data/index.mdx)
-- [Modifying Data](endpoint/modify/index.mdx)
-- [Non 200 Responses](endpoint/non-200/index.mdx)
-
 ## Head
 
 - [Title](head/title/index.mdx)

diff --git a/...c/routes/qwikcity/endpoint/data/index.mdx → ...rc/routes/qwikcity/routing/data/index.mdx b/...c/routes/qwikcity/endpoint/data/index.mdx → ...rc/routes/qwikcity/routing/data/index.mdx
@@ -18,11 +18,11 @@ The first step is to structure the directories and files so that we can create t
         - index.tsx     # https://example.com/product/1234
 ```
 
-## Implement Endpoint
+## Implement onGet
 
-An endpoint is a `onGet` function that retrieves data (typically from a database, or other stores.) The retrieved data can be returned directly as JSON or used as an input to the component to render HTML. The `onGet` function receives the `params` to extract the parameters used to do data lookup. 
+In a "page" endpoint context, an `onGet` function retrieves data (typically from a database, or other stores). The retrieved data can be returned directly as JSON or used as an input to the component to render HTML. The `onGet` function receives the `params` to extract the parameters used to do data lookup. 
 
-The `onGet` function returns the product data.
+In this example the `onGet` function returns the product data that is used inside of our component with the `useEndpoint()` function.
 
 ```typescript
 // File: src/routes/product/[skuId]/details.js
@@ -44,7 +44,7 @@ export const onGet: RequestHandler<EndpointData> = async ({ params }) => {
 };
 ```
 
-## Using Endpoint in Component
+## Using onGet in a Component
 
 An endpoint `onGet` function retrieves data and makes it available to the component using `useEndpoint()`. 
 
@@ -83,3 +83,4 @@ export default component$(() => {
 6. You may use `typeof onGet` to keep your `onGet` function and `useEndpoint()` types in sync. Qwik City is smart enough to determine the types for you. 
 
 All of the above is done to abstract the data access from the component in a way that results in correct behavior on both the server and the client.
+
diff --git a/packages/docs/src/routes/qwikcity/routing/default-index/index.mdx b/packages/docs/src/routes/qwikcity/routing/default-index/index.mdx
diff --git a/packages/docs/src/routes/qwikcity/routing/endpoints/index.mdx b/packages/docs/src/routes/qwikcity/routing/endpoints/index.mdx
@@ -0,0 +1,25 @@
+---
+title: Endpoints
+---
+
+# Endpoints
+
+As we discussed previously, an endpoint in Qwik City is `folders + an index`.
+
+For `index.md` and `index.mdx` files ((more here)[/qwikcity/content/mdx]), these endpoints will just return HTML and nothing else. For this section, we will focus on index.ts and index.tsx endpoints.
+
+## Page & Data Endpoints
+
+In Qwik City, "Page" and "Data" endpoints are the same except for one difference: a page exports a default component$ to render html. To learn about defining a page component, you can (read more here)[qwikcity/content/component]. A quick example would look like this:
+
+```typescript
+// File: src/routes/some/path/index.tsx
+import { component$ } from '@builder.io/qwik';
+
+// Notice the default export
+export default component$(() => {
+  return <h1>Hello World!</h1>;
+});
+```
+
+In the following sections, we'll look at the other things we can do within endpoint files.
diff --git a/packages/docs/src/routes/qwikcity/routing/error-responses/index.mdx b/packages/docs/src/routes/qwikcity/routing/error-responses/index.mdx
@@ -0,0 +1,70 @@
+---
+title: Qwik City - Non-200 Response
+---
+
+# Qwik City - Non-200 Response
+
+At times it is necessary to respond with HTTP status codes other than 200. In such cases, response handler is the place to determine what status code should be returned.
+
+Assume this file layout.
+```
+- src/
+  - routes/
+    - product/
+      - [skuId]/
+        - index.tsx     # https://example.com/product/1234
+```
+
+## 404 - Not Found
+
+Let's say that a user does a request to an invalid `skuId` such as `https://example.com/product/999`. In this case, we would like to return a 404 HTTP status code and render a 404 page. The place where we determine if the request is valid or not is in the request handler by looking into the database. Even if the response is non-200, the component still gets a chance to render a page (Except in the redirect case.)
+
+```typescript
+// File: src/routes/product/[skuId]/index.tsx
+import { component$ } from '@builder.io/qwik';
+
+type EndpointData = ProductData | null;
+
+interface ProductData {
+  skuId: string;
+  price: number;
+  description: string;
+}
+export const onGet: RequestHandler<EndpointData> = async ({ params, response }) => {
+  const product = await loadProductFromDatabase(params.skuId);
+
+  if (!product) {
+    // Product data not found
+    // but the data is still given to the renderer to decide what to do
+    response.status = 404
+    return null
+  } else {
+    // ...
+  }
+};
+
+export default component$(() => {
+  const resource = useEndpoint<typeof onGet>(); //equivalent to useEndpoint<EndpointData>
+
+  if (resource.state=='resolved' && !resource.resolved) {
+    // Early return for 404
+    return <div>404: Product not found!!!</div>
+  }
+
+  // Normal rendering
+  return (
+    <Resource 
+      resource={resource}
+      onPending={() => <div>Loading...</div>}
+      onError={() => <div>Error</div>}
+      onResolved={() => (
+        <>
+          <h1>Product: {product.productId}</h1>
+          <p>Price: {product.price}</p>
+          <p>{product.description}</p>
+        </>
+      )}
+    />
+  );
+});
+```
diff --git a/...routes/qwikcity/endpoint/modify/index.mdx → .../routes/qwikcity/routing/modify/index.mdx b/...routes/qwikcity/endpoint/modify/index.mdx → .../routes/qwikcity/routing/modify/index.mdx
@@ -4,9 +4,7 @@ title: Qwik City - Modify Data
 
 # Qwik City - Modify Data
 
-> NOTE: Not yet implemented.
- 
-Just like routes can define a way to fetch data, they can also define HTTP verbs to modify data. These are `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. We have already discussed the `GET` verb in the previous section. Each of these verbs has a corresponding `on___` method such as `onGet`, `onPost`, `onPut`, `onPatch`, and `onDelete`.
+Endpoints can define a way to fetch data and they can also define HTTP verbs to modify data. These are `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. We have already discussed the `GET` verb in the previous section. Each of these verbs has a corresponding `on___` method such as `onGet`, `onPost`, `onPut`, `onPatch`, and `onDelete`.
 
 ```typescript
 // File: src/routes/product/[skuId]/index.tsx