forked from argoproject/navis-documentcloud
-
Notifications
You must be signed in to change notification settings - Fork 14
/
readme.txt
134 lines (93 loc) · 6.26 KB
/
readme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
=== DocumentCloud ===
Contributors: chrisamico, reefdog
Tags: documentcloud, documents, journalism, reporting, research
Requires at least: 3.5
Tested up to: 4.7
Stable tag: trunk
License: GPLv2
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Embed DocumentCloud resources in WordPress content.
== Description ==
[DocumentCloud](https://www.documentcloud.org/) is a service that allows journalists to analyze, annotate and publish documents, hosted by Investigative Reporters & Editors. Initial development of this plugin supported by [NPR](http://www.npr.org) as part of the [StateImpact](http://stateimpact.npr.org) project.
This plugin allows you to embed DocumentCloud resources using either the raw URL on its own line:
Here's something you should really take a look at:
https://www.documentcloud.org/documents/282753-lefler-thesis.html
Isn't that interesting?
Or a custom shortcode:
[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html"]
When you save, WordPress fetches and stores the actual embed code HTML from the DocumentCloud servers using oEmbed. You can freely toggle between visual and HTML mode without mangling embed code, and your embed will always be up to date with the latest embed code.
By default, documents will have a responsive width (it will narrow and widen as necessary to fill available content area) and use the theme's default height. If you want to override this, you can either set `responsive="false"` or explicitly set a `width`:
[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html" width="600"]
You can set your own defaults in Settings > DocumentCloud, but default widths will be ignored unless `responsive` is disabled:
[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html" responsive="false"]
To embed a single page, use any page-specific URL. Pages ignore `width/height` and always act responsively:
[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html#document/p1"]
To embed a note, use any note-specific URL. Notes ignore `width/height` and always act responsively:
[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html#document/p1/a53674"]
Here's the full list of embed options you can pass via shortcode attributes; some are specific to the type of resource you're embedding.
**All resources:**
- `url` (**required**, string): Full URL of the DocumentCloud resource.
- `container` (string): ID of element to insert the embed into; if excluded, embedder will create its own container.
**Documents only:**
- `height` (integer): Height (in pixels) of the embed.
- `width` (integer): Width (in pixels) of the embed. If used, will implicitly set `responsive="false"`.
- `responsive` (boolean): Use responsive layout, which dynamically adjusts width to fill content area. Defaults `true`.
- `responsive_offset` (integer): Distance (in pixels) to vertically offset the viewer for some responsive embeds.
- `page` (integer): Page number to have the document scroll to by default.
- `note` (integer): ID of the note that the document should highlight by default.
- `notes` (boolean): Hide or show notes.
- `search` (boolean): Hide or show search form.
- `sidebar` (boolean): Hide or show sidebar.
- `pdf` (boolean): Hide or show link to download original PDF.
- `text` (boolean): Hide or show text tab.
- `zoom` (boolean): Hide or show zoom slider.
- `format` (string): Indicate to the theme that this is a wide asset by setting this to `wide`. Defaults `normal`.
You can read more about publishing and embedding DocumentCloud resources on https://www.documentcloud.org/help/publishing.
== Installation ==
1. Upload the contents of the plugin to `wp-content/plugins/documentcloud`
2. Activate the plugin through the "Plugins" menu
3. In your posts, embed documents, pages, or notes using the DocumentCloud button or the `[documentcloud]` shortcode
4. Optional: Set a default width/height for all DocumentCloud embeds (which can be overridden on a per-embed basis with the `height/width` attributes) at Settings > DocumentCloud. (This default width will only be used if you set `responsive="false"` on an embed.)
**Upgrading from Navis DocumentCloud:** If you're currently using the Navis DocumentCloud plugin (from which this plugin was built), you'll want to deactivate or delete it before installing this plugin.
== Changelog ==
= 0.4.3 =
* Separate the oEmbed config options (provided as params to the endpoint) from the embed config options (encoded as params on the `url`) (#48)
* Rename `default_page` and `default_note` options back to `page` and `note` (#47)
* Remove `sidebar`, `text`, and `pdf` default values
= 0.4.2 =
* Recognize Unicode document slugs (#37)
= 0.4.1 =
* Conform syntax to WordPress VIP plugin requirements (#30) (@bcampeau)
* Fixed: Bare URLs now get default parameters (#35)
* Fixed: Pages/notes on docs with uppercase slugs now embeddable (#36)
= 0.4.0 =
* Support embedding pages (#28)
* Support embedding raw contextual page/note URLs (#29)
* Check for existence of things to stop triggering PHP notices (#27)
* Add DocumentCloud logo for plugin (#26)
* Fix ability to specify a container in the shortcode
* Improve embeddable resource pattern recognition
= 0.3.3 =
* Remove unused TinyMCE components
* Resolve CVE-2015-2807 reported by dxw Security at https://security.dxw.com/advisories/publicly-exploitable-xss-in-wordpress-plugin-navis-documentcloud/
= 0.3.2 =
* Implement a few best practice security measures
= 0.3.1 =
* Check for old (Navis) plugin and warn admins of conflict
* Add note about raw URLs to README
* Stop storing shortcode attributes in the `postmeta` table
= 0.3 =
* Add support for embedding notes.
* Default to responsive.
* Enable caching.
= 0.2 =
* Fetch embed code via oEmbed instead of generating statically.
* Add new options: `container`, `responsive`, `responsive_offset`, `default_page`, `default_note`, `notes`, `search`, and `zoom`.
* Deprecate `id` attribute. It's still usable, but support may drop in the future. Use `url` instead.
= 0.1 =
* Initial release.
== Upgrade Notice ==
= 0.3 =
Adds support for embedding notes and enables caching.
= 0.2 =
Adds oEmbed support for future-proofing embed codes. Provides additional embed options like `default_page`.