Pagination: add Getting Started tutorial (DevExpress#6890)

Author: vladaskorohodova

applications/GettingStartedWith/Pagination/index.css

@@ -0,0 +1,5 @@
+#cards {
+    display: flex;
+    justify-content: center;
+    flex-wrap: wrap;
+}  

applications/GettingStartedWith/Pagination/index.html

@@ -0,0 +1,3 @@
+<div id="pagination"></div>
+<div id="cards"></div>
+<div id="load-panel"></div>

applications/GettingStartedWith/Pagination/index.js

@@ -0,0 +1,118 @@
+const total = 100;
+const hexCodes = [];
+const apiEndpoint = 'https://www.thecolorapi.com/id?hex=';
+const cache = new Map();
+
+function fetchData(colorId) {
+    return new Promise((resolve, reject) => {
+        if (cache.has(colorId)) {
+            resolve(cache.get(colorId));
+        } else {
+            $.getJSON(apiEndpoint + colorId, (data) => {
+                const colorData = {
+                    image: data.image.bare,
+                    name: data.name.value,
+                };
+                cache.set(colorId, colorData);
+                resolve(colorData);
+            }).fail(() => {
+                reject(new Error(`Error loading color for hex: ${colorId}`));
+            });
+        }
+    });
+}
+
+const getRandomPastelColor = () => {
+    const hue = Math.floor(Math.random() * 360);
+    const saturation = Math.random() * 0.4 + 0.2;
+    const brightness = Math.random() * 0.3 + 0.7;
+    return hsvToHex(hue, saturation, brightness);
+};
+
+const hsvToHex = (h, s, v) => {
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    const i = Math.floor(h / 60);
+    const f = h / 60 - i;
+    const p = v * (1 - s);
+    const q = v * (1 - f * s);
+    const t = v * (1 - (1 - f) * s);
+    switch (i % 6) {
+        case 0: r = v; g = t; b = p; break;
+        case 1: r = q; g = v; b = p; break;
+        case 2: r = p; g = v; b = t; break;
+        case 3: r = p; g = q; b = v; break;
+        case 4: r = t; g = p; b = v; break;
+        case 5: r = v; g = p; b = q; break;
+    }
+    const toHex = (x) => {
+        const hex = Math.round(x * 255).toString(16);
+        return hex.length === 1 ? `0${hex}` : hex;
+    };
+    return toHex(r) + toHex(g) + toHex(b);
+};
+
+const renderCards = async (pageSize, pageIndex) => {
+    $('#cards').empty();
+    const startIndex = (pageIndex - 1) * pageSize;
+    const endIndex = pageIndex * pageSize;
+
+    const hexSubset = hexCodes.slice(startIndex, endIndex);
+    const promises = hexSubset.map((hex) => fetchData(hex));
+    try {
+        const pageColors = await Promise.all(promises);
+        pageColors.forEach((color) => {
+            const image = $('<img>').attr({
+                src: color.image,
+                alt: color.name,
+            });
+            $('#cards').append(image);
+        });
+    } catch (error) {
+        console.error('Error rendering cards:', error);
+    }
+};
+
+$(() => {
+    for (let i = 0; i < total; i += 1) {
+        hexCodes.push(getRandomPastelColor());
+    }
+
+    const loadPanel = $('#load-panel')
+        .dxLoadPanel({
+            position: {
+                my: 'top',
+                at: 'top',
+                of: '#cards',
+            },
+            visible: false,
+            showIndicator: true,
+            showPane: true,
+            hideOnOutsideClick: false,
+        })
+        .dxLoadPanel('instance');
+
+    const pagination = $('#pagination')
+        .dxPagination({
+            showInfo: true,
+            showNavigationButtons: true,
+            itemCount: total,
+            pageIndex: 1,
+            pageSize: 5,
+            onOptionChanged: (e) => {
+                if (e.name === 'pageSize' || e.name === 'pageIndex') {
+                    const pageIndex = pagination.option('pageIndex');
+                    const pageSize = pagination.option('pageSize');
+                    loadPanel.show();
+                    renderCards(pageSize, pageIndex).finally(() => loadPanel.hide());
+                }
+            },
+        })
+        .dxPagination('instance');
+
+    const pageSize = pagination.option('pageSize');
+    const pageIndex = pagination.option('pageIndex');
+    loadPanel.show();
+    renderCards(pageSize, pageIndex).finally(() => loadPanel.hide());
+});

concepts/05 UI Components/Pagination/05 Getting Started with Pagination/00 Getting Started with Pagination.md

@@ -0,0 +1,13 @@
+#include tutorials-intro-installationnote
+
+Pagination is a UI component that allows users to navigate through pages and change page size at runtime.
+
+This tutorial explains how to add Pagination to a page and configure the component's core settings. It also covers implementing remote pagination. Colored cards are loaded each time a user switches pages or changes page size. The final result is displayed below:
+
+<div class="simulator-desktop-container" data-view="/Content/Applications/24_2/GettingStartedWith/Pagination/index.html, /Content/Applications/24_2/GettingStartedWith/Pagination/index.js, /Content/Applications/24_2/GettingStartedWith/Pagination/index.css"></div>
+
+Each section in this tutorial describes a single configuration step. You can also find the full source code in the following GitHub repository:
+
+#include btn-open-github with {
+    href: "https://github.com/DevExpress-Examples/devextreme-getting-started-with-pagination"
+}

concepts/05 UI Components/Pagination/05 Getting Started with Pagination/05 Create Pagination.md

@@ -0,0 +1,95 @@
+---
+##### jQuery
+[Add DevExtreme to your jQuery application](/concepts/58%20jQuery%20Components/05%20Add%20DevExtreme%20to%20a%20jQuery%20Application/00%20Add%20DevExtreme%20to%20a%20jQuery%20Application.md '/Documentation/Guide/jQuery_Components/Add_DevExtreme_to_a_jQuery_Application/') and use the following code to create a Pagination component:
+
+    <!-- tab: index.js -->
+    $(function() {
+        $("#pagination").dxPagination({ });
+    });
+
+    <!-- tab: index.html -->
+    <html>
+        <head>
+            <!-- ... -->
+            <script type="text/javascript" src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
+            <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/minor_24_2/css/dx.light.css">
+            <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/minor_24_2/js/dx.all.js"></script>
+            <script type="text/javascript" src="index.js"></script>
+        </head>
+        <body>
+            <div id="pagination"></div>
+        </body>
+    </html>
+
+
+##### Angular
+
+[Add DevExtreme to your Angular application](/concepts/40%20Angular%20Components/10%20Getting%20Started/03%20Add%20DevExtreme%20to%20an%20Angular%20CLI%20Application '/Documentation/Guide/Angular_Components/Getting_Started/Add_DevExtreme_to_an_Angular_CLI_Application/') and use the following code to create a Pagination component:
+
+    <!-- tab: app.component.html -->
+    <dx-pagination></dx-pagination>
+
+    <!-- tab: app.component.ts -->
+    import { Component } from '@angular/core';
+
+    @Component({
+        selector: 'app-root',
+        templateUrl: './app.component.html',
+        styleUrls: ['./app.component.css']
+    })
+    export class AppComponent {
+
+    }
+
+    <!-- tab: app.module.ts -->
+    import { BrowserModule } from '@angular/platform-browser';
+    import { NgModule } from '@angular/core';
+    import { AppComponent } from './app.component';
+
+    import { DxPaginationModule } from 'devextreme-angular';
+
+    @NgModule({
+        declarations: [
+            AppComponent
+        ],
+        imports: [
+            BrowserModule,
+            DxPaginationModule
+        ],
+        providers: [ ],
+        bootstrap: [AppComponent]
+    })
+    export class AppModule { }
+
+##### Vue
+
+[Add DevExtreme to your Vue application](/concepts/55%20Vue%20Components/05%20Add%20DevExtreme%20to%20a%20Vue%20Application/00%20Add%20DevExtreme%20to%20a%20Vue%20Application.md '/Documentation/Guide/Vue_Components/Add_DevExtreme_to_a_Vue_Application/') and use the following code to create a Pagination component:
+
+    <!-- tab: App.vue -->
+    <template>
+        <DxPagination />
+    </template>
+
+    <script setup lang="ts">
+    import 'devextreme/dist/css/dx.light.css';
+    import { DxPagination } from 'devextreme-vue/pagination';
+    </script>
+
+##### React
+
+[Add DevExtreme to your React application](/concepts/50%20React%20Components/05%20Add%20DevExtreme%20to%20a%20React%20Application/00%20Add%20DevExtreme%20to%20a%20React%20Application.md '/Documentation/Guide/React_Components/Add_DevExtreme_to_a_React_Application/') and use the following code to create a Pagination component:
+
+    <!-- tab: App.tsx -->
+    import React from 'react';
+    import 'devextreme/dist/css/dx.light.css';
+    import { Pagination } from 'devextreme-react/pagination';
+
+    function App(): JSX.Element {
+        return (
+            <Pagination />
+        );
+    }
+
+    export default App;
+
+---

concepts/05 UI Components/Pagination/05 Getting Started with Pagination/10 Configure Pagination.md

@@ -0,0 +1,100 @@
+This tutorial step guides you through the basic Pagination setup.
+
+Specify the following settings:
+
+* [itemCount](/Documentation/ApiReference/UI_Components/dxPagination/Configuration/#itemCount) sets the total number of items. Pagination does not function properly without this setting.
+* [pageIndex](/Documentation/ApiReference/UI_Components/dxPagination/Configuration/#pageIndex) sets the initial page to display. This tutorial sets **pageIndex** to 3 (the default value is 1).
+* [allowedPageSizes](/Documentation/ApiReference/UI_Components/dxPagination/Configuration/#allowedPageSizes) specifies page sizes available to users. Modify this list as needed. Include `'all'` to allow users to display all items on one page. This tutorial uses the default value: `[5, 10]`.
+* [pageSize](/Documentation/ApiReference/UI_Components/dxPagination/Configuration/#pageSize) specifies the initial page size.
+
+The following code snippet demonstrates how to apply the aforementioned settings:
+
+---
+##### jQuery
+
+    <!-- tab: index.js -->
+    const total = 100;
+    $(() => {
+        const pagination = $('#pagination')
+            .dxPagination({
+                showInfo: true,
+                showNavigationButtons: true,
+                itemCount: total,
+                pageIndex: 3,
+                pageSize: 5,
+            })
+        .dxPagination('instance');
+    });
+
+##### Angular
+
+    <!-- tab: app.component.html -->
+    <dx-pagination
+        [showInfo]="true"
+        [showNavigationButtons]="true"
+        [itemCount]="total"
+        [pageIndex]="pageIndex"
+        [pageSize]="pageSize"
+    >
+    </dx-pagination>
+
+    <!-- tab: app.component.ts -->
+    import { Component } from '@angular/core';
+
+    @Component({
+        selector: 'app-root',
+        templateUrl: './app.component.html',
+        styleUrls: ['./app.component.css']
+    })
+    export class AppComponent {
+        total = 100;
+        pageIndex = 3;
+        pageSize = 5;
+    }
+
+##### Vue
+
+    <!-- tab: App.vue -->
+    <template>
+        <DxPagination
+            :show-info="true"
+            :show-navigation-buttons="true"
+            v-model:page-index="pageIndex"
+            v-model:page-size="pageSize"
+            :item-count="total"
+        />
+    </template>
+
+    <script setup lang="ts">
+    // ...
+    import { ref } from 'vue';
+
+    const total = 100;
+    const pageSize = ref(5);
+    const pageIndex = ref(3);
+    </script>
+
+##### React
+
+    <!-- tab: App.tsx -->
+    import React, { useState } from 'react';
+    // ...
+    const total = 100;
+
+    function App(): JSX.Element {
+        const [pageSize, setPageSize] = useState<number>(5);
+        const [pageIndex, setPageIndex] = useState<number>(3);
+        return (
+            <Pagination
+                showInfo={true}
+                showNavigationButtons={true}
+                pageIndex={pageIndex}
+                pageSize={pageSize}
+                itemCount={total}
+            />
+        );
+    }
+
+    export default App;
+
+---