Merge pull request #279 from infinum/feature/docs-additonal

updating docs

website/forms/basics.mdx

@@ -5,8 +5,125 @@ title: Basics
 
 import { Video } from './../src/docs/videos';
 
-*Content coming soon...*
+## How to use it?
+
+Eighshift Forms is a WordPress plugin that allows you to create forms in a visual way. It is based on the [Gutenberg editor](https://wordpress.org/gutenberg/).
+At this time, the plugin is not a part of the WordPress repository, so it needs to be installed manually.
+
+To install it you should:
+1. Open the Eightshift Forms [GitHub repository](https://github.com/infinum/eightshift-forms/releases) and find the latest release.
+2. In the latest release details, under _Assets_, find the `release.zip` file and download it to you project folder.
+3. After you unzip it it will be available in you WordPress admin under _Plugins_ section.
+4. Activate the plugin
+
+![GitHub screen](/img/forms/releases.webp)
+
+## Terminogy
+
+We will use some terms in this documentation that you should be familiar with.
+* **Form** - a collection of fields that used to collect data from the user
+* **Field** - single data input element
+* **Form listing**  - list of all created forms
+* **Locations** - list of places a form is used on the website
+* **Edit form** - allows editing a form
+* **Trashed forms** - list of forms that are marked as deleted (but not yet deleted permanently)
+* **Form settings** - settings for a specific form
+* **Global settings** - settings shared between all forms
+* **Admin bar** - a collection of buttons and indicators displayed on the top of the admin area
+* **Form quick menu bar** - menu with shortcut buttons for easy access to functions like editing the form or changing its settings, shown only when logged in
+* **Form picker block** - block that allows selecting a form that will be displayed on the frontend
+
+## Forms listing
+
+This page lists all created forms, which can be used in pages, posts, etc.
+Also, it contains multiple useful features to help manage the forms.
+
+* Form type filter - filter your listing page by the form type
+* Delete - delete one or more forms
+* Sync - sync one or more forms with the external integration and update the form fields
+* Duplicate - duplicate one or more forms
+* Trashed - see all the trashed forms
+* Create - add a form
+* Locations - see all the locations where a form is displayed
+* Setting - edit the form settings
+* Edit form - edit the form
+* Warnings - see all the warnings related to the form
+* Multi-language - see all the languages that are used on the form (if you using a multi-language plugin)
+
+![Forms listing screen](/img/forms/listing.webp)
+
+### Locations
+
+Shows a list of all the places on the website that a selected form is used.
+
+More details are available [here](features/locations).
+
+![Listing screen](/img/forms/locations-listing.webp)
+
+### Edit form
+
+Opens a Gutenberg editor where you can modify and configure the form fields within a form.
+
+More details are available [here](first-form).
+
+![Edit screen](/img/forms/editor.webp)
+
+### Trashed forms
+
+Trashed forms screen shows a list of forms that are marked as deleted.
+A form that is marked as deleted will not be shown in the frontend, nor in the list of forms in the Form picker.
+
+In the list of trashed forms, a form can be either restored or permanently deleted by clicking on the respective button.
+
+Please note that the "Permanently delete" action is not reversible!
+
+![Trashed screen](/img/forms/trashed.webp)
+
+## Form settings
+
+Every form has a settings page where its behaviour can be defined. The changes here will not affect other forms.
+
+ Access it by clicking on `Settings` in the form listing page.
+
+![Settings screen](/img/forms/settings.webp)
+
+## Global settings
+
+Global settings define settings that are shared between all forms. Access it by clicking on `Global settings` in the main WordPress sidebar.
+
+Note that in some cases specific form settings can override global settings, e.g. validation messages.
+
+![Global settings screen](/img/forms/global-settings.webp)
+
+### Dashboard
+
+The dashboards gives you an overview of the currently active features and enables activating and deactivating of them.
+
+More details can be found [here](features/dashboard).
+
+![Dashboard screen](/img/forms/dashboard.webp)
+
+## Admin bar
+
+Admin bar is a toolbar displayed on the top of the WordPress admin interface. It is shown only when logged in.
+
+It contains various WordPress functionalities, as well as an _Eightshift forms_ menu, which contains shortcuts to the list of forms, current form settings, global settings, troubleshooting tools, etc.
+
+![Admin bar](/img/forms/admin-top-bar.webp)
+
+## Form quick menu bar
+
+The quick menu bar allows easy access to form editing and form settings.
+It is shown besides a form, in the frontend view, only when logged in.
+
+![Quick menu screen](/img/forms/quick-bar.webp)
+
+## Form picker block
+
+The `Form picker` block allows choosing a form that will be shown on the frontend. It is available in the Gutenberg editor, under the `Eighshift Forms` category.
+
+![Form picker screen](/img/forms/form-picker.webp)
+
+
+<Video type='forms' video='basics' />
 
-<Video type='forms' video='intro'/>
-<Video type='forms' video='basics' useTitle={false} />
-<Video type='forms' video='firstForm' useTitle={false} />

website/forms/features/dashboard.md

@@ -0,0 +1,10 @@
+---
+id: dashboard
+title: Dashboard
+---
+
+The dashboards gives you an overview of the currently active features and enables activating and deactivating of them.
+
+More details can be found [here](features/dashboard).
+
+![Dashboard screen](/img/forms/dashboard.webp)

website/forms/features/locations.md

@@ -21,4 +21,4 @@ In form settings under the `locations` tab, you can see the same information as
 
 You can also find the form location in the top bar of the WordPress admin.
 
-![Top bar screen](/img/forms/topbar.webp)
+![Admin bar screen](/img/forms/admin-top-bar.webp)

website/forms/features/wpml.md

@@ -0,0 +1,32 @@
+---
+id: wpml
+title: WPML
+---
+
+WPML is plugin that allows multi-lingual functionality for the website, allowing features like post and media translations. Eightshift Forms is fully compatible with WPML, and allows adding language variants (_translations_) to forms.
+
+![WPML screen](/img/forms/wpml.webp)
+
+## How to use
+
+If using WPML, enable the _WPML_ feature in form settings. This will ensure the forms is displayed correctly in the form listing page, and that all the multi-language features work.
+
+## Features affected by WPML
+
+WPML affects the following features:
+
+### Forms listing
+
+By default, we use `get_locale()`to retrieve the default language of the project. Once WPML is activated, a new language tag is assigned to each setting, and the forms display only in the language they're assigned to.
+
+### Forms selector
+
+When selecting forms in the Forms picker, only the forms in the current editing language are visible.
+
+### Forms settings
+
+Forms settings are unique for each language variant of the form.
+
+### Global settings
+
+Global settings, similar to form settings, are unique for each language variation, with the exception of API keys, tokens, etc.

website/forms/first-form.mdx

@@ -0,0 +1,47 @@
+---
+id: first-form
+title: Your first form
+---
+
+import { Video } from './../src/docs/videos';
+
+Adding your first form and displaying it on the frontend is simple:
+1. Enable the form type you want to use in the Eightshift forms Dashboard
+2. Create a form in the WordPress admin
+3. Configure the form and add the fields needed
+4. Add the _Form picker_ block in the place you want to show the form, and select your newly created form
+
+## Integrations
+By default none of the integrations are enabled.
+
+To enable one, go to the _Dashboard_ page of the Eightshift Forms admin settings.
+
+More details can be found [here](features/dashboard).
+
+![Dashboard screen](/img/forms/dashboard.webp)
+
+## Create a form
+
+To create a form, open the WordPress admin, find _Eightshift Forms_ in the sidebar, then click on _Add new form_.
+
+An editing screen will open, with a selector for the form type. If you don't see a form type in the selector, make sure it's enabled in the Dashboard.
+
+After clicking the form type, the Form block will be automatically added, the form initialized, and some fields may be added by default.
+
+![Form Type Picker screen](/img/forms/form-type-picker.webp)
+
+To change form settings, clicking on `Edit settings` in the options sidebar.
+
+![Forms Sidebar screen](/img/forms/forms-sidebar.webp)
+
+## Add the form to the page/post/custom post type
+
+To display the form, add the _Form_ block and select a form to display.
+
+![Form picker screen](/img/forms/form-picker.webp)
+
+More settings can be found in options sidebar.
+
+![Form Sidebar screen](/img/forms/form-sidebar.webp)
+
+<Video type='forms' video='firstForm' useTitle={false} />

website/forms/integrations/pipedrive.md

@@ -0,0 +1,6 @@
+---
+id: jira
+title: Jira
+---
+
+*Coming soon...*

website/forms/php/filters/integrations/jira.md

@@ -3,17 +3,4 @@ id: jira
 title: Jira
 ---
 
-This filter provides you the ability to change how we map Clearbit fields so you can combine multiple fields in one add some new one.
-
-```php
-add_filter('es_forms_integrations_clearbit_map', function(array $params): array {
-	$street = $params['company-street-number'] ?? '';
-	$city = $params['company-city'] ?? '';
-	$postalCode = $params['company-postal-code'] ?? '';
-
-	$params['company-location-combined'] = "{$street} {$city} {$postalCode}";
-
-	return $params;
-});
-
-
+*Coming soon...*

website/forms/php/filters/integrations/pipedrive.md

@@ -0,0 +1,6 @@
+---
+id: pipedrive
+title: Pipedrive
+---
+
+*Coming soon...*

website/forms/php/helpers.md

@@ -5,6 +5,8 @@ title: Helpers
 
 Eightshift Forms offers static helpers that can be implemented in your project. The key difference between these helpers and filters is that you can use the former in your theme or plugin code regardless of the load cycle.
 
+All helpers can be found [here](https://github.com/infinum/eightshift-forms/blob/develop/src/Helpers/esForms.php).
+
 ### esFormsGetFormIdByName
 
 This function retrieves the custom, unique name of a form, as set in the Form settings, from the provided form ID. It's useful when applying specific settings to one or more forms using filters in your project.
@@ -58,3 +60,15 @@ if (\function_exists('esFormsGetComponentsRender')) {
   $render = esFormsGetComponentsRender('<component>', '[<attributes>]');
 }
 ```
+
+### esFormRenderForm
+
+If you want to output a form in a custom template or block, you can use this helper to do so.
+
+Please note that not all functionalities are available, and certain options might not be available.
+
+```php
+if (\function_exists('esFormRenderForm')) {
+  echo esFormRenderForm('<formId>', '[<attributes>]');
+}
+```

website/forms/welcome.md → website/forms/welcome.mdx

@@ -3,6 +3,8 @@ id: welcome
 title: Welcome
 ---
 
+import { Video } from './../src/docs/videos';
+
 Welcome to the Eightshift Forms documentation! This powerful and versatile WordPress project is designed to revolutionize the way you handle forms in your web development projects.
 
 Eightshift Forms were crafted to streamline the process of creating and managing forms for your websites or web applications. Whether you're building a simple contact form or a complex multi-step survey, this package offers the flexibility and tools you need to achieve your goals with ease.
@@ -32,3 +34,5 @@ Here's a glimpse of what Eightshift Forms brings to the table:
 - Security and performance: Uses nonce verification, sanitization and escaping to ensure your forms are secure. It also uses AJAX to submit forms without reloading the page, improving user experience and speed.
 
 Whether you're a seasoned developer seeking to optimize your form-building process or a beginner looking for a reliable and feature-rich solution, Eightshift Forms has something to offer for everyone.
+
+<Video type='forms' video='intro' useTitle={false} />

website/sidebars-forms.js

@@ -3,11 +3,13 @@ module.exports = {
 		'Getting Started': [
 			'welcome',
 			'basics',
+			'first-form',
 			{
 				'type': 'category',
 				'label': 'Features',
 				'items': [
 					[
+						'features/dashboard',
 						'features/conditional-tags',
 						'features/enrichment',
 						'features/geolocation',
@@ -26,6 +28,7 @@ module.exports = {
 						'features/migrations',
 						'features/cloudflare',
 						'features/country-list',
+						'features/wpml',
 					],
 				],
 			},
@@ -46,6 +49,7 @@ module.exports = {
 					'integrations/mailerlite',
 					'integrations/moments',
 					'integrations/workable',
+					'integrations/pipedrive',
 				],
 			},
 		],
@@ -77,6 +81,7 @@ module.exports = {
 									'php/global-variables/integrations/mailerlite',
 									'php/global-variables/integrations/moments',
 									'php/global-variables/integrations/workable',
+									'php/global-variables/integrations/pipedrive',
 								],
 							},
 						]

website/src/docs/integration-filters.jsx

@@ -4,11 +4,11 @@ import { reformatCode } from '../../utils/shared.jsx';
 
 export function IntegrationFilters(props) {
 	const {
-		name,
 		filter,
 		onlyUse = [
 			'dataFilter',
 			'prePostParamsFilter',
+			'order',
 		],
 	} = props;
 
@@ -62,7 +62,7 @@ export function IntegrationFilters(props) {
 			{onlyUse.includes('prePostParamsFilter') &&
 				<>
 					<h2>Pre post params</h2>
-					<p>Change form fields data before it is sent to the external integration. This way you can manuipulate data and provide additional mapping to the data sent to the integration.</p>
+					<p>Change form fields data before it is sent to the external integration. This way you can manipulate data and provide additional mapping to the data sent to the integration.</p>
 
 					<CodeBlock language="php">
 						{reformatCode(`
@@ -84,6 +84,26 @@ export function IntegrationFilters(props) {
 					</CodeBlock>
 				</>
 			}
+
+			{onlyUse.includes('order') &&
+				<>
+					<h2>Order fields</h2>
+					<p>Forces a specific form fields order, regardless of one set in the editor. Fields that are not defined here will follow the natural in-editor order.</p>
+					<p>Not all fields need to have an order defined. For example, if you want to make sure <code>firstname</code>, <code>lastname</code> and <code>email</code> are displayed first, this filter can help.</p>
+
+					<CodeBlock language="php">
+						{reformatCode(`
+							add_filter('es_forms_integrations_${filter}_order', function(): array {
+								return [
+									'firstname',
+									'lastname',
+									'email',
+								];
+							});
+						`)}
+					</CodeBlock>
+				</>
+			}
 		</>
 	);
 }