Skip to content

Commit

Permalink
update readmes
Browse files Browse the repository at this point in the history
  • Loading branch information
@joshuadavidnelson
joshuadavidnelson committed Feb 3, 2025
1 parent 9744843 commit e09a1d4
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 276 deletions.
168 changes: 22 additions & 146 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,164 +19,40 @@ Allows posts and pages to be archived so you can unpublish content without havin

## Description

This plugin allows you to archive your WordPress content similar to the way you archive your e-mail.
This plugin gives you the power to archive your WordPress content.

* Unpublish your posts and pages without having to trash them
* Archive content is hidden from public view
* Compatible with posts, pages, and public custom post types
* Ideal for sites where certain kinds of content is not meant to be evergreen
* Easily extended (see below)

**[Over 13](https://translate.wordpress.org/projects/wp-plugins/archived-post-status/)** languages supported

**Pull requests welcome, please follow [these guidelines](/code-of-conduct.md).**

**Please see [issues reported](https://github.com/joshuadavidnelson/archived-post-status/issues) there before going to the plugin forum.**

**Did you find this plugin helpful? Please consider [leaving a 5-star review](https://wordpress.org/support/view/plugin-reviews/archived-post-status).**

## Frequently Asked Questions

### Isn't this the same as using the Draft or Private statuses?

Actually, no, they are not the same thing.

The Draft status is a "pre-published" status that is reserved for content that is still being worked on. You can still make changes to content marked as Draft, and you can preview your changes.

The Private status is a special kind of published status. It means the content is published, but only certain logged-in users can view it.

The Archived post status, on the other hand, is meant to be a "post-published" status. Once a post has been set to Archived it can no longer be edited or viewed.

Of course, you can always change the status back to Draft or Publish if you want to be able to edit its content again.

### Can't I just trash old content I don't want anymore?

Yes, there is nothing wong with trashing old content. And the behavior of the Archived status is very similar to that of trashing.

However, WordPress permanently deletes trashed posts after 30 days ([see here](https://codex.wordpress.org/Trash_status#Default_Days_before_Permanently_Deleted)).

This is what makes the Archived post status handy. You can unpublish content without having to delete it forever.

### Where are the options for this plugin?

This plugin does not have a settings page. However, there are numerous hooks available in the plugin so you can customize default behaviors. Many of those hooks are listed below in this FAQ.

### Why are Archived posts appearing on the front-end?
This is most likely because you are viewing your site while being logged in as an Editor or Administrator.

By default, any user with the [`read_private_posts`](http://codex.wordpress.org/Roles_and_Capabilities#read_private_posts) capability will see Archived posts appear on the front-end of your site.

You can change the default read capability by adding this hook to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):

```php
function my_aps_default_read_capability( $capability ) {
$capability = 'read';

return $capability;
}
add_filter( 'aps_default_read_capability', 'my_aps_default_read_capability' );
```

### Can I make Archived posts appear on the front-end for all users?
Yes, add these hooks to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):

```php
add_filter( 'aps_status_arg_public', '__return_true' );
add_filter( 'aps_status_arg_private', '__return_false' );
add_filter( 'aps_status_arg_exclude_from_search', '__return_false' );
```
WordPress supports a publishing workflow by marking content with a post status:
* 3 for pre-published states: _draft_, _pending_, and _future_. These are editable and pre-viewable, not yet ready for public view.
* 2 types of published statuses: _publish_ and _private_. These are viewable to the public or specific users.
* 1 non-published status: _trash_. Trashed content is not editable or viewable and [automatically deleted](https://codex.wordpress.org/Trash_status#Default_Days_before_Permanently_Deleted) after 30 days.

### Can I change the status name?
The one thing missing here is a status for content that is _viewable_ but **not** editable.

You can change the post status name, the "Archived" string, by adding the code snippet to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):
### Introducing the Archive

```
add_filter( 'aps_archived_label_string', function( $label ) {
$label = 'Custom Label'; // replace with your custom label
return $label;
});
```
The 'archive' status marks content to a _post-published_ state, viewable to some but no longer edited. Examples might include:

This will change the name used in the admin and on the post title label (see below).
* an out-of-date walkthrough
* a review of a discontinued product
* a rough draft replaced with a final version
* an old, time-specific post that is now irrelevant

### How to modify or disable the "Archived" label added to the post title
Whatever the reason, incorporating the 'Archive' status can be a useful addition to your WordPress editing workflow.

This plugin automatically adds `Archived:` to the title of archived content. (Note that archived content is only viewable to logged in users with the [`read_private_posts`](http://codex.wordpress.org/Roles_and_Capabilities#read_private_posts) capability).

You can modify the label text, the separator, whether it appears before or after the title, or disable it entirely.

Follow the examples below, adding the code snippet to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins).

#### Remove the label

`add_filter( 'aps_title_label', '__return_false' );`

#### Place the label _after_ the title

`add_filter( 'aps_title_label_before', '__return_false' );`

#### Change the separator

The separator is the string between the "Archived" label and the post title, _including spaces_. When the label appears before the title, the separator is a colon and space `: `, if the label is placed after the title it is a dash with spaces on each side ` - `.

You can customize the separator with the following filter:
```
add_filter( 'aps_title_separator', function( $sep ) {
$sep = ' ~ '; // replace with your separator
return $sep;
});
```

### Can I make Archived posts hidden from the "All" list in the WP Admin, similar to Trashed posts?

Add these hooks to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):

```php
add_filter( 'aps_status_arg_public', '__return_false' );
add_filter( 'aps_status_arg_private', '__return_false' );
add_filter( 'aps_status_arg_show_in_admin_all_list', '__return_false' );
```

Please note that there is a [bug in core](https://core.trac.wordpress.org/ticket/24415) that requires public and private to be set to false in order for the `aps_status_arg_show_in_admin_all_list` to also be false.

### Can I exclude the Archived status from appearing on certain post types?

Add this hook to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):

```php
function my_aps_excluded_post_types( $post_types ) {
$post_types[] = 'my_custom_post_type';

return $post_types;
}
add_filter( 'aps_excluded_post_types', 'my_aps_excluded_post_types' );
```

### My archived posts have disappeared when I deactivate the plugin!

Don't worry, your content is _not_ gone it's just __inaccessible__. Unfortunately, using a custom post status like `archive` is only going to work while the plugin is active.

If you have archived content and deactivate or delete this plugin, that content will disappear from _view_. Your content is in the database - WordPress just no longer recognizes the `post_status` because this plugin is not there to set this post status up.

If you no longer need the plugin but want to retain your archived content:
1. Activate this plugin
2. Switch all the archived posts/pages/post types to a native post status, like 'draft' or 'publish'
3. THEN deactivate/delete the plugin.


## Screenshots

### Post list table screen.
* Unpublish your posts and pages without having to trash them
* Compatible with posts, pages, and public custom post types
* Ideal for sites where certain kinds of content is not meant to be evergreen
* Archive content is hidden from public view, only users with Editor or higher roles can see archived content.

![Post list table screen.](.wordpress-org/screenshot-1.png)
**Pull requests welcome, please follow [these guidelines](/code-of-conduct.md).**

### Quick Edit mode.
**Please see [issues reported](https://github.com/joshuadavidnelson/archived-post-status/issues) there before going to the plugin forum.**

![Quick Edit mode.](.wordpress-org/screenshot-2.png)
**Did you find this plugin helpful? Please consider [leaving a 5-star review](https://wordpress.org/support/view/plugin-reviews/archived-post-status).**

### Publish metabox controls.
## Documentation

![Publish metabox controls.](.wordpress-org/screenshot-3.png)
Learn how to use and extend the plugin at [docs.archivedpoststat.us](https://docs.archivedpoststat.us/)

## Contributing

Expand Down
156 changes: 26 additions & 130 deletions readme.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,157 +3,53 @@ Contributors: joshuadnelson, fjarrett
Tags: archive, archived, post status, archive post, admin, status, workflow
Requires at least: 5.9
Requires PHP: 8.1
Tested up to: 6.7.1
Stable tag: 0.4.0
License: GPL-2.0
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Use an "Archived" status to unpublish content without having to trash it.

== Description ==

This plugin allows you to archive your WordPress content similar to the way you archive your e-mail.
This plugin gives you the power to archive your WordPress content.

* Unpublish your posts and pages without having to trash them
* Archive content is hidden from public view
* Compatible with posts, pages, and public custom post types
* Ideal for sites where certain kinds of content is not meant to be evergreen
* Easily extended (see below)

**[Over 13](https://translate.wordpress.org/projects/wp-plugins/archived-post-status/)** languages supported

**Did you find this plugin helpful? Please consider [leaving a 5-star review](https://wordpress.org/support/view/plugin-reviews/archived-post-status).**

**Development of this plugin is done [on GitHub](https://github.com/joshuadavidnelson/archived-post-status). Pull requests welcome. Please see [issues reported](https://github.com/joshuadavidnelson/archived-post-status/issues) there before going to the plugin forum.**

== Frequently Asked Questions ==

= Isn't this the same as using the Draft or Private statuses? =

Actually, no, they are not the same thing.

The Draft status is a "pre-published" status that is reserved for content that is still being worked on. You can still make changes to content marked as Draft, and you can preview your changes.

The Private status is a special kind of published status. It means the content is published, but only certain logged-in users can view it.

The Archived post status, on the other hand, is meant to be a "post-published" status. Once a post has been set to Archived it can no longer be edited or viewed.

Of course, you can always change the status back to Draft or Publish if you want to be able to edit its content again.

= Can't I just trash old content I don't want anymore? =

Yes, there is nothing wong with trashing old content. And the behavior of the Archived status is very similar to that of trashing.

However, WordPress permanently deletes trashed posts after 30 days ([see here](https://codex.wordpress.org/Trash_status#Default_Days_before_Permanently_Deleted)).

This is what makes the Archived post status handy. You can unpublish content without having to delete it forever.

= Where are the options for this plugin? =

This plugin does not have a settings page. However, there are numerous hooks available in the plugin so you can customize default behaviors. Many of those hooks are listed below in this FAQ.

= Why are Archived posts appearing on the front-end? =

Archived content is by default viewable for users with the any user with the [`read_private_posts`](http://codex.wordpress.org/Roles_and_Capabilities#read_private_posts) capability.

This means if you are viewing your site while being logged in as an Editor or Administrator, you will see the archived content. However, lower user roles and non-logged-in users will not see the archived content.

You can change the default read capability by adding this hook to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):
WordPress supports a publishing workflow by marking content with a post status:
* 3 for pre-published states: _draft_, _pending_, and _future_. These are editable and pre-viewable, not yet ready for public view.
* 2 types of published statuses: _publish_ and _private_. These are editable and viewable to the public or specific users.
* 1 non-published status: _trash_. Trashed content is not editable or viewable and [automatically deleted](https://codex.wordpress.org/Trash_status#Default_Days_before_Permanently_Deleted) after 30 days.

<pre lang="php">
function my_aps_default_read_capability( $capability ) {
$capability = 'read';
The one thing missing here is a status for content that is _viewable_ but **not** editable.

return $capability;
}
add_filter( 'aps_default_read_capability', 'my_aps_default_read_capability' );
</pre>
=== Introducing the Archive ===

= Can I make Archived posts appear on the front-end for all users? =
The 'archive' status marks content to a _post-published state, viewable to some but no longer edited. Examples might include:

Add these hooks to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):
* an out-of-date walkthrough
* a review of a discontinued product
* a rough draft replaced with a final version
* an old, time-specific post that is now irrelevant

<pre lang="php">
add_filter( 'aps_status_arg_public', '__return_true' );
add_filter( 'aps_status_arg_private', '__return_false' );
add_filter( 'aps_status_arg_exclude_from_search', '__return_false' );
</pre>
Whatever the reason, incorporating the 'Archive' status can be a useful addition to your WordPress editing workflow.

= Can I change the status name? =

You can change the post status name, the "Archived" string, by adding the code snippet to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):

<pre lang="php">
add_filter( 'aps_archived_label_string', function( $label ) {
$label = 'Custom Label'; // replace with your custom label
return $label;
});
</pre>

This will change the name used in the admin and on the post title label (see below).

= How to modify or disable the "Archived" label added to the post title =

This plugin automatically adds `Archived:` to the title of archived content. (Note that archived content is only viewable to logged in users with the [`read_private_posts`](http://codex.wordpress.org/Roles_and_Capabilities#read_private_posts) capability).

You can modify the label text, the separator, whether it appears before or after the title, or disable it entirely.

Follow the examples below, adding the code snippet to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins).

**Remove the label**

`add_filter( 'aps_title_label', '__return_false' );`

**Place the label _after_ the title**

`add_filter( 'aps_title_label_before', '__return_false' );`

**Change the separator**

The separator is the string between the "Archived" label and the post title, _including spaces_. When the label appears before the title, the separator is a colon and space `: `, if the label is placed after the title it is a dash with spaces on each side ` - `.

You can customize the separator with the following filter:

<pre lang="php">
add_filter( 'aps_title_separator', function( $sep ) {
$sep = ' ~ '; // replace with your separator
return $sep;
});
</pre>

= Can I make Archived posts hidden from the "All" list in the WP Admin, similar to Trashed posts? =

Add these hooks to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):

<pre lang="php">
add_filter( 'aps_status_arg_public', '__return_false' );
add_filter( 'aps_status_arg_private', '__return_false' );
add_filter( 'aps_status_arg_show_in_admin_all_list', '__return_false' );
</pre>

Please note that there is a [bug in core](https://core.trac.wordpress.org/ticket/24415) that requires public and private to be set to false in order for the `aps_status_arg_show_in_admin_all_list` to also be false.

= Can I exclude the Archived status from appearing on certain post types? =
* Unpublish your posts and pages without having to trash them
* Compatible with posts, pages, and public custom post types
* Ideal for sites where certain kinds of content is not meant to be evergreen
* Archive content is hidden from public view, only users with Editor or higher roles can see archived content.

Add this hook to your theme's `functions.php` file or as an [MU plugin](http://codex.wordpress.org/Must_Use_Plugins):
**Learn how to use and extend the plugin at [docs.archivedpoststat.us](https://docs.archivedpoststat.us/)**

<pre lang="php">
function my_aps_excluded_post_types( $post_types ) {
$post_types[] = 'my_custom_post_type';
**[Over 13](https://translate.wordpress.org/projects/wp-plugins/archived-post-status/)** languages supported

return $post_types;
}
add_filter( 'aps_excluded_post_types', 'my_aps_excluded_post_types' );
</pre>
**Did you find this plugin helpful? Please consider [leaving a 5-star review](https://wordpress.org/support/view/plugin-reviews/archived-post-status).**

= My archived posts have disappeared when I deactivate the plugin! =
**Development of this plugin is done [on GitHub](https://github.com/joshuadavidnelson/archived-post-status). Pull requests welcome. Please see [issues reported](https://github.com/joshuadavidnelson/archived-post-status/issues) there before going to the plugin forum.**

Don't worry, your content is _not_ gone it's just __inaccessible__. Unfortunately, using a custom post status like `archive` is only going to work while the plugin is active.
== Frequently Asked Questions ==

If you have archived content and deactivate or delete this plugin, that content will disappear from _view_. Your content is in the database - WordPress just no longer recognizes the `post_status` because this plugin is not there to set this post status up.
= New FAQ & Docs Site =

If you no longer need the plugin but want to retain your archived content:
1. Activate this plugin
2. Switch all the archived posts/pages/post types to a native post status, like 'draft' or 'publish'
3. THEN deactivate/delete the plugin.
Refer to the FAQs at [docs.archivedpoststat.us](https://docs.archivedpoststat.us/)

= Help! I need support =

Expand Down

0 comments on commit e09a1d4

Please sign in to comment.