Merge pull request #1053 from nep/Pro-Variables-doc-cleanup

Pro variables doc cleanup

Author: TomJaeger

docs/add-ons/pro-variables/fieldtype.md

@@ -27,7 +27,9 @@ The value of the field will be the _variable name_, for example: `my_var`. To ou
 
 ## Examples
 
-Say you have 5 different testimonial quotes stored as variables in the variable group Quotes, named `lv_quote_1` to `lv_quote_5`. To each News entry, you want to add one of those quotes. Then add a Pro Variables field to your News field group, eg. `news_quote`. Then select the Quotes group in the field settings. To output the quote, you’d need code like this:
+Say you have 5 different testimonial quotes stored as variables in the variable group Quotes, named `pv_quote_1` to `pv_quote_5`. (Remember, you can create these in one pass using the (suffix option)[/add-ons/pro-variables/manage.md#variable-creation-options].)
+
+To each News entry, you want to add one of those quotes. Then add a Pro Variables field to your News field group, eg. `news_quote`. Then select the Quotes group in the field settings. To output the quote, you’d need code like this:
 
     {exp:channel:entries channel="news"}
       <h2>{title}</h2>
@@ -54,4 +56,4 @@ If you’re allowing for multiple selections, you can use the channel field as a
       {news_quotes}
         <blockquote><p>{{var}}</p></blockquote>
       {/news_quotes}
-    {/exp:channel:entries}
+    {/exp:channel:entries}

docs/add-ons/pro-variables/manage.md

@@ -17,11 +17,11 @@ There are a couple of extra properties you can assign to variables, other than t
 
 ### Variable name
 
-Name of the variable you can use in your templates. Example: `lv_my_special_var`.
+Name of the variable you can use in your templates. Example: `pv_my_special_var`. You can use (`{suffix}`)[#variable-creation-options] in this setting.
 
 ### Variable label
 
-The label a user sees when editing the contents of the variable.
+The label a user sees when editing the contents of the variable. You can use (`{suffix}`)[#variable-creation-options] in this setting.
 
 ### Variable notes
 
@@ -37,21 +37,27 @@ You can hide variables from regular users (non-managers) on a per-variable basis
 
 ### Early parsing
 
-You can enable early parsing on a per-variable basis.
+You can enable early parsing on a per-variable basis, if this is enabled overall in Pro Variable settings.
 
 ### Variable type
 
 Choose any variable type that suits your needs best. [Here’s a list of variable types that come with Pro Variables.](/add-ons/pro-variables/type.md) Each type will reveal additional type-specific properties.
 
 ## Variable creation options
 
-When creating a new variable, you have two extra options you can use. First, you can **set the initial value** of the variable, so it has a value upon creation. Second, you can enter any amount of **suffixes**, separated by a space. A new variable will be created for each suffix entered, each with identical settings apart from the suffix.
+When creating a new variable, you have two extra options you can use. 
+
+First, you can **set the initial value** of the variable, so it has an existing value upon creation. 
+
+Second, you can enter any amount of **suffixes**, separated by a space. A new variable will be created for each suffix entered, each with identical settings apart from the suffix.
 
 When using the suffix option, you can use `{suffix}` in both the variable name as the variable label. This will be replaced by the actual suffix upon creation.
 
+NOTE: You can use this for language options (en fr de nl), for creating a set of numbered fields (1 2 3 4), for creating a collection of fields for social media links (fb tiktok instagram linkedin), and more. 
+
 ## Variable groups
 
-You can create any number of groups to organize your variables. These groups will appear in the Group drop down for each variable, so you can assign a group to it. On the module home page, variable managers can sort the groups using drag and drop. Variable managers can also edit and delete the groups from here, by clicking on the edit or delete icon next to the group name. You can alter the variable order in a group by editing the group’s properties.
+You can create any number of groups to organize your variables. These groups will appear in the Group dropdown for each variable, so you can assign a group to it. On the module home page, variable managers can sort the groups using drag and drop. Variable managers can also edit and delete the groups from here, by clicking on the edit or delete icon next to the group name. You can alter the variable order in a group by editing the group’s properties.
 
 
 ### Group label
@@ -81,4 +87,4 @@ If you want to duplicate the group variables, enter a single suffix to be applie
 
 ## Suffix options
 
-You can choose to either _append_ the suffix to each new variable, or to _replace_ an existing suffix for each new variable. Please note that the suffix is considered to be the part of the variable name _after the last underscore_.
+You can choose to either _append_ the suffix to each new variable, or to _replace_ an existing suffix for each new variable. Please note that the suffix is considered to be the part of the variable name _after the last underscore_.

docs/add-ons/pro-variables/settings.md

@@ -13,19 +13,21 @@
 
 ### Select Variable Managers
 
-Select the member groups that are allowed to manage the variables, rather than just editing their contents.
+Select the member groups that are allowed to manage the variables (create, modify settings, delete), rather than just editing their contents. Overall access to Pro Variables is controled in the Member Role settings under "Allowed add-on access," but by default only Super Admins can manage variables -- all other member roles will only have access to edit the variables.
 
 ### Clear cache
 
-If set to Yes, all native cache will be cleared after variables are saved. If set to Ask, a checkbox will appear next to the Save Changes button to optionally clear the cache. It will be unchecked by default with opt-in, checked by default with opt-out.
+If set to No, changing a Pro Variable will never clear the cache. If set to Yes, all native cache will be cleared whenever any variables are saved. If set to "Optionally", you will see two buttons: "Save Variables" and "Save and Clear Cache" to optionally clear the cache.
 
 ### Enable early parsing?
 
-Choose if variables can be parsed early in the parsing order; before or after existing Snippets and config-variables. Yes, before Snippets will parse early parsed Pro Variables before Snippets and variables set in config.php; Yes, after Snippets will parse them after. 
+This controls the overall ability for Pro Variables to be parsed early in the parsing order. By default, which is "No," all Pro Variables will be parsed quite late in the parsing order (i.e. when Global Variables are parsed). If set to Yes at all, then you can control the parsing timing of each individual Pro Variable. If set to "Yes, before Snippets," early parsing will happen just before existing Template Partials and config variables are parsed, which means they can include Partials. If set to "Yes, after Snippets," that means EE will parse (chosen) Pro Variables just after Template Partials and variables set in config.php, so you can include Pro Variables in those places.
+
+NOTE: You also need to turn on early parsing for each individual variable you want to exhibit this behavior.
 
 WARN: Use caution when turning on this feature, as users could potentially break your templates!
 
 
 ### Variable types
 
-Here you can find a list of available Variable Types and Pro Variables compatible Field Types. Select which types you want to enable. Disabled types will not appear in the module.
+Here you can find a list of available Variable Types — Pro Variables-compatible Field Types. Select which types you want to enable. Disabled types will not be made available in the module.

docs/add-ons/pro-variables/tags.md

@@ -17,7 +17,7 @@ In most cases, the simple global variable syntax, eg. `{my_var}` will do. Global
 
     {exp:pro_variables:parse var="my_var"}
 
-Use the Parse, Single or Pair tag to parse variables during the Module & Plugin stage. You can also use parameters, which will allow for more options than just using the variable syntax. Some variable types, like RTE and Grid, require using the tag syntax to trigger additional processing.
+Use the Parse, Single or Pair tags to parse variables during the Module & Plugin stage of template parsing. Parse can be used as either a single or a pair tag - but that can sometimes confuse the EE parser if it's in use both ways in a template. Like all `exp:` tags, these can be assigned parameters, which will allow for more options than just using the variable syntax. Some variable types, like File, RTE and Grid, require using the tag syntax to trigger additional processing.
 
 TIP: TIP: **{ee:u}** Learn more about the parsing stages at [ExpressionEngine University](https://u.expressionengine.com/course/ee-conf-spring-summit-2021/eeconf-spring-2021-but-first-parse-order-and-php-in-expressionengines-templates).
 
@@ -27,7 +27,7 @@ NOTE: **Note:** Whenever you need parameters or additional processing, use the *
 
 #### `var`
 
-Name of the variable you want to parse. Use a colon to separate site name and variable name if you want to parse a variable belonging to a specific site, eg. `my_site:my_var`. If this parameter is omitted, all Pro Variables inside the tag pair are simply replaced with their values.
+Name of the variable you want to parse. If you're using multi-site manager, use a colon to separate site name and variable name if you want to parse a variable belonging to a specific site, e.g. `my_site:my_var`. If the var parameter is omitted (it is optional with a tag pair), all Pro Variables inside the tag pair are replaced with their values.
 
 #### `multiple`
 
@@ -37,38 +37,47 @@ If set to `yes`, the tag will loop through the different values of the variable.
 
 Use in combination with `multiple="yes"` to limit the number of results displayed.
 
-
 #### _3rd party_
 
 If you’re displaying a 3rd party field type, you can use all parameters you would normally use for the field channel variable pair.
 
-### Variables
+### Variable Options
+
+NOTE: **Note:** Some of these `{my_var:…}` variable options are available _only_ when using the Parse tag pair or Pair tag pair, _and_ if the variable type allows multiple items to be selected. For more options on the native variable types, [check their properties](/add-ons/pro-variables/type.md).
 
-#### `{_my_var_:data}`
+#### `{my_var:data}`
 
 The variable value.
 
-#### `{_my_var_:data_label}`
+#### `{my_var:data_label}`
 
 The variable value’s label, when displaying a Checkbox Group, Radio Group or Select variable type.
 
-#### `{_my_var_:label}`
+#### `{my_var:label}`
 
 The variable label, as displayed in the Control Panel.
 
-#### `{_my_var_:count}`
+#### `{my_var:count}`
 
 Current count of the loop.
 
-#### `{_my_var_:total_results}`
+#### `{my_var:total_results}`
 
 Total of iterations of the loop.
 
 #### _3rd party_
 
 If you’re displaying a 3rd party field type, you can use all variables you would normally use inside the field channel variable pair.
 
-NOTE: **Note:** the `{_my_var_:…}` variables are _only_ available when using the Parse tag pair or Pair tag pair, _and_ if the variable type allows multiple items to be selected. For more options on the native variable types, [check their properties](/add-ons/pro-variables/type.md).
+### Variable Modifiers
+
+You can use [variable modifiers](templates/variable-modifiers.md) on Pro Variables when using them in a tag pair.
+
+    {exp:pro_variables:parse}
+      Encrypted text var: {my_text:encrypt}
+    {/exp:pro_variables:parse}
+
+### Code Examples
 
     {exp:pro_variables:parse var="my_site:my_var"}
 
@@ -97,15 +106,15 @@ In order to avoid conflicts with multiple instances of the Parse tag, both singl
 
 ## Pair tag
 
-    {exp:pro_variables:pair var="my_var"}{/exp:pro_variables:pair}
+    {exp:pro_variables:pair var="my_var"}{my_var:data}{/exp:pro_variables:pair}
 
 In order to avoid conflicts with multiple instances of the Parse tag, both single and paired, you can use the alias `{exp:pro_variables:pair}` for tag pair use. It is identical to the Parse tag, but meant for tag pair use only.
 
-You can also use [variable modifiers](templates/variable-modifiers.md) on pro variables when using them in a tag pair:
+You can also use [variable modifiers](templates/variable-modifiers.md) on Pro Variables when using them in a tag pair:
 
-    {exp:pro_variables:parse}
+    {exp:pro_variables:pair var="my_text"}
       Encrypted text var: {my_text:encrypt}
-    {/exp:pro_variables:parse}
+    {/exp:pro_variables:pair}
 
 ## Label tag
 
@@ -117,29 +126,33 @@ You can display the label of any variable by using this tag. Use as single tag o
 
 #### `var`
 
-Name of the variable you want to fetch the label from. Use a colon to separate site name and variable name if you want to parse a variable belonging to a specific site, eg. `my_site:my_var`. _This is a required parameter_.
+Name of the variable you want to fetch the label from. Use a colon to separate site name and variable name if you want to parse a variable belonging to a specific site, e.g. `my_site:my_var`. _This is a required parameter_.
 
 ## Options tag
 
+      {exp:pro_variables:options var="my_site:my_multi_var"}
+        <label><input type="checkbox" value="{my_multi_var:data}" {checked} /> {my_multi_var:data_label}</label>
+      {/exp:pro_variables:options}
+      
 This tag pair allows you to display the options for a given variable. Use this in combination with the **Checkbox Group**, **Radio Group** and **Select** variable types.
 
 ### Parameters
 
 #### `var`
 
-Name of the variable you want to parse. Use a colon to separate site name and variable name if you want to parse a variable belonging to a specific site, eg. `my_site:my_var`. _This is a required parameter_.
+Name of the variable you want to parse e.g. `var="my_var"` . Use a colon to separate site name and variable name if you want to parse a variable belonging to a specific site, eg. `my_site:my_var`. _This is a required parameter_.
 
-### Variables
+### Variables and Variable Options
 
-#### `{_my_var_:data}`
+#### `{my_var:data}`
 
 Value of the option.
 
-#### `{_my_var_:data_label}`
+#### `{my_var:data_label}`
 
 Associated label of the value.
 
-#### `{_my_var_:label}`
+#### `{my_var:label}`
 
 Label of the variable itself.
 
@@ -161,7 +174,9 @@ The total amount of options.
 
 #### `{count}`
 
-The count out of the current option.
+The count of the current option.
+
+### Code Examples
 
     {exp:pro_variables:options var="my_multi_var"}
       {if count == 1}<ul>{/if}

docs/add-ons/pro-variables/type.md

@@ -42,11 +42,11 @@ Character to separate multiple values. Either a new line (`\n`), a pipe (`|`) or
 
 Displays a date picker. To output anything other than a timestamp, use the `{exp:pro_variables:single}` tag. This takes the same parameters as the native Date field. Additionally, use `modifier="relative"` to output a relative date string.
 
-### Code examples
+### Code example
 
-    {exp:pro_variables:single var="my_var" format="%Y-%m-%d"}
+    {exp:pro_variables:single var="my_date_var" format="%Y-%m-%d"}
 
-    {exp:pro_variables:single var="my_var" modifier="relative"}
+    {exp:pro_variables:single var="my_date_var" modifier="relative"}
 
 ## File
 
@@ -58,6 +58,16 @@ Uses the native [File field](/fieldtypes/file.md). To output the variable, alway
 
 Allows applying modifiers, which, among other, are used to apply [on-the-fly image manipulations](/fieldtypes/file.md#on-the-fly-image-manipulations) to files
 
+### Code example
+
+    {exp:pro_variables:pair var="my_file_var"}
+    	<figure>
+    		<img src="{my_file_var:image}">
+    		<figcaption>Photo by {my_file_var:credit}</figcaption>
+    	</figure>
+    	{my_file_var:description}
+    {/exp:pro_variables:pair}
+
 ## Grid
 
 Uses the native [Grid field](/fieldtypes/grid.md). All native types are available, _except for Relationships and Members_. To output the variable, use the `{exp:pro_variables:pair}` or `{exp:pro_variables:single}` tag where appropriate. You can use any of Grid’s [parameters](/fieldtypes/grid.md#parameters) and [variables](/fieldtypes/grid.md#variables) using these tags. Additionally, one more parameter is available:
@@ -68,17 +78,9 @@ Uses the native [Grid field](/fieldtypes/grid.md). All native types are availabl
 
 Any of the available [modifiers](/fieldtypes/grid.md#modifiers), which will trigger the output the modifier provides.
 
-### Code examples
+### Code example
 
-    {exp:pro_variables:pair var="my_var"}
-    	<figure>
-    		<img src="{my_var:image}">
-    		<figcaption>Photo by {my_var:credit}</figcaption>
-    	</figure>
-    	{my_var:description}
-    {/exp:pro_variables:pair}
-
-    {exp:pro_variables:single var="my_var" modifier="total_rows"}
+    {exp:pro_variables:single var="my_grid_var" modifier="total_rows"}
 
 ## Radio Group
 
@@ -257,10 +259,11 @@ The short name of the Image Manipulation you want to output. Alternatively, you
 
 ### Code examples
 
-    {exp:pro_variables:single var="pv_files_var" manipulation="squared"}
+    {exp:pro_variables:single var="my_files_var" manipulation="squared"}
+
+    {exp:pro_variables:pair var="my_files_var"}
+      <img src="{my_files_var:squared}" alt="">
 
-    {exp:pro_variables:pair var="pv_files_var"}
-      <img src="{pv_files_var:squared}" alt="">
     {/exp:pro_variables:pair}
 
 ## Table
@@ -292,13 +295,15 @@ Limit the number of rows displayed.
 
 ### Code examples
 
-    {exp:pro_variables:pair var="pv_table_var"}
+    {exp:pro_variables:pair var="my_table_var"}
+
       {if count == 1}<ul>{/if}
         <li><a href="{cell_1}">{cell_2}</a></li>
       {if count == total_results}</ul>{/if}
     {/exp:pro_variables:pair}
 
-    {exp:pro_variables:pair var="pv_table_var" sort="random" limit="1"}
+
+    {exp:pro_variables:pair var="my_table_var" sort="random" limit="1"}
       Random link: <a href="{cell_1}">{cell_2}</a>
     {/exp:pro_variables:pair}
 
@@ -356,14 +361,16 @@ To be used in combination with `format`. Possible values: `none`, `safe` or `all
 
 #### `preparse:_my_var_`
 
-If the variable content contains variables that need to be parsed before it is put in the template, you can use this parameter, similar to [embed variables](/templates/embedding.md#embedding-variables). For example: setting the parameter `preparse:foo="bar"` will replace the variable `{preparse:foo}` with `bar` in the variable content.
+If the variable content itself contains variables that ought to be parsed before the Pro Variable is put in the template, you can use this parameter. It's similar to [embed variables](/templates/embedding.md#embedding-variables). For example: setting the parameter `preparse:foo="bar"` will replace `{preparse:foo}` with `bar` in the variable content.
 
 #### `preparse_prefix`
 
-See above, change the default variable prefix from `preparse` to something else. For example, the parameters `preparse:foo="bar" preparse_prefix="pv"` will replace the variable `{pv:foo}` with `bar` inside the variable content.
+Used with pre-parsing, this changes the default variable prefix from `preparse` to something else. For example, the parameters `preparse_prefix="pv" preparse:foo="bar"` will replace `{pv:foo}` with `bar` inside the variable content.
 
 ### Code examples
 
     {exp:pro_variables:single var="my_var" formatting="xhtml" html="all"}
 
-    {exp:pro_variables:single var="my_var" preparse:entry_id="12"}
+    {!-- for a variable that has {pv:entry_id} and {pv:cat_id} in its content --}
+    {exp:pro_variables:single var="my_var" preparse:entry_id="12" preparse:cat_id="9" preparse_prefix="pv"}
+