Attachments - Version 3.2

Version Description

  • Added option to disable the Settings screen
  • Added the ability to set a default for fields using the metadata that exists in WordPress. Available defaults include: title, caption, alt, and description. If set, the metadata for the correlating field will be used as the field default when initially adding an Attachment from the Media modal. Only applies to text, textarea, and wysiwyg fields.
  • Added a get_single() method that allows you to specifically retrieve a single Attachment
  • Clarified some documentation
Download this release

Release Info

Developer jchristopher
Plugin Icon wp plugin Attachments
Version 3.2
Comparing to
See all releases

Code changes from version 3.1.4 to 3.2

Files changed (8) hide show
  1. README.md +38 -10
  2. classes/class.attachments.php +53 -18
  3. classes/class.field.php +13 -1
  4. classes/fields/class.field.text.php +1 -1
  5. classes/fields/class.field.textarea.php +1 -1
  6. classes/fields/class.field.wysiwyg.php +1 -1
  7. index.php +1 -1
  8. readme.txt +50 -22
README.md CHANGED
@@ -74,6 +74,12 @@ Version 3 is a **major** rewrite. While I've taken precautions in ensuring you w
74
 
75
  ## Usage
76
 
 
 
 
 
 
 
77
  When Attachments is first activated, a default instance is created titled Attachments. It has two fields:
78
 
79
  1. Title
@@ -116,22 +122,26 @@ function my_attachments( $attachments )
116
  * Fields for the instance are stored in an array. Each field consists of
117
  * an array with three keys: name, type, label.
118
  *
119
- * name - (string) The field name used. No special characters.
120
- * type - (string) The registered field type.
121
  * Fields available: text, textarea, wysiwyg
122
- * label - (string) The label displayed for the field.
 
 
123
  */
124
 
125
  'fields' => array(
126
  array(
127
- 'name' => 'title', // unique field name
128
- 'type' => 'text', // registered field type
129
- 'label' => __( 'Title', 'attachments' ), // label to display
 
130
  ),
131
  array(
132
- 'name' => 'caption', // unique field name
133
- 'type' => 'wysiwyg', // registered field type
134
- 'label' => __( 'Caption', 'attachments' ), // label to display
 
135
  )
136
  ),
137
 
@@ -203,6 +213,18 @@ You can also retrieve various attributes of the current Attachment directly usin
203
  <?php endif; ?>
204
  ```
205
 
 
 
 
 
 
 
 
 
 
 
 
 
206
  ## Screenshots
207
 
208
  ##### An Attachments meta box sitting below the content editor
@@ -244,12 +266,18 @@ Attachments uses WordPress' built in Media library for uploads and storage.
244
 
245
  #### I lost my Attachments after upgrading!
246
 
247
- ***DO NOT update any Post/Page/CPT with Attachments***, the data has not been lost. Please [contact me](http://mondaybynoon.com/contact/) to begin a bugfix
248
 
249
  ## Changelog
250
 
251
  <dl>
252
 
 
 
 
 
 
 
253
  <dt>3.1.4</dt>
254
  <dd>Changed 'Delete' to 'Remove' so as to not make it sound like the file itself would be deleted from Media (props Lane Goldberg)</dd>
255
  <dd>Better handling of posts that have no Attachments when saving</dd>
74
 
75
  ## Usage
76
 
77
+ Attachments ships with a `Settings` screen (found under the `Settings` menu in the main WordPress admin navigation) that facilitates data migration from version 1.x and also offers some code snippets. If you would like to **disable the Settings screen** add the following to your theme's `functions.php`:
78
+
79
+ ```php
80
+ define( 'ATTACHMENTS_SETTINGS_SCREEN', false ); // disable the Settings screen
81
+ ```
82
+
83
  When Attachments is first activated, a default instance is created titled Attachments. It has two fields:
84
 
85
  1. Title
122
  * Fields for the instance are stored in an array. Each field consists of
123
  * an array with three keys: name, type, label.
124
  *
125
+ * name - (string) The field name used. No special characters.
126
+ * type - (string) The registered field type.
127
  * Fields available: text, textarea, wysiwyg
128
+ * label - (string) The label displayed for the field.
129
+ * caption - (string) The default WordPress metadata to use when initially adding the Attachment
130
+ * Defaults available: title, caption, alt, description
131
  */
132
 
133
  'fields' => array(
134
  array(
135
+ 'name' => 'title', // unique field name
136
+ 'type' => 'text', // registered field type
137
+ 'label' => __( 'Title', 'attachments' ), // label to display
138
+ 'default' => 'title', // default value upon selection
139
  ),
140
  array(
141
+ 'name' => 'caption', // unique field name
142
+ 'type' => 'textarea', // registered field type
143
+ 'label' => __( 'Caption', 'attachments' ), // label to display
144
+ 'default' => 'caption', // default value upon selection
145
  )
146
  ),
147
 
213
  <?php endif; ?>
214
  ```
215
 
216
+ If you don't want to use the above implementation to loop through your Attachments, can also retrieve them explicitly:
217
+
218
+ ```php
219
+ <?php $attachments = new Attachments( 'attachments' ); ?>
220
+ <?php if( $attachments->exist() ) : ?>
221
+ <?php if( $attachment = $attachments->get_single( 0 ) ) : ?>
222
+ <h3>Attachment at index 0:</h3>
223
+ <pre><?php print_r( $attachment ); ?></pre>
224
+ <?php endif; ?>
225
+ <?php endif; ?>
226
+ ```
227
+
228
  ## Screenshots
229
 
230
  ##### An Attachments meta box sitting below the content editor
266
 
267
  #### I lost my Attachments after upgrading!
268
 
269
+ ***DO NOT update any Post/Page/CPT with Attachments***, the data has not been lost. Please **[Upgrade notice](#upgrade-notice)**.
270
 
271
  ## Changelog
272
 
273
  <dl>
274
 
275
+ <dt>3.2</dt>
276
+ <dd>Added option to disable the Settings screen</dd>
277
+ <dd>Added the ability to set a default for fields using the metadata that exists in WordPress. Available defaults include: title, caption, alt, and description. If set, the metadata for the correlating field will be used as the field default when initially adding an Attachment from the Media modal. Only applies to text, textarea, and wysiwyg fields.</dd>
278
+ <dd>Added a `get_single()` method that allows you to specifically retrieve a single Attachment</dd>
279
+ <dd>Clarified some documentation</dd>
280
+
281
  <dt>3.1.4</dt>
282
  <dd>Changed 'Delete' to 'Remove' so as to not make it sound like the file itself would be deleted from Media (props Lane Goldberg)</dd>
283
  <dd>Better handling of posts that have no Attachments when saving</dd>
classes/class.attachments.php CHANGED
@@ -59,7 +59,7 @@ if ( !class_exists( 'Attachments' ) ) :
59
 
60
  // establish our environment variables
61
 
62
- $this->version = '3.1.4';
63
  $this->url = ATTACHMENTS_URL;
64
  $this->dir = ATTACHMENTS_DIR;
65
 
@@ -89,7 +89,10 @@ if ( !class_exists( 'Attachments' ) ) :
89
  add_action( 'add_meta_boxes', array( $this, 'meta_box_init' ) );
90
  add_action( 'admin_footer', array( $this, 'admin_footer' ) );
91
  add_action( 'save_post', array( $this, 'save' ) );
92
- add_action( 'admin_menu', array( $this, 'admin_page' ) );
 
 
 
93
 
94
  // with version 3 we'll be giving at least one admin notice
95
  add_action( 'admin_notices', array( $this, 'admin_notice' ) );
@@ -198,6 +201,18 @@ if ( !class_exists( 'Attachments' ) ) :
198
 
199
 
200
 
 
 
 
 
 
 
 
 
 
 
 
 
201
  /**
202
  * Returns the asset (array) for the current Attachment
203
  *
@@ -539,11 +554,14 @@ if ( !class_exists( 'Attachments' ) ) :
539
  attachment.attributes.attachment_thumb = attachment.attributes.icon;
540
 
541
  // only thumbnails have sizes which is what we're on the hunt for
542
- if(attachments_isset(attachment.attributes.sizes)){
543
- if(attachments_isset(attachment.attributes.sizes.thumbnail)){
544
- if(attachments_isset(attachment.attributes.sizes.thumbnail.url)){
545
- // use the thumbnail
546
- attachment.attributes.attachment_thumb = attachment.attributes.sizes.thumbnail.url;
 
 
 
547
  }
548
  }
549
  }
@@ -553,6 +571,19 @@ if ( !class_exists( 'Attachments' ) ) :
553
  // append the template
554
  $element.find('.attachments-container').append(template(templateData));
555
 
 
 
 
 
 
 
 
 
 
 
 
 
 
556
  $('body').trigger('attachments/new');
557
 
558
  // if it wasn't an image we need to ditch the dimensions
@@ -706,14 +737,16 @@ if ( !class_exists( 'Attachments' ) ) :
706
  // fields for this instance (array)
707
  'fields' => array(
708
  array(
709
- 'name' => 'title', // unique field name
710
- 'type' => 'text', // registered field type
711
- 'label' => __( 'Title', 'attachments' ), // label to display
 
712
  ),
713
  array(
714
- 'name' => 'caption', // unique field name
715
- 'type' => 'text', // registered field type
716
- 'label' => __( 'Caption', 'attachments' ), // label to display
 
717
  ),
718
  ),
719
 
@@ -861,13 +894,14 @@ if ( !class_exists( 'Attachments' ) ) :
861
 
862
  if( isset( $this->fields[$type] ) )
863
  {
864
- $name = sanitize_title( $field['name'] );
865
- $label = esc_html( $field['label'] );
 
866
 
867
- $value = ( isset( $attachment->fields->$name ) ) ? $attachment->fields->$name : null;
868
 
869
- $field = new $this->fields[$type]( $name, $label, $value );
870
- $field->value = $field->format_value_for_input( $field->value );
871
 
872
  // does this field already have a unique ID?
873
  $uid = ( isset( $attachment->uid ) ) ? $attachment->uid : null;
@@ -876,6 +910,7 @@ if ( !class_exists( 'Attachments' ) ) :
876
  $field->set_field_instance( $instance, $field );
877
  $field->set_field_identifiers( $field, $uid );
878
  $field->set_field_type( $type );
 
879
 
880
  ?>
881
  <div class="attachments-attachment-field attachments-attachment-field-<?php echo $instance; ?> attachments-attachment-field-<?php echo $field->type; ?> attachment-field-<?php echo $field->name; ?>">
59
 
60
  // establish our environment variables
61
 
62
+ $this->version = '3.2';
63
  $this->url = ATTACHMENTS_URL;
64
  $this->dir = ATTACHMENTS_DIR;
65
 
89
  add_action( 'add_meta_boxes', array( $this, 'meta_box_init' ) );
90
  add_action( 'admin_footer', array( $this, 'admin_footer' ) );
91
  add_action( 'save_post', array( $this, 'save' ) );
92
+
93
+ // only show the Settings screen if it hasn't been explicitly disabled
94
+ if( !( defined( 'ATTACHMENTS_SETTINGS_SCREEN' ) && ATTACHMENTS_SETTINGS_SCREEN === false ) )
95
+ add_action( 'admin_menu', array( $this, 'admin_page' ) );
96
 
97
  // with version 3 we'll be giving at least one admin notice
98
  add_action( 'admin_notices', array( $this, 'admin_notice' ) );
201
 
202
 
203
 
204
+ /**
205
+ * Returns a specific Attachment
206
+ *
207
+ * @since 3.2
208
+ */
209
+ function get_single( $index )
210
+ {
211
+ return isset( $this->attachments[$index] ) ? $this->attachments[$index] : false;
212
+ }
213
+
214
+
215
+
216
  /**
217
  * Returns the asset (array) for the current Attachment
218
  *
554
  attachment.attributes.attachment_thumb = attachment.attributes.icon;
555
 
556
  // only thumbnails have sizes which is what we're on the hunt for
557
+ // TODO: this is a mess
558
+ if(attachments_isset(attachment.attributes)){
559
+ if(attachments_isset(attachment.attributes.sizes)){
560
+ if(attachments_isset(attachment.attributes.sizes.thumbnail)){
561
+ if(attachments_isset(attachment.attributes.sizes.thumbnail.url)){
562
+ // use the thumbnail
563
+ attachment.attributes.attachment_thumb = attachment.attributes.sizes.thumbnail.url;
564
+ }
565
  }
566
  }
567
  }
571
  // append the template
572
  $element.find('.attachments-container').append(template(templateData));
573
 
574
+ // see if we need to set a default
575
+ // TODO: can we tie this into other field types (select, radio, checkbox)?
576
+ $element.find('.attachments-attachment:last .attachments-fields input, .attachments-attachment:last .attachments-fields textarea').each(function(){
577
+ if($(this).data('default')){
578
+ var meta_for_default = $(this).data('default');
579
+ if(attachments_isset(attachment.attributes)){
580
+ if(attachments_isset(attachment.attributes[meta_for_default])){
581
+ $(this).val(attachment.attributes[meta_for_default]);
582
+ }
583
+ }
584
+ }
585
+ });
586
+
587
  $('body').trigger('attachments/new');
588
 
589
  // if it wasn't an image we need to ditch the dimensions
737
  // fields for this instance (array)
738
  'fields' => array(
739
  array(
740
+ 'name' => 'title', // unique field name
741
+ 'type' => 'text', // registered field type
742
+ 'label' => __( 'Title', 'attachments' ), // label to display
743
+ 'default' => 'title', // default value upon selection
744
  ),
745
  array(
746
+ 'name' => 'caption', // unique field name
747
+ 'type' => 'wysiwyg', // registered field type
748
+ 'label' => __( 'Caption', 'attachments' ), // label to display
749
+ 'default' => 'caption', // default value upon selection
750
  ),
751
  ),
752
 
894
 
895
  if( isset( $this->fields[$type] ) )
896
  {
897
+ $name = sanitize_title( $field['name'] );
898
+ $label = esc_html( $field['label'] );
899
+ $default = isset( $field['default'] ) ? $field['default'] : false; // validated in the class
900
 
901
+ $value = ( isset( $attachment->fields->$name ) ) ? $attachment->fields->$name : null;
902
 
903
+ $field = new $this->fields[$type]( $name, $label, $value );
904
+ $field->value = $field->format_value_for_input( $field->value );
905
 
906
  // does this field already have a unique ID?
907
  $uid = ( isset( $attachment->uid ) ) ? $attachment->uid : null;
910
  $field->set_field_instance( $instance, $field );
911
  $field->set_field_identifiers( $field, $uid );
912
  $field->set_field_type( $type );
913
+ $field->set_field_default( $default );
914
 
915
  ?>
916
  <div class="attachments-attachment-field attachments-attachment-field-<?php echo $instance; ?> attachments-attachment-field-<?php echo $field->type; ?> attachment-field-<?php echo $field->name; ?>">
classes/class.field.php CHANGED
@@ -28,12 +28,18 @@ if ( !class_exists( 'Attachments_Field' ) ) :
28
  public $type; // field type as it was registered
29
  public $uid; // unique id for field
30
  public $value; // the value for the field
 
 
31
 
32
  function __construct( $name = 'name', $label = 'Name', $value = null )
33
  {
34
  $this->name = sanitize_title( $name );
35
  $this->label = __( esc_attr( $label) );
36
  $this->value = $value;
 
 
 
 
37
  }
38
 
39
  function set_field_instance( $instance, $field )
@@ -64,10 +70,16 @@ if ( !class_exists( 'Attachments_Field' ) ) :
64
  $this->type = $field_type;
65
  }
66
 
 
 
 
 
 
 
67
  public function html( $field )
68
  {
69
  ?>
70
- <input type="text" name="<?php esc_attr_e( $field->field_name ); ?>" id="<?php esc_attr_e( $field->field_id ); ?>" class="attachments attachments-field attachments-field-<?php esc_attr_e( $field->field_name ); ?> attachments-field-<?php esc_attr_e( $field->field_id ); ?>" value="<?php esc_attr_e( $field->value ); ?>" />
71
  <?php
72
  }
73
 
28
  public $type; // field type as it was registered
29
  public $uid; // unique id for field
30
  public $value; // the value for the field
31
+ public $defaults; // stores possible defaults the user can use which correlate with WP Media meta
32
+ public $default; // the user-defined default value when first selected from the modal
33
 
34
  function __construct( $name = 'name', $label = 'Name', $value = null )
35
  {
36
  $this->name = sanitize_title( $name );
37
  $this->label = __( esc_attr( $label) );
38
  $this->value = $value;
39
+ $this->default = '';
40
+
41
+ $this->defaults = array( 'title', 'caption', 'alt', 'description' ); // WordPress-specific Media meta
42
+ // TODO: determine how to integrate with custom metadata that was added to Media
43
  }
44
 
45
  function set_field_instance( $instance, $field )
70
  $this->type = $field_type;
71
  }
72
 
73
+ function set_field_default( $default = '' )
74
+ {
75
+ if( is_string( $default ) && !empty( $default ) && in_array( strtolower( $default ), $this->defaults ) )
76
+ $this->default = strtolower( $default );
77
+ }
78
+
79
  public function html( $field )
80
  {
81
  ?>
82
+ <input type="text" name="<?php esc_attr_e( $field->field_name ); ?>" id="<?php esc_attr_e( $field->field_id ); ?>" class="attachments attachments-field attachments-field-<?php esc_attr_e( $field->field_name ); ?> attachments-field-<?php esc_attr_e( $field->field_id ); ?>" value="<?php esc_attr_e( $field->value ); ?>" data-default="<?php esc_attr_e( $field->default ); ?>" />
83
  <?php
84
  }
85
 
classes/fields/class.field.text.php CHANGED
@@ -18,7 +18,7 @@ class Attachments_Field_Text extends Attachments_Field implements Attachments_Fi
18
  function html( $field )
19
  {
20
  ?>
21
- <input type="text" name="<?php esc_attr_e( $field->field_name ); ?>" id="<?php esc_attr_e( $field->field_id ); ?>" class="attachments attachments-field attachments-field-<?php esc_attr_e( $field->field_name ); ?> attachments-field-<?php esc_attr_e( $field->field_id ); ?>" value="<?php esc_attr_e( $field->value ); ?>" />
22
  <?php
23
  }
24
 
18
  function html( $field )
19
  {
20
  ?>
21
+ <input type="text" name="<?php esc_attr_e( $field->field_name ); ?>" id="<?php esc_attr_e( $field->field_id ); ?>" class="attachments attachments-field attachments-field-<?php esc_attr_e( $field->field_name ); ?> attachments-field-<?php esc_attr_e( $field->field_id ); ?>" value="<?php esc_attr_e( $field->value ); ?>" data-default="<?php esc_attr_e( $field->default ); ?>" />
22
  <?php
23
  }
24
 
classes/fields/class.field.textarea.php CHANGED
@@ -18,7 +18,7 @@ class Attachments_Field_Textarea extends Attachments_Field implements Attachment
18
  function html( $field )
19
  {
20
  ?>
21
- <textarea type="text" name="<?php esc_attr_e( $field->field_name ); ?>" id="<?php esc_attr_e( $field->field_id ); ?>" class="attachments attachments-field attachments-field-<?php esc_attr_e( $field->field_name ); ?> attachments-field-<?php esc_attr_e( $field->field_id ); ?>"><?php echo esc_textarea( $field->value ); ?></textarea>
22
  <?php
23
  }
24
 
18
  function html( $field )
19
  {
20
  ?>
21
+ <textarea type="text" name="<?php esc_attr_e( $field->field_name ); ?>" id="<?php esc_attr_e( $field->field_id ); ?>" class="attachments attachments-field attachments-field-<?php esc_attr_e( $field->field_name ); ?> attachments-field-<?php esc_attr_e( $field->field_id ); ?>" data-default="<?php esc_attr_e( $field->default ); ?>"><?php echo esc_textarea( $field->value ); ?></textarea>
22
  <?php
23
  }
24
 
classes/fields/class.field.wysiwyg.php CHANGED
@@ -34,7 +34,7 @@ class Attachments_Field_WYSIWYG extends Attachments_Field implements Attachments
34
  ?>
35
  <div class="wp-editor-wrap attachments-field-wysiwyg-editor-wrap">
36
  <div class="wp-editor-container">
37
- <textarea name="<?php esc_attr_e( $field->field_name ); ?>" id="<?php esc_attr_e( $field->field_id ); ?>" class="wp-editor-area attachments attachments-field attachments-field-wysiwyg attachments-field-<?php esc_attr_e( $field->field_name ); ?> attachments-field-<?php esc_attr_e( $field->field_id ); ?>" rows="10"><?php echo $field->value; ?></textarea>
38
  </div>
39
  </div>
40
  <?php
34
  ?>
35
  <div class="wp-editor-wrap attachments-field-wysiwyg-editor-wrap">
36
  <div class="wp-editor-container">
37
+ <textarea name="<?php esc_attr_e( $field->field_name ); ?>" id="<?php esc_attr_e( $field->field_id ); ?>" class="wp-editor-area attachments attachments-field attachments-field-wysiwyg attachments-field-<?php esc_attr_e( $field->field_name ); ?> attachments-field-<?php esc_attr_e( $field->field_id ); ?>" rows="10" data-default="<?php esc_attr_e( $field->default ); ?>"><?php echo $field->value; ?></textarea>
38
  </div>
39
  </div>
40
  <?php
index.php CHANGED
@@ -6,7 +6,7 @@
6
  * Description: Attachments gives the ability to append any number of Media Library items to Pages, Posts, and Custom Post Types
7
  * Author: Jonathan Christopher
8
  * Author URI: http://mondaybynoon.com/
9
- * Version: 3.1.4
10
  * Text Domain: attachments
11
  * Domain Path: /languages/
12
  * License: GPLv2 or later
6
  * Description: Attachments gives the ability to append any number of Media Library items to Pages, Posts, and Custom Post Types
7
  * Author: Jonathan Christopher
8
  * Author URI: http://mondaybynoon.com/
9
+ * Version: 3.2
10
  * Text Domain: attachments
11
  * Domain Path: /languages/
12
  * License: GPLv2 or later
readme.txt CHANGED
@@ -4,7 +4,7 @@ Donate link: http://mondaybynoon.com/donate/
4
  Tags: post, page, posts, pages, images, PDF, doc, Word, image, jpg, jpeg, picture, pictures, photos, attachment
5
  Requires at least: 3.0
6
  Tested up to: 3.5
7
- Stable tag: 3.1.4
8
  License: GPLv2 or later
9
  License URI: http://www.gnu.org/licenses/gpl-2.0.html
10
 
@@ -56,8 +56,16 @@ There is a lot more information on [Attachments' GitHub page](https://github.com
56
  1. Download the plugin and extract the files
57
  1. Upload `attachments` to your `~/wp-content/plugins/` directory
58
  1. Activate the plugin through the 'Plugins' menu in WordPress
59
- 1. Implement Attachments in your theme's `functions.php` or your own plugin (see **Usage**)
60
- 1. Update your templates where applicable (see **Usage**)
 
 
 
 
 
 
 
 
61
 
62
  == Frequently Asked Questions ==
63
 
@@ -67,15 +75,15 @@ You need to turn on Attachments for your post types. View the Attachments settin
67
 
68
  = Attachments are not showing up in my theme =
69
 
70
- You will need to edit your theme files where applicable. Please reference the **Usage** instructions.
71
 
72
  = How do I disable the default Attachments meta box? =
73
 
74
- You will need to edit your Attachments configuration. Please reference the **Usage** instructions.
75
 
76
  = How do I change the fields for each Attachment? =
77
 
78
- You will need to edit your Attachments configuration. Please reference the **Usage** instructions.
79
 
80
  = Where are uploads saved? =
81
 
@@ -83,7 +91,7 @@ Attachments uses WordPress' built in Media library for uploads and storage.
83
 
84
  = I lost my Attachments after upgrading! =
85
 
86
- ***DO NOT update any Post/Page/CPT with Attachments***, the data has not been lost. Please [contact me](http://mondaybynoon.com/contact/) to begin a bugfix
87
 
88
  == Screenshots ==
89
 
@@ -95,6 +103,12 @@ Attachments uses WordPress' built in Media library for uploads and storage.
95
 
96
  == Changelog ==
97
 
 
 
 
 
 
 
98
  = 3.1.4 =
99
  * Changed 'Delete' to 'Remove' so as to not make it sound like the file itself would be deleted from Media (props Lane Goldberg)
100
  * Better handling of posts that have no Attachments when saving
@@ -301,11 +315,7 @@ Attachments uses WordPress' built in Media library for uploads and storage.
301
  == Upgrade Notice ==
302
 
303
  = 3.0 =
304
- **You will need to update your theme files that use Attachments 3.0**. Version 1.x of Attachments has been *fully deprecated* but is still available. If you would like to continue to use the (no longer supported) 1.x version you may add the following to your wp-config.php:
305
-
306
- `define( 'ATTACHMENTS_LEGACY', true ); // force the legacy version of Attachments`
307
-
308
- Version 3 is a *major* rewrite. While I've taken precautions in ensuring you won't lose any saved data it is important to back up your databse prior to upgrading in case something goes wrong. This version is a complete rewrite so all legacy data will be left in place, but a migration must take place to match the new data storage model and workflow.
309
 
310
  = 1.0.8 =
311
  As always, be sure to back up your database and files before upgrading.
@@ -328,6 +338,10 @@ Planned feature additions include:
328
 
329
  == Usage ==
330
 
 
 
 
 
331
  When Attachments is first activated, a default instance is created titled Attachments. It has two fields:
332
 
333
  1. Title
@@ -367,23 +381,27 @@ function my_attachments( $attachments )
367
  * Fields for the instance are stored in an array. Each field consists of
368
  * an array with three keys: name, type, label.
369
  *
370
- * name - (string) The field name used. No special characters.
371
- * type - (string) The registered field type.
372
  * Fields available: text, textarea, wysiwyg
373
- * label - (string) The label displayed for the field.
 
 
374
  */
375
 
376
  'fields' => array(
377
  array(
378
- 'name' => 'title', // unique field name
379
- 'type' => 'text', // registered field type
380
- 'label' => __( 'Title', 'attachments' ), // label to display
 
381
  ),
382
  array(
383
- 'name' => 'caption', // unique field name
384
- 'type' => 'wysiwyg', // registered field type
385
- 'label' => __( 'Caption', 'attachments' ), // label to display
386
- ),
 
387
  ),
388
 
389
  );
@@ -446,3 +464,13 @@ You can also retrieve various attributes of the current Attachment using these u
446
  <?php endwhile; ?>
447
  </ul>
448
  <?php endif; ?>`
 
 
 
 
 
 
 
 
 
 
4
  Tags: post, page, posts, pages, images, PDF, doc, Word, image, jpg, jpeg, picture, pictures, photos, attachment
5
  Requires at least: 3.0
6
  Tested up to: 3.5
7
+ Stable tag: 3.2
8
  License: GPLv2 or later
9
  License URI: http://www.gnu.org/licenses/gpl-2.0.html
10
 
56
  1. Download the plugin and extract the files
57
  1. Upload `attachments` to your `~/wp-content/plugins/` directory
58
  1. Activate the plugin through the 'Plugins' menu in WordPress
59
+ 1. Implement Attachments in your theme's `functions.php` or your own plugin (see **Other Notes > Usage**)
60
+ 1. Update your templates where applicable (see **Other Notes > Usage**)
61
+
62
+ = Upgrading from version 1.x =
63
+
64
+ **You will need to update your theme files that use Attachments 3.0**. Version 1.x of Attachments has been *fully deprecated* but is still available. If you would like to continue to use the (no longer supported) 1.x version you may add the following to your wp-config.php:
65
+
66
+ `define( 'ATTACHMENTS_LEGACY', true ); // force the legacy version of Attachments`
67
+
68
+ Version 3 is a *major* rewrite. While I've taken precautions in ensuring you won't lose any saved data it is important to back up your databse prior to upgrading in case something goes wrong. This version is a complete rewrite so all legacy data will be left in place, but a migration must take place to match the new data storage model and workflow.
69
 
70
  == Frequently Asked Questions ==
71
 
75
 
76
  = Attachments are not showing up in my theme =
77
 
78
+ You will need to edit your theme files where applicable. Please reference the **Other Notes > Usage** instructions.
79
 
80
  = How do I disable the default Attachments meta box? =
81
 
82
+ You will need to edit your Attachments configuration. Please reference the **Other Notes > Usage** instructions.
83
 
84
  = How do I change the fields for each Attachment? =
85
 
86
+ You will need to edit your Attachments configuration. Please reference the **Other Notes > Usage** instructions.
87
 
88
  = Where are uploads saved? =
89
 
91
 
92
  = I lost my Attachments after upgrading! =
93
 
94
+ ***DO NOT update any Post/Page/CPT that should have existing Attachments***, the data *has not been lost*. Please reference the **Installation > Upgrade Notice** details.
95
 
96
  == Screenshots ==
97
 
103
 
104
  == Changelog ==
105
 
106
+ = 3.2 =
107
+ * Added option to disable the Settings screen
108
+ * Added the ability to set a default for fields using the metadata that exists in WordPress. Available defaults include: title, caption, alt, and description. If set, the metadata for the correlating field will be used as the field default when initially adding an Attachment from the Media modal. Only applies to text, textarea, and wysiwyg fields.
109
+ * Added a `get_single()` method that allows you to specifically retrieve a single Attachment
110
+ * Clarified some documentation
111
+
112
  = 3.1.4 =
113
  * Changed 'Delete' to 'Remove' so as to not make it sound like the file itself would be deleted from Media (props Lane Goldberg)
114
  * Better handling of posts that have no Attachments when saving
315
  == Upgrade Notice ==
316
 
317
  = 3.0 =
318
+ Now piggybacking the awesome Media workflow introduced in WordPress 3.5
 
 
 
 
319
 
320
  = 1.0.8 =
321
  As always, be sure to back up your database and files before upgrading.
338
 
339
  == Usage ==
340
 
341
+ Attachments ships with a `Settings` screen (found under the `Settings` menu in the main WordPress admin navigation) that facilitates data migration from version 1.x and also offers some code snippets. If you would like to **disable the Settings screen** add the following to your theme's `functions.php`:
342
+
343
+ `define( 'ATTACHMENTS_SETTINGS_SCREEN', false ); // disable the Settings screen`
344
+
345
  When Attachments is first activated, a default instance is created titled Attachments. It has two fields:
346
 
347
  1. Title
381
  * Fields for the instance are stored in an array. Each field consists of
382
  * an array with three keys: name, type, label.
383
  *
384
+ * name - (string) The field name used. No special characters.
385
+ * type - (string) The registered field type.
386
  * Fields available: text, textarea, wysiwyg
387
+ * label - (string) The label displayed for the field.
388
+ * caption - (string) The default WordPress metadata to use when initially adding the Attachment
389
+ * Defaults available: title, caption, alt, description
390
  */
391
 
392
  'fields' => array(
393
  array(
394
+ 'name' => 'title', // unique field name
395
+ 'type' => 'text', // registered field type
396
+ 'label' => __( 'Title', 'attachments' ), // label to display
397
+ 'default' => 'title', // default value upon selection
398
  ),
399
  array(
400
+ 'name' => 'caption', // unique field name
401
+ 'type' => 'textarea', // registered field type
402
+ 'label' => __( 'Caption', 'attachments' ), // label to display
403
+ 'default' => 'caption', // default value upon selection
404
+ )
405
  ),
406
 
407
  );
464
  <?php endwhile; ?>
465
  </ul>
466
  <?php endif; ?>`
467
+
468
+ If you don't want to use the above implementation to loop through your Attachments, can also retrieve them explicitly:
469
+
470
+ `<?php $attachments = new Attachments( 'attachments' ); ?>
471
+ <?php if( $attachments->exist() ) : ?>
472
+ <?php if( $attachment = $attachments->get_single( 0 ) ) : ?>
473
+ <h3>Attachment at index 0:</h3>
474
+ <pre><?php print_r( $attachment ); ?></pre>
475
+ <?php endif; ?>
476
+ <?php endif; ?>`