Merge pull request #1074 from nep/patch-3

Adding documentation about file:XX:url and compatibility mode

Author: TomJaeger

docs/add-ons/file.md

@@ -23,6 +23,8 @@ In addition, the File module supports [Pagination](templates/pagination.md).
 
 NOTE: **Note:** If you're looking for how to use file fields in your channel entries loops, you should look at [the file field variable usage documentation](fieldtypes/file.md#template-tags) in the channel fields documentation.
 
+NOTE: **Note:** If you uploaded the file using the Textarea, Text Input or RTE fields, you should look at [the textarea field documentation](fieldtypes/textarea.md#filexxurl-tag--inserting-a-file).
+
 The File Entries tag allows you to display files and their associated meta-data on the frontend through the use of standard ExpressionEngine tags.
 
 Here is a simple example of a possible usage of this tag:
@@ -35,7 +37,7 @@ Here is a simple example of a possible usage of this tag:
       {/categories}
 
       {if url:small}
-        <p><a href="{id_path='gallery/comments'}"><img src="{url:small}" width="{width:small}" height="{height:small}" alt="{title}" title="{title}" /></a></p>
+        <p><a href="{id_path='gallery/comments'}" title="{title}"><img src="{url:small}" width="{width:small}" height="{height:small}" alt="{title}" /></a></p>
       {/if}
 
       {description}
@@ -314,7 +316,7 @@ Multiple instances of the {switch=} tag may be used and the system will intellig
 
 ### `{title}`
 
-The title of the entry.
+The title of the file.
 
 ### `{total_results}`
 

docs/control-panel/file-manager/file-manager.md

@@ -189,6 +189,10 @@ Tip: How to Turn off File Manager Compatibility Mode
 <iframe src="https://www.youtube.com/embed/V1sRqz-b83k?si=0YrmOgxxcfhbWl_L" title="Turn off File Manager Compatibility Mode in ExpressionEngine" width="1920" height="1080" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
 </div>
 
-ExpressionEngine 7+ stores files in the database differently then previous versions (using `{file:XX:url}` format instead of `{filedir_X}filename.ext`). This enables ExpressionEngine to provide a more powerful overall experience with files, such as storing files in subfolders, moving files to different locations, and collecting file usage data.
+ExpressionEngine 7+ stores files in the database differently then previous versions, and references them using a `{file:XX:url}` format instead of `{filedir_X}filename.ext`). This change enables ExpressionEngine to provide a more powerful overall experience with files: you can store files in subfolders, you can move files to different locations without breaking references in content, and EE can track if and where each file is in use.
 
-ExpressionEngine will still parse the `{filedir_X}` tags in templates or channel entries. However, third-party add-ons that parse file data on their own may not be compatible with the `{file:XX:url}` syntax, causing issues. In order to prevent a bad user experience, users can enable Compatibility Mode for the sites that are upgraded from earlier versions. If you know all installed add-ons are compatible with the new file format, you can run the Update File Usage (found in Tools-> Utilities-> Update File Usage) and then disable Compatibility Mode from the [Content & Design settings](/control-panel/settings/content-design.md#run-file-manager-in-compatibility-mode).
+However, third-party add-ons that parse file data on their own may not be compatible with the `{file:XX:url}` syntax, causing issues. In order to prevent a bad user experience, users can enable Compatibility Mode for the sites that are upgraded from earlier versions, though for a modern site, it is recommended to leave compatibility mode off.
+
+If you know all installed add-ons are compatible with the new file format, you can run the Update File Usage (found in Tools-> Utilities-> Update File Usage), which will also convert all old file references to the new format. Then disable Compatibility Mode from the [Content & Design settings](/control-panel/settings/content-design.md#run-file-manager-in-compatibility-mode).
+
+Regardless of mode status, ExpressionEngine will still parse the `{filedir_X}` tags in channel entry fields.

docs/fieldtypes/file.md

@@ -119,6 +119,10 @@ This variable simply displays the content from the "Descriptive name of upload d
 
 The file's extension, if it has one.
 
+### `{file:XX:url}`
+
+This is not actually a template tag. It appears in the contents of an entry's field to reference a file. See [Textarea Fieldtype](/fieldtypes/textarea.md#filexxurl-tag--inserting-a-file).
+
 ### `{file_id}`
 
 The unique id of the file.

docs/fieldtypes/text.md

@@ -17,11 +17,21 @@ Text Input is a single-lined free-form writing space where you can enter text or
 
 ### Maximum Characters
 
-The maximum number of characters this field should allow.
+The maximum number of characters this field should allow. This will not affect existing entries, but the limit will be in effect when you try to edit them.
 
 ### Text Formatting
 
-Specifies how the entered-text will be formatted when rendered on the front-end. Choices include replacing each linebreak with a `BR` tag, automatically surrounding paragraphs with `P` tags, or Markdown processing. [Additional plugins](development/text-formatting.md) may be installed to provide more text formatting options.
+Specifies how the entered text will be formatted when rendered on the front-end. Choices include:
+
+* **None** - content will be output exactly as entered
+* [**Auto line break**](/general/text-formatting.html#auto-br) - simply replaces each linebreak with a `<br>` tag
+* [**Markdown**](/general/text-formatting.html#markdown) - processes content as Markdown and outputs HTML
+* **XML Encode** - content is formatted and escaped for safe use in an XML document like an RSS feed
+* [**XHTML**](/general/text-formatting.html#auto-xhtml) - Encloses paragraphs with `<p>` tags, adds curly quotes, and does other more advanced processing to make plain text into proper HTML while leaving any HTML intact.
+
+For a text input field, the output may not seem to vary too much. [Additional plugins](development/plugins.md) may be installed to provide more text formatting options.
+
+NOTE: **Note:** To see the Markdown or XML Encode options, those add-ons on must be installed.
 
 ### Allow Override?
 

docs/fieldtypes/textarea.md

@@ -23,7 +23,17 @@ Height of the editor in rows of text.
 
 ### Text Formatting
 
-Specifies how the entered-text will be formatted when rendered on the front-end. Choices include replacing each linebreak with a `BR` tag, automatically surrounding paragraphs with `P` tags, or Markdown processing. [Additional plugins](development/text-formatting.md) may be installed to provide more text formatting options.
+Specifies how the entered text will be formatted when rendered on the front-end. Choices include:
+
+* **None** - content will be output exactly as entered
+* [**Auto line break**](/general/text-formatting.html#auto-br) - simply replaces each linebreak with a `<br>` tag
+* [**Markdown**](/general/text-formatting.html#markdown) - processes content as Markdown and outputs HTML
+* **XML Encode** - content is formatted and escaped for safe use in an XML document like an RSS feed
+* [**XHTML**](/general/text-formatting.html#auto-xhtml) - Encloses paragraphs with `<p>` tags, adds curly quotes, and does other more advanced processing to make plain text into proper HTML while leaving any HTML intact.
+
+XHTML is an original EE formatting option and it is a good default for plain text that needs to be output as nice HTML, especially for text that contains some HTML as well.   [Additional plugins](development/plugins.md) may be installed to provide more text formatting options.
+
+NOTE: **Note:** To see the Markdown or XML Encode options, those add-ons on must be installed.
 
 ### Allow Override?
 
@@ -37,6 +47,25 @@ Either left-to-right, or right-to-left.
 
 Show formatting buttons to make writing markup easier, show a smiley chooser, or show a file chooser button to easily insert images or links to files.
 
+## {file:XX:url} Tag / Inserting a File
+
+In a textarea field, when you add a file using the field tools, EE will insert code like this:
+
+Images
+
+    <img src="{file:XX:url}" alt="" height="200" width="200">
+
+Other Files
+
+    <a href="{file:xx:url}">other-file.pdf</a>
+
+When the field is output, EE will replace `{file:XX:url}` with the file's URL.
+
+With that tag in the content of the field, EE will also track the file as being used in this entry. This information is updated whenever an entry is saved with a field containing `{file:XX:url}`. If you reference an uploaded file directly by URL, EE will not track that the file is in use in that entry. This tracking is true for other field types as well, but those other field types often do not display the tag directly as `{file:XX:url}`.
+
+If your site is set to [Compatibility Mode](/control-panel/file-manager/file-manager.md#compatibility-mode) for backwards compatibility with older add-ons, file references will instead look like `{filedir_X}filename.ext` and usage will not be tracked.
+
+
 ## Parsing File Tags
 
 The Textarea fieldtype supports the use of file tags in the format `{file:XX:field}` where `XX` is the file ID and `field` is any field associated with that file, such as `url`, `filename`, `title`, etc.