278 lines
11 KiB
JavaScript
278 lines
11 KiB
JavaScript
import { expandInfo } from "./expandInfo";
|
|
import { fieldsInfo } from "./fieldsInfo";
|
|
import { filterSyntax } from "./filterSyntax";
|
|
|
|
export function docsList(collection) {
|
|
const baseURL = app.utils.getApiExampleURL();
|
|
|
|
const isSuperusersOnly = collection.listRule === null;
|
|
|
|
const baseDummyRecord = {
|
|
collectionId: collection.id,
|
|
collectionName: collection.name,
|
|
};
|
|
|
|
const responses = [
|
|
{
|
|
title: 200,
|
|
value: JSON.stringify(
|
|
{
|
|
page: 1,
|
|
perPage: 30,
|
|
totalPages: 1,
|
|
totalItems: 2,
|
|
items: [
|
|
Object.assign(baseDummyRecord, app.utils.getDummyFieldsData(collection)),
|
|
Object.assign(baseDummyRecord, app.utils.getDummyFieldsData(collection)),
|
|
],
|
|
},
|
|
null,
|
|
2,
|
|
),
|
|
},
|
|
{
|
|
title: 400,
|
|
value: `
|
|
{
|
|
"status": 400,
|
|
"message": "Something went wrong while processing your request.",
|
|
"data": {}
|
|
}
|
|
`,
|
|
},
|
|
];
|
|
if (isSuperusersOnly) {
|
|
responses.push({
|
|
title: 403,
|
|
value: `
|
|
{
|
|
"status": 403,
|
|
"message": "Only superusers can access this action.",
|
|
"data": {}
|
|
}
|
|
`,
|
|
});
|
|
}
|
|
|
|
return t.div(
|
|
{ pbEvent: "apiPreviewList", className: "content" },
|
|
// description
|
|
t.p(null, `Fetch a paginated ${collection.name} records list, supporting sorting and filtering.`),
|
|
app.components.codeBlockTabs({
|
|
className: "sdk-examples m-t-sm",
|
|
historyKey: "pbLastSDK",
|
|
tabs: [
|
|
{
|
|
title: "JS SDK",
|
|
language: "js",
|
|
value: `
|
|
import PocketBase from 'pocketbase';
|
|
|
|
const pb = new PocketBase('${baseURL}');
|
|
|
|
...
|
|
|
|
// fetch a paginated records list
|
|
const resultList = await pb.collection('${collection.name}').getList(1, 50, {
|
|
filter: 'someField1 != someField2',
|
|
});
|
|
|
|
// you can also fetch all records at once via getFullList
|
|
const records = await pb.collection('${collection.name}').getFullList({
|
|
sort: '-someField',
|
|
});
|
|
|
|
// or fetch only the first record that matches the specified filter
|
|
const record = await pb.collection('${collection.name}').getFirstListItem(
|
|
'someField="test"',
|
|
{ expand: 'relField1,relField2.subRelField' },
|
|
);
|
|
`,
|
|
footnote: t.div(
|
|
{ className: "txt-right" },
|
|
t.a({
|
|
href: import.meta.env.PB_JS_SDK_URL,
|
|
target: "_blank",
|
|
rel: "noopener noreferrer",
|
|
textContent: "JS SDK docs",
|
|
}),
|
|
),
|
|
},
|
|
{
|
|
title: "Dart SDK",
|
|
language: "dart",
|
|
value: `
|
|
import 'package:pocketbase/pocketbase.dart';
|
|
|
|
final pb = PocketBase('${baseURL}');
|
|
|
|
...
|
|
|
|
// fetch a paginated records list
|
|
final resultList = await pb.collection('${collection.name}').getList(
|
|
page: 1,
|
|
perPage: 50,
|
|
filter: 'someField1 != someField2',
|
|
);
|
|
|
|
// you can also fetch all records at once via getFullList
|
|
final records = await pb.collection('${collection.name}').getFullList(
|
|
sort: '-someField',
|
|
);
|
|
|
|
// or fetch only the first record that matches the specified filter
|
|
final record = await pb.collection('${collection.name}').getFirstListItem(
|
|
'someField="test"',
|
|
expand: 'relField1,relField2.subRelField',
|
|
);
|
|
`,
|
|
footnote: t.div(
|
|
{ className: "txt-right" },
|
|
t.a({
|
|
href: import.meta.env.PB_DART_SDK_URL,
|
|
target: "_blank",
|
|
rel: "noopener noreferrer",
|
|
textContent: "Dart SDK docs",
|
|
}),
|
|
),
|
|
},
|
|
{
|
|
title: "curl",
|
|
language: "bash",
|
|
value: `
|
|
curl \\
|
|
-H 'Authorization:TOKEN' \\
|
|
'${baseURL}/api/collections/${collection.name}/records?perPage=50'
|
|
`,
|
|
},
|
|
],
|
|
}),
|
|
// api
|
|
t.div({ className: "block m-t-base" }, t.strong(null, "API details")),
|
|
t.div(
|
|
{ className: "alert info api-preview-alert" },
|
|
t.span({ className: "label method" }, "GET"),
|
|
t.span({ className: "path" }, `/api/collections/${collection.name}/records`),
|
|
() => {
|
|
if (isSuperusersOnly) {
|
|
return t.small({ className: "extra" }, "Requires superuser Authorization:TOKEN header");
|
|
}
|
|
},
|
|
),
|
|
t.table(
|
|
{ className: "api-preview-table query-params" },
|
|
t.thead(
|
|
null,
|
|
t.tr(
|
|
null,
|
|
t.th({ className: "min-width txt-primary" }, "?query params"),
|
|
t.th({ className: "min-width" }, "Type"),
|
|
t.th(null, "Description"),
|
|
),
|
|
),
|
|
t.tbody(
|
|
null,
|
|
t.tr(
|
|
null,
|
|
t.td({ className: "min-width" }, "page"),
|
|
t.td({ className: "min-width" }, t.span({ className: "label" }, "Number")),
|
|
t.td(null, "The page (aka. offset) of the paginated list (default to 1)."),
|
|
),
|
|
t.tr(
|
|
null,
|
|
t.td({ className: "min-width" }, "perPage"),
|
|
t.td({ className: "min-width" }, t.span({ className: "label" }, "Number")),
|
|
t.td(null, "Specify the max returned records per page (default to 30)."),
|
|
),
|
|
t.tr(
|
|
null,
|
|
t.td({ className: "min-width" }, "sort"),
|
|
t.td({ className: "min-width" }, t.span({ className: "label" }, "String")),
|
|
t.td(
|
|
null,
|
|
t.p(
|
|
null,
|
|
"Specify the records order attribute(s).",
|
|
t.br(),
|
|
"Add -/+ (default) in front of the attribute for DESC / ASC order.",
|
|
),
|
|
t.p(
|
|
null,
|
|
"For example:",
|
|
app.components.codeBlock({
|
|
value: `// DESC by created and ASC by id\n?sort=-created,id`,
|
|
}),
|
|
),
|
|
t.p(
|
|
null,
|
|
"In addition to the collection non-hidden fields, the following special sort fields could be also used: ",
|
|
t.code(null, "@random"),
|
|
" ",
|
|
t.code({ hidden: () => collection.type == "view" }, "@rowid"),
|
|
".",
|
|
),
|
|
),
|
|
),
|
|
t.tr(
|
|
null,
|
|
t.td({ className: "min-width" }, "filter"),
|
|
t.td({ className: "min-width" }, t.span({ className: "label" }, "String")),
|
|
t.td(
|
|
null,
|
|
t.p(null, "Filter the returned records. For example:"),
|
|
app.components.codeBlock({
|
|
value: `?filter=(id='abc' && created>'2022-01-01')`,
|
|
footnote: "All query params must be properly URL encoded (the SDKs do this automatically).",
|
|
}),
|
|
filterSyntax(),
|
|
),
|
|
),
|
|
t.tr(
|
|
null,
|
|
t.td({ className: "min-width" }, "expand"),
|
|
t.td({ className: "min-width" }, t.span({ className: "label" }, "String")),
|
|
t.td(null, expandInfo()),
|
|
),
|
|
t.tr(
|
|
null,
|
|
t.td({ className: "min-width" }, "fields"),
|
|
t.td({ className: "min-width" }, t.span({ className: "label" }, "String")),
|
|
t.td(null, fieldsInfo()),
|
|
),
|
|
t.tr(
|
|
null,
|
|
t.td({ className: "min-width" }, "skipTotal"),
|
|
t.td({ className: "min-width" }, t.span({ className: "label" }, "Boolean")),
|
|
t.td(
|
|
null,
|
|
t.p(
|
|
null,
|
|
"If set to ",
|
|
t.code(null, "1/true"),
|
|
" the total counts query will be skipped and the response fields ",
|
|
t.code(null, "totalItems"),
|
|
" and ",
|
|
t.code(null, "totalPages"),
|
|
" will have -1 value.",
|
|
),
|
|
t.p(
|
|
null,
|
|
"This could drastically speed up the search queries when the total counters are not needed or cursor based pagination is used.",
|
|
" For optimization purposes, it is set by default in the ",
|
|
t.code(null, "getFirstListItem()"),
|
|
" and ",
|
|
t.code(null, "getFullList()"),
|
|
" SDKs methods.",
|
|
),
|
|
),
|
|
),
|
|
),
|
|
),
|
|
// responses
|
|
t.div({ className: "block m-t-base m-b-sm" }, t.strong(null, "Example responses")),
|
|
app.components.codeBlockTabs({
|
|
tabs: responses,
|
|
}),
|
|
);
|
|
}
|