
Vactory Flag simplifies the process for developers to easily enable flag features for various content types.

<Callout>

In this tutorial, we'll use Academy (vactory_academy) content as an example.

</Callout>

#### Below are the steps to follow

##### 1. Enable the module with the following drush command
`drush en vactory_decoupled_flag -y`

##### 2. Enabling flags for content type
Go to content type configuration
`/admin/structure/types/manage/vactory_academy` and enable flags for this content type, as illustrated in the image below

![](/images/vactory-flag/flag-config.png)

##### 3. Expose flag fields to the frontend

To enable flag features for any content type listing, add the following fields to the relevant widget configuration (widget of type json_api_collection)

- **has_flag:** Indicates if the flag is enabled for this content type.
- **is_flagged:** Indicates if a specific node is flagged by the current user.

```jsx
collection:
  type: json_api_collection
  label: 'JSON:API'
  options:
    '#required': TRUE
    '#default_value':
      id: "vactory_academy_favorite"
      resource: node--vactory_academy
      filters:
        - fields[node--vactory_academy]=is_flagged,has_flag,...
```

##### 4. Adding the Flag in the Frontend
Receive the has_flag and is_flagged fields, then include them in the normalizer.

```jsx
export const normalizeNode = (node) => {
	return {
		id: node?.drupal_internal__nid,
		hasFlag: node?.has_flag,
		isFlagged: node?.is_flagged,
        ...
	}
}
```

In the relevant widget (card componenet), add the Flag component as follows

```jsx title=modules/academy/AcademyCard.jsx
import { Flag } from "@/ui"

export const AcademyCard = ({
	title,
	id,
	isFlagged,
	hasFlag,
}) => {
    ...
    {hasFlag && (
      <Flag
		id={id}
		title={title}
		module="default_flag"
		className="absolute right-4 top-4 cursor-pointer"
		isFlagged={isFlagged}
        reloadPage={reloadPage}
	  />
    )}
    ...
}

```
We can also include it on the detail page by adding the two fields to the node configuration

```jsx title=modules/academy/AcademyNode.jsx
export const config = {
	id: "node--vactory_academy",
	params: {
		fields: {
			"node--vactory_academy":
				"has_flag,is_flagged,...",
		},
		...
	},
}
```

##### 5. Create a DF to list content flagged by the current user

Create a JSON:API collection for the desired content type and ensure you have added the following elements:
- Expose our key fields, is_flagged and has_flag
- Add this token to ensure the retrieval of only the flagged content by the current user
**[vactory:flagged_nodes:vactory_academy]**

<Callout>
NB : replace 'vactory_academy' with your content type.
</Callout>

- Include this cache configuration in your json_api_collection to make your listing cacheable per user and flagging entity
```jsx
cache_tags:
  - flagging_list
cache_contexts
 - user
```

Here is the complete example

```jsx
collection:
  type: json_api_collection
  label: 'JSON:API'
  options:
    '#required': TRUE
    '#default_value':
      id: "vactory_academy_favorite"
      resource: node--vactory_academy
      filters:
        - fields[node--vactory_academy]=is_flagged,has_flag,...
        ...
        - "[vactory:flagged_nodes:vactory_academy]"
      cache_tags:
        - flaggging_list
      cache_contexts:
        - user
```
After setting up the widget for this dynamic field on the frontend, define the 'reloadPage' function and pass it to the card componenet.
This helps update the data when a user unflags content.

```jsx title=modules/academy/AcademyFavoriteWidget.jsx

const FavoriteAcademy = ({ data }) => {
	
	const reloadPage = async () => {
		const nids = await getCurrentUserFalggedArticles()
		setFilters((prev) => {
			let filters = {
				...prev,
			}
			filters.page = {
				...filters.page,
				offset: 0,
			}
			filters.filter.internal_favourite = {
				condition: {
					path: "drupal_internal__nid",
					operator: "IN",
					value: nids?.nids,
				},
			}
			return filters
		})
	}
	const getCurrentUserFalggedArticles = async () => {
		const response = await drupal.fetch(`api/flagging/all/vactory_academy`, {
			withAuth: true,
			method: "GET",
		})
		if (response.ok) {
			return await response.json()
		}
		return []
	}
	useUpdateEffect(async () => {
		const nids = await getCurrentUserFalggedArticles()
		setFilters((prev) => {
			let filters = {
				...prev,
			}
			// Update pager.
			filters.page = {
				...filters.page,
				offset: (pager - 1) * (filters?.page?.limit || defaulPagetLimit),
			}
			filters.filter.internal_favourite = {
				condition: {
					path: "drupal_internal__nid",
					operator: "IN",
					value: nids?.nids,
				},
			}
			return filters
		})
	}, [pager])
	return (
        ...
		<AcademyCard {...post} reloadPage={reloadPage} />
		...
	)
}


```




Vactory flag


### Overview

This guide explains how to upgrade your existing paragraphs implementation to include copy, paste, and delete functionality. 

We'll break this down into the original implementation and the enhanced version with the new features.

This feature is enabled only for content types that include paragraphs. The field used to determine this is **field_vactory_paragraph**, which is mandatory for the feature to function.

### Prerequisites

Before configuring the Copy-Paste feature, ensure the following requirements are met:

The project uses **@vactorynext/core** and **voidagency/vactory_starter_kit**, which support this functionality.

### Original Implementation

The original implementation simply maps through paragraphs and renders them using a **ParagraphsController**:

```jsx title=./components/modules/contrib/page/PageNode.jsx
{node?.field_vactory_paragraphs.map((paragraph) => (
    <React.Fragment key={paragraph.id}>
        <ParagraphsController
            key={paragraph.id}
            data={paragraph}
            hasAMP={false}
            isAmp={isAmp}
            DF_DEV_MAPPING={DF_DEV_MAPPING}
            ContainerComponent={Container}
            ImageComponent={Image}
            Widgets={Widgets}
            IconComponent={Icon}
            HeadingComponent={Heading}
            TextComponent={Text}
            TabsComponent={Tabs}
            AccordionComponent={Accordion}
            isAnimated={true}
            AnimationComponent={CustomAnimation}
            animationKeyframe={fadeInRightAnimation}
        />
    </React.Fragment>
))}
```


### Enhanced Implementation

To enable copy-paste functionality, we’ll introduce a **ParagraphWrapper** and **ParagraphToolbox** components that handles the state for the copy, paste, delete and insert paragraph actions for each paragraph.

#### Step 1: Adding the Wrapper Component

To add copy-paste functionality, wrap the entire paragraph section in a ParagraphWrapper. 
This component will manage state for the actions (copy, paste, delete), enabling each paragraph to be individually controlled and modified.

Replace your existing paragraph rendering code with the following:

Navigate to the Node Template file in your Next.js project. For example, for the content type vactory_page, edit the file located at:

`components/modules/contrib/page/PageNode.jsx`

```jsx title=./components/modules/contrib/page/PageNode.jsx
import { ParagraphsController, ParagraphWrapper } from "@vactorynext/core/paragraphs"
import { toast } from "react-toastify"

<>
    <ParagraphWrapper
        initialParagraphs={node?.field_vactory_paragraphs}
        nid={node.drupal_internal__nid}
        toast={toast}
    >
        {({
            paragraphs,
			handleCopy,
			handlePaste,
			handleDelete,
			handleInsert,
			templates,
			isLiveMode = false,
			showPasteButtons
        }) => (
           <>
				{paragraphs?.map((paragraph, index) => (
					<React.Fragment key={paragraph.id}>
						<ParagraphsController
							key={paragraph.id}
							data={paragraph}
							hasAMP={false}
							isAmp={isAmp}
							DF_DEV_MAPPING={DF_DEV_MAPPING}
							ContainerComponent={Container}
							ImageComponent={Image}
							Widgets={Widgets}
							IconComponent={Icon}
							HeadingComponent={Heading}
							TextComponent={Text}
							TabsComponent={Tabs}
							AccordionComponent={Accordion}
							isAnimated={true}
							AnimationComponent={CustomAnimation}
							animationKeyframe={fadeInRightAnimation}
							weight={index}
						/>
					</React.Fragment>
				))}
			</>
        )}
    </ParagraphWrapper>
</>
```

<Callout>
Don't forget to import the toast component and pass it to the ParagraphWrapper component as demonstrated above. This is essential for displaying notifications.
</Callout>

#### Step 2: Adding Action Buttons for Each Paragraph

Now, add **ParagraphToolbox** component which is had the action buttons for copy, paste, delete and insert template actions. These buttons will allow users to copy a paragraph, paste and insert a new paragraph before or after, and delete paragraphs as needed.

Updated Code with Action Buttons:


* **1. import ParagraphToolbox component**

```jsx title=./components/modules/contrib/page/PageNode.jsx
import {
	ParagraphsController,
	ParagraphWrapper,
    // highlight-start
	ParagraphToolbox,
    // highlight-end
} from "@vactorynext/core/paragraphs"
```

* **1. Add ParagraphToolbox component to your code**

```jsx title=./components/modules/contrib/page/PageNode.jsx
	<ParagraphWrapper
		initialParagraphs={node?.field_vactory_paragraphs}
		nid={node.drupal_internal__nid}
		toast={toast}
	>
		{({
			paragraphs,
			handleCopy,
			handlePaste,
			handleDelete,
			handleInsert,
			templates,
			isLiveMode = false,
			showPasteButtons,
		}) => (
			<>
				{paragraphs?.map((paragraph, index) => (
					<React.Fragment key={paragraph.id}>
						{isLiveMode && (
							<ParagraphToolbox
								onHandleCopy={handleCopy}
								onHandlePast={handlePaste}
								onHandleDelete={handleDelete}
								handleInsert={handleInsert}
								props={{
									parent_id: node.drupal_internal__nid,
									pid: paragraph.drupal_internal__id,
									type: paragraph.type,
									weight: index,
									isFirst: index === 0,
									templates,
								}}
								showPasteButtons={showPasteButtons}
							/>
						)}
						<ParagraphsController
							key={paragraph.id}
							data={paragraph}
							hasAMP={false}
							isAmp={isAmp}
							DF_DEV_MAPPING={DF_DEV_MAPPING}
							ContainerComponent={Container}
							ImageComponent={Image}
							Widgets={Widgets}
							IconComponent={Icon}
							HeadingComponent={Heading}
							TextComponent={Text}
							TabsComponent={Tabs}
							AccordionComponent={Accordion}
							isAnimated={true}
							AnimationComponent={CustomAnimation}
							animationKeyframe={fadeInRightAnimation}
							weight={index}
						/>
						{isLiveMode && paragraphs?.length === index + 1 && (
							<ParagraphToolbox
								onHandleCopy={handleCopy}
								onHandlePast={handlePaste}
								onHandleDelete={handleDelete}
								handleInsert={handleInsert}
								props={{
									parent_id: node.drupal_internal__nid,
									pid: paragraph.drupal_internal__id,
									type: paragraph.type,
									weight: paragraphs?.length === index + 1 ? index + 1 : index,
									isFirst: false,
									isLast: paragraphs?.length === index + 1,
									templates,
								}}
								showPasteButtons={showPasteButtons}
							/>
						)}
					</React.Fragment>
				))}
			</>
		)}
	</ParagraphWrapper>
```

#### Step 3: Adding the field_live_mode field to the configuration object

Edit the configuration constants in the Node Template to include the **field_live_mode** field. 

Update the configuration object as follows:

```jsx
export const config = {
    id: "node--vactory_page",
    params: {
        fields: {
            "node--vactory_page": 
                "field_vactory_paragraphs,node_bg_image,node_class,node_body_class,node_banner_title,node_banner_image,node_banner_mobile_image,node_banner_description,node_banner_showbreadcrumb,field_sticky_ancre,field_df_sticky,field_live_mode",
            "media--image": "thumbnail",
            "file--image": "uri",
            "paragraph--vactory_component": 
                "drupal_internal__id,paragraph_section,paragraph_identifier,paragraph_container,field_animation,container_spacing,paragraph_css_class,paragraph_background_color,paragraph_background_image,field_vactory_component,field_vactory_title,field_background_color,field_paragraph_hide_lg,field_paragraph_hide_sm,field_position_image_x,field_position_image_y,field_size_image,field_vactory_flag,field_vactory_flag_2,paragraph_background_parallax",
            "paragraph--vactory_paragraph_multi_template": 
                "drupal_internal__id,paragraph_section,paragraph_identifier,paragraph_container,field_animation,container_spacing,paragraph_css_class,paragraph_background_color,paragraph_background_image,field_vactory_component,field_vactory_title,field_paragraph_introduction,field_vactory_paragraph_tab,field_background_color,field_multi_paragraph_type,field_paragraph_hide_lg,field_paragraph_hide_sm,field_position_image_x,field_position_image_y,field_size_image,field_vactory_flag,field_vactory_flag_2,paragraph_background_parallax",
        },
        include: 
            "field_vactory_paragraphs,field_vactory_paragraphs.field_vactory_paragraph_tab,field_vactory_paragraphs.paragraph_background_image,field_vactory_paragraphs.paragraph_background_image.thumbnail,node_bg_image,node_bg_image.thumbnail,node_banner_image,node_banner_mobile_image,node_banner_image.thumbnail,node_banner_mobile_image.thumbnail",
    },
};
```

<Callout>The addition of the field_live_mode field is used to determine whether the current user has the permission to utilize the Copy-Paste feature.</Callout>

Copy past


### Overview

As an example, we'll demonstrate how to filter a list of "projects" by their associated **filiale**. 

![](/images/node-filtre/node-filtre.png)

Follow these steps to expose the list of **filiale** to your front-end application and integrate the filter into your listing.

### Step 1: Expose the List of Filiales to the Front-End

To make the list of filiales available to the front-end application, modify the settings.yml configuration file. 
This configuration will expose all nodes of the type "filiale."

Add the following code snippet to your settings.yml file:

```jsx
filiales:
  type: decoupled_entity_reference
  options:
    '#default_value':
      entity_reference:
        bundle: filiale
        entity_type: node
```

This configuration serves to expose all nodes of the "filiale" content type. It allows the front-end application to retrieve and use these nodes in various features, such as filtering.

### Step 2: Map the Exposed Data on the Front-End

Once the list is available on the front-end, map the data to a usable format for your filter component. 
Use the following code snippet to transform the filiales data into filter options.

```jsx
const allFiliales = {
    id: "all",
    value: "all",
    label: t("Filiale"), // Default label for "All Filiales"
    // slug: "all",
    disabled: false,
}
const filialeOptions = data.components[0].filiales.map((filiale) => ({
  id: filiale.id,
  value: filiale.id,
  label: filiale.label,
  // slug: filiale.label.toLowerCase().replace(/\s+/g, "-"),
  disabled: false,
}));
```

### Step 3: Integrate the Filter into the Listing

```jsx
<UseListingFilter
  filters={[
    {
      type: "select",
      componentType: SelectNative,
      name: "secteur",
      id: "secteur",
      label: t("Nx:Secteur"),
      variant: "filter",
      list: context.terms?.secteur_projet,
      className: "min-w-[25%] w-full",
      position: 1,
    },
    // highlight-start
    {
      type: "select",
      componentType: SelectNative,
      name: "filiale",
      id: "filiale",
      label: t("Nx:Filiale"),
      variant: "filter",
      className: "min-w-[25%] w-full",
      list: [allFiliales, ...filialeOptions], // Include allFiliales as the default option
      position: 2,
    },
    // highlight-end
    {
      type: "select",
      componentType: SelectNative,
      name: "ville",
      id: "ville",
      label: t("Nx:Villes"),
      variant: "filter",
      className: "min-w-[25%] w-full",
      list: context.terms?.villes,
      position: 3,
    },
  ]}
  control={control}
/>
```

### Step 3: Integrate the Filter into the filters object

```jsx
setFilters((prev) => {
			let filters = {
				...prev,
			}
            // highlight-start
			if (!selectedFiliale || selectedFiliale === allFiliales.id) {
				delete filters?.filter?.filiale
			} else {
				filters.filter.filiale = {
					condition: {
						path: "field_filiale.drupal_internal__nid",
						operator: "=",
						value: selectedFiliale,
					},
				}
			}
            // highlight-end
})
```

Listing - filtre by entity


- Visit : `/fr/admin/features`
- Enable shield
- Setup your **Credentials** using a user and a password.
- Paths is optional but you can use it to only apply basic auth to those paths, patterns used should match https://www.npmjs.com/package/path-to-regexp.
By default it will apply basic auth to all requests with a few exceptions.

![](/images/basic-auth/paths.png)

<Callout icon="⚠️">
Due to the nature of NextJs, this feature only works in hard navigations and not soft ones using Next Router to navigate between pages.
</Callout>

Basic Auth


## Introduction 

The main utility of the taxonomy results module is to track the frequency of term usage within
the desired entity. 

**Concrete Example** : For instance, it allows us to display exclusively those terms that 
have been used in the listing filters.

## Installation 

1. Enable the module with the following drush command : `drush en vactory_taxonomy_results -y`

2. Visit : `/admin/config/system/taxonomy-results-count`

You need to enable for each entity type the concerned bundle that results count should be calculated for related taxonomy term entity reference fields (whenever exists).

![](/images/taxonomy-results/taxonomy-results.png)

Then you need to check **Calculate taxonomy term results after saving configuration** checkbox to start counting each term results process after saving configuration

![](/images/taxonomy-results/calculate-terms-after-saving.png)

Then try to access results count entity list through `/admin/content/term-result-count`

![](/images/taxonomy-results/view-count-terms.png)

## Custom Plugin TermResultCountManager

The module by default provide a default term result count plugin, you could add you're own calculation, by creating a new plugin, the plugin class should be defined in 
`my_module/src/Plugin/TermResultCounter` and implements the method termResultCount.

See example on: `vactory_taxonomy_results/src/Plugin/TermResultCounter/DefaultTermResultCounter.php`

## Client Side

```jsx title=./apps/starter/components/modules/news/NewsListWidget.jsx
const NewsListWidget = ({ data }) => {
	console.log({data})
	return <>News listing</>
}
```

Visit the **news listing** page to see the taxonomies object :

![](/images/taxonomy-results/taxonomies-logs.png)

We observe the addition of a new property **results** to the term object, providing us with additional 
information regarding the frequency of this term's usage within the relevant entity, which, 
in our case, pertains to the node entity, vactory_news bundle.

<Callout icon="⚠️">
We can see that the results object is an array of objects. This arrangement allows us to calculate 
terms using various plugins, including custom ones. Each object in the array indicates which plugin 
was used for term calculation.
</Callout>

Taxonomy Results


## Introduction 
The main purpose of this element **dynamic_api_fetcher** is to facilitate the retrieval of data from external sources 
via HTTP GET requests. It serves as a element within your dynamic field to connect to other 
web services or APIs and retrieve information.

## How to use it ?

Start by creating your widget :

```jsx
name: "Test - Dynamic API Fetcher"
multiple: false
category: 'API'
enabled: TRUE
fields:
  data:
    type: dynamic_api_fetch
    label: "API Fetcher"
```

Integrate the template into the intended page.

![](/images/dynamic-api-fetcher/dynamic-api-fetcher-element.png)

**Inputs :**

- **URL **: The URL (Uniform Resource Locator) is the web address of the resource you want to retrieve
data from.

- **Query Parameters** : Query parameters allow you to send additional data or instructions to the API.
They are often used to filter, sort, or customize the data you want to retrieve.

- **Headers** : Headers are a way to include metadata about the request. They can be used to send 
information such as authentication tokens, and other instructions to the API.

## Useful hooks 

You've also provided two hooks for customization: **hook_dynamic_api_fetch_config_alter** 
and **hook_dynamic_api_fetch_result**. 
These hooks allow you to modify the request configuration and alter the results before they are 
presented to the front end.

![](/images/dynamic-api-fetcher/dynamic-api-fetcher.png)

- **hook_dynamic_api_fetch_config_alter(&$api_config, $info)** : This hook is used to modify the 
request configuration before making the GET request. You can alter the URL, query parameters, 
or headers as needed. For example, you might want to add authentication headers or change the URL 
based on some conditions.

```jsx title=./your_custom_module.module
/**
 * Alter DF dynamic_api_fetch config.
 *
 * @param $api_config
 * @param $info
 */
function hook_dynamic_api_fetch_config_alter($api_config, $info) {
  if (isset($info['uuid']) && $info['uuid'] = 'vactory_news:fetch') {
    // Alter config here.
    $api_config['header']['api-key'] = '094bd386-a4af-492d-83dd-8c7deb02ba2e';
  }
}
```

- **hook_dynamic_api_fetch_result(&$result, $info)** : This hook is used to alter the results of the API 
request before they are presented to the front end. You can manipulate the data received from the 
API response, transform it, or perform any other necessary operations.

```jsx title=./your_custom_module.module
/**
 * Alter DF dynamic_api_fetch response.
 *
 * @param $result
 * @param $info
 */
function hook_dynamic_api_fetch_result_alter($result, $info) {
  if (isset($info['uuid']) && $info['uuid'] = 'vactory_news:fetch') {
    // Alter response here.
    $result['news'] = isset($result['posts']) ? $result['posts'] : $result['error'];
  }
}
```

Dynamic API Fetcher


In this tutorial, we will explore the step-by-step process of implementing a popularity filter feature for various content types.

<Callout>

In this tutorial, we'll use News content (vactory_news) as an example.

</Callout>


#### Below are the steps to follow

##### 1. Enable the module
`drush en vactory_node_view_count -y`


##### 2. Enabling popularity filter for content type
Go to content type configuration
`/admin/structure/types/manage/vactory_news` and enable the feature for this content type, as illustrated in the image below

![](/images/popularity-filter/config.png)

##### 3. Add popularity filer to the listing
This variable is used to verify whether the feature is activated for the specific content type in question.
```jsx title=modules/news/NewsListWidget.jsx
		const node_has_views_count =
			data?.components?.[0]?.collection?.optional_data?.node_has_views_count
```

Depending on the status of this variable (if it's true), we add the filter.

```jsx title=modules/news/NewsListWidget.jsx
	if (node_has_views_count) {
		sortingList = [
			...sortingList,
			{
				id: "popularite",
				value: "popularite",
				slug: "popularite",
				label: t("Nx:Trier par les plus populaires"),
			},
		]
	}
```

Add the filter to useUpdateEffect
```jsx title=modules/news/NewsListWidget.jsx
	if (sortedValue == "popularite") {
		filters.sort = {
			"sort-popularite": {
				direction: "DESC",
				path: "field_node_count_view",
			},
		}
	}
```

<Callout>

Note: This method of adding a filter is provided as an example; feel free to customize it according to your widget.

</Callout>




Popularity Filter


## Configure the Sitemap

#### Access Simple XML Sitemap Configuration

Navigate to Configuration > Search and Metadata > Simple XML Sitemap. **/admin/config/search/xmlsitemap**

Navigate to Settings Tab :

Configure the Sitemap URL Base: (This defines the base URL for your sitemap. Typically, it would be something like https://yourdomain.com.)

![](/images/sitemap/advanced-settings.png)

#### Set Content Type Priorities and Frequencies

Adjust settings for each content type:

Content Types: Assign priority and frequency to different content types. For example, news posts might be updated weekly, while static pages are updated monthly.

- Priority: Define the importance of each content type on a scale of 0.0 to 1.0.
- Change Frequency: Specify how often content is likely to change (e.g., daily, weekly, monthly).

![](/images/sitemap/entities-settings.png)

#### Generate the Sitemap

Once the configuration is complete, you need to generate the sitemap.

- Click on the Rebuild Links tab.
- Click Save Configuration to generate your sitemap.

![](/images/sitemap/rebuild.png)

#### Verify the Sitemap

To ensure that your sitemap is correctly generated, navigate to the URL specified in the settings (usually https://yourdomain.com/sitemap.xml). 
You should see an XML file listing all the pages included in your sitemap.

#### Multilang sitemap

To ensure that your sitemap is correctly generated for each language defined on your website, navigate to List and click on **Add XML Sitemap**, and fill the fields form.

![](/images/sitemap/multi-lang.png)


Getting Started

Architecture

Configuration

Building Pages

Cross Content

Caching

Front

Features

Vactory Next Optimisation

Vactory Next Changelog

Deployment

Guides