Merge pull request #127 from contember/scopes

add scopes

docs/intro/interface.mdx

@@ -59,7 +59,7 @@ The naming of pages (and by extension, URL paths) is automated. The name given t
 For example, if you have a default export from a file named `post.tsx`, the resulting page name would be `post`. If there's a function within the same file that's exported as edit, the page name would be `post/edit`.
 
 <DocsCards>
-  <DocsCard header="Pages and routing" href="/reference/admin/pages/defining-pages">
+  <DocsCard header="Pages and routing" href="/reference/admin/pages/overview">
     <p>Understand how pages and routing works.</p>
   </DocsCard>
 </DocsCards>
@@ -135,7 +135,7 @@ export default () => (
 This is done with `redirectOnSuccess` prop where we specify link to page where user should be redirected. This is our first encounter with Contember Interface query language. Now if you create a new article you're automatically redirected to the edit page.
 
 <DocsCards>
-  <DocsCard header="All pages" href="/reference/admin/pages/defining-pages/">
+  <DocsCard header="All pages" href="/reference/admin/pages/overview/">
     <p>Explanation of all pages components.</p>
   </DocsCard>
   <DocsCard header="Query language" href="/reference/admin/data-binding/query-language">
@@ -204,4 +204,4 @@ And that's it! You have just created a simple data model and created custom inte
   <DocsCard header="Going live with your project" href="/intro/deployment">
     <p>How to deploy Contember project.</p>
   </DocsCard>
-</DocsCards>
+</DocsCards>

docs/reference/admin/pages/links.md

@@ -2,6 +2,9 @@
 title: Links and redirects
 ---
 
+Contember's `Link` component and `useRedirect` hook offer powerful navigation capabilities within your application. The `Link` component creates hyperlinks to various routes, with support for both static and dynamic route parameters. The `useRedirect` hook, on the other hand, provides programmable navigation, letting you change routes based on application logic. These tools facilitate a highly navigable and interactive user interface. Further details can be found in the main documentation
+section.
+
 ## Links
 
 The `Link` component allows you to create a link to a specific route in your application. The `to` prop specifies the destination page: 

docs/reference/admin/pages/overview.md

@@ -0,0 +1,34 @@
+---
+title: Routing and pages overview
+---
+
+
+In order to define pages in Contember Interface, you need to export function components from files in the `admin/pages` directory (or its subdirectory).
+
+In the functions exported from page components, you will usually use one of the prepared [scope](./scopes.md) or [page](./pages-components) components provided by Contember.
+
+```typescript jsx
+export default () => {
+	return (
+		<>
+			<p>Page content here</p>
+		</>
+	)
+}
+```
+
+## [Routing](./routing)
+
+Contember's routing system allows flexible structuring of your interface based on exported components from your files. You can create pages, subpages or nested pages based on your project's needs. This approach offers an intuitive way to design the navigation flow in your application. For more details, refer to the [routing section](./routing) in our documentation.
+
+## [Links and redirects](./links.md)
+
+In Contember, navigating through your application is made easy and intuitive through a range of dedicated components and hooks. These tools simplify the creation of hyperlinks, support static and dynamic parameters, and allow for programmable route changes based on your application's logic. This enables you to build a highly interactive and user-friendly interface, enhancing the overall user experience. For more specific information, please refer to the [links chapter](./links.md).
+
+## <span className="version">Interface 1.2+</span> [Scopes](./scopes)
+
+Contember provides several prepared scope components to help you quickly set up common pages in your admin panel. These scope components handle common tasks like loading and saving data, rendering form fields and displaying entity lists.
+
+## [Pages](./pages-components)
+
+While page components were once the standard for defining individual pages in Contember, they now represent a legacy approach. In new applications, we highly recommend utilizing [scopes](./scopes) for enhanced flexibility and efficiency.

docs/reference/admin/pages/defining-pages.md → docs/reference/admin/pages/pages-components.md

@@ -1,32 +1,14 @@
 ---
-title: Pages
+title: Legacy pages
 ---
 
-In order to define pages in Contember Interface, you need to export function components from files in the `admin/pages` directory (or its subdirectory).
+Contember provides several prepared page components to help you quickly set up common page types in your interface. These page components handle common tasks like loading and saving data, rendering form fields, and displaying entity lists.
 
-In the functions exported from page components, you will usually use one of the prepared page components provided by Contember. The most simple is the `GenericPage`:
+:::caution Page components are deprecated
 
-```typescript jsx
-export default () => {
-	return (
-		<GenericPage>
-			Content goes here
-		</GenericPage>
-	)
-}
-```
-
-## Routing
-
-Page names (and basically URL path) are constructed automatically. The resulting page name for the page will be determined by the file and function name, with slashes separating them. For example, the `default` export from a file named `post.tsx` will have the page name `post`, while a function exported as `edit` from a same file will be named `post/edit`. If a function is in a subdirectory, its path will also include the subdirectory name. For instance, a function named `edit` exported from
-`post/category.tsx` will have the name `post/category/edit`.
+The use of page components in Contember to define individual pages is now deemed a legacy approach. Although it served its purpose in earlier applications, it lacks the flexibility and efficiency that modern applications require. For any new developments, we strongly recommend transitioning towards using [scope components](./scopes).
 
-See how to [create links](./links.md).
-
-
-## Pages
-
-Contember provides several prepared page components to help you quickly set up common page types in your admin panel. These page components handle common tasks like loading and saving data, rendering form fields, and displaying entity lists.
+:::
 
 ### GenericPage
 
@@ -35,6 +17,7 @@ The most basic page component in Contember. It simply renders its children insid
 For more details on these props and their usage, see the [API reference](../api/v1.2/Pages/GenericPage.mdx).
 
 #### Example how to use GenericPage
+
 ```typescript jsx
 import { GenericPage } from '@contember/admin'
 
@@ -90,6 +73,7 @@ The `redirectOnSuccess` prop allows you to specify a target page to navigate to
 For more details on EditPage props and their usage, see the [API reference](../api/v1.2/Pages/EditPage.mdx).
 
 #### Example how to use EditPage
+
 ```typescript jsx
 import { EditPage } from '@contember/admin'
 
@@ -120,6 +104,7 @@ A `rendererProps` prop can be used to modify the layout of the page, such as add
 For more details on DetailPage props and their usage, see the [API reference](../api/v1.2/Pages/DetailPage.mdx).
 
 #### Example how to use DetailPage
+
 ```typescript jsx
 import { DetailPage, Field } from '@contember/admin'
 
@@ -158,7 +143,6 @@ export default () => {
 }
 ```
 
-
 ### DataGridPage
 
 `DataGridPage` is a page component that wraps a `DataGrid` component. It allows you to display a list of specified entities in a more advanced way, with features such as pagination and filtering.
@@ -194,18 +178,17 @@ export default () => {
 }
 ```
 
-
 ### MultiEditPage
 
 `MultiEditPage` is a page component in Contember that allows you to edit multiple entities on a single page. It is essentially a wrapper around the `Repeater` component, which means that you can use it to add, remove, and sort items within the page.
 
-To use` MultiEditPage`, you must specify the entities you want to edit using the `entities` prop (of type [qualified entity list](../data-binding/query-language#qualified-entity-list)). To control the behavior of the `Repeater`, you can pass props such as `sortableBy` through the `rendererProps` prop of `MultiEditPage`. This will allow you to specify which fields should be used to sort the items in the `Repeater`. You can also pass custom props to modify the layout of the page using the `rendererProps` prop.
+To use` MultiEditPage`, you must specify the entities you want to edit using the `entities` prop (of type [qualified entity list](../data-binding/query-language#qualified-entity-list)). To control the behavior of the `Repeater`, you can pass props such as `sortableBy` through the `rendererProps` prop of `MultiEditPage`. This will allow you to specify which fields should be used to sort the items in the `Repeater`. You can also pass custom props to modify the layout of the page using
+the `rendererProps` prop.
 
 `MultiEditPage` should only be used for editing a small number of entities, as it does not support advanced features such as pagination or filtering.
 
 For more details on MultiEditPage props and their usage, see the [API reference](../api/v1.2/Pages/EditPage.mdx).
 
-
 #### Example how to use MultiEditPage
 
 ```typescript jsx

docs/reference/admin/pages/routing.md

@@ -0,0 +1,89 @@
+---
+title: Routing
+---
+
+Page names (and basically URL path) are constructed automatically. The resulting page name for the page will be determined by the file and function name, with slashes separating them. For example, the `default` export from a file named `post.tsx` will have the page name `post`, while a function exported as `edit` from a same file will be named `post/edit`. If a function is in a subdirectory, its path will also include the subdirectory name. For instance, a function named `edit` exported from
+`post/category.tsx` will have the name `post/category/edit`.
+
+## Routing options
+
+To define pages in Contember, you can use different exports. Each function exported from a page component defines a separate page. If you're looking for more advanced routing setups, understanding how to leverage different exports will be beneficial.
+
+### Default Export
+
+The `default` export is used to create the base page. It is given the name of the file.
+
+```typescript jsx
+export default () => {
+	return (
+		<>
+			<p>Post overview here</p>
+		</>
+	)
+}
+```
+
+In the above example, if this was the `default` export from a file named `post.tsx`, the page name would be `post`.
+
+### Named Exports
+
+Named exports allow you to define subpages. The name of the function you export will be added to the URL path after a slash. For example:
+
+```typescript jsx
+export const Edit = () => {
+	return (
+		<>
+			<p>Edit post here</p>
+		</>
+	)
+}
+```
+
+In this case, if the `Edit` function was exported from a file named `post.tsx`, the page name would be `post/edit`.
+
+### Exports from Subdirectories
+
+If your function is within a subdirectory, its path will also include the subdirectory name. This allows you to further nest your pages and organize your interface. For example, if you have a function named `Edit` exported from `post/category.tsx`, the page name would be `post/category/edit`.
+
+```typescript jsx
+export const Edit = () => {
+	return (
+		<>
+			<p>Edit post category here</p>
+		</>
+	)
+}
+```
+
+### Multiple Named Exports from a Single File
+
+Building upon the routing options provided by Contember, you can define multiple pages from a single file using multiple named exports.
+
+Consider the following example from a file named `post.tsx`, where we're exporting two different components: `Create` and `Edit`.
+
+```typescript jsx
+// This is the Create Post page
+export const Create = () => {
+	return (
+		<>
+			<p>Here is where you can create a new post.</p>
+		</>
+	)
+}
+
+// This is the Edit Post page
+export const Edit = () => {
+	return (
+		<>
+			<p>Here is where you can edit an existing post.</p>
+		</>
+	)
+}
+```
+
+With this setup, you're defining two new pages within your Contember interface:
+
+1. `post/create` - This page is rendered when the `Create` component is called.
+2. `post/edit` - This page is rendered when the `Edit` component is called.
+
+The names used for the exports, in this case, `Create` and `Edit`, will be reflected in the URL path for their respective pages. It's beneficial to use descriptive names as they give the user an understanding of the page's content or function.