feat(docs): add pagination tutorial and related files #196

timDeHof · 2023-10-04T15:58:46Z

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.

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 route
The 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

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.

vercel · 2023-10-04T15:58:51Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
website	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 30, 2023 8:06pm

gewenyu99 · 2023-10-05T14:21:28Z

This amazing, I'll check it out soon!

src/routes/docs/tutorials/pagination/step-5/+page.markdoc

src/routes/docs/tutorials/pagination/step-6/+page.markdoc

gewenyu99 · 2023-10-05T14:29:58Z

src/routes/docs/tutorials/pagination/step-8/+page.markdoc

+    </div>
+  );
+}
+```


What if we also add an alternative cursor pagination that shows both cursor before and cursor after to have next and previous page?

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.

Yeah, let's clearly point it out, and trust the user to read carefully. 😄

I added the "load previous" button above the todos.

@timDeHof what do you think to have the same buttons as the offset?: aligned at the bottom and with the text back and forward.

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

@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.

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.

gewenyu99 · 2023-10-05T14:35:00Z

@timDeHof How do you feel about adding Query.cursorBefore(firstId) into the example to show "previous page" for cursor pagination, too? 👀

src/routes/docs/tutorials/pagination/step-1/+page.markdoc

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

src/routes/docs/tutorials/pagination/step-6/+page.markdoc

timDeHof · 2023-10-05T23:01:18Z

src/routes/docs/tutorials/pagination/step-7/+page.markdoc

+```
+
+In the next step, we will replace our current pagination method with the cursor pagination method.


Hopefully, this is clearly telling the user that the two files are different.

src/routes/docs/tutorials/pagination/step-6/+page.markdoc

src/routes/docs/tutorials/pagination/step-1/+page.markdoc

gewenyu99

My initial thoughts from Office hours, not a full review.

I'll add more later, thanks @timDeHof !

gewenyu99 · 2023-10-10T15:13:26Z

src/routes/docs/tutorials/+page.svelte

@@ -50,6 +50,17 @@
 							</p>
 						</a>
 					</li>
+					<li class="is-mobile-col-span-2">


Let's leave it out, we'lll update this page later with all of the new tutorials

Ok, I removed it. So now you travel to it by the URL?

@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

src/routes/docs/tutorials/pagination/step-1/+page.markdoc

gewenyu99 · 2023-10-10T15:16:40Z

src/routes/docs/tutorials/pagination/step-1/+page.markdoc

+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.


Focus on the end goal, title and this part should focus on general pagination with Appwrite + react, not the app.

src/routes/docs/tutorials/pagination/step-1/+page.markdoc

gewenyu99

@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!

src/routes/docs/tutorials/pagination/step-4/+page.markdoc

src/routes/docs/tutorials/pagination/step-5/+page.markdoc

src/routes/docs/tutorials/pagination/step-6/+page.markdoc

src/routes/docs/tutorials/pagination/step-7/+page.markdoc

gewenyu99 · 2023-10-11T20:30:48Z

src/routes/docs/tutorials/pagination/step-8/+page.markdoc

+    </div>
+  );
+}
+```


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.

gewenyu99

Amazing work Tim!

Just a few ideas throw in. This is almost ready :D

gewenyu99 · 2023-10-24T19:39:25Z

src/routes/docs/tutorials/pagination/step-4/+page.markdoc

+{% /table %}
+
+# Add Permissions {% #add-permissions %}
+1. Go to the 'Collection Settings' tab.


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.

ok, But would we assume that user is still in the collection.

src/routes/docs/tutorials/pagination/step-4/+page.markdoc

gewenyu99 · 2023-10-24T19:43:54Z

src/routes/docs/tutorials/pagination/step-4/+page.markdoc

+# 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.


Add a comment about not doing this in prod. obv

would I use the Info tag for this?

Suggested change

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 %}

src/routes/docs/tutorials/pagination/step-5/+page.markdoc

src/routes/docs/tutorials/pagination/step-4/+page.markdoc

gewenyu99 · 2023-10-24T20:35:39Z

src/routes/docs/tutorials/pagination/step-8/+page.markdoc

+{% tabsitem #Basic-cursor-pagination title="Basic Cursor Pagination" %}
+
+Create a file and named `src/components/BasicCursorPagination.jsx`, insert the following code:
+```js


Forgot to import react?

Yes, and I guess this one should have the debounce function in it too

gewenyu99 · 2023-10-24T20:38:24Z

src/routes/docs/tutorials/pagination/step-8/+page.markdoc

+import { useTodos } from '../lib/context/todos';
+import BasicCursorPagination from '../components/BasicCursorPagination';
+
+export function TodosPage() {


The name again should be Todos cause that's what App.jsx imports

Suggested change

export function TodosPage() {

export function Todos() {

gewenyu99 · 2023-10-24T20:41:51Z

src/routes/docs/tutorials/pagination/step-8/+page.markdoc

+          TODOS_DATABASE_ID,
+          TODOS_COLLECTION_ID,
+          [
+            Query.orderDesc("$createdAt"),


Wrong way :P

gewenyu99 · 2023-10-24T20:42:54Z

src/routes/docs/tutorials/pagination/step-8/+page.markdoc

+        setCurrentPage(currentPage + 1)
+        setFirstId(response.documents[0].$id);
+        setLastId(response.documents[response.documents.length - 1].$id);
+        setTodos([...todos, ...response.documents]);


I think for paged, you should just have response.documents

gewenyu99 · 2023-10-24T20:45:33Z

src/routes/docs/tutorials/pagination/step-8/+page.markdoc

+```js
+import React, { useEffect } from 'react';
+
+function InfiniteScroll(props) {


Don't think this is working haha~

Let's just use a button to load 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.

Yeah it's fine. They can go figure out the UI, not within scope.

src/routes/docs/tutorials/pagination/step-5/+page.markdoc

timDeHof · 2023-10-25T18:11:59Z

src/routes/docs/tutorials/pagination/step-5/+page.markdoc

+import { ID } from "appwrite";
+
+export const TODOS_DATABASE_ID = "[YOUR_DATABASE_ID]";
+export const TODOS_COLLECTION_ID = "[YOUR_COLLECTION_ID]";


Suggested change

export const TODOS_COLLECTION_ID = "[YOUR_COLLECTION_ID]";

timDeHof · 2023-10-25T18:22:16Z

src/routes/docs/tutorials/pagination/step-5/+page.markdoc

+        TODOS_DATABASE_ID,
+        TODOS_COLLECTION_ID,


since the app is created using Vite, these env variables should be like this:

Suggested change

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.

timDeHof · 2023-10-25T18:39:32Z

src/routes/docs/tutorials/pagination/step-5/+page.markdoc

+
+# 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.
+


Suggested change

# 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.

timDeHof · 2023-10-25T19:28:03Z

src/routes/docs/tutorials/pagination/step-7/+page.markdoc

+
+# 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.


I will make similar changes here like I did in the step 5's suggestion.

timDeHof

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.

src/routes/docs/tutorials/pagination/step-5/+page.markdoc

src/routes/docs/tutorials/pagination/step-6/+page.markdoc

src/routes/docs/tutorials/pagination/step-7/+page.markdoc

src/routes/docs/tutorials/pagination/step-8/+page.markdoc

src/routes/docs/tutorials/pagination/step-6/+page.markdoc

gewenyu99 · 2023-10-30T20:11:50Z

src/routes/docs/tutorials/pagination/step-6/+page.markdoc

+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";


Suggested change

import { useTodos } from "../lib/context/todos";

import { useTodos } from "../lib/context/todos-offset-pagination"";

gewenyu99

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!

gewenyu99 · 2024-04-08T20:22:18Z

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.

timDeHof · 2024-04-08T20:31:02Z

My discord username is timdehof but my display name is Tim

timDeHof marked this pull request as draft October 4, 2023 16:00

timDeHof marked this pull request as ready for review October 4, 2023 16:00

vercel bot deployed to Preview October 4, 2023 16:04 View deployment

Haimantika requested a review from gewenyu99 October 4, 2023 16:22

gewenyu99 suggested changes Oct 5, 2023

View reviewed changes

timDeHof commented Oct 5, 2023

View reviewed changes

src/routes/docs/tutorials/pagination/step-1/+page.markdoc Outdated Show resolved Hide resolved

timDeHof commented Oct 5, 2023

View reviewed changes

src/routes/docs/tutorials/pagination/step-6/+page.markdoc Outdated Show resolved Hide resolved

vercel bot deployed to Preview October 5, 2023 22:47 View deployment

timDeHof commented Oct 5, 2023

View reviewed changes

src/routes/docs/tutorials/pagination/step-6/+page.markdoc Outdated Show resolved Hide resolved

timDeHof requested a review from gewenyu99 October 5, 2023 23:20

Meldiron reviewed Oct 10, 2023

View reviewed changes

src/routes/docs/tutorials/pagination/step-1/+page.markdoc Outdated Show resolved Hide resolved

gewenyu99 suggested changes Oct 10, 2023

View reviewed changes

gewenyu99 suggested changes Oct 11, 2023

View reviewed changes

TorstenDittmann added the documentation Improvements or additions to documentation label Oct 18, 2023

timDeHof requested a review from gewenyu99 October 19, 2023 14:38

vercel bot deployed to Preview October 19, 2023 14:39 View deployment

gewenyu99 suggested changes Oct 24, 2023

View reviewed changes

timDeHof commented Oct 25, 2023

View reviewed changes

src/routes/docs/tutorials/pagination/step-5/+page.markdoc Outdated Show resolved Hide resolved

timDeHof commented Oct 25, 2023

View reviewed changes

vercel bot had a problem deploying to Preview October 30, 2023 19:28 Failure