Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
@caleb531
caleb531 committed May 26, 2015
2 parents 495ff33 + 7ac976b commit 944bbb3
Show file tree
Hide file tree
Showing 5 changed files with 115 additions and 53 deletions.
3 changes: 2 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# Awesome CPT
*Copyright 2014 Caleb Evans*

*Copyright 2015 Caleb Evans*
*Licensed under the MIT license*

Awesome CPT is a set of classes designed to make coding WordPress custom post
Expand Down
8 changes: 7 additions & 1 deletion classes/class-awesome-post-type.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,14 @@ public function __construct( $params ) {
// Otherwise, generate messages
add_filter( 'post_updated_messages', array( $this, 'post_updated_messages' ), 10 );
}
// Ensures that built-in taxonomies are registered for post type
if ( ! empty( $this->args['taxonomies'] ) ) {
foreach ( $this->args['taxonomies'] as $taxonomy_id ) {
register_taxonomy_for_object_type( $taxonomy_id, $this->id )
}
}
}

// Initialize CPT
public function init() {
register_post_type( $this->id, $this->args );
Expand Down
75 changes: 49 additions & 26 deletions docs/meta-boxes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

## General usage

You can create a new taxonomy using the `Awesome_Meta_Box` class, the constructor for which accepts an array of properties. This array accepts a number of various properties.
You can create a new taxonomy using the `Awesome_Meta_Box` class, the
constructor for which accepts an array of properties. This array accepts a
number of various properties.

* `id`: required; the ID of the meta box
* `title`: required; the displayed title of the meta box
Expand All @@ -11,7 +13,8 @@ You can create a new taxonomy using the `Awesome_Meta_Box` class, the constructo
* `priority`: optional; the priority within the context where the meta box should show (`high`, `core`, `default`, or `low`)
* `fields`: optional; an array of data fields that are to be displayed in the meta box

Assuming a new instance of `Awesome_Post_Type` (with an `id` of `movie`) has already been created:
Assuming a new instance of `Awesome_Post_Type` (with an `id` of `movie`) has
already been created:

```
$release_date = new Awesome_Meta_Box( array(
Expand All @@ -21,12 +24,14 @@ $release_date = new Awesome_Meta_Box( array(
'context' => 'normal',
'priority' => 'high',
'fields' => array()
) )
) );
```

## Fields

As mentioned above, each `Awesome_Meta_Box` instance must have an array of fields, each of which represents a form field in the meta box. This array can any number of field, each of which is itself an array.
As mentioned above, each `Awesome_Meta_Box` instance must have an array of
fields, each of which represents a form field in the meta box. This array can
any number of field, each of which is itself an array.

Each field accepts the following properties:

Expand Down Expand Up @@ -62,12 +67,13 @@ $release_date = new Awesome_Meta_Box( array(
'placeholder' => 'Enter the movie release date here'
)
)
) )
) );
```

### `before` and `after` properties

As briefly mentioned above, the `before` and `after` properties determine what HTML should precede and follow (respectively) any given field.
As briefly mentioned above, the `before` and `after` properties determine what
HTML should precede and follow (respectively) any given field.

```
array(
Expand All @@ -80,7 +86,8 @@ array(
)
```

If you'd prefer to set the default `before` and `after` HTML for all fields, modify the static `field_defaults` array.
If you'd prefer to set the default `before` and `after` HTML for all fields,
modify the static `field_defaults` array.

```
Awesome_Meta_Box::$field_defaults['before'] = ''
Expand All @@ -89,7 +96,8 @@ Awesome_Meta_Box::$field_defaults['after'] = '<br />'

### Examples

Below are examples of the various input types you can create. For all of these types, Awesome CPT will handle the HTML escaping of values on your behalf.
Below are examples of the various input types you can create. For all of these
types, Awesome CPT will handle the HTML escaping of values on your behalf.

#### Text fields (`<input type='text'>`)

Expand All @@ -107,28 +115,32 @@ array(
```
array(
'id' => 'review',
'type' => 'textarea',
'type' => 'textarea',
'placeholder' => 'Enter a short review of the movie'
)
```

#### Checkboxes (`<input type='checkbox'>`)

Note that Awesome CPT will automatically add a `hidden` input to allow for the proper saving of the checkbox value. This default unchecked value is `off`.
Note that Awesome CPT will automatically add a `hidden` input to allow for the
proper saving of the checkbox value. This default unchecked value is `off`.

```
array(
'id' => 'supports_3d',
'type' => 'checkbox',
'type' => 'checkbox',
'label' => 'Available in 3D?',
'value' => 'on',
'checked' => false
)
```

The following example will output a list of checkboxes for selecting the languages in which the movie is available.
The following example will output a list of checkboxes for selecting the
languages in which the movie is available.

Note that each field `name` ends in a pair of brackets—this is to ensure the checked values are properly saved. Also note that the example utilizes the `before` and `after` properties to
Note that each field `name` ends in a pair of brackets—this is to ensure the
checked values are properly saved. Also note that the example utilizes the
`before` and `after` properties to

```
array(
Expand Down Expand Up @@ -166,7 +178,7 @@ array(
```
array(
'id' => 'my_radio_button',
'type' => 'radio',
'type' => 'radio',
'label' => 'My Radio Button',
'checked' => false
)
Expand All @@ -177,7 +189,7 @@ array(
```
array(
'id' => 'my_radio_button',
'type' => 'radio',
'type' => 'radio',
'label' => 'My Radio Button',
'src' => get_template_directory_uri() . '/images/myimage.png',
'alt' => 'My Image'
Expand Down Expand Up @@ -216,9 +228,12 @@ array(

##### Custom options

Instead of passing an array of option arrays, you can also pass a function reference to the `options` property. The referenced function must return an array in the same form as the one above (an array of option arrays).
Instead of passing an array of option arrays, you can also pass a function
reference to the `options` property. The referenced function must return an
array in the same form as the one above (an array of option arrays).

See the example below, which modifies the previous example to dynamically generate a menu of ratings.
See the example below, which modifies the previous example to dynamically
generate a menu of ratings.

```
array(
Expand All @@ -241,14 +256,15 @@ array(
)
```

Again, note that the anonymous functions used above are only supported in PHP 5.3 and newer.
Again, note that the anonymous functions used above are only supported in PHP
5.3 and newer.

#### Date pickers (`<input type='date'>`)

```
array(
'id' => 'my_date_picker',
'type' => 'date',
'type' => 'date',
'label' => 'My Date Picker',
'value' => '2014-01-01'
)
Expand All @@ -259,17 +275,21 @@ array(
```
array(
'id' => 'my_color_picker',
'type' => 'color',
'type' => 'color',
'label' => 'My Color Picker',
'value' => '#000'
)
```

#### Custom fields

You can also specify custom HTML for your field by passing a function reference to the `populate` property. This allows for dynamic generation of your field to fit your needs (such as querying posts or sending a request).
You can also specify custom HTML for your field by passing a function reference
to the `populate` property. This allows for dynamic generation of your field to
fit your needs (such as querying posts or sending a request).

Note that you still need to specify the field's ID in the field array, though you can access this in your `populate` function for awesome reuse (via the `$field` parameter).
Note that you still need to specify the field's ID in the field array, though
you can access this in your `populate` function for awesome reuse (via the
`$field` parameter).

```
array(
Expand All @@ -282,15 +302,18 @@ array(
)
```

Also note that using the `populate` callback will require you to escape the variables you use.
Also note that using the `populate` callback will require you to escape the
variables you use.

#### Filters

You can also pass the value of a meta box field through a filter before being saved to the database or displayed in the field.
You can also pass the value of a meta box field through a filter before being
saved to the database or displayed in the field.

##### `save` filter

The meta value will be run through the `save` filter before the meta data is saved to the post object.
The meta value will be run through the `save` filter before the meta data is
saved to the post object.

```
array(
Expand All @@ -307,7 +330,7 @@ array(

##### `display` filter

The meta value will be run through the `display` filter before being displayed
The meta value will be run through the `display` filter before being displayed

```
array(
Expand Down
59 changes: 43 additions & 16 deletions docs/post-types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,14 @@

## Basic syntax

You can create a new custom post type using the `PostType` class. The constructor for which accepts an array containing properties specific to Awesome CPT (these include most of the properties documented below).
You can create a new custom post type using the `PostType` class. The
constructor for which accepts an array containing properties specific to Awesome
CPT (these include most of the properties documented below).

Ever post type requires an ID (lowercase letters and underscores only) and the singular and plural variants of the post type name (letters and spaces only). The singular and plural names should be lowercase *in most cases* (special casing is mentioned in the next section).
Ever post type requires an ID (lowercase letters and underscores only) and the
singular and plural variants of the post type name (letters and spaces only).
The singular and plural names should be lowercase *in most cases* (special
casing is mentioned in the next section).

```
$movie = new Awesome_Post_Type( array(
Expand All @@ -26,11 +31,14 @@ $small_group = new Awesome_Post_Type( array(
) );
```

Note that internally, the custom post type is initialized when WordPress is initialized (via the `init` action, with a priority of 10).
Note that internally, the custom post type is initialized when WordPress is
initialized (via the `init` action, with a priority of 10).

## Names

Awesome CPT will automatically generate capitalized and title variants based on the `name` array you provide (using `ucfirst()` and `ucwords()`, respectively). For instance, the above `small_group` post type is equivalent to the following:
Awesome CPT will automatically generate capitalized and title variants based on
the `name` array you provide (using `ucfirst()` and `ucwords()`, respectively).
For instance, the above `small_group` post type is equivalent to the following:

```
$small_group = new Awesome_Post_Type( array(
Expand All @@ -50,7 +58,9 @@ $small_group = new Awesome_Post_Type( array(
) );
```

In most cases, you can let Awesome CPT correctly generate these other name variants. However, for names which require special casing, you may specify these variants yourself.
In most cases, you can let Awesome CPT correctly generate these other name
variants. However, for names which require special casing, you may specify these
variants yourself.

```
$tv_show = new Awesome_Post_Type( array(
Expand All @@ -72,7 +82,8 @@ $tv_show = new Awesome_Post_Type( array(

## Arguments

Awesome CPT also accepts an array of arguments (the same arguments array passed to `register_post_type`) via the `args` property:
Awesome CPT also accepts an array of arguments (the same arguments array passed
to `register_post_type`) via the `args` property:

```
$movie = new Awesome_Post_Type( array(
Expand All @@ -89,13 +100,17 @@ $movie = new Awesome_Post_Type( array(
) );
```

You can read about these possible arguments via the [WordPress Codex](http://codex.wordpress.org/Function_Reference/register_post_type#Arguments).
You can read about these possible arguments via the [WordPress
Codex](http://codex.wordpress.org/Function_Reference/register_post_type#Arguments).

Note that all Awesome CPT post types are made public by default (in contrast to the normal WordPress default for `public`).
Note that all Awesome CPT post types are made public by default (in contrast to
the normal WordPress default for `public`).

## Labels

CTP Classes will automatically create labels for your post type based on the `name`, `title`, and `cap_name` arrays. For instance, the first `small_group` example will generate the following labels:
CTP Classes will automatically create labels for your post type based on the
`name`, `title`, and `cap_name` arrays. For instance, the first `small_group`
example will generate the following labels:

```
'name' => 'Small Groups'
Expand Down Expand Up @@ -132,9 +147,12 @@ $small_group = new Awesome_Post_Type( array(

### Messages

One of the unique features of Awesome CPT is its ability to automatically generate action messages for your post type. These messages appear when you publish, schedule, or update a post.
One of the unique features of Awesome CPT is its ability to automatically
generate action messages for your post type. These messages appear when you
publish, schedule, or update a post.

If you wish to override these messages, Awesome CPT allows you to hook directly into the `post_updated_messages` filter, like so:
If you wish to override these messages, Awesome CPT allows you to hook directly
into the `post_updated_messages` filter, like so:

```
function my_post_updated_messages( $messages ) {
Expand All @@ -153,7 +171,10 @@ $movie = new Awesome_Post_Type( array(

## Columns

You can add columns to a custom post type's admin screen using the `add_columns()` method. The method accepts an array as its only argument, which in turn accepts a variable number of arrays. Each of these arrays contains properties for each column.
You can add columns to a custom post type's admin screen using the
`add_columns()` method. The method accepts an array as its only argument, which
in turn accepts a variable number of arrays. Each of these arrays contains
properties for each column.

The properties of each column include:

Expand Down Expand Up @@ -187,7 +208,9 @@ $tv_show->add_columns( array(
) );
```

Note that the anonymous functions used above are only supported in PHP 5.3 and newer. For older versions, define your function beforehand, and set the `populate` property to the function's name as a string.
Note that the anonymous functions used above are only supported in PHP 5.3 and
newer. For older versions, define your function beforehand, and set the
`populate` property to the function's name as a string.

```
...
Expand All @@ -205,7 +228,10 @@ Naturally, you can also reference methods if you are working within a class:

### Sortable columns

To make a column sortable, simply specify the `meta_key` and `orderby` properties for any given column. The value for the `meta_key` property must be the ID of some meta data stored on the post. The `orderby` property is the generic name of the data by which you are sorting (as shown in the page URL).
To make a column sortable, simply specify the `meta_key` and `orderby`
properties for any given column. The value for the `meta_key` property must be
the ID of some meta data stored on the post. The `orderby` property is the
generic name of the data by which you are sorting (as shown in the page URL).

```
array(
Expand All @@ -217,9 +243,10 @@ array(
'meta_key' => 'gross_income',
'orderby' => 'gross_income',
'numeric' => true
)
);
```

Setting the `numeric` property's value to `true` will sort the column numerically rather than alphabetically.
Setting the `numeric` property's value to `true` will sort the column
numerically rather than alphabetically.

## [Read about taxonomies](taxonomies.md)
Loading

0 comments on commit 944bbb3

Please sign in to comment.