Skip to content

Commit 16aa7be

Browse files
jools-rjools-r
committed
Update Readme
1 parent cb4e557 commit 16aa7be

File tree

2 files changed

+212
-23
lines changed

2 files changed

+212
-23
lines changed

‎README.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# jcr_image_custom
2+
3+
Adds up to five extra custom fields of up to 255 characters to the
4+
[Content ›
5+
Images](http://docs.textpattern.io/administration/images-panel) panel
6+
along with corresponding tags to output the custom field and to test if
7+
it contains a value or matches a specific value.
8+
9+
### Use cases
10+
11+
Use whenever extra information needs to be stored with an image. For
12+
example:
13+
14+
- Store a youtube/vimeo link or video-ID with an image for generating
15+
custom video poster images.
16+
- Store the download url of a corresponding hi-res press image not
17+
stored in txp.
18+
- Store the year a picture / photograph was taken
19+
- Store the copyright owners name + link
20+
- ...
21+
22+
## Installation / Deinstallation / Upgrading
23+
24+
### Installation
25+
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.
29+
30+
### Upgrading
31+
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.
37+
38+
### De-installation
39+
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.
45+
46+
## Plugin tags
47+
48+
### jcr_image_custom
49+
50+
Outputs the content of the image custom field.
51+
52+
#### Tag attributes
53+
54+
`name`\
55+
Specifies the name of the image custom field.\
56+
Example: Use `name="copyright_author"` to output the copyright_author
57+
custom field. Default: jcr_image_custom_1.
58+
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.
65+
66+
`default`\
67+
Specifies the default output if the custom field is empty\
68+
Example: Use `default="Org Name"` to output "Org Name", e.g. for when no
69+
copyright_author explicitly given. Default: empty.
70+
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.
75+
76+
`class`\
77+
Specifies a class to be added to the `wraptag` attribute\
78+
Example: Use `wraptag="p" class="copyright"` to output
79+
`<p class="copyright">Custom field value</p>`. Default: empty
80+
81+
### jcr_if_image_custom
82+
83+
Tests for existence of an image custom field, or whether one or several
84+
matches a value or pattern.
85+
86+
#### Tag attributes
87+
88+
`name`\
89+
Specifies the name of the image custom field.\
90+
Example: Use `name="copyright_author"` to output the copyright_author
91+
custom field. Default: jcr_image_custom_1.
92+
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 image custom field.\
97+
Example: Use `value="english"` to output only those images whose
98+
"language" image custom field is english. Default: none.
99+
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.\
103+
Default: exact.
104+
105+
`separator`\
106+
Item separator for match="any" or "all". Otherwise ignored.\
107+
Default: empty.
108+
109+
## Examples
110+
111+
### Example 1
112+
113+
Output a gallery of custom video poster-images (from images assigned to
114+
the image category "videos") that open a corresponding youtube video
115+
(defined in the image custom field) in a lightbox modal:
116+
117+
<txp:images wraptag="ul" break="li" category="videos" class="video-gallery">
118+
<a href="//www.youtube.com/watch?v=<txp:jcr_image_custom name="youtube_id" />" title="<txp:image_info type="caption" />" data-lity>
119+
<txp:thumbnail />
120+
<txp:jcr_image_custom name="youtube_author" wraptag="p" class="author" />
121+
</a>
122+
</txp:images>
123+
124+
where the image custom field is used to store the Video ID of the
125+
YouTube video. This example uses the [lity](http://sorgalla.com/lity/)
126+
lightbox script.
127+
128+
### Example 2
129+
130+
Outputs the copyright author with or without link:
131+
132+
<txp:images wraptag="ul" break="li" class="photoset">
133+
<figure class="photo">
134+
<txp:image />
135+
<figcaption>
136+
<txp:image_info type="caption" wraptag="p" />
137+
<txp:jcr_if_image_custom name="copyright_link">
138+
<a href="<txp:jcr_image_custom name="copyright_link" />" class="img-owner"><txp:jcr_image_custom name="copyright_author" /></a>
139+
<txp:else />
140+
<txp:jcr_image_custom name="copyright_author" wraptag="span" class="img-owner" />
141+
</txp:jcr_if_image_custom>
142+
</figcaption>
143+
</figure>
144+
</txp:images>
145+
146+
## Custom field labels
147+
148+
The label displayed alongside the custom field in the edit image panel
149+
can be changed by specifying a new label using the *Install from
150+
Textpack* field in the [Admin ›
151+
Languages](http://docs.textpattern.io/administration/languages-panel.html)
152+
panel. Enter your own information in the following pattern and click
153+
**Upload**:
154+
155+
#@owner jcr_image_custom
156+
#@language en, en-gb, en-us
157+
#@image
158+
jcr_image_custom_1 => Your label
159+
jcr_image_custom_2 => Your other label
160+
161+
replacing `en` with your own language and `Your label` with your own
162+
desired label.
163+
164+
## Changelog and credits
165+
166+
### Changelog
167+
168+
- Version 0.2.0 -- 2020/12/17 -- Expand to handle multiple custom
169+
fields
170+
- Version 0.1.1 -- 2016/12/05 -- Remedy table not being created on
171+
install
172+
- Version 0.1 -- 2016/04/16
173+
174+
### Credits
175+
176+
Robert Wetzlmayr's
177+
[wet_profile](https://github.com/rwetzlmayr/wet_profile) plugin for the
178+
starting point, and further examples by [Stef
179+
Dawson](http://www.stefdawson.com) and [Jukka
180+
Svahn](https://github.com/gocom).

‎README.textile‎

Lines changed: 32 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,7 @@ h1. jcr_image_custom
22

33
Adds up to five extra custom fields of up to 255 characters to the "Content › Images":http://docs.textpattern.io/administration/images-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-
h3(#installation). Installation
6-
7-
Paste the code into the _Admin › Plugins_ panel, install and enable the plugin.
8-
9-
10-
h2. Use cases
5+
h3. Use cases
116

127
Use whenever extra information needs to be stored with an image. For example:
138

@@ -18,7 +13,22 @@ Use whenever extra information needs to be stored with an image. For example:
1813
* …
1914

2015

21-
h2(#tags). Tags
16+
h2. Installation / Deinstallation / Upgrading
17+
18+
h3. Installation
19+
20+
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.
21+
22+
h3. Upgrading
23+
24+
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.
25+
26+
h3. De-installation
27+
28+
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.
29+
30+
31+
h2. Plugin tags
2232

2333
h3. jcr_image_custom
2434

@@ -63,17 +73,19 @@ If not specified, the tag tests for the existence of any value in the specified
6373
Example: Use @value="english"@ to output only those images whose “language” image custom field is english. Default: none.
6474

6575
@match@
66-
Match testing: exact, any, all, pattern. See the docs for "if_custom_field":https://docs.textpattern.com/tags/if_custom_field.
76+
Match testing: exact, any, all, pattern. See the docs for “if_custom_field”:https://docs.textpattern.com/tags/if_custom_field.
6777
Default: exact.
6878

6979
@separator@
70-
Item separator for @match="any"@ or @"all"@. Otherwise ignored.
80+
Item separator for match="any" or "all". Otherwise ignored.
7181
Default: empty.
7282

7383

74-
h2(#examples). Examples
84+
h2. Examples
85+
86+
h3. Example 1
7587

76-
1. Output a gallery of custom video poster-images (from images assigned to the image category "videos") that open a corresponding youtube video (defined in the image custom field) in a lightbox modal:
88+
Output a gallery of custom video poster-images (from images assigned to the image category "videos") that open a corresponding youtube video (defined in the image custom field) in a lightbox modal:
7789

7890
bc. <txp:images wraptag="ul" break="li" category="videos" class="video-gallery">
7991
<a href="//www.youtube.com/watch?v=<txp:jcr_image_custom name="youtube_id" />" title="<txp:image_info type="caption" />" data-lity>
@@ -84,8 +96,9 @@ bc. <txp:images wraptag="ul" break="li" category="videos" class="video-gallery">
8496

8597
p. where the image custom field is used to store the Video ID of the YouTube video. This example uses the "lity":http://sorgalla.com/lity/ lightbox script.
8698

99+
h3. Example 2
87100

88-
2. Outputs the copyright author with or without link:
101+
Outputs the copyright author with or without link:
89102

90103
bc. <txp:images wraptag="ul" break="li" class="photoset">
91104
<figure class="photo">
@@ -102,24 +115,20 @@ bc. <txp:images wraptag="ul" break="li" class="photoset">
102115
</txp:images>
103116

104117

105-
h2. Changing the label of the custom field
118+
h2. Custom field labels
106119

107-
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.html panel. Enter your own information in the following pattern and click *Upload*:
120+
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*:
108121

109-
bc.. #@admin
110-
#@language en
122+
bc. #@owner jcr_image_custom
123+
#@language en, en-gb, en-us
124+
#@image
111125
jcr_image_custom_1 => Your label
112126
jcr_image_custom_2 => Your other label
113127

114-
p. replacing @en-gb@ with your own language and @Your label@ with your own desired label.
115-
116-
117-
h2(#deinstallation). De-installation
118-
119-
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.
128+
p. replacing @en@ with your own language and @Your label@ with your own desired label.
120129

121130

122-
h2(#changelog). Changelog + Credits
131+
h2. Changelog and credits
123132

124133
h3. Changelog
125134

0 commit comments

Comments
 (0)