Skip to content

Commit a292acc

Browse files
jools-rjools-r
committed
Update readme
1 parent 120c200 commit a292acc

File tree

2 files changed

+171
-119
lines changed

2 files changed

+171
-119
lines changed

‎README.md‎

Lines changed: 129 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,136 +1,176 @@
11
# jcr_section_custom
22

3-
Adds up to five extra custom fields of to 255 characters to the [Presentation › Sections](http://docs.textpattern.io/administration/sections-panel) pane along with corresponding tags to output the custom field, and to test if it contains a value or matches a specific value.
3+
Adds up to five extra custom fields of up to 255 characters to the
4+
[Presentation ›
5+
Sections](http://docs.textpattern.io/administration/sections-panel)
6+
panel along with corresponding tags to output the custom field and to
7+
test if it contains a value or matches a specific value.
48

9+
### Use cases
510

6-
## Use cases
11+
Use whenever extra information needs to be stored with a section. For
12+
example:
713

8-
Use whenever extra information needs to be stored with a section. For example:
14+
- Store a txp image ID number and use it to associate a cover image
15+
with the section.
16+
- Store associated details, for example the background colour or key
17+
colour of a section.
18+
- To use a different title for the menu than the section title.
19+
- To create links between parallel sections in different languages.
20+
- ...
921

10-
* Store a txp image ID number and use it to associate a cover image with the section.
11-
* Store associated details, for example the background colour or key colour of a section.
12-
* To use a different title for the menu than the section title.
13-
* To create links between parallel sections in different languages.
14-
* …
22+
## Installation / Deinstallation / Upgrading
1523

24+
### Installation
1625

17-
## Installation
26+
Paste the `.txt` installer code into the *Admin › Plugins* panel, or
27+
upload the plugin's `.php` file via the *Upload plugin* button, then
28+
install and enable the plugin.
1829

19-
Paste the code into the _Admin › Plugins_ panel, install and enable the plugin.
30+
### Upgrading
2031

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

22-
## Tags
38+
### De-installation
2339

24-
`<txp:jcr_section_custom />`
40+
The plugin cleans up after itself: deinstalling (deleting) the plugin
41+
removes the extra columns from the database as well as custom field
42+
names and labels. To stop using the plugin but keep the custom field
43+
data in the database, just disable (deactivate) the plugin but don't
44+
delete it.
2545

26-
Outputs the content of the section custom field.
27-
28-
### Tag attributes
29-
30-
**name**
31-
32-
Specifies the name of the section custom field.
33-
Example: Use `name="title_image"` to output the title_image custom field. Default: custom_field_1.
34-
35-
**escape**
36-
37-
Escape HTML entities such as `<`, `>` and `&` prior to echoing the field contents.
38-
Example: Use `escape=""` to suppress conversion. Default: `html`.
39-
40-
**default**
46+
## Plugin tags
4147

42-
Specifies the default output if the custom field is empty
43-
Example: Use `default="123"` to output "123", e.g. for use as the default image ID number. Default: empty.
48+
### jcr_section_custom
4449

45-
**wraptag**
50+
Outputs the content of the section custom field.
4651

47-
Wrap the custom field contents in an HTML tag
48-
Example: Use `wraptag="h2"` to output `<h2>Custom field value</h2>`. Default: empty.
52+
#### Tag attributes
4953

50-
**class**
54+
`name`\
55+
Specifies the name of the section custom field.\
56+
Example: Use `name="title_image"` to output the title_image custom
57+
field. Default: jcr_sec_custom_1.
5158

52-
Specifies a class to be added to the `wraptag` attribure
53-
Example: Use `wraptag="p" class="intro"` to output `<p class="intro">Custom field value</p>`. Default: empty
59+
`escape`\
60+
Escape HTML entities such as `<`, `>` and `&` prior to echoing the field
61+
contents.\
62+
Supports extended escape values in txp 4.8\
63+
Example: Use `escape="textile"` to convert textile in the value.
64+
Default: none.
5465

55-
`<txp:jcr_if_section_custom />`
66+
`default`\
67+
Specifies the default output if the custom field is empty\
68+
Example: Use `default="123"` to output "123", e.g. for use as the
69+
default image ID number. Default: empty.
5670

57-
Tests for existence of a section custom field, or whether one or several matches a value.or pattern.
71+
`wraptag`\
72+
Wrap the custom field contents in an HTML tag\
73+
Example: Use `wraptag="h2"` to output `<h2>Custom field value</h2>`.
74+
Default: empty.
5875

59-
### Tag attributes
76+
`class`\
77+
Specifies a class to be added to the `wraptag` attribute\
78+
Example: Use `wraptag="p" class="intro"` to output
79+
`<p class="intro">Custom field value</p>`. Default: empty
6080

61-
**name**
81+
### jcr_if_section_custom
6282

63-
Specifies the name of the section custom field.
64-
Example: Use `name="title_image"` to output the title_image custom field. Default: jcr_sec_custom_1.
83+
Tests for existence of a section custom field, or whether one or several
84+
matches a value or pattern.
6585

66-
**value**
86+
#### Tag attributes
6787

68-
Value to test against (optional).
69-
If not specified, the tag tests for the existence of any value in the specified section custom field.
70-
Example: Use `value="english"` to output only those sections whose “language” section custom field is english. Default: none.
88+
`name`\
89+
Specifies the name of the section custom field.\
90+
Example: Use `name="title_image"` to output the title_image custom
91+
field. Default: jcr_sec_custom_1.
7192

72-
**match**
93+
`value`\
94+
Value to test against (optional).\
95+
If not specified, the tag tests for the existence of any value in the
96+
specified section custom field.\
97+
Example: Use `value="english"` to output only those sections whose
98+
"language" section custom field is english. Default: none.
7399

74-
Match testing: exact, any, all, pattern. See the docs for [if_custom_field](https://docs.textpattern.com/tags/if_custom_field).
100+
`match`\
101+
Match testing: exact, any, all, pattern. See the docs for
102+
[if_custom_field](https://docs.textpattern.com/tags/if_custom_field).\
75103
Default: exact.
76104

77-
**separator**
78-
79-
Item separator for match="any" or "all". Otherwise ignored.
105+
`separator`\
106+
Item separator for match="any" or "all". Otherwise ignored.\
80107
Default: empty.
81108

109+
## Examples
82110

83-
## Example
84-
85-
1. Outputs the specified title image from the image ID number. If no image is specified a default image with image ID# 123 is output:
86-
87-
```
88-
<txp:section_list>
89-
<txp:images id='<txp:jcr_section_custom name="title_image" escape="" default="123" />'>
90-
<txp:image />
91-
</txp:images>
92-
</txp:section_list>
93-
```
94-
95-
where the section custom field is used to store the Image ID# of the title image.
111+
### Example 1
96112

97-
2. Outputs a menu of only those sections whose "language" custom field equals "english":
113+
Outputs the specified title image from the image ID number. If no image
114+
is specified a default image with image ID\# 123 is output:
98115

99-
```
100-
<txp:section_list wraptag="ul" break="" class="nav en">
101-
<txp:jcr_if_section_custom name="language" value="english">
102-
<li><txp:section title link /></li>
103-
</txp:jcr_if_section_custom>
104-
</txp:section_list>
105-
```
116+
<txp:section_list>
117+
<txp:images id='<txp:jcr_section_custom name="title_image" escape="" default="123" />'>
118+
<txp:image />
119+
</txp:images>
120+
</txp:section_list>
106121

107-
## Changing the label of the custom field
122+
where the section custom field is used to store the Image ID\# of the
123+
title image.
108124

109-
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*:
125+
### Example 2
110126

111-
```
112-
#@admin
113-
#@language en-gb
114-
jcr_sec_custom_1 => Your label
115-
jcr_sec_custom_2 => Your other label
116-
…
117-
```
127+
Outputs a menu of only those sections whose "language" custom field
128+
equals "english":
118129

119-
replacing `en-gb` with your own language and `Your label` with your own desired label.
130+
<txp:section_list wraptag="ul" break="" class="nav en">
131+
<txp:jcr_if_section_custom name="language" value="english">
132+
<li><txp:section title link /></li>
133+
</txp:jcr_if_section_custom>
134+
</txp:section_list>
120135

136+
## Custom field labels
121137

122-
## De-installation
138+
The label displayed alongside the custom field in the edit image panel
139+
can be changed by specifying a new label using the *Install from
140+
Textpack* field in the [Admin ›
141+
Languages](http://docs.textpattern.io/administration/languages-panel.html)
142+
panel. Enter your own information in the following pattern and click
143+
**Upload**:
123144

124-
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.
145+
#@owner jcr_section_custom
146+
#@language en, en-gb, en-us
147+
#@section
148+
jcr_sec_custom_1 => Your label
149+
jcr_sec_custom_2 => Your other label
150+
…
125151

152+
replacing `en` with your own language and `Your label` with your own
153+
desired label.
126154

127-
## Changelog
155+
## Changelog and credits
128156

129-
* Version 0.2 – 2020/03/04 – Expand to handle multiple custom fields
130-
* Version 0.15 – 2018/07/18 – Remedy table not being created on install
131-
* Version 0.1 – 2016/03/04 – First release
157+
### Changelog
132158

159+
- Version 0.2.3 -- 2020/12/18 -- No new functionality. Textpack fixes
160+
and align with other custom field plugins
161+
- Version 0.2.2 -- 2020/06/27 -- Handle migration from previous
162+
versions of the plugin on install
163+
- Version 0.2.1 -- 2020/06/27 -- Fix for missing custom_field name vs.
164+
missing value for cf
165+
- Version 0.2 -- 2020/03/04 -- Expand to handle multiple custom fields
166+
- Version 0.1 -- 2018/07/18 -- Remedy table not being created on
167+
install
168+
- Version 0.1 -- 2016/03/04 -- First release
133169

134-
## Credits
170+
### Credits
135171

136-
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).
172+
Robert Wetzlmayr's
173+
[wet_profile](https://github.com/rwetzlmayr/wet_profile) plugin for the
174+
starting point, and further examples by [Stef
175+
Dawson](http://www.stefdawson.com) and [Jukka
176+
Svahn](https://github.com/gocom).

0 commit comments

Comments
 (0)