DOC Link field User manual

silverstripe · Feb 22, 2024 · 7c11469 · 7c11469
1 parent c74c049
commit 7c11469
Show file tree

Hide file tree

Showing 22 changed files with 172 additions and 0 deletions.
diff --git a/docs/en/userguide/01_links_types.md b/docs/en/userguide/01_links_types.md
@@ -0,0 +1,77 @@
+---
+title: Links types
+summary: Primary link types provided by the LinkField module.
+---
+
+# Link types
+
+The main types of links listed in this section are accessible to users by default. This list may change, potentially expanding if developers introduce additional link types, or shrinking as detailed in the ["Allowed types"](#allowed-types) section.
+
+![A screenshot of the links type allowed by default](./_images/link_types.png)
+
+## Page on this site
+
+![A screenshot of the form "Page on this site"](./_images/page_link_mw_1.png)
+
+This link type enables the creation of a link to a page within the specified website. The form includes the following fields for completion:
+
+- **Page** - This field presents a dropdown menu containing existing pages on the website. Additionally, the input field features an autocomplete function, simplifying the process for users to select the desired page from the provided list. This field is required.
+- **Query String** - This field allows you to include a query string in the link. It's handy if you need to perform certain actions when the link is clicked. For instance, it's useful when linking to a search results page for a specific query. This field is optional.
+- **Anchor** - A named anchor serves to link to a specific part or section of a page. It must be present on the destination page to appear in the dropdown list. However, this field doesn't provide the functionality to create a new anchors on the linked page itself. This field is optional.
+- **Link Text** - This field is designed to specify the title displayed for the link. If left blank, the title of the linked page will be used instead. This field is optional.
+- **Open in new window** - This option determine whether the link will open in a new window or tab. This field is optional.
+
+## Link to a file
+
+![A screenshot of the form "Link to a file"](./_images/file_link_mw_1.png)
+
+This link type enables you to provide a link to a file.
+
+- **File** - This field is used to generate a link to a file. The file can either be uploaded at the time of creating the link or selected from existing files. This field is required.
+- **Link Text** - This field is designed to specify the title displayed for the link. If left blank, the name of the file will be used instead. This field is optional.
+- **Open in new window** - This option determine whether the link will open in a new window or tab. This field is optional.
+
+## Link to external URL
+
+![A screenshot of the form "Link to external URL"](./_images/external_link_mw_1.png)
+
+This link type lets you add a link to resources hosted externally from the site.
+
+- **External URL** - This field is designated for entering the URL address of external resources. The provided input undergoes validation to ensure conformity with internet standards for all URL components. This field is required.
+- **Link Text** - This field is designed to specify the title displayed for the link. If the title is not specified, the link URL will be used instead. This field is optional.
+- **Open in new window** - This option determine whether the link will open in a new window or tab. This field is optional.
+
+## Link to email address
+
+![A screenshot of the form "Link to email address"](./_images/email_link_mw_1.png)
+
+This link type enables you to generate an email link with all essential attributes. Clicking on the link will automatically launch the user's email client and pre-fill the "To" field with a designated email address.
+
+- **Email address** - This field is intended for users to input email address. To ensure compliance with standards, the entered email addresses undergo validation. This field is required.
+- **Link Text** - This field is designed to specify the title displayed for the link. If the title is not specified, the email address will be used instead. This field is optional.
+
+## Phone number
+
+![A screenshot of the form "Phone number"](./_images/phone_link_mw_1.png)
+
+This type generates a link with phone number that enables users to simply click on the number and initiate a call, eliminating the need to manually jot down or remember it.
+
+- **Phone** - This field is provided for users to input phone number. The entered data is checked to ensure compliance with standards. This field is required.
+- **Link Text** - This field is designed to specify the title displayed for the link. If the title is not specified, the phone number will be used instead. This field is optional.
+
+## Default title
+
+As you may have observed, each link type includes a "Link Text" field. This field is optional. If left empty during link creation, the default title associated with the link type will be used when the page is displayed.
+
+## Validation error
+
+As you can see, the main link fields must be filled out. Additionally, some fields are checked to ensure they meet specific standards, such as the correct format for external link URLs. If there's an error, the field will be highlighted in red, and an error message will prompt the user to make corrections.
+
+![A screenshot of the form "Link to a file"](./_images/validation_error.png)
+
+## Allowed types
+
+Business logic may impose limitations on the types of links accessible to CMS users, thereby restricting the available selection to a limited list.
+For instance, if a particular page allows only links to other pages within the same site, the dropdown menu will exclusively feature the "Page on this site" link type.
+
+![A screenshot of the links type allowed by default](./_images/allowed_types.png)
diff --git a/docs/en/userguide/02_work_with_link_field.md b/docs/en/userguide/02_work_with_link_field.md
@@ -0,0 +1,69 @@
+---
+title: Using the link field
+summary: How to work with the link field and multi-ink field in the CMS.
+---
+
+# Using the link field
+
+Previous sections provided fundamental knowledge for creating links. In contrast, this section will delve into the specifics of link field, offering insights into its functionalities like sorting and deletion, essential for effective link management.
+
+The LinkField module offers two primary types of fields: one for managing a single link and the other for managing multiple links. While there are some differences in how these fields operate, let's first outline the key aspects that are common to both types of fields.
+
+  - To view more detailed information or make changes to an existing link, click anywhere on the link details. This opens the modal window where adjustments can be made. If no changes are required, you can simply close the modal window.
+
+  - Once a new link is created, basic information about it will be displayed in the Link field.
+
+  - Any information entered is automatically saved upon the creation of a new link or when you update the link data.
+
+  - To publish links, you need to publish a page or data object using the link field. 
+
+  - Once created, you can modify the link type. To change a link to a different type, you must delete the existing link and create a new one.
+
+## Disabled or read-only links
+
+If a user doesn't have the right permissions for editing a link (usually because they can't edit the page the link is on), editing capabilities for these links will be disabled. This is usually referred to as read-only mode. In read-only mode, links cannot be edited, archived, or reordered - but all of the information about them can be viewed.
+
+The following examples below illustrate the appearance of a link field and modal window when the link is in a read-only state.
+
+![A screenshot of the disabled linkfields](./_images/disabled_linkfields.png)
+
+![A screenshot of the disabled link](./_images/disabled_link.png)
+
+## Single link field
+
+![A screenshot of the single link field](./_images/single_link_field.png)
+
+The single link field is designed for managing individual links. To create a new link, you can click on the "Add link" button and select the desired link type from the dropdown menu. This action opens a modal window where you can input the necessary information for creating the link. For detailed information about the default link types, please refer to the ["Link types"](./01_links_types.md) section.
+
+## Multi link field
+
+![A screenshot of the multilink field](./_images/multi_link_field.png)
+
+The multi link field functions similarly to the single link field, but with multiple links. You can create various links and easily manage them within a single field. Additionally, they can sort the links as needed. The order of links in the field will be the order they're displayed on the front end.
+
+### Sorting multi link field
+
+Let's explore an example demonstrating how you can arrange created links using the Drag & Drop feature.
+When hovering the mouse cursor over a link to be moved, it will visually highlight.
+
+![A screenshot of the multilink field](./_images/reorder_links_1.png)
+
+By clicking and holding the left mouse button while over the link, one can drag it to the desired position. After releasing the mouse button, all existing links will adjust accordingly.
+
+![A screenshot of the multilink field](./_images/reorder_links_2.png)
+
+New changes will be automatically saved, and modified links will be identified.
+
+![A screenshot of the multilink field](./_images/reorder_links_3.png)
+
+## Delete links
+
+You can remove an existing link by clicking on the "Archive" button.
+
+![A screenshot of the multilink field](./_images/delete_button.png)
+
+## Version history 
+
+Link Field includes versioning support, meaning any changes made are recorded in the change history. Additionally, a badge will appear to indicate interference whenever modifications are made.
+
+![A screenshot of the modified link](./_images/modified_link.png)
diff --git a/docs/en/userguide/_images/allowed_types.png b/docs/en/userguide/_images/allowed_types.png
diff --git a/docs/en/userguide/_images/delete_button.png b/docs/en/userguide/_images/delete_button.png
diff --git a/docs/en/userguide/_images/disabled_link.png b/docs/en/userguide/_images/disabled_link.png
diff --git a/docs/en/userguide/_images/disabled_linkfields.png b/docs/en/userguide/_images/disabled_linkfields.png
diff --git a/docs/en/userguide/_images/email_link_mw_1.png b/docs/en/userguide/_images/email_link_mw_1.png
diff --git a/docs/en/userguide/_images/external_link_mw_1.png b/docs/en/userguide/_images/external_link_mw_1.png
diff --git a/docs/en/userguide/_images/file_link_mw_1.png b/docs/en/userguide/_images/file_link_mw_1.png
diff --git a/docs/en/userguide/_images/link_field.png b/docs/en/userguide/_images/link_field.png
diff --git a/docs/en/userguide/_images/link_types.png b/docs/en/userguide/_images/link_types.png
diff --git a/docs/en/userguide/_images/modified_link.png b/docs/en/userguide/_images/modified_link.png
diff --git a/docs/en/userguide/_images/multi_link_field.png b/docs/en/userguide/_images/multi_link_field.png
diff --git a/docs/en/userguide/_images/page_link_mw_1.png b/docs/en/userguide/_images/page_link_mw_1.png
diff --git a/docs/en/userguide/_images/page_link_mw_2.png b/docs/en/userguide/_images/page_link_mw_2.png
diff --git a/docs/en/userguide/_images/phone_link_mw_1.png b/docs/en/userguide/_images/phone_link_mw_1.png
diff --git a/docs/en/userguide/_images/reorder_links_1.png b/docs/en/userguide/_images/reorder_links_1.png
diff --git a/docs/en/userguide/_images/reorder_links_2.png b/docs/en/userguide/_images/reorder_links_2.png
diff --git a/docs/en/userguide/_images/reorder_links_3.png b/docs/en/userguide/_images/reorder_links_3.png
diff --git a/docs/en/userguide/_images/single_link_field.png b/docs/en/userguide/_images/single_link_field.png
diff --git a/docs/en/userguide/_images/validation_error.png b/docs/en/userguide/_images/validation_error.png
diff --git a/docs/en/userguide/index.md b/docs/en/userguide/index.md
@@ -0,0 +1,26 @@
+---
+title: Managing links in the CMS
+summary: How to use the Link Field module to manage links in the CMS.
+---
+
+# Managing links in the CMS
+
+## Before we begin
+> [!IMPORTANT]
+> Make sure that your SilverStripe CMS installation has the [LinkField](https://packagist.org/packages/silverstripe/linkfield) module installed.
+
+## Introduction
+
+In this section, we will show the process of managing links using the LinkField module. This module provides a clean interface for creating and managing links in the CMS.
+
+![A screenshot of the link field on the page](_images/link_field.png)
+
+There are two main types of link field: one for managing a single link and another for managing multiple links. Each type of Link field will be discussed in the ["Using the link field"](./02_work_with_link_field.md) section.
+
+The module streamlines the link creation process by providing a user-friendly form that includes all essential fields necessary for link management.
+
+An important aspect to highlight is that newly generated links are automatically stored, eliminating the need for the user to save the entire page. Moreover, the link types inherently support versioning, ensuring that any modifications made within Link field are traceable in the change history.
+
+## User manual
+
+[CHILDREN includeFolders]