diff --git a/docs/source/client/actions/actions.md b/docs/source/client/actions/actions.md index 6c8292f333..aec0e80931 100644 --- a/docs/source/client/actions/actions.md +++ b/docs/source/client/actions/actions.md @@ -1,16 +1,16 @@ # Actions -Plone has the concept of configurable actions called `portal_actions`. +Plone has the idea of configurable actions called `portal_actions`. Each action defines an `id`, a `title`, the required permissions, and a condition that will be checked to decide whether the action will be available for a user. Actions are sorted by categories. Actions can be used to build user interface elements that adapt to the available actions. -An example is the Plone toolbar where the `object_tabs` (view, edit, folder contents, sharing) and the `user_actions` (login, logout, preferences) are used to display to the user only those actions that are allowed for the currently logged in user. +Plone's toolbar displays permissible actions like `object_tabs` (view, edit, folder contents, sharing) and `user_actions` (login, logout, preferences) for the logged-in user's access. The available actions for the currently logged in user can be retrieved by calling the `@actions` endpoint on a specific context. This also works for unauthenticated users. -## Get Actions +## Get actions ### Query function diff --git a/docs/source/client/actions/addons.md b/docs/source/client/actions/addons.md index c4176f183e..349f2a51d7 100644 --- a/docs/source/client/actions/addons.md +++ b/docs/source/client/actions/addons.md @@ -1,7 +1,7 @@ # Add-ons Add-on product records can be addressed through the `@addons` endpoint in a Plone site. -In order to address a specific record, the profile ID has to be passed as a path segment, such as `/plone/@addons/plone.session`. +To address a specific record, the profile ID has to be passed as a path segment, such as `/plone/@addons/plone.session`. Reading or writing add-ons metadata requires the `cmf.ManagePortal` permission. @@ -27,7 +27,7 @@ Use the `useGetAddon` hook to get an add-on at a given path. ### Parameters -- **addonId**: string +- **`addonId`**: string - **Required**: Yes @@ -43,7 +43,7 @@ Use the `useInstallAddon` hook to install an add-on at a given path. ### Parameters -- **addonId**: string +- **`addonId`**: string - **Required**: Yes @@ -59,7 +59,7 @@ Use the `useUninstallAddon` hook to uninstall an add-on at a given path. ### Parameters -- **addonId**: string +- **`addonId`**: string - **Required**: Yes @@ -75,7 +75,7 @@ Use the `useInstallProfileAddon` hook to install an add-on profile at a given pa ### Parameters -- **addonId**: string +- **`addonId`**: string - **Required**: Yes @@ -95,6 +95,6 @@ Use the `useUpgradeAddon` hook to upgrade an add-on at a given path. ### Parameters -- **addonId**: string +- **`addonId`**: string - **Required**: Yes diff --git a/docs/source/client/actions/aliases.md b/docs/source/client/actions/aliases.md index 91540d5262..df52fdaeb8 100644 --- a/docs/source/client/actions/aliases.md +++ b/docs/source/client/actions/aliases.md @@ -2,124 +2,64 @@ A mechanism to redirect old URLs to new ones. -When an object is moved (renamed or cut/pasted into a different location), the redirection storage will remember the old path. It is smart enough to deal with transitive references (if we have a -> b and then add b -> c, it is replaced by a reference a -> c) and circular references (attempting to add a -> a does nothing). +When an object is moved (renamed or cut-and-pasted into a different location), the redirection storage will remember the old path. +It handles transitive references intelligently (for example a -> b, b -> c becomes a -> c), ignoring circular ones (for example attempting a -> a has no effect). -## Get Aliases List +## Get aliases list -### Query function +```{js:function} getAliasesListQuery Use the `getAliasesListQuery` function to get the query for fetching the aliases list. -### Hook +:hook: `useGetAliasesList` +``` -Use the `useGetAliasesList` hook to get the aliases list. +## Get aliases -## Get Aliases - -### Query function +```{js:function} getAliasesQuery(path) Use the `getAliasesQuery` function to get the query for fetching the aliases for a page. -### Hook - -Use the `useGetAliases` hook to get the aliases for a page. - -### Parameters - -- **path**: string - - - **Required:** Yes - -## Add Aliases for Multiple Pages - -### Mutation function - -Use the `createAliasesMutation` function to get the mutation for adding aliases for multiple pages. - -### Hook - -Use the `useCreateAliases` hook to add aliases for multiple pages. +:arg string path: Description of the `path` parameter. +:hook: `useGetAliases` +``` -### Parameters +## Add aliases for many pages -- **data**: object +```{js:function} createAliasesMutation(data) - - **Required:** Yes - - It can have the following fields: +Use the `createAliasesMutation` function to get the mutation for adding aliases for many pages. - `items: object[]`: +:arg array data: It can have the following fields: + - items: An array of objects with the following fields: + - path: string + - redirect_to: string + - [datetime]: string +:hook: `useCreateAliases` +``` - - **Required:** Yes - - An array of objects with the following fields: +## Add aliases for a page - `path: string` - - - **Required:** Yes - - `datetime: string` - - - **Required:** No - - `redirect_to: string` - - - **Required:** Yes - -## Add Aliases for a Page - -### Mutation function +```{js:function} createAliasesMutation(path, data) Use the `createAliasesMutation` function to get the mutation for adding aliases for a page. -### Hook - -Use the `useCreateAliases` hook to add aliases for a page. - -### Parameters +:arg string path: Description of the `path` parameter. +:arg object data: It can have the following fields: + -items: An array of objects with the following fields: + -path: string +:hook: `useCreateAliases` +``` -- **path**: string +## Delete aliases - - **Required:** Yes - -- **data**: object - - - **Required:** Yes - - It can have the following fields: - - `items: object[]`: - - - **Required:** Yes - - An array of objects with the following fields: - - `path: string` - - - **Required:** Yes - -## Delete Aliases - -### Mutation function +```{js:function} deleteAliasesMutation(path, data) Use the `deleteAliasesMutation` function to get the mutation for deleting aliases for a page. -### Hook - -Use the `useDeleteAliases` hook to delete aliases for a page. - -### Parameters - -- **path**: string - - - **Required:** Yes - -- **data**: object - - - **Required:** Yes - - It can have the following fields: - - `items: object[]`: - - - **Required:** Yes - - An array of objects with the following fields: - - `path: string` - - - **Required:** Yes +:arg string path: Description of the `path` parameter. +:arg object data: It can have the following fields: + -items: An array of objects with the following fields: + -path: string +:hook: `useDeleteAliases` +``` \ No newline at end of file diff --git a/docs/source/client/actions/breadcrumbs.md b/docs/source/client/actions/breadcrumbs.md index 3b2e7c5259..3d4bc72774 100644 --- a/docs/source/client/actions/breadcrumbs.md +++ b/docs/source/client/actions/breadcrumbs.md @@ -1,6 +1,6 @@ # Breadcrumbs -## Get Breadcrumbs +## Get breadcrumbs ### Query function diff --git a/docs/source/client/actions/comments.md b/docs/source/client/actions/comments.md index a323b2d6c5..1b4c07e3ee 100644 --- a/docs/source/client/actions/comments.md +++ b/docs/source/client/actions/comments.md @@ -6,7 +6,7 @@ Commenting can be enabled globally for specific content types and for single con When commenting is enabled on your content object, you can retrieve a list of all existing comments, add new comments, reply to existing comments, or delete a comment. -## Get Comments List +## Get comments list ### Query function @@ -22,7 +22,7 @@ Use the `useGetCommentsList` hook to get the comments list for a page. - **Required:** Yes -## Add Comment +## Add comment ### Mutation function @@ -38,7 +38,7 @@ Use the `useCreateComment` hook to add a comment for a page. - **Required:** Yes -- **reply_id**: string +- **`reply_id`**: string - **Required:** No - The id of the comment to which you want to reply @@ -53,7 +53,7 @@ Use the `useCreateComment` hook to add a comment for a page. - **Required:** Yes - The content of the comment. -## Update Comment +## Update comment ### Mutation function @@ -69,7 +69,7 @@ Use the `useUpdateComment` hook to update a comment for the given id and path. - **Required:** Yes -- **comment_id**: string +- **`comment_id`**: string - **Required:** Yes @@ -83,7 +83,7 @@ Use the `useUpdateComment` hook to update a comment for the given id and path. - **Required:** Yes - The content of the comment. -## Delete Comment +## Delete comment ### Mutation function @@ -99,6 +99,6 @@ Use the `useDeleteComment` hook to delete a comment for the given id and path. - **Required:** Yes -- **comment_id**: string +- **`comment_id`**: string - **Required:** Yes diff --git a/docs/source/client/actions/content.md b/docs/source/client/actions/content.md index 826296126a..ee785f7cf4 100644 --- a/docs/source/client/actions/content.md +++ b/docs/source/client/actions/content.md @@ -2,7 +2,7 @@ Get the data for a specific content given its path. -## Get Content +## Get content ### Query options function @@ -26,7 +26,7 @@ Use the `useGetContent` hook to get the content at a given path. - **Required:** No -- **fullObjects:** boolean +- **`fullObjects`:** `boolean` - **Required:** No @@ -34,7 +34,7 @@ Use the `useGetContent` hook to get the content at a given path. - **Required:** No -## Add Content +## Add content ### Mutation options function @@ -152,7 +152,7 @@ Use the `useCreateContent` hook to add content at a given path. - **Required:** No -## Update Content +## Update content ### Mutation function @@ -258,7 +258,7 @@ Use the `useUpdateContent` hook to update content at a given path. - **Required**: No -## Delete Content +## Delete content ### Mutation function @@ -280,7 +280,7 @@ Use the `useDeleteContent` hook to delete content at a given path. (relatedobject)= -#### RelatedObject +#### `RelatedObject` `@id: string` diff --git a/docs/source/client/actions/contextnavigation.md b/docs/source/client/actions/contextnavigation.md index 6b992dbd04..661f42f7d6 100644 --- a/docs/source/client/actions/contextnavigation.md +++ b/docs/source/client/actions/contextnavigation.md @@ -1,8 +1,8 @@ -# Context Navigation +# Context navigation -The `@contextnavigation` endpoint uses the same semantics as the classic Plone navigation portlet. Instead of storing the portlet configuration in a portlet assignment storage, you can pass these as parameters to the service or expand the component. +The `@contextnavigation` endpoint uses the same semantics as the classic Plone navigation `portlet`. Instead of storing the `portlet` configuration in a `portlet` assignment storage, you can pass these as parameters to the service or expand the part. -## Get Context Navigation +## Get context navigation ### Query function diff --git a/docs/source/client/actions/controlpanels.md b/docs/source/client/actions/controlpanels.md index f85a8eca8c..d510e85a3a 100644 --- a/docs/source/client/actions/controlpanels.md +++ b/docs/source/client/actions/controlpanels.md @@ -1,9 +1,9 @@ -# Control Panels +# Control panels Control panels in Plone allow you to configure the global site setup of a Plone site. The `@controlpanels` endpoint in `plone.restapi` allows you to list all existing control panels in a Plone site, and to retrieve or edit the settings of a specific control panel. -## Get Control Panels List +## Get control panels list ### Query function @@ -13,7 +13,7 @@ Use the `getControlpanelsQuery` function to get the query for fetching the contr Use the `useGetControlpanels` hook to get the control panels list. -## Get Control Panel +## Get control panel ### Query function @@ -29,7 +29,7 @@ Use the `useGetControlpanel` hook to get a control panel at a given path. - **Required**: Yes -## Add Custom Elements in Control Panel +## Add custom elements in control panel ### Mutation function @@ -45,7 +45,7 @@ Use the `useCreateControlpanel` hook to add a custom element in the control pane - **Required**: Yes -## Update Custom Elements in Control Panel +## Update custom elements in control panel ### Mutation function @@ -61,7 +61,7 @@ Use the `useUpdateControlpanel` hook to update a custom element in the control p - **Required**: Yes -## Delete Custom Elements in Control Panel +## Delete custom elements in control panel ### Mutation function diff --git a/docs/source/client/actions/copymove.md b/docs/source/client/actions/copymove.md index 91bad9f4da..d0dcaca5ca 100644 --- a/docs/source/client/actions/copymove.md +++ b/docs/source/client/actions/copymove.md @@ -1,4 +1,4 @@ -# Copy and Move +# Copy and move ## Copying an object @@ -10,7 +10,7 @@ The source object can be specified either by URL, path, UID or `intid`: To move a content object, send a `POST` request to the `/@move` endpoint at the destination's URL with the source object specified in the request body. The source object can be specified either by URL, path, UID or `intid`: -## Copy Content +## Copy content ### Mutation function @@ -33,7 +33,7 @@ Use the `useCopy` hook to copy a content object. - **Required:** Yes - The source object to copy. It can be specified either by URL, path, UID or `intid`. -## Move Content +## Move content ### Mutation function diff --git a/docs/source/client/actions/email-notification.md b/docs/source/client/actions/email-notification.md index 03de071e19..ed6821aaaf 100644 --- a/docs/source/client/actions/email-notification.md +++ b/docs/source/client/actions/email-notification.md @@ -1,12 +1,12 @@ -# Email Notification +# Email notification -## Contact Site Owner (Contact Form) +## Contact site owner (contact form) Plone allows the user to contact the site owner via a form on the website. -This makes sure the site owner does not have to expose their email addresses publicly. +This makes sure the site owner doesn't have to expose their email addresses publicly. At the same time, it allows the users to reach out to the site owners. -## Send Email Notification +## Send email notification ### Mutation function diff --git a/docs/source/client/actions/email-send.md b/docs/source/client/actions/email-send.md index 2613b865b6..dcf81cc523 100644 --- a/docs/source/client/actions/email-send.md +++ b/docs/source/client/actions/email-send.md @@ -1,8 +1,8 @@ -# Email Send +# Email send To send an email to an arbitrary email address use the /@email-send endpoint. -## Send Email +## Send email ### Mutation function diff --git a/docs/source/client/actions/groups.md b/docs/source/client/actions/groups.md index 364b69f6f5..14ac3aff05 100644 --- a/docs/source/client/actions/groups.md +++ b/docs/source/client/actions/groups.md @@ -3,7 +3,7 @@ Available groups in a Plone site can be created, queried, updated, and deleted by interacting with the `/@groups` endpoint on the portal root. This requires an authenticated user. -## Get Groups list +## Get groups list ### Query function @@ -13,7 +13,7 @@ Use the `getGroupsQuery` function to get the query for fetching the groups list. Use the `useGetGroups` hook to get the groups list. -## Get Group +## Get group ### Query function @@ -29,7 +29,7 @@ Use the `useGetGroup` hook to get a group at a given path. - **Required**: Yes -## Add Group +## Add group ### Mutation function @@ -78,7 +78,7 @@ Use the `useCreateGroup` hook to add a group at a given path. - **Required**: No -## Update Group +## Update group ### Mutation function @@ -111,7 +111,7 @@ Use the `useUpdateGroup` hook to update an existing group at the given path. - **Required**: No -## Delete Group +## Delete group ### Mutation function diff --git a/docs/source/client/actions/history.md b/docs/source/client/actions/history.md index a7cb7c126d..1679bca219 100644 --- a/docs/source/client/actions/history.md +++ b/docs/source/client/actions/history.md @@ -1,10 +1,10 @@ # History -The `@history` endpoint exposes history and versioning information on previous versions of the content. +The `@history` endpoint exposes history and versioning information on earlier versions of the content. Each change or workflow change on a content object or file is listed. -It also allows to revert to a previous version of the file. +It also allows to revert to a earlier version of the file. -## Get History +## Get history ### Query function @@ -20,7 +20,7 @@ Use the `useGetHistory` hook to get the history for a page. - **Required**: Yes -## Get Versioned History +## Get versioned history ### Query function @@ -40,15 +40,15 @@ Use the `useGetHistoryVersioned` hook to get the versioned history for a page. - **Required**: Yes -## Revert to Version +## Revert to version ### Mutation function -Use the `revertHistoryMutation` function to get the mutation for reverting to a previous version of a page. +Use the `revertHistoryMutation` function to get the mutation for reverting to a earlier version of a page. ### Hook -Use the `useRevertHistory` hook to revert to a previous version of a page. +Use the `useRevertHistory` hook to revert to a earlier version of a page. ### Parameters diff --git a/docs/source/client/actions/linkintegrity.md b/docs/source/client/actions/linkintegrity.md index d29ca24938..ecf0548d58 100644 --- a/docs/source/client/actions/linkintegrity.md +++ b/docs/source/client/actions/linkintegrity.md @@ -1,7 +1,7 @@ -# Link Integrity +# Link integrity When you create relations between content objects in Plone (for example, via relation fields or links in text blocks), these relations are stored in the database. -The Plone user interface will use those stored relations to show a warning when you try to delete a content object that is still referenced elsewhere. +The Plone user interface will use those stored relations to show a warning when you try to delete a content object that's still referenced elsewhere. Link integrity avoids broken links ("breaches") in the site. This check includes content objects that are located within a content object ("folderish content"). @@ -9,7 +9,7 @@ This check includes content objects that are located within a content object ("f The `@linkintegrity` endpoint returns the list of reference breaches. If there are none, it will return an empty list (`[]`). -## Get Link Integrity +## Get link integrity ### Query function @@ -21,6 +21,6 @@ Use the `useGetLinkIntegrity` hook to get the link integrity for a page. ### Parameters -- **uids**: string +- **`UIDs`**: string - **Required:** Yes diff --git a/docs/source/client/actions/lock.md b/docs/source/client/actions/lock.md index 93a288ca53..14a0b000f3 100644 --- a/docs/source/client/actions/lock.md +++ b/docs/source/client/actions/lock.md @@ -1,13 +1,13 @@ # Locking -Locking is a mechanism to prevent users from accidentally overriding each other's changes. +Locking is a mechanism to prevent users from overriding each other's changes. When a user edits a content object in Plone, the object is locked until the user hits the {guilabel}`Save` or {guilabel}`Cancel` button. If a second user tries to edit the object at the same time, she will see a message that this object is locked. The API consumer can create, read, update, and delete a content-type lock. -## Get Lock Info +## Get lock info ### Query function @@ -23,7 +23,7 @@ Use the `useGetLock` hook to get the lock info for a page. - **Required:** Yes -## Add Lock +## Add lock ### Mutation function @@ -54,7 +54,7 @@ Use the `useCreateLock` hook to add a lock for a page. - **Required:** No - The timeout of the lock in seconds. If not given, the default timeout is used. -## Update Lock +## Update lock ### Mutation function @@ -70,11 +70,11 @@ Use the `useUpdateLock` hook to update a lock for a page. - **Required:** Yes -- **locktoken**: string +- **`locktoken`**: string - **Required:** Yes -## Delete Lock +## Delete lock ### Mutation function diff --git a/docs/source/client/actions/navigation.md b/docs/source/client/actions/navigation.md index 936738802c..568d95d79f 100644 --- a/docs/source/client/actions/navigation.md +++ b/docs/source/client/actions/navigation.md @@ -2,7 +2,7 @@ Get the top-level navigation items or navigation item tree with the navigation endpoint. -## Get Navigation +## Get navigation ### Query function diff --git a/docs/source/client/actions/navroot.md b/docs/source/client/actions/navroot.md index cef5058930..f1721a02a9 100644 --- a/docs/source/client/actions/navroot.md +++ b/docs/source/client/actions/navroot.md @@ -1,9 +1,9 @@ # Navigation root -Plone has a concept called {term}`navigation root` which provides a way to root catalog queries, searches, breadcrumbs, and other content types in a given section of the site. -This feature is useful when working with subsites or multilingual sites, because it allows the site manager to restrict searches or navigation queries to a specific location in the site. +Plone has a idea called {term}`navigation root` which provides a way to root catalog queries, searches, breadcrumbs, and other content types in a given section of the site. +Enables site managers in sub-sites or multilingual sites to confine searches or navigation queries within specific site sections, enhancing search precision. -## Get Navigation Root +## Get navigation root ### Query function diff --git a/docs/source/client/actions/principals.md b/docs/source/client/actions/principals.md index e45c01eac0..14d811e5f6 100644 --- a/docs/source/client/actions/principals.md +++ b/docs/source/client/actions/principals.md @@ -1,10 +1,10 @@ # Principals -This endpoint will search for all the available principals in the local PAS plugins when given a query string. -We define a principal as any user or group in the system. +This endpoint will search for all the available principals in the local `PAS` plugins when given a query string. +A principal encompasses any user or group within the system. This endpoint requires an authenticated user. -## Principals Search +## Principals search ### Query function diff --git a/docs/source/client/actions/querysources.md b/docs/source/client/actions/querysources.md index d79df31286..ec1a7470f7 100644 --- a/docs/source/client/actions/querysources.md +++ b/docs/source/client/actions/querysources.md @@ -1,14 +1,14 @@ -# Querysources +# `Querysources` -## Get querysource +## Get `querysource` ### Query function -Use the `getQuerysourceQuery` function to get the query for fetching the querysource for a given path, field and query. +Use the `getQuerysourceQuery` function to get the query for fetching the `querysource` for a given path, field, and query. ### Hook -Use the `useGetQuerysource` hook to get the querysource for a given path, field and query. +Use the `useGetQuerysource` hook to get the `querysource` for a given path, field, and query. ### Parameters diff --git a/docs/source/client/actions/querystring.md b/docs/source/client/actions/querystring.md index 7e65da351c..57f0f5070f 100644 --- a/docs/source/client/actions/querystring.md +++ b/docs/source/client/actions/querystring.md @@ -1,8 +1,8 @@ -# Querystring +# `Querystring` The `@querystring` endpoint returns the `querystring` configuration of `plone.app.querystring`. -## Get Querystring +## Get `querystring` ### Query function diff --git a/docs/source/client/actions/querystringsearch.md b/docs/source/client/actions/querystringsearch.md index 2377e3720c..b109ecfcf3 100644 --- a/docs/source/client/actions/querystringsearch.md +++ b/docs/source/client/actions/querystringsearch.md @@ -1,8 +1,8 @@ -# Querystring Search +# `Querystring` search The `@querystring-search` endpoint returns search results that can be filtered on search criteria. -## Get Querystring Search +## Get `querystring` search ### Query function @@ -58,7 +58,7 @@ Use the `useGetQuerystringSearch` hook to get the search results for a page. - **Required**: No -## Get Querystring Search Using POST request +## Get `querystring` search using `POST` request ### Mutation function diff --git a/docs/source/client/actions/registry.md b/docs/source/client/actions/registry.md index 3492cbdcbd..538481a607 100644 --- a/docs/source/client/actions/registry.md +++ b/docs/source/client/actions/registry.md @@ -5,7 +5,7 @@ To address a specific record, the fully qualified dotted name of the registry re Reading or writing registry records require the `cmf.ManagePortal` permission. -## Get Registry List +## Get registry list ### Query function @@ -15,7 +15,7 @@ Use the `getRegistriesQuery` function to get the query for fetching the list of Use the `useGetRegistries` hook to get the list of all available registry records. -## Get Registry +## Get registry ### Query function @@ -31,7 +31,7 @@ Use the `useGetRegistry` hook to get a registry record at a given path. - **Required:** Yes -## Update Registry +## Update registry ### Mutation function diff --git a/docs/source/client/actions/relations.md b/docs/source/client/actions/relations.md index 7375746eeb..57a0a15f53 100644 --- a/docs/source/client/actions/relations.md +++ b/docs/source/client/actions/relations.md @@ -7,10 +7,10 @@ A single relation is defined by source, target, and relation name. You can define relations either with content type schema fields `RelationChoice` or `RelationList`, or with types `isReferencing` or `iterate-working-copy`. - Relations based on fields of a content type schema are editable by users. -- The relations `isReferencing` (block text links to a Plone content object) and `iterate-working-copy` (working copy is enabled and the content object is a working copy) are not editable. - They are created and deleted with links in text, respectively creating and deleting working copies. +- The relations `isReferencing` (block text links to a Plone content object) and `iterate-working-copy` (working copy is enabled and the content object is a working copy) aren't editable. + They're created and deleted with links in text, respectively creating and deleting working copies. -## Get Relations List +## Get relations list ### Query function @@ -20,7 +20,7 @@ Use the `getRelationsListQuery` function to get the query for fetching the list Use the `useGetRelationsList` hook to get the list of all existing relations user has access to. -## Get Relations +## Get relations ### Query function @@ -40,11 +40,11 @@ Use the `useGetRelations` hook to get the relations for the given parameters. - **Required**: No -- **onlyBroken**: boolean +- **`onlyBroken`**: `boolean` - **Required**: No -## Add Relation +## Add relation ### Mutation function @@ -73,7 +73,7 @@ Use the `useCreateRelations` hook to add a relation for the given parameters. - **Required**: Yes -## Fix Relation +## Fix relation ### Mutation function @@ -94,7 +94,7 @@ Use the `useFixRelations` hook to fix broken relations. - **Required**: No -## Delete Relation +## Delete relation ### Mutation function diff --git a/docs/source/client/actions/roles.md b/docs/source/client/actions/roles.md index 56dd692570..0ec010b667 100644 --- a/docs/source/client/actions/roles.md +++ b/docs/source/client/actions/roles.md @@ -3,7 +3,7 @@ Available roles in a Plone site can be queried by interacting with the `/@roles` endpoint on the portal root. This action requires an authenticated user. -## Get Roles +## Get roles ### Query function diff --git a/docs/source/client/actions/rules.md b/docs/source/client/actions/rules.md index a3d91f3f71..d026f04c8b 100644 --- a/docs/source/client/actions/rules.md +++ b/docs/source/client/actions/rules.md @@ -1,6 +1,6 @@ # Rules -## Get Rules +## Get rules ### Query function @@ -16,7 +16,7 @@ Use the `useGetRules` hook to get the content-rules for a page. - **Required:** Yes -## Add Rule +## Add rule ### Mutation function @@ -28,11 +28,11 @@ Use the `useCreateRule` hook to add a content-rule to a page. ### Parameters -- **ruleId**: string +- **`ruleId`**: string - **Required:** Yes -## Update Rules +## Update rules ### Mutation function @@ -73,7 +73,7 @@ Use the `useUpdateRules` hook to update content-rules for the given rule ids. - **Required:** No -## Delete Rule +## Delete rule ### Mutation function diff --git a/docs/source/client/actions/search.md b/docs/source/client/actions/search.md index 914cfd1fa0..3ebdb91346 100644 --- a/docs/source/client/actions/search.md +++ b/docs/source/client/actions/search.md @@ -3,14 +3,14 @@ Content in a Plone site can be searched for by invoking the `/@search` endpoint in any context: A search is _contextual_ by default. -In other words, it is bound to a specific context—a _collection_ in HTTP REST terms—and searches within that collection and any sub-collections. +In other words, it's bound to a specific context—a _collection_ in HTTP REST terms—and searches within that collection and any sub-collections. A Plone site is also a collection. -We therefore have a global search by invoking the `/@search` endpoint on the site root. -We also have contextual searches by invoking that endpoint on any other context. +A global search is accessible by calling the `/@search` endpoint on the site root. +Contextual searches are available by using the same endpoint on any other context. All searches use the same pattern. -## Get Search +## Get search ### Query function diff --git a/docs/source/client/actions/site.md b/docs/source/client/actions/site.md index d0d75216cc..d3d3a3cbfd 100644 --- a/docs/source/client/actions/site.md +++ b/docs/source/client/actions/site.md @@ -3,7 +3,7 @@ The `@site` endpoint provides general site-wide information, such as the site title, logo, and other information. It uses the `zope2.View` permission, which requires appropriate authorization. -## Get Site +## Get site ### Query function diff --git a/docs/source/client/actions/system.md b/docs/source/client/actions/system.md index 6b865af911..70e1803fb6 100644 --- a/docs/source/client/actions/system.md +++ b/docs/source/client/actions/system.md @@ -2,7 +2,7 @@ The `@system` endpoint exposes system information about the Plone backend. -## Get System Information +## Get system information ### Query function diff --git a/docs/source/client/actions/transactions.md b/docs/source/client/actions/transactions.md index ccaba11562..56bedd14f9 100644 --- a/docs/source/client/actions/transactions.md +++ b/docs/source/client/actions/transactions.md @@ -2,9 +2,9 @@ The `@transactions` endpoint exposes transactions that have been made through the Plone website. Each change through the Plone website is listed. -It also allows to revert transactions so that the Plone website can be reverted to a previous state. +It also allows to revert transactions so that the Plone website can be reverted to a earlier state. -## Get Transactions +## Get transactions ### Query function @@ -14,7 +14,7 @@ Use the `getTransactionsQuery` function to get the query for fetching the list o Use the `useGetTransactions` hook to get the list of all transactions in the portal. -## Revert Transactions +## Revert transactions ### Mutation function @@ -31,6 +31,6 @@ Use the `useRevertTransactions` hook to revert transactions in the portal. - **Required**: Yes - It can have the following fields: - - **transactionIds**: string[] + - **`transactionIds`**: string[] - **Required**: Yes diff --git a/docs/source/client/actions/translations.md b/docs/source/client/actions/translations.md index dd72e822c1..3666de7bc1 100644 --- a/docs/source/client/actions/translations.md +++ b/docs/source/client/actions/translations.md @@ -2,7 +2,7 @@ Translations endpoint is used to handle the translation information of the content objects. -## Get Translation +## Get translation ### Query function @@ -18,7 +18,7 @@ Use the `useGetTranslation` hook to get the translation information of the given - **Required:** Yes -## Link Translation +## Link translation ### Mutation function @@ -43,11 +43,11 @@ Use the `useLinkTranslation` hook to link a translation to the given path. - **Required:** Yes -## Unlink Translation +## Unlink translation ### Mutation function -Use the `unlinkTranslationMutation` function to get the mutation for unlinking a translation from the given path. +Use the `unlinkTranslationMutation` function to get the mutation for `unlinking` a translation from the given path. ### Hook diff --git a/docs/source/client/actions/types.md b/docs/source/client/actions/types.md index 533c59056a..255c97e323 100644 --- a/docs/source/client/actions/types.md +++ b/docs/source/client/actions/types.md @@ -2,7 +2,7 @@ Available content types in a Plone site can be listed and queried by accessing the `/@types` endpoint on any context. -## Get Types List +## Get types list ### Query function @@ -12,7 +12,7 @@ Use the `getTypesQuery` function to get the query for fetching the list of all a Use the `useGetTypes` hook to get the list of all available types. -## Get Type +## Get type ### Query function @@ -24,11 +24,11 @@ Use the `useGetType` hook to get the information about the content type provided ### Parameters -- **contentPath**: string +- **`contentPath`**: string - **Required:** Yes -## Get Type Field +## Get type field ### Query function @@ -44,7 +44,7 @@ Use the `useGetTypeField` hook to get the information about the field of the typ - **Required:** Yes -## Add Type Field/Fieldset +## Add type field/fieldset ### Mutation function @@ -56,7 +56,7 @@ Use the `useCreateTypeField` hook to add a field/fieldset to the type provided. ### Parameters -- **contentPath**: string +- **`contentPath`**: string - **Required:** Yes @@ -81,7 +81,7 @@ Use the `useCreateTypeField` hook to add a field/fieldset to the type provided. - **Required:** Yes -## Update Type Field/Fieldset +## Update type field/fieldset ### Mutation function @@ -93,7 +93,7 @@ Use the `useUpdateTypeField` hook to update a field/fieldset of the type provide ### Parameters -- **contentPath**: string +- **`contentPath`**: string - **Required:** Yes diff --git a/docs/source/client/actions/upgrade.md b/docs/source/client/actions/upgrade.md index 0fb4dccfe8..d939f26dd6 100644 --- a/docs/source/client/actions/upgrade.md +++ b/docs/source/client/actions/upgrade.md @@ -3,7 +3,7 @@ A Plone site needs to be in sync with the version available on the file system. The `@upgrade` endpoint exposes upgrade information about the Plone backend, and supports running the upgrade of the site. -## Get Upgrade Information +## Get upgrade information ### Query function @@ -13,7 +13,7 @@ Use the `getUpgradeQuery` function to get the query for fetching the upgrade inf Use the `useGetUpgrade` hook to get the upgrade information about the Plone backend. -## Run Upgrade +## Run upgrade ### Mutation function diff --git a/docs/source/client/actions/users.md b/docs/source/client/actions/users.md index 01eb1e653e..169618cbab 100644 --- a/docs/source/client/actions/users.md +++ b/docs/source/client/actions/users.md @@ -3,7 +3,7 @@ Available users in a Plone site can be created, queried, updated, and deleted by interacting with the `/@users` endpoint on portal root. This action requires an authenticated user: -## Get Users list +## Get users list ### Query function @@ -19,7 +19,7 @@ Use the `useGetUsers` hook to get the list of all users in the portal. - **Required**: No -- **groupsFilter**: string[] +- **`groupsFilter`**: string[] - **Required**: No @@ -31,7 +31,7 @@ Use the `useGetUsers` hook to get the list of all users in the portal. - **Required**: No -## Get User +## Get user ### Query function @@ -47,7 +47,7 @@ Use the `useGetUser` hook to get the information about an individual user at the - **Required**: Yes -## Add User +## Add user ### Mutation function @@ -100,7 +100,7 @@ Use the `useCreateUser` hook to add a new user at the given path. - **Required**: Yes -## Update User +## Update user ### Mutation function @@ -149,7 +149,7 @@ Use the `useUpdateUser` hook to update an existing user at the given path. - **Required**: No -## Delete User +## Delete user ### Mutation function @@ -165,7 +165,7 @@ Use the `useDeleteUser` hook to delete an existing user at the given path. - **Required**: Yes -## Update User Password +## Update user password ### Mutation function @@ -194,7 +194,7 @@ Use the `useUpdatePassword` hook to update an existing user password at the give - **Required**: Yes -## Reset User Password +## Reset user password ### Mutation function @@ -210,7 +210,7 @@ Use the `useResetPassword` hook to reset an existing user password at the given - **Required**: Yes -## Reset User Password with Token +## Reset user password with token ### Mutation function diff --git a/docs/source/client/actions/userschema.md b/docs/source/client/actions/userschema.md index b8d4d76143..cc115105b6 100644 --- a/docs/source/client/actions/userschema.md +++ b/docs/source/client/actions/userschema.md @@ -1,12 +1,12 @@ # User schema Users in Plone have a set of properties defined by a default set of fields such as `fullname`, `email`, `portrait`, and other fields. -These properties define the site user's profile and the user itself via the Plone UI, or the site managers can add them in a variety of ways including PAS plugins. +These properties define the site user's profile and the user itself via the Plone UI, or the site managers can add them in a variety of ways including `PAS` plugins. -These fields are dynamic and customizable by integrators so they do not adhere to a fixed schema interface. -This dynamic schema is exposed by this endpoint in order to build the user's profile form. +These fields are dynamic and customizable by integrators so they don't adhere to a fixed schema interface. +This dynamic schema is exposed by this endpoint to build the user's profile form. -## Get User Schema +## Get user schema ### Query function diff --git a/docs/source/client/actions/vocabularies.md b/docs/source/client/actions/vocabularies.md index cfff6f9e79..24d5d4c910 100644 --- a/docs/source/client/actions/vocabularies.md +++ b/docs/source/client/actions/vocabularies.md @@ -3,7 +3,7 @@ Vocabularies are a set of allowed choices that back a particular field. They contain so-called _terms_ which represent those allowed choices. -## Get Vocabularies List +## Get vocabularies list ### Query function @@ -13,7 +13,7 @@ Use the `getVocabulariesListQuery` function to get the query for fetching the li Use the `useGetVocabulariesList` hook to get the list of all available vocabularies. -## Get Vocabularies +## Get vocabularies ### Query function diff --git a/docs/source/client/actions/workflow.md b/docs/source/client/actions/workflow.md index c0f7ff45c9..2e24ef1c83 100644 --- a/docs/source/client/actions/workflow.md +++ b/docs/source/client/actions/workflow.md @@ -5,9 +5,9 @@ Currently the workflow support is limited to executing transitions on content. ``` In Plone, content almost always has a {term}`workflow` attached. -We can get the current state and history of an object by issuing a `GET` request for any context: +Retrieve an object's current state and history by sending a `GET` request for any context: -## Get Workflow +## Get workflow ### Query function @@ -23,7 +23,7 @@ Use the `useGetWorkflow` hook to get the workflow for the given path. - **Required:** Yes -## Add Workflow +## Add workflow ### Mutation function diff --git a/docs/source/client/actions/workingcopy.md b/docs/source/client/actions/workingcopy.md index b327e5879e..473ce48312 100644 --- a/docs/source/client/actions/workingcopy.md +++ b/docs/source/client/actions/workingcopy.md @@ -1,13 +1,13 @@ -# Working Copy +# Working copy ```{note} This feature is available only on Plone 5 or greater. ``` Plone has a _working copy_ feature provided by the core package `plone.app.iterate`. -It allows the users to create a working copy of a published or live content object, and work with it until it is ready to be published without having to edit the original object. +Users can create a working copy of a live content object, allowing independent editing before publishing, without altering the original object. -## Get Working Copy +## Get working copy ### Query function @@ -23,7 +23,7 @@ Use the `useGetWorkingcopy` hook to get the working copy of a content object. - **Required:** Yes -## Add Working Copy +## Add working copy ### Mutation function @@ -39,7 +39,7 @@ Use the `useCreateWorkingcopy` hook to add a working copy of a content object. - **Required:** Yes -## Check In Working Copy +## Check in working copy ### Mutation function @@ -55,7 +55,7 @@ Use the `useCheckinWorkingcopy` hook to check in a working copy to update the or - **Required:** Yes -## Delete Working Copy +## Delete working copy ### Mutation function diff --git a/docs/source/client/future-improvements.md b/docs/source/client/future-improvements.md index 37bdfdf351..92623df24e 100644 --- a/docs/source/client/future-improvements.md +++ b/docs/source/client/future-improvements.md @@ -33,24 +33,24 @@ Then we can import action hooks directly from the package like: `import { useGet This would mean that anyone who wants to use `@plone/client` would need to install `@plone/client @tanstack/react-query axios` now, but it has some added benefits too: 1. mocking direct dependencies of projects is much easier. We can then mock `axios` directly instead of using `nock`, although the latter has no clear downsides either -2. the projects that wants to use `@plone/client` can bring their own `@tanstack/react-query` - otherwise they would need to import the `@tanstack/react-query` dependency indirectly from `@plone/client` and then cannot have their own version of it without conflicts - same applies to any project that already uses `axios` as well -3. projects using other frameworks like vue would need to install `@tanstack/vue-query` anyway, so we need to have some consistency around frameworks, thus it makes sense that projects with react also bring their own version of the dependency +2. the projects that wants to use `@plone/client` can bring their own `@tanstack/react-query` - otherwise they would need to import the `@tanstack/react-query` dependency indirectly from `@plone/client` and then can't have their own version of it without conflicts - same applies to any project that already uses `axios` as well +3. projects using other frameworks like Vue would need to install `@tanstack/vue-query` anyway, so we need to have some consistency around frameworks, thus it makes sense that projects with react also bring their own version of the dependency -## SSR support in @plone/client +## `SSR` support in `@plone/client` -For implementing SSR with TanStack Query, the challenge is to figure out the data dependencies for a component that is rendered on the server. +For implementing `SSR` with TanStack Query, the challenge is to figure out the data dependencies for a part that's rendered on the server. -We can consider the following approaches to implement SSR: +We can consider the following approaches to implement `SSR`: ### Manual approach -In this approach, Server-Side Rendering (SSR) is achieved by explicitly controlling the prefetching and caching of queries using the TanStack Query library in conjunction with the @plone/client library. +In this approach, Server-Side Rendering (SSR) is achieved by explicitly controlling the `prefetching` and caching of queries using the TanStack Query library in conjunction with the @plone/client library. The steps for this approach are as follows: 1. Collect all the query options (query key and query function) for all @plone/client action calls that want to enable SSR caching -2. Trigger a prefetch on all collected queries and wait until resolution -3. Render the component to string on the server +2. Trigger a `prefetch` on all collected queries and wait until resolution +3. Render the part to string on the server 4. Pass the data from collected queries to TanStack Query cache hydration Refer to official docs for more information: https://tanstack.com/query/v4/docs/react/guides/ssr @@ -63,7 +63,7 @@ Do the following on each API call in the handler function: 1. Render the component to string twice on the server 2. On the first render, collect query options (query key and query function) for all @plone/client action calls that want to enable SSR caching -3. Trigger a prefetch on all collected queries and wait until resolution +3. Trigger a `prefetch` on all collected queries and wait until resolution 4. On the second render pass the data from collected queries to TanStack Query cache hydration POC using the approach described below: https://github.com/hemant-hc/tanstack-query-ssr-example diff --git a/docs/source/client/index.md b/docs/source/client/index.md index 90745f291a..2b72825dab 100644 --- a/docs/source/client/index.md +++ b/docs/source/client/index.md @@ -10,7 +10,7 @@ myst: # Plone REST API JavaScript client This part of the documentation describes the Plone REST API JavaScript client. -It is a framework agnostic library based on [TanStack Query](https://tanstack.com/query/latest). +It's a framework agnostic library based on [TanStack Query](https://tanstack.com/query/latest). ```{toctree} :caption: Contents diff --git a/docs/source/client/misc.md b/docs/source/client/misc.md index 7eb1ac3d5a..2664e6710b 100644 --- a/docs/source/client/misc.md +++ b/docs/source/client/misc.md @@ -4,8 +4,8 @@ The `queryWithConfig` and `mutationWithConfig` functions are utility functions that accept two parameters: `method`, representing the original function, and `configGetter`, a function returning the required configuration object. Using `configGetter` instead of the direct configuration ensures the latest value is used, preventing closures. -These functions return another function, taking the same parameters as the original but excluding the config property. -They then invoke the original function with the configuration fetched from configGetter. +These functions return another function, taking the same parameters as the original but excluding the `config` property. +They then invoke the original function with the configuration fetched from `configGetter`. Utilizing these functions reduces import clutter in client files by obviating the need to import argument types for each query or mutation function. ## `queryHookFromQuery` and `mutationHookFromMutation` functions @@ -13,4 +13,4 @@ Utilizing these functions reduces import clutter in client files by obviating th The `queryHookFromQuery` and `mutationHookFromMutation` functions are utility functions that take a query or mutation function respectively, and yield a corresponding hook function. They use helper functions to extract the types of argument and return objects from the given query or mutation function. The resulting hook function is returned with the appropriate type casting. -They use useQuery and useMutation internally so that the user doesn't have to use `useQuery` or `useMutation` directly. +They use `useQuery` and `useMutation` internally so that the user doesn't have to use `useQuery` or `useMutation` directly. diff --git a/docs/source/client/quick-start.md b/docs/source/client/quick-start.md index 63ed27773f..34c31cb795 100644 --- a/docs/source/client/quick-start.md +++ b/docs/source/client/quick-start.md @@ -1,8 +1,8 @@ -# Quick Start +# Quick start -The Javascript Plone client is a library that provides easy access to the Plone REST API from a client written in TypeScript. +The JavaScript Plone client is a library that provides easy access to the Plone REST API from a client written in TypeScript. This client can be used as an alternative to directly interacting with the Plone REST API. -It is based on the foundations that [@tanstack/query](https://tanstack.com/query/latest) lays off. +It's based on the foundations that [@tanstack/query](https://tanstack.com/query/latest) lays off. It should be possible to use it in React/Vue/Solid/Svelte projects. It provides the artifacts that TanStack Query requires to work: @@ -11,14 +11,14 @@ It provides the artifacts that TanStack Query requires to work: - API request layer The API request layer allows to build and send arbitrary requests to Plone REST API endpoints. -It has the potential to also be able to send requests to other APIs (provided the custom Query options factories/functions). +It has the potential to also be able to send requests to other `APIs` (provided the custom Query options factories/functions). -The Javascript Plone client is conceived to work with TanStack Query, the query or mutation functions can be used to call any Plone REST API endpoint without using it. -These functions can be used in other use cases like command line helpers, scripts or programatic tests. +The JavaScript Plone client is conceived to work with TanStack Query, the query or mutation functions can be used to call any Plone REST API endpoint without using it. +These functions can be used in other use cases like command line helpers, scripts or programmatic tests. ## Installation​ -To install the Javascript Plone client run the following command: +To install the JavaScript Plone client run the following command: ```shell yarn add @plone/client @@ -42,7 +42,7 @@ const client = ploneClient.initialize({ ## Query (or mutation) options factories -A query (or mutation) options factory is a TanStack Query basic artifact, a function that returns an object, ready to be passed to a React Query hook (in case that we are in a React environment) or to the TanStack Query adapter that we are using in our framework. +A query (or mutation) options factory in TanStack Query is a function providing an object for React Query hooks or the utilized framework's Query adapter. ```ts import { useQuery } from '@tanstack/react-query'; @@ -52,10 +52,10 @@ const { getContentQuery } = client; const { data, isLoading } = useQuery(getContentQuery({ path: pathname })); ``` -The query (or mutation) factories ara functions that take an object as arguments. -These arguments can have some common properties (like the path) and other specific depending on the nature of the endpoint that they are correspond with. +The query (or mutation) factories are functions that take an object as arguments. +These arguments can have some common properties (like the path) and other specific depending on the nature of the endpoint that they're correspond with. -This is a complete example of the usage of the client in a React client component: +This is a complete example of the usage of the client in a React client part: ```jsx import { useQuery } from '@tanstack/react-query'; @@ -87,7 +87,7 @@ export default function Title() { } ``` -## Plone Client React Hooks +## Plone client react hooks This package also provides custom hooks for actions that can be used directly in functional React components. diff --git a/docs/source/conf.py b/docs/source/conf.py index a57bd18da5..e159188e43 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -144,6 +144,7 @@ myst_enable_extensions = [ "deflist", # You will be able to utilise definition lists # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists + "fieldlist", # For docstrings, "linkify", # Identify “bare” web URLs and add hyperlinks. "colon_fence", # You can also use ::: delimiters to denote code fences,\ # instead of ```. diff --git a/packages/client/news/5491.documentation b/packages/client/news/5491.documentation new file mode 100644 index 0000000000..05e63378df --- /dev/null +++ b/packages/client/news/5491.documentation @@ -0,0 +1 @@ +Fixed documentation errors and improved documentation in the "docs/source/client" directory, specifically changing inline literals formatting to exact matches instead of bold, and ensuring all headings are in sentence case to reduce spelling errors. See https://6.docs.plone.org/volto/client/index.html for usage. @Hrittik20 \ No newline at end of file diff --git a/packages/volto/src/components/manage/Contents/Contents.jsx b/packages/volto/src/components/manage/Contents/Contents.jsx index 9cbd896903..97778e0c1b 100644 --- a/packages/volto/src/components/manage/Contents/Contents.jsx +++ b/packages/volto/src/components/manage/Contents/Contents.jsx @@ -1191,7 +1191,7 @@ class Contents extends Component { return this.props.token && this.props.objectActions?.length > 0 ? ( <> {folderContentsAction ? ( - + diff --git a/packages/volto/src/components/theme/View/TabularView.jsx b/packages/volto/src/components/theme/View/TabularView.jsx index 8fe47e9b00..586e7797ab 100644 --- a/packages/volto/src/components/theme/View/TabularView.jsx +++ b/packages/volto/src/components/theme/View/TabularView.jsx @@ -30,7 +30,7 @@ const TabularView = ({ content }) => { )}
- +