DOC Link field User manual

silverstripe · Feb 21, 2024 · a4844b1 · a4844b1
1 parent c74c049
commit a4844b1
Show file tree

Hide file tree

Showing 22 changed files with 184 additions and 0 deletions.
diff --git a/docs/en/userguide/01_User_manual/01_links_types.md b/docs/en/userguide/01_User_manual/01_links_types.md
@@ -0,0 +1,87 @@
+---
+title: Links types
+summary: Primary link types provided by the LinkField module.
+---
+
+# Basic types of links
+
+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/01_links_types/link_types.png)
+
+- [Page on this site](#page-on-this-site)
+- [Link to a file](#file-link)
+- [Link to external URL](#external-link)
+- [Link to email address](#email-link)
+- [Phone number](#phone-link)
+- [Default title](#default-title)
+- [Allowed types](#allowed-types)
+- [Validation error](#validation-error)
+
+## Page on this site
+
+![A screenshot of the form "Page on this site"](../_images/01_links_types/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/01_links_types/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/01_links_types/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/01_links_types/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/01_links_types/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.
+
+## 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/01_links_types/allowed_types.png)
+
+## 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/01_links_types/validation_error.png)
+
diff --git a/docs/en/userguide/01_User_manual/02_work_with_link_field.md b/docs/en/userguide/01_User_manual/02_work_with_link_field.md
@@ -0,0 +1,71 @@
+---
+title: Essential functionalities associated with the link field
+summary: How to work with the Link field and Multi Link field in the CMS.
+---
+
+# Essential functionalities associated with the Link field
+
+Previous sections provided fundamental knowledge for creating links. In contrast, this section will delve into the specifics of Likfeld, 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 creating a single link and the other for generating 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.
+
+> [!NOTE]
+> Any information entered is automatically saved upon the creation of a new link or when updates are made to the link data by the user.
+
+> [!NOTE]
+> Once created, the user is unable to modify the link type. To establish a different type of link, the user must initiate a new creation process from the beginning.
+
+## Single Link field
+
+![A screenshot of the single link field](../_images/02_work_with_link_fields/single_link_field.png)
+
+The Single LinkField module is designed for managing individual links. To create a new link, users can click on the "Add link" button and select the desired link type from the dropdown menu. This action opens a modal window where users 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.
+
+Once a new link is created, basic information about it will be displayed in the Link field.
+
+To view more detailed information or make changes to an existing link, users need to click the Link field button again. This action opens the modal window where adjustments can be made. If no changes are required, users can simply close the modal window.
+
+
+## Multi Link field
+
+![A screenshot of the multilink field](../_images/02_work_with_link_fields/multi_link_field.png)
+
+The MultiLink Field functions similarly to the Single Link Field but offers notable advantages. Users can create various links and easily manage them within a single field. Additionally, they can conveniently sort the links as needed, enhancing usability.
+
+### Sorting multi link field
+
+Let's explore an example demonstrating how users 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/02_work_with_link_fields/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/02_work_with_link_fields/reorder_links_2.png)
+
+New changes will be automatically saved, and modified links will be identified.
+
+![A screenshot of the multilink field](../_images/02_work_with_link_fields/reorder_links_3.png)
+
+
+## Delete Link
+
+The user has the ability to remove an existing link by clicking on the "Archive" button. Upon doing so, the link will be deleted, and the change will be automatically saved.
+
+![A screenshot of the multilink field](../_images/02_work_with_link_fields/delete_button.png)
+
+## Disabled or Read only links
+
+At times, it's necessary to limit certain users' access to creating, editing or removing links. Consequently, editing capabilities for these links will be disabled, rendering them available to users solely in read-only mode. Additionally, users won't be able to reorder these links if they were created using Multi Link field.
+
+The following examples below illustrate what to expect for the user if editing link capabilities are not available.
+
+![A screenshot of the disabled linkfields](../_images/02_work_with_link_fields/disabled_linkfields.png)
+
+![A screenshot of the disabled link](../_images/02_work_with_link_fields/disabled_link.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/02_work_with_link_fields/modified_link.png)
diff --git a/docs/en/userguide/01_about_link_field.md b/docs/en/userguide/01_about_link_field.md
@@ -0,0 +1,26 @@
+---
+title: Creating links in the CMS
+summary: How to use the Link Field module to create links in the CMS.
+---
+
+# Creating links in the CMS with LinkField module
+
+## Before we begin
+> [!IMPORTANT]
+> Make sure that your SilverStripe CMS installation has the [LinkField](https://addons.silverstripe.org/add-ons/silverstripe/linkfield/) module installed.
+
+## Introduction
+
+In this section, we will delve into the process of creating links using the versatile LinkField module. This module offers the flexibility to generate links of diverse types, such as "Page on this site" link or "Link to a file". For further insights, refer to the ["Basic types of links"](01_User_manual/01_links_types.md) section.
+
+![A screenshot of the link field on the page](_images/link_field.png)
+
+There are two primary types of Link field functionalities: one for crafting a single link and another for managing multiple links of similar or varying types. Each type of Link field will be comprehensively discussed in the subsequent section ["Essential functionalities associated with the Link field"](01_User_manual/02_work_with_link_field.md).
+
+The module streamlines the link creation process by providing a user-friendly form that includes all essential fields necessary for link generation. Additionally, it enables sorting capabilities and performs field validation based on the link type during saving.
+
+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 Folder=01_User_manual]
diff --git a/docs/en/userguide/_images/01_links_types/allowed_types.png b/docs/en/userguide/_images/01_links_types/allowed_types.png
diff --git a/docs/en/userguide/_images/01_links_types/email_link_mw_1.png b/docs/en/userguide/_images/01_links_types/email_link_mw_1.png
diff --git a/docs/en/userguide/_images/01_links_types/external_link_mw_1.png b/docs/en/userguide/_images/01_links_types/external_link_mw_1.png
diff --git a/docs/en/userguide/_images/01_links_types/file_link_mw_1.png b/docs/en/userguide/_images/01_links_types/file_link_mw_1.png
diff --git a/docs/en/userguide/_images/01_links_types/link_types.png b/docs/en/userguide/_images/01_links_types/link_types.png
diff --git a/docs/en/userguide/_images/01_links_types/page_link_mw_1.png b/docs/en/userguide/_images/01_links_types/page_link_mw_1.png
diff --git a/docs/en/userguide/_images/01_links_types/page_link_mw_2.png b/docs/en/userguide/_images/01_links_types/page_link_mw_2.png
diff --git a/docs/en/userguide/_images/01_links_types/phone_link_mw_1.png b/docs/en/userguide/_images/01_links_types/phone_link_mw_1.png
diff --git a/docs/en/userguide/_images/01_links_types/validation_error.png b/docs/en/userguide/_images/01_links_types/validation_error.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/delete_button.png b/docs/en/userguide/_images/02_work_with_link_fields/delete_button.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/disabled_link.png b/docs/en/userguide/_images/02_work_with_link_fields/disabled_link.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/disabled_linkfields.png b/docs/en/userguide/_images/02_work_with_link_fields/disabled_linkfields.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/modified_link.png b/docs/en/userguide/_images/02_work_with_link_fields/modified_link.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/multi_link_field.png b/docs/en/userguide/_images/02_work_with_link_fields/multi_link_field.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/reorder_links_1.png b/docs/en/userguide/_images/02_work_with_link_fields/reorder_links_1.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/reorder_links_2.png b/docs/en/userguide/_images/02_work_with_link_fields/reorder_links_2.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/reorder_links_3.png b/docs/en/userguide/_images/02_work_with_link_fields/reorder_links_3.png
diff --git a/docs/en/userguide/_images/02_work_with_link_fields/single_link_field.png b/docs/en/userguide/_images/02_work_with_link_fields/single_link_field.png
diff --git a/docs/en/userguide/_images/link_field.png b/docs/en/userguide/_images/link_field.png