Skip to content

Commit 24687ab

Browse files
jools-rjools-r
committed
Update Readme
1 parent 4216afc commit 24687ab

File tree

2 files changed

+162
-109
lines changed

2 files changed

+162
-109
lines changed

‎README.md‎

Lines changed: 121 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,163 @@
11
# jcr_link_custom
22

3-
Adds up to five extra custom fields of up to 255 characters to the [Content › Links](http://docs.textpattern.io/administration/links-panel) panel and provides a corresponding tag to output the custom field.
3+
Adds up to five extra custom fields of up to 255 characters to the
4+
[Content › Links](http://docs.textpattern.io/administration/links-panel)
5+
panel along with corresponding tags to output the custom field and to
6+
test if it contains a value or matches a specific value.
47

8+
### Use cases
59

6-
## Use cases
10+
Use whenever extra information needs to be stored with a link. For
11+
example:
712

8-
Use whenever extra information needs to be stored with a link. For example:
13+
- Store a txp image ID number and use it to attach a logo to a link.
14+
- Store associated details, for example the location of a linked
15+
organisation.
16+
- ...
917

10-
- Store a txp image ID number and use it to attach a logo to a link.
11-
- Store associated details, for example the location of a linked organisation.
12-
- …
18+
## Installation / Deinstallation / Upgrading
1319

20+
### Installation
1421

15-
## Installation
22+
Paste the `.txt` installer code into the *Admin › Plugins* panel, or
23+
upload the plugin's `.php` file via the *Upload plugin* button, then
24+
install and enable the plugin.
1625

17-
Paste the code into the *Admin › Plugins* panel, install and enable the plugin.
26+
### Upgrading
1827

28+
The plugin automatically migrates custom field data and the database
29+
structure from the earlier single custom field variant (v0.1) to the new
30+
format. No changes are needed to the public tags as the new default
31+
settings correspond to the old tag. Nevertheless, it is always advisable
32+
to make a database backup before upgrading.
1933

20-
## Tags
34+
### De-installation
2135

22-
### txp:jcr_link_custom
36+
The plugin cleans up after itself: deinstalling (deleting) the plugin
37+
removes the extra columns from the database as well as custom field
38+
names and labels. To stop using the plugin but keep the custom field
39+
data in the database, just disable (deactivate) the plugin but don't
40+
delete it.
2341

24-
Outputs the content of the link custom field.
25-
26-
#### Tag attributes
42+
## Plugin tags
2743

28-
`name`
29-
Specifies the name of the link custom field.
30-
Example: Use `name="image_id"` to output the image_id custom field. Default: jcr_link_custom_1.
44+
### jcr_link_custom
3145

32-
`escape`
33-
Escape HTML entities such as `<`, `>` and `&` prior to echoing the field contents.
34-
Supports extended escape values in txp 4.8+
35-
Example: Use `escape="textile"` to convert textile in the value. Default: none.
46+
Outputs the content of the link custom field.
3647

37-
`default`
38-
Specifies the default output if the custom field is empty
39-
Example: Use `default="123"` to output "123", e.g. for use as the default image ID number. Default: empty.
48+
#### Tag attributes
4049

41-
`wraptag`
42-
Wrap the custom field contents in an HTML tag
43-
Example: Use `wraptag="h2"` to output `<h2>Custom field value</h2>`. Default: empty.
50+
`name`\
51+
Specifies the name of the link custom field.\
52+
Example: Use `name="image_id"` to output the image_id custom field.
53+
Default: jcr_link_custom_1.
54+
55+
`escape`\
56+
Escape HTML entities such as `<`, `>` and `&` prior to echoing the field
57+
contents.\
58+
Supports extended escape values in txp 4.8+\
59+
Example: Use `escape="textile"` to convert textile in the value.
60+
Default: none.
61+
62+
`default`\
63+
Specifies the default output if the custom field is empty\
64+
Example: Use `default="123"` to output "123", e.g. for use as the
65+
default image ID number. Default: empty.
66+
67+
`wraptag`\
68+
Wrap the custom field contents in an HTML tag\
69+
Example: Use `wraptag="h2"` to output `<h2>Custom field value</h2>`.
70+
Default: empty.
4471

45-
`class`
46-
Specifies a class to be added to the `wraptag` attribure
47-
Example: Use `wraptag="p" class="intro"` to output `<p class="intro">Custom field value</p>`. Default: empty
72+
`class`\
73+
Specifies a class to be added to the `wraptag` attribute\
74+
Example: Use `wraptag="p" class="intro"` to output
75+
`<p class="intro">Custom field value</p>`. Default: empty
4876

49-
### txp:jcr_if_link_custom
77+
### jcr_if_link_custom
5078

51-
Tests for existence of a link custom field, or whether one or several matches a value or pattern.
79+
Tests for existence of a link custom field, or whether one or several
80+
matches a value or pattern.
5281

5382
#### Tag attributes
5483

55-
`name`
56-
Specifies the name of the link custom field.
57-
Example: Use `name="image_id"` to output the image_id custom field. Default: jcr_link_custom_1.
58-
59-
`value`
60-
Value to test against (optional).
61-
If not specified, the tag tests for the existence of any value in the specified link custom field.
62-
Example: Use `value="english"` to output only those links whose “language” link custom field is english. Default: none.
63-
64-
`match`
65-
Match testing: exact, any, all, pattern. See the docs for [if_custom_field](https://docs.textpattern.com/tags/if_custom_field).
84+
`name`\
85+
Specifies the name of the link custom field.\
86+
Example: Use `name="image_id"` to output the image_id custom field.
87+
Default: jcr_link_custom_1.
88+
89+
`value`\
90+
Value to test against (optional).\
91+
If not specified, the tag tests for the existence of any value in the
92+
specified link custom field.\
93+
Example: Use `value="english"` to output only those links whose
94+
"language" link custom field is english. Default: none.
95+
96+
`match`\
97+
Match testing: exact, any, all, pattern. See the docs for
98+
[if_custom_field](https://docs.textpattern.com/tags/if_custom_field).\
6699
Default: exact.
67100

68-
`separator`
69-
Item separator for match="any" or "all". Otherwise ignored
101+
`separator`\
102+
Item separator for match="any" or "all". Otherwise ignored.\
70103
Default: empty.
71104

105+
## Examples
72106

73-
## Example
74-
75-
Produce a list of linked partner logos (from link assigned to the link category "partners"):
76-
77-
```
78-
<txp:linklist wraptag="ul" break="li" category="partners">
79-
<txp:jcr_if_link_custom name="image_id" value="">
80-
<a href="<txp:link_url />" title="<txp:link_name />"><txp:link_name /></a>
81-
<txp:else />
82-
<a href="<txp:link_url />" title="<txp:link_name />"><txp:image id='<txp:jcr_link_custom name="image_id" />' limit="1" /></a>
83-
</txp:jcr_if_link_custom>
84-
</txp:linklist>
85-
```
86-
87-
when the "image_id" link custom field is used to store the Image ID# of the logo.
107+
### Example 1
88108

109+
Produce a list of linked partner logos (from link assigned to the link
110+
category "partners"):
89111

90-
## Changing the label of the custom field
112+
<txp:linklist wraptag="ul" break="li" category="partners">
113+
<txp:jcr_if_link_custom name="image_id" value="">
114+
<a href="<txp:link_url />" title="<txp:link_name />"><txp:link_name /></a>
115+
<txp:else />
116+
<a href="<txp:link_url />" title="<txp:link_name />"><txp:image id='<txp:jcr_link_custom name="image_id" />' limit="1" /></a>
117+
</txp:jcr_if_link_custom>
118+
</txp:linklist>
91119

92-
The name of custom field can be changed by specifying a new label using the *Install from Textpack* field in the [Admin › Languages](http://docs.textpattern.io/administration/languages-panel) panel. Enter your own information in the following pattern and click **Upload**:
120+
where the `image_id` link custom field is used to store the Image ID\#
121+
of the logo.
93122

94-
```
95-
#@admin
96-
#@language en-gb
97-
jcr_link_custom_1 => Your label
98-
jcr_link_custom_2 => Your other label
99-
```
123+
## Custom field labels
100124

101-
replacing `en-gb` with your own language and `Your label` with your own desired label.
125+
The label displayed alongside the custom field in the edit image panel
126+
can be changed by specifying a new label using the *Install from
127+
Textpack* field in the [Admin ›
128+
Languages](http://docs.textpattern.io/administration/languages-panel.html)
129+
panel. Enter your own information in the following pattern and click
130+
**Upload**:
102131

132+
#@owner jcr_link_custom
133+
#@language en, en-gb, en-us
134+
#@link
135+
jcr_link_custom_1 => Your label
136+
jcr_link_custom_2 => Your other label
103137

104-
## De-installation
138+
replacing `en` with your own language and `Your label` with your own
139+
desired label.
105140

106-
The plugin cleans up after itself: deinstalling the plugin removes the extra column from the database. To stop using the plugin but keep the database tables, just disable (deactivate) the plugin but don't delete it.
107-
108-
109-
## Changelog + Credits
141+
## Changelog and credits
110142

111143
### Changelog
112144

113-
- Version 0.2 – 2020/06/23 – Expand to handle multiple custom fields + migrate from v1
114-
- Version 0.1.1 – 2016/12/0518 – Remedy table not being created on install
115-
- Version 0.1 – 2016/03/04 – First release
116-
145+
- Version 0.2.4 -- 2020/12/20 -- Align with other custom field plugins
146+
- Version 0.2.3 -- 2020/06/29 -- Tag registration + textpack fixes
147+
- Version 0.2.2 -- 2020/06/27 -- Handle migration from previous
148+
versions of the plugin on install
149+
- Version 0.2.1 -- 2020/06/27 -- Fix for missing custom_field name vs.
150+
missing value for cf
151+
- Version 0.2 -- 2020/06/23 -- Expand to handle multiple custom
152+
fields + migrate from v1
153+
- Version 0.1.1 -- 2016/12/0518 -- Remedy table not being created on
154+
install
155+
- Version 0.1 -- 2016/03/04 -- First release
117156

118157
### Credits
119158

120-
Robert Wetzlmayr’s [wet_profile](https://github.com/rwetzlmayr/wet_profile) plugin for the starting point, and further examples by [Stef Dawson](http://www.stefdawson.com) and [Jukka Svahn](https://github.com/gocom).
159+
Robert Wetzlmayr's
160+
[wet_profile](https://github.com/rwetzlmayr/wet_profile) plugin for the
161+
starting point, and further examples by [Stef
162+
Dawson](http://www.stefdawson.com) and [Jukka
163+
Svahn](https://github.com/gocom).

‎README.textile‎

Lines changed: 41 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
h1. jcr_link_custom
22

3-
Adds up to five extra custom fields of up to 255 characters to the "Content › Links":http://docs.textpattern.io/administration/links-panel panel and provides a corresponding tag to output the custom field.
3+
Adds up to five extra custom fields of up to 255 characters to the "Content › Links":http://docs.textpattern.io/administration/links-panel panel along with corresponding tags to output the custom field and to test if it contains a value or matches a specific value.
44

5-
6-
h2. Use cases
5+
h3. Use cases
76

87
Use whenever extra information needs to be stored with a link. For example:
98

@@ -12,25 +11,35 @@ Use whenever extra information needs to be stored with a link. For example:
1211
* …
1312

1413

15-
h2. Installation
14+
h2. Installation / Deinstallation / Upgrading
15+
16+
h3. Installation
17+
18+
Paste the @.txt@ installer code into the _Admin › Plugins_ panel, or upload the plugin's @.php@ file via the _Upload plugin_ button, then install and enable the plugin.
19+
20+
h3. Upgrading
21+
22+
The plugin automatically migrates custom field data and the database structure from the earlier single custom field variant (v0.1) to the new format. No changes are needed to the public tags as the new default settings correspond to the old tag. Nevertheless, it is always advisable to make a database backup before upgrading.
23+
24+
h3. De-installation
1625

17-
Paste the code into the _Admin › Plugins_ panel, install and enable the plugin.
26+
The plugin cleans up after itself: deinstalling (deleting) the plugin removes the extra columns from the database as well as custom field names and labels. To stop using the plugin but keep the custom field data in the database, just disable (deactivate) the plugin but don't delete it.
1827

1928

20-
h2. Tags
29+
h2. Plugin tags
2130

22-
h3. txp:jcr_link_custom
31+
h3. jcr_link_custom
2332

2433
Outputs the content of the link custom field.
2534

2635
h4. Tag attributes
2736

2837
@name@
29-
Specifies the name of the link custom field.
38+
Specifies the name of the link custom field.
3039
Example: Use @name="image_id"@ to output the image_id custom field. Default: jcr_link_custom_1.
3140

3241
@escape@
33-
Escape HTML entities such as @<@, @>@ and @&@ prior to echoing the field contents.
42+
Escape HTML entities such as @<@, @>@ and @&@ prior to echoing the field contents.
3443
Supports extended escape values in txp 4.8+
3544
Example: Use @escape="textile"@ to convert textile in the value. Default: none.
3645

@@ -43,34 +52,36 @@ Wrap the custom field contents in an HTML tag
4352
Example: Use @wraptag="h2"@ to output @<h2>Custom field value</h2>@. Default: empty.
4453

4554
@class@
46-
Specifies a class to be added to the @wraptag@ attribure
55+
Specifies a class to be added to the @wraptag@ attribute
4756
Example: Use @wraptag="p" class="intro"@ to output @<p class="intro">Custom field value</p>@. Default: empty
4857

49-
h3. txp:jcr_if_link_custom
58+
h3. jcr_if_link_custom
5059

5160
Tests for existence of a link custom field, or whether one or several matches a value or pattern.
5261

5362
h4. Tag attributes
5463

5564
@name@
56-
Specifies the name of the link custom field.
65+
Specifies the name of the link custom field.
5766
Example: Use @name="image_id"@ to output the image_id custom field. Default: jcr_link_custom_1.
5867

5968
@value@
60-
Value to test against (optional).
69+
Value to test against (optional).
6170
If not specified, the tag tests for the existence of any value in the specified link custom field.
6271
Example: Use @value="english"@ to output only those links whose “language” link custom field is english. Default: none.
6372

6473
@match@
65-
Match testing: exact, any, all, pattern. See the docs for “if_custom_field”:https://docs.textpattern.com/tags/if_custom_field.
74+
Match testing: exact, any, all, pattern. See the docs for "if_custom_field":https://docs.textpattern.com/tags/if_custom_field.
6675
Default: exact.
6776

6877
@separator@
69-
Item separator for match="any" or "all". Otherwise ignored
78+
Item separator for match="any" or "all". Otherwise ignored.
7079
Default: empty.
7180

7281

73-
h2. Example
82+
h2. Examples
83+
84+
h3. Example 1
7485

7586
Produce a list of linked partner logos (from link assigned to the link category "partners"):
7687

@@ -82,35 +93,34 @@ bc. <txp:linklist wraptag="ul" break="li" category="partners">
8293
</txp:jcr_if_link_custom>
8394
</txp:linklist>
8495

85-
p. when the "image_id" link custom field is used to store the Image ID# of the logo.
96+
p. where the @image_id@ link custom field is used to store the Image ID# of the logo.
8697

8798

88-
h2. Changing the label of the custom field
99+
h2. Custom field labels
89100

90-
The name of custom field can be changed by specifying a new label using the _Install from Textpack_ field in the "Admin › Languages":http://docs.textpattern.io/administration/languages-panel panel. Enter your own information in the following pattern and click *Upload*:
101+
The label displayed alongside the custom field in the edit image panel can be changed by specifying a new label using the _Install from Textpack_ field in the "Admin › Languages":http://docs.textpattern.io/administration/languages-panel.html panel. Enter your own information in the following pattern and click *Upload*:
91102

92-
bc.. #@admin
93-
#@language en-gb
103+
bc. #@owner jcr_link_custom
104+
#@language en, en-gb, en-us
105+
#@link
94106
jcr_link_custom_1 => Your label
95107
jcr_link_custom_2 => Your other label
96108

97-
p. replacing @en-gb@ with your own language and @Your label@ with your own desired label.
98-
99-
100-
h2. De-installation
109+
p. replacing @en@ with your own language and @Your label@ with your own desired label.
101110

102-
The plugin cleans up after itself: deinstalling the plugin removes the extra column from the database. To stop using the plugin but keep the database tables, just disable (deactivate) the plugin but don't delete it.
103111

104-
105-
h2. Changelog + Credits
112+
h2. Changelog and credits
106113

107114
h3. Changelog
108115

116+
* Version 0.2.4 – 2020/12/20 – Align with other custom field plugins
117+
* Version 0.2.3 – 2020/06/29 – Tag registration + textpack fixes
118+
* Version 0.2.2 – 2020/06/27 – Handle migration from previous versions of the plugin on install
119+
* Version 0.2.1 – 2020/06/27 – Fix for missing custom_field name vs. missing value for cf
109120
* Version 0.2 – 2020/06/23 – Expand to handle multiple custom fields + migrate from v1
110-
* Version 0.1.1 – 2016/12/0518 – Remedy table not being created on install
121+
* Version 0.1.1 – 2016/12/0518 – Remedy table not being created on install
111122
* Version 0.1 – 2016/03/04 – First release
112123

113-
114124
h3. Credits
115125

116-
Robert Wetzlmayr’s "wet_profile":https://github.com/rwetzlmayr/wet_profile plugin for the starting point, and further examples by "Stef Dawson":http://www.stefdawson.com and "Jukka Svahn":https://github.com/gocom.
126+
Robert Wetzlmayr’s "wet_profile":https://github.com/rwetzlmayr/wet_profile plugin for the starting point, and further examples by "Stef Dawson":http://www.stefdawson.com and "Jukka Svahn":https://github.com/gocom.

0 commit comments

Comments
 (0)