Feature getodk/central#1348: Add pagination info in the query parameter

PR Feedback
+ Created paginationQueryRef composable
+ Removed pagination query parameter when navigating to the map view
+ Included skipSettingSnapshotFilter to the fetchChunk function

Author: sadiqkhoja

src/components/entity/table-view.vue

@@ -18,7 +18,7 @@ except according to the terms contained in the LICENSE file.
     type="entity"
     :top="pagination.size"
     :filter="filter != null || !!searchTerm"
-    :total-count="dataset.dataExists ? dataset.entities : 0"/>
+    :total-count="dataset.dataExists && !pagination.page ? dataset.entities : 0"/>
   <!-- @update:page is emitted on size change as well -->
   <Pagination v-if="pagination.count > 0"
     v-model:page="pagination.page" v-model:size="pagination.size"
@@ -33,6 +33,7 @@ import { inject, reactive, useTemplateRef, watch } from 'vue';
 import EntityTable from './table.vue';
 import OdataLoadingMessage from '../odata-loading-message.vue';
 import Pagination from '../pagination.vue';
+import usePaginationQueryRef from '../../composables/pagination-query-ref';
 
 import { apiPaths } from '../../util/request';
 import { noop, reemit } from '../../util/util';
@@ -59,7 +60,8 @@ const datasetName = inject('datasetName');
 const { dataset, odataEntities, deletedEntityCount } = useRequestData();
 
 const pageSizeOptions = [250, 500, 1000];
-const pagination = reactive({ page: 0, size: pageSizeOptions[0], count: 0 });
+const { pageNumber, pageSize } = usePaginationQueryRef(pageSizeOptions);
+const pagination = reactive({ page: pageNumber, size: pageSize, count: 0 });
 
 // For more information about how the snapshot filter works, see
 // SubmissionTableView.
@@ -78,11 +80,13 @@ const setSnapshotFilter = () => {
 // `clear` indicates whether odataEntities should be cleared before sending the
 // request. `refresh` indicates whether the request is a background refresh
 // (whether the refresh button was pressed).
-const fetchChunk = (clear, refresh = false) => {
+const fetchChunk = (clear, refresh = false, skipSettingSnapshotFilter = false) => {
   // Are we fetching the first chunk of entities or the next chunk?
   const first = clear || refresh;
-  if (first) {
+  if (first && !skipSettingSnapshotFilter) {
     setSnapshotFilter();
+  }
+  if (refresh) {
     pagination.page = 0;
   }
 
@@ -115,6 +119,11 @@ const fetchChunk = (clear, refresh = false) => {
   })
     .then(() => {
       pagination.count = odataEntities.count;
+      const lastPage = Math.max(0, Math.ceil(pagination.count / pagination.size) - 1);
+      if (pagination.page > lastPage) {
+        pagination.page = lastPage;
+        fetchChunk(true, false, true);
+      }
 
       if (props.deleted) {
         deletedEntityCount.cancelRequest();
@@ -128,6 +137,7 @@ const fetchChunk = (clear, refresh = false) => {
 };
 fetchChunk(true);
 watch([() => props.deleted, () => props.filter, () => props.searchTerm], () => {
+  pagination.page = 0;
   fetchChunk(true);
 });
 const handlePageChange = () => {

src/components/submission/table-view.vue

@@ -18,7 +18,7 @@ except according to the terms contained in the LICENSE file.
     type="submission"
     :top="pagination.size"
     :filter="!!filter"
-    :total-count="totalCount"/>
+    :total-count="pagination.page ? 0 : totalCount"/>
   <!-- @update:page is emitted on size change as well -->
   <Pagination v-if="pagination.count > 0"
     v-model:page="pagination.page" v-model:size="pagination.size"
@@ -33,6 +33,7 @@ import { computed, reactive, useTemplateRef, watch } from 'vue';
 import OdataLoadingMessage from '../odata-loading-message.vue';
 import Pagination from '../pagination.vue';
 import SubmissionTable from './table.vue';
+import usePaginationQueryRef from '../../composables/pagination-query-ref';
 
 import { apiPaths } from '../../util/request';
 import { noop, reemit } from '../../util/util';
@@ -72,7 +73,8 @@ const emit = defineEmits(['review', 'delete', 'restore']);
 const { odata, deletedSubmissionCount } = useRequestData();
 
 const pageSizeOptions = [250, 500, 1000];
-const pagination = reactive({ page: 0, size: pageSizeOptions[0], count: 0 });
+const { pageNumber, pageSize } = usePaginationQueryRef(pageSizeOptions);
+const pagination = reactive({ page: pageNumber, size: pageSize, count: 0 });
 
 let snapshotFilter;
 const setSnapshotFilter = () => {
@@ -99,13 +101,15 @@ const odataSelect = computed(() => {
 });
 
 // `clear` indicates whether this.odata should be cleared before sending the
-// request. `refresh` indicates whether the request is a background refresh
+// request. `refresh` indicates whether the request is a background refresh.
 // (whether the refresh button was pressed).
-const fetchChunk = (clear, refresh = false) => {
+const fetchChunk = (clear, refresh = false, skipSettingSnapshotFilter = false) => {
   // Are we fetching the first chunk of submissions or the next chunk?
   const first = clear || refresh;
-  if (first) {
+  if (first && !skipSettingSnapshotFilter) {
     setSnapshotFilter();
+  }
+  if (refresh) {
     pagination.page = 0;
   }
 
@@ -136,6 +140,11 @@ const fetchChunk = (clear, refresh = false) => {
   })
     .then(() => {
       pagination.count = odata.count;
+      const lastPage = Math.max(0, Math.ceil(pagination.count / pagination.size) - 1);
+      if (pagination.page > lastPage) {
+        pagination.page = lastPage;
+        fetchChunk(true, false, true);
+      }
 
       if (props.deleted) {
         deletedSubmissionCount.cancelRequest();
@@ -148,7 +157,10 @@ const fetchChunk = (clear, refresh = false) => {
     .catch(noop);
 };
 fetchChunk(true);
-watch([() => props.filter, () => props.deleted], () => { fetchChunk(true); });
+watch([() => props.filter, () => props.deleted], () => {
+  pagination.page = 0;
+  fetchChunk(true);
+});
 watch(() => props.fields, (_, oldFields) => {
   if (oldFields != null) fetchChunk(true);
 });

src/composables/data-view.js

@@ -18,7 +18,16 @@ export default () => {
 
   const dataView = useQueryRef({
     fromQuery: (query) => (!query.deleted && query.map === 'true' ? 'map' : 'table'),
-    toQuery: (value) => ({ map: value === 'map' ? 'true' : null })
+    toQuery: (value) => {
+      if (value === 'map') {
+        return {
+          map: true,
+          'page-size': null,
+          'page-number': null
+        };
+      }
+      return { map: null };
+    }
   });
 
   const options = computed(() => [

src/composables/pagination-query-ref.js

@@ -0,0 +1,41 @@
+/*
+Copyright 2025 ODK Central Developers
+See the NOTICE file at the top-level directory of this distribution and at
+https://github.com/getodk/central-frontend/blob/master/NOTICE.
+
+This file is part of ODK Central. It is subject to the license terms in
+the LICENSE file found in the top-level directory of this distribution and at
+https://www.apache.org/licenses/LICENSE-2.0. No part of ODK Central,
+including this file, may be copied, modified, propagated, or distributed
+except according to the terms contained in the LICENSE file.
+*/
+
+import useQueryRef from './query-ref';
+
+export default (pageSizeOptions = [250, 500, 1000]) => {
+  const pageNumber = useQueryRef({
+    fromQuery: (query) => {
+      const num = Number.parseInt(query['page-number'], 10);
+      if (!num || num < 0) return 0;
+      return num - 1;
+    },
+    toQuery: (value) => ({ 'page-number': value === 0 ? null : value + 1 })
+  });
+
+  const pageSize = useQueryRef({
+    fromQuery: (query) => {
+      const size = Number.parseInt(query['page-size'], 10);
+
+      if (!size || size < pageSizeOptions[0]) return pageSizeOptions[0];
+      if (size >= pageSizeOptions[2]) return pageSizeOptions[2];
+      if (size >= pageSizeOptions[1]) return pageSizeOptions[1];
+      return pageSizeOptions[0];
+    },
+    toQuery: (value) => ({ 'page-size': value })
+  });
+
+  return {
+    pageNumber,
+    pageSize
+  };
+};

test/components/entity/list.spec.js

@@ -919,6 +919,72 @@ describe('EntityList', () => {
           component.find('.pagination select').element.value.should.be.eql('2');
         });
     });
+
+    it('adds page-size query parameter when page size is changed', () => {
+      createEntities(251);
+      return load('/projects/1/entity-lists/trees/entities')
+        .complete()
+        .request(component => {
+          const sizeDropdown = component.find('.pagination select:has(option[value="500"])');
+          return sizeDropdown.setValue(500);
+        })
+        .respondWithData(() => testData.entityOData(500))
+        .afterResponse(component => {
+          component.vm.$route.query['page-size'].should.equal('500');
+        });
+    });
+
+    it('adds page-number query parameter when next page is clicked', () => {
+      createEntities(251);
+      return load('/projects/1/entity-lists/trees/entities')
+        .complete()
+        .request(component =>
+          component.find('button[aria-label="Next page"]').trigger('click'))
+        .respondWithData(() => testData.entityOData(250, 250))
+        .afterResponse(component => {
+          component.vm.$route.query['page-number'].should.equal('2');
+        });
+    });
+
+    it('displays the correct page when page-number is provided in URL', () => {
+      createEntities(501);
+      return load('/projects/1/entity-lists/trees/entities?page-number=2', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select').element.value.should.be.eql('1');
+        });
+    });
+
+    it('displays correct number of rows when page-size is provided in URL', () => {
+      createEntities(600);
+      return load('/projects/1/entity-lists/trees/entities?page-size=500', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select:has(option[value="500"])').element.value.should.be.eql('500');
+        });
+    });
+
+    it('selects first page when page-number is less than 1 in URL', () => {
+      createEntities(251);
+      return load('/projects/1/entity-lists/trees/entities?page-number=0', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select').element.value.should.be.eql('0');
+        });
+    });
+
+    it('selects last page when page-number is greater than last page in URL', () => {
+      createEntities(501);
+      return load('/projects/1/entity-lists/trees/entities?page-number=999', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select').element.value.should.be.eql('2');
+        });
+    });
+
+    it('floors page-size to nearest valid value when invalid page-size is provided in URL', () => {
+      createEntities(251);
+      return load('/projects/1/entity-lists/trees/entities?page-size=350', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select:has(option[value="500"])').element.value.should.be.eql('250');
+        });
+    });
   });
 
   describe('deleted entities', () => {
@@ -949,7 +1015,7 @@ describe('EntityList', () => {
 
     it('updates the deleted count', () => {
       testData.extendedEntities.createPast(1, { deletedAt: new Date().toISOString() });
-      return load('/projects/1/entity-lists/truee/entities', { root: false, container: { router: testRouter() } })
+      return load('/projects/1/entity-lists/tree/entities', { root: false, container: { router: testRouter() } })
         .complete()
         .request(component =>
           component.get('.toggle-deleted-entities').trigger('click'))

test/components/submission/field-dropdown.spec.js

@@ -9,6 +9,7 @@ import testData from '../../data';
 import { loadSubmissionList } from '../../util/submission';
 import { mergeMountOptions, mount } from '../../util/lifecycle';
 import { testRequestData } from '../../util/request-data';
+import { mockLogin } from '../../util/session';
 
 const mountComponent = (options) =>
   mount(SubmissionFieldDropdown, mergeMountOptions(options, {
@@ -25,6 +26,10 @@ const strings = (min, max) => {
 };
 
 describe('SubmissionFieldDropdown', () => {
+  beforeEach(() => {
+    mockLogin();
+  });
+
   it('passes an option for each selectable field', () => {
     const component = mountComponent({
       container: {

test/components/submission/list.spec.js

@@ -942,5 +942,97 @@ describe('SubmissionList', () => {
           component.find('.pagination select').element.value.should.be.eql('2');
         });
     });
+
+    it('adds page-size query parameter when page size is changed', () => {
+      createSubmissions(251);
+      return load('/projects/1/forms/f/submissions')
+        .complete()
+        .request(component => {
+          const sizeDropdown = component.find('.pagination select:has(option[value="500"])');
+          return sizeDropdown.setValue(500);
+        })
+        .respondWithData(() => testData.submissionOData(500))
+        .afterResponse(component => {
+          component.vm.$route.query['page-size'].should.equal('500');
+        });
+    });
+
+    it('adds page-number query parameter when next page is clicked', () => {
+      createSubmissions(251);
+      return load('/projects/1/forms/f/submissions')
+        .complete()
+        .request(component =>
+          component.find('button[aria-label="Next page"]').trigger('click'))
+        .respondWithData(() => testData.submissionOData(250, 250))
+        .afterResponse(component => {
+          component.vm.$route.query['page-number'].should.equal('2');
+        });
+    });
+
+    it('displays the correct page when page-number is provided in URL', () => {
+      createSubmissions(501);
+      return load('/projects/1/forms/f/submissions?page-number=2', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select').element.value.should.be.eql('1');
+        });
+    });
+
+    it('displays correct number of rows when page-size is provided in URL', () => {
+      createSubmissions(600);
+      return load('/projects/1/forms/f/submissions?page-size=500', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select:has(option[value="500"])').element.value.should.be.eql('500');
+        });
+    });
+
+    it('selects first page when page-number is less than 1 in URL', () => {
+      createSubmissions(251);
+      return load('/projects/1/forms/f/submissions?page-number=0', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select').element.value.should.be.eql('0');
+        });
+    });
+
+    it('selects last page when page-number is greater than last page in URL', () => {
+      createSubmissions(501);
+      return load('/projects/1/forms/f/submissions?page-number=999', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select').element.value.should.be.eql('2');
+        });
+    });
+
+    it('floors page-size to nearest valid value when invalid page-size is provided in URL', () => {
+      createSubmissions(251);
+      return load('/projects/1/forms/f/submissions?page-size=350', { root: false })
+        .afterResponse(component => {
+          component.find('.pagination select:has(option[value="500"])').element.value.should.be.eql('250');
+        });
+    });
+
+    it('removes page-number from query parameter when switching to map view', () => {
+      const { geopoint } = testData.fields;
+      const fields = [geopoint('/location')];
+      testData.extendedForms.createPast(1, { fields });
+      testData.extendedSubmissions.createPast(251);
+
+      return load('/projects/1/forms/f/submissions', { container: { router: testRouter() } })
+        .complete()
+        .request(component =>
+          component.find('button[aria-label="Next page"]').trigger('click'))
+        .respondWithData(() => testData.submissionOData(250, 250))
+        .afterResponse(component => {
+          // Verify we're on page 2
+          component.vm.$route.query['page-number'].should.equal('2');
+        })
+        .request(component => {
+          const radioField = component.getComponent('.radio-field');
+          const mapOption = radioField.findAll('input[type="radio"]')[1];
+          return mapOption.trigger('change');
+        })
+        .respondWithData(testData.submissionGeojson)
+        .afterResponse(component => {
+          component.vm.$route.query.should.not.have.property('page-number');
+        });
+    });
   });
 });