-
Notifications
You must be signed in to change notification settings - Fork 182
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(docs): add pagination tutorial and related files #196
feat(docs): add pagination tutorial and related files #196
Conversation
feat(pagination): add layout, page, and markdoc files for pagination tutorial feat(pagination): add step-1, step-2, step-3, step-4, step-5, and step-10 markdoc files The changes include adding a new page for the pagination tutorial in the docs section. Additionally, the necessary layout, page, and markdoc files are added for each step of the pagination tutorial. This allows users to learn about pagination in a React app using the Appwrite backend. The tutorial covers topics such as setting up the project, creating a database, initializing the Appwrite SDK, and seeding the database with data. feat(docs): add new files for pagination tutorial steps 6 and 7 The changes include the addition of two new files: `src/routes/docs/tutorials/pagination/step-6/+page.markdoc` and `src/routes/docs/tutorials/pagination/step-7/+page.markdoc`. These files contain the code and instructions for implementing pagination in a React application using Appwrite backend. The `step-6` file adds the initial code for displaying tasks using context and a custom hook, while the `step-7` file adds the implementation for offset pagination and the UI components for navigating through the dataset. feat(docs): add tutorial pages for implementing cursor pagination and discussing trade-offs feat(docs): add page for implementing cursor pagination in a React app using Appwrite backend A new tutorial page has been added to the documentation that explains what cursor pagination is and how to implement it in a React app using the Appwrite backend. The page provides an overview of cursor pagination and its benefits, and includes code examples for implementing cursor pagination using Appwrite's `listDocuments()` command. feat(docs): add page for discussing the trade-offs between offset pagination and cursor pagination A new tutorial page has been added to the documentation that discusses the trade-offs between offset pagination and cursor pagination. The page provides a comparison table highlighting the pros and cons of each pagination method, and offers guidance on when to use each method based on different application requirements. The page also includes a recap section summarizing the key points to consider when choosing a pagination method in Appwrite.
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
This amazing, I'll check it out soon! |
</div> | ||
); | ||
} | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What if we also add an alternative cursor pagination that shows both cursor before and cursor after to have next and previous page?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great idea, I can have a "load previous" above the tasks to utilize the cursor before. Also I'm a little afraid that the tutorial may confuse the user by not pointing out that offset pagination and cursor pagination setup are just showing the app using one or the other, not both. I think you mentioned that was a third method that a user could use.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, let's clearly point it out, and trust the user to read carefully. 😄
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added the "load previous" button above the todos.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@timDeHof what do you think to have the same buttons as the offset?: aligned at the bottom and with the text back and forward.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep, @timDeHof doing it like this:
Under implementation discuss the different forms it could take:
- Just a load more button like many apps
- Navigation buttons.
You can show both methods in the same page using a tabs component like the one here:
https://appwrite.io/docs/products/databases/collections
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gewenyu99 Thanks for the idea. It made me think of other ways of using the tabs components in the tutorial. Here is what I was thinking on "adding todos" page, the different files could combine as seen in the image below:
Also on "environment setup" page, Since the "seeding collection" steps is combined allowing it to be the only thing on the page as seen in the image below:
I think it could be moved to the "add database" page.
I believe this component will let us combine some steps. Also I think it could have the multicode component like how the tabs component on the collections page is constructed in the future.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wouldn't do it this way; what I would do, is I would use it for the paged vs. infinite scroll cursor pagination methods.
We use tabs to denote two alternative ways to do the same thing
So for parallel flows in writing, not serial flows.
@timDeHof How do you feel about adding |
The commit fixes capitalization and punctuation errors in the titles and descriptions of the tutorial files. This improves consistency and readability in the documentation. docs(pagination): update tutorial pages for offset and cursor pagination methods feat(pagination): add offset pagination method to the app The tutorial page for implementing offset pagination is updated to provide a clear explanation of what offset pagination is and how it can be used in a React app with an Appwrite backend. The code examples and instructions are also updated to reflect the changes. feat(pagination): add cursor pagination method to the app The tutorial page for implementing cursor pagination is updated to provide a clear explanation of what cursor pagination is and how it can be used in a React app with an Appwrite backend. The code examples and instructions are also updated to reflect the changes. feat(pagination): discuss trade-offs between offset and cursor pagination methods A new tutorial page is added to discuss the trade-offs between offset and cursor pagination methods. The page provides a comparison of the two methods in terms of simplicity, performance, data consistency, scalability, implementation complexity, and direct page access. It
``` | ||
|
||
In the next step, we will replace our current pagination method with the cursor pagination method. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hopefully, this is clearly telling the user that the two files are different.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My initial thoughts from Office hours, not a full review.
I'll add more later, thanks @timDeHof !
@@ -50,6 +50,17 @@ | |||
</p> | |||
</a> | |||
</li> | |||
<li class="is-mobile-col-span-2"> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's leave it out, we'lll update this page later with all of the new tutorials
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok, I removed it. So now you travel to it by the URL?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@timDeHof We will add it somewhere else, but we need to figure out how we'll do it. Dw about it, we'll handle it on our side :D
readtime: 10 | ||
--- | ||
|
||
**Todos App**: An app to track all your todos that you'll need to get done. In this tutorial, you will build the todos app with appwrite and react. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Focus on the end goal, title and this part should focus on general pagination with Appwrite + react, not the app.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@timDeHof AMAZING start, I really appreciate it. Let's look at the first comments and make the changes, then let me know when I should review again.
Thank you so much!
</div> | ||
); | ||
} | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep, @timDeHof doing it like this:
Under implementation discuss the different forms it could take:
- Just a load more button like many apps
- Navigation buttons.
You can show both methods in the same page using a tabs component like the one here:
https://appwrite.io/docs/products/databases/collections
…eralized and focus more on pagination. Fixed title and description to use sentence case. Changed difficulty to 'intermediate' from 'beginner'. Changed readtime to '20' from '10'. Added tabsto the different methods to showcase usage of each.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Amazing work Tim!
Just a few ideas throw in. This is almost ready :D
{% /table %} | ||
|
||
# Add Permissions {% #add-permissions %} | ||
1. Go to the 'Collection Settings' tab. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So should just be Settings, we don't use quotes, we use bold text to show the exact text of UI element your referring to, applies everywhere.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ok, But would we assume that user is still in the collection.
# Add Permissions {% #add-permissions %} | ||
1. Go to the 'Collection Settings' tab. | ||
2. Scroll to the 'Permissions' section. | ||
3. Add the `Any` role, ensuring you select both `CREATE` and `READ` permissions. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a comment about not doing this in prod. obv
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
would I use the Info tag for this?
3. Add the `Any` role, ensuring you select both `CREATE` and `READ` permissions. | |
3. Add the `Any` role, ensuring you select both `CREATE` and `READ` permissions. | |
{% info %} | |
Do Not Do this in Production. This is only for this tutorial | |
{% /info %} | |
{% tabsitem #Basic-cursor-pagination title="Basic Cursor Pagination" %} | ||
|
||
Create a file and named `src/components/BasicCursorPagination.jsx`, insert the following code: | ||
```js |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Forgot to import react?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, and I guess this one should have the debounce function in it too
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Haha yees!
import { useTodos } from '../lib/context/todos'; | ||
import BasicCursorPagination from '../components/BasicCursorPagination'; | ||
|
||
export function TodosPage() { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The name again should be Todos
cause that's what App.jsx imports
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
export function TodosPage() { | |
export function Todos() { |
TODOS_DATABASE_ID, | ||
TODOS_COLLECTION_ID, | ||
[ | ||
Query.orderDesc("$createdAt"), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Wrong way :P
setCurrentPage(currentPage + 1) | ||
setFirstId(response.documents[0].$id); | ||
setLastId(response.documents[response.documents.length - 1].$id); | ||
setTodos([...todos, ...response.documents]); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think for paged, you should just have response.documents
```js | ||
import React, { useEffect } from 'react'; | ||
|
||
function InfiniteScroll(props) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't think this is working haha~
Let's just use a button to load more 😅
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I guess todos were too little for the required window. This may be a tutorial on infinite scrolling image gallery searches or something that would make it more practical to use with.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah it's fine. They can go figure out the UI, not within scope.
import { ID } from "appwrite"; | ||
|
||
export const TODOS_DATABASE_ID = "[YOUR_DATABASE_ID]"; | ||
export const TODOS_COLLECTION_ID = "[YOUR_COLLECTION_ID]"; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
export const TODOS_COLLECTION_ID = "[YOUR_COLLECTION_ID]"; |
TODOS_DATABASE_ID, | ||
TODOS_COLLECTION_ID, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
since the app is created using Vite, these env variables should be like this:
TODOS_DATABASE_ID, | |
TODOS_COLLECTION_ID, | |
import.meta.env.APPWRITE_DATABASE_ID, | |
import.meta.env.APPWRITE_COLLECTION_ID, |
we can tell them to write them like this so the env variables will not be exposed to the client.
|
||
# Seeding the collection {% #seeding-the-collection %} | ||
We'll now create a script that populates documents from a `setup.json` file.Create a new file `./db/setup.js` in the root of your project directory for this purpose. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
# Create environment configuration file {% #create-env-file %} | |
Now, let's set up the environment configuration for our project. | |
Follow these steps to create a `.env` file in the root directory of the project. | |
1. Navigate to the root of the project using your terminal or file explorer. | |
2. Create a new file named `.env` (make sure that there is no file extension like `.txt`). | |
3. Open the `.env` file with your preferred text editor. | |
4. Add the necessary environment variables and their values for your respective project, database, and collection IDs in the format `KEY=VALUE`. Each variable should be on a new line. | |
{% code %} | |
APPWRITE_PROJECT_ID=[YOUR_PROJECT_ID] | |
APPWRITE_DATABASE_ID=[YOUR_DATABASE_ID] | |
APPWRITE_COLLECTION_ID=[YOUR_COLLECTION_ID] | |
{% /code %} | |
4. Save the file. | |
This `.env` file will now act as the central place for your project's environment-specific configurations. Make sure not to sure this file publicly, especially if it contains sensitive information like API keys or database credentials. |
|
||
# Update the todos context {% #update-the-todos-context %} | ||
|
||
Update the contents of `src/lib/context/todos.jsx` with the following code, replacing `[YOUR_DATABASE_ID]` and `[YOUR_COLLECTION_ID]` with your project ID and collection ID. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I will make similar changes here like I did in the step 5's suggestion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I haven't made any changes to the docs yet. But I did add some suggestions/comments to the new changes just to see if its the direction you want to go with.
Create four new files in `src/pages/` folder, name them `TodosWithOffsetPagination`, `TodosWithOffsetPaginationAndNumbers`, `TodosWithBasicCursorPagination`, and `TodosWithBidirectionalCursorPagination `. Then insert this placeholder code in each file: | ||
|
||
```js | ||
import { useTodos } from "../lib/context/todos"; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
import { useTodos } from "../lib/context/todos"; | |
import { useTodos } from "../lib/context/todos-offset-pagination""; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is fine for a hacktoberfest contribution.
I'm going to make more changes, so I'll merge it into one of our branches and I'll just make the small adjustments to fit our docs better. Thanks!
Hey there! There were a lot of big PRs during this Hacktoberfest, and we wanted to give everyone ample time to collaborate with our engineering team. If you were able to merge your PRs during October, amazing. If it’s still not merged, don’t worry about it either. Either way, we’ve got your Hacktoberfest swag minted and ready to ship. Please comment with your Discord username here so we can contact you about your shipping information to deliver your Hacktoberfest swag. |
My discord username is timdehof but my display name is Tim |
feat(pagination): add layout, page, and markdoc files for pagination tutorial feat(pagination): add step-1, step-2, step-3, step-4, step-5, and step-10 markdoc files The changes include adding a new page for the pagination tutorial in the docs section. Additionally, the necessary layout, page, and markdoc files are added for each step of the pagination tutorial. This allows users to learn about pagination in a React app using the Appwrite backend. The tutorial covers topics such as setting up the project, creating a database, initializing the Appwrite SDK, and seeding the database with data.
feat(docs): add new files for pagination tutorial steps 6 and 7
![offset-pagination-demo](https://private-user-images.githubusercontent.com/2568193/272634778-5394bbee-922d-47b3-ae2e-0475069df15f.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQxNDgzNzYsIm5iZiI6MTcyNDE0ODA3NiwicGF0aCI6Ii8yNTY4MTkzLzI3MjYzNDc3OC01Mzk0YmJlZS05MjJkLTQ3YjMtYWUyZS0wNDc1MDY5ZGYxNWYuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgyMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MjBUMTAwMTE2WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZTNjODYzNzY3MDJkNjU2NjEzOWMyYzYyNTlmZTcxMjRlYThhZGQ1YmEzYTRkMDU1ZjU4Mzg2ZjgwZTcyYWQyMSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.w8Vp8_7GTdI3UIWdiZPNO9pqHgCLHyKD2DHL9rva0vA)
The changes include the addition of two new files:
src/routes/docs/tutorials/pagination/step-6/+page.markdoc
andsrc/routes/docs/tutorials/pagination/step-7/+page.markdoc
. These files contain the code and instructions for implementing pagination in a React application using Appwrite backend. Thestep-6
file adds the initial code for displaying tasks using context and a custom hook, while thestep-7
file adds the implementation for offset pagination and the UI components for navigating through the dataset.feat(docs): add tutorial pages for implementing cursor pagination and discussing trade-offs feat(docs): add page for implementing cursor pagination in a React app using Appwrite backend A new tutorial page has been added to the documentation that explains what cursor pagination is and how to implement it in a React app using the Appwrite backend. The page provides an overview of cursor pagination and its benefits, and includes code examples for implementing cursor pagination using Appwrite's
![cursor-pagination-demo](https://private-user-images.githubusercontent.com/2568193/272634930-ce07743c-35ae-45bf-9dd0-4a5bb93f9a9b.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQxNDgzNzYsIm5iZiI6MTcyNDE0ODA3NiwicGF0aCI6Ii8yNTY4MTkzLzI3MjYzNDkzMC1jZTA3NzQzYy0zNWFlLTQ1YmYtOWRkMC00YTViYjkzZjlhOWIuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgyMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MjBUMTAwMTE2WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9MTEzZjI5YWI2YTJhNTc5MTI4OTkwNGM5OTFmMmQyMDQzZjJlOGE0MmIyODEzNDliMTlkODkzZjA4Yzg4N2FmZCZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.qDG04kqHQxTXkv_PKEycnGBUjTm8sZyNxA6qOl1Ljbk)
listDocuments()
command.feat(docs): add page for discussing the trade-offs between offset pagination and cursor pagination A new tutorial page has been added to the documentation that discusses the trade-offs between offset pagination and cursor pagination. The page provides a comparison table highlighting the pros and cons of each pagination method, and offers guidance on when to use each method based on different application requirements. The page also includes a recap section summarizing the key points to consider when choosing a pagination method in Appwrite.
What does this PR do?
Adds a tutorial a functional app that showcases using Appwrite's pagination methods with React. for the moment, appwrite setup is for a web app.
Test Plan
The tutorial can be found in the route
/docs/tutorials/pagination/
It can also be viewed on the website as a tutorial card under
/docs/tutorials
routeThe tutorial can be tested by going through the steps in the tutorial
Related PRs and Issues
#78
Have you read the Contributing Guidelines on issues?
Yes