hypothesis / wp-hypothesis

Hypothesis WordPress plugin

hypothes.is for WordPress

Stable versions are available on the Hypothesis plugin page on WordPress.org.

Install this plugin

Via composer

This plugin can be installed with composer, from the standard package registry (packagist.org)

composer require hypothesis/wp-hypothesis

Via WordPress plugins directory

1. Visit your WordPress plugins page (/wp-admin/plugins.php)
2. Click the Add New button
3. Search the WordPress plugins directory for Hypothes.is
4. Click Install Now.
5. Click Activate
6. Visit your WordPress Settings > Hypothesis page to configure how it works on your site

Development

1. Install php and the dom and mbstring extensions.
2. Download Composer, the PHP package manager.
3. Run make dev. This will start a local WordPress instance with this plugin mounted on it.
4. Access http://localhost:8080 (the first time you'll have to finish setting up WordPress by following presented instructions)

Publishing

Follow these steps to publish a new plugin version.

1. Update the package version in hypothesis.php, readme.txt and package.json
2. Update readme.txt, adding the new version with its list of changes, under the Changelog section.
3. Merge the changes into the main branch¹. We use Semantic Versioning.
4. Create a tag pointing at the version-change commit and generate a new GitHub release (details follow). Publishing a GitHub release will kick off a GitHub Action that will publish the plugin to wordpress.org

Note

The package will be automatically published in packagist.org just by pushing the new git tag.

Creating a GitHub release

Create a new GitHub release with these values:

1. Tag: Create a new tag for the release, targeting the main branch (your just-merged version bump should be at the tip)². The tag should match the version number, e.g. v5.2.1.
2. Title: Use the tag name.
3. Click the Auto-generate release notes button to generate release notes and edit as needed. We use Keep a Changelog formatting.³
4. Leave other fields alone/as defaults.

License

BSD-3-Clause

Footnotes

1. Unlike other PRs, a version-bump PR does not require review. But do wait for CI to complete first. ↩

2. You can create a tag manually as a separate step if you want to tag a non-tip commit. ↩

3. You can look at release notes for other recent releases as exemplars. You don't need to include every change (especially, e.g., dependency updates). ↩

wp-hypothesis's Issues

Update logos in hypothesis plugin page

The page is displaying old ore no logos at all. See https://wordpress.org/plugins/hypothesis

We should update this to use up-to-date branding.

Same goes for the generic WordPress account we created: https://profiles.wordpress.org/hypodev/

PHP <5.4 compatibility problems

Relaying a report from our support email address:

After I updated the Hypothes.is plugin on my Wordpress website to the version mentioned above, it was not accessible anymore. I had to delete the plugin folder via my FTP access; that restored service immediately. The error message I found in my server logs was:

mod_fcgid: stderr: PHP Parse error: syntax error, unexpected '[' in /var/www/vhosts/wordpress.karstens.eu/httpdocs/wp-content/plugins/hypothesis/hypothesis.php on line 409

I'm not sure, but I'd guess this is a result of 1f8a0c6, which replaced array() with [] in a number of places.

It appears that this short syntax for arrays was only introduced in PHP 5.4: https://secure.php.net/manual/en/language.types.array.php#syntax

We should either revert that part of the change, or clearly document that we only support PHP>=5.4.

Do you think you might have time to look at this, @greatislander?

Updating knowledge base documentation - quick start guide and PDFs

• use Jeremy's educator guide as a template for creating KBase article on PDFs
• edit existing "quick start guide" to make clearer

this task comes out of Zendesk metrics for Jan 2018, where these two topics generated the most user requests

handle PDFs hosted via WordPress on other file storage systems

When WordPress is configured to host its Media Library in a different environment than the local file system (eg, AWS S3), this plugin doesn't launch the Hypothesis client with PDFs stored in such a
"foreign" Media Library using via.hypothes.is. This may have to do with cross-domain issues.

To recreate:

• Use a WP instance configured to store its Media Library in another place (eg, an AWS S3 plugin like https://deliciousbrains.com/wp-offload-s3/).
• Upload a PDF to the Media Library and verify it is stored in an alternate location (eg, AWS S3).
• Navigate to the PDF location and verify that it launches without via.hypothes.is.
• You may be able to test the issue by forcing the PDF to be stored locally again and launch it to see if it then launches with via.hypothes.is.

Include PDF.js viewer

For optional PDF + annotation viewing:
http://github.com/hypothesis/pdf.js-hypothes.is/

Automate publishing via GitHub actions

Use https://github.com/10up/action-wordpress-plugin-deploy to automate the publishing of the plugin.

Contributing upstream?

First, thanks for developing this plugin!

Second, Hypothesis would like to continue work on this project, and use your existing foundation as a base. For us to do that well, I wanted to ask if you could do two things:

1. would you be open to moving ownership of this plugin to the hypothesis org here at GitHub?
2. would you (relatedly) be open to licensing it under the BSD?

You're also welcome to sign our Contributors License Agreement, but I'm not sure that's necessary in this case.

Thanks, @timmmmyboy!

Also, @dwhly says "hi" 😄

Translation

Where could I translate all the strings of the plugin to spanish? Not only the ones of the adjustments area.

Thanks

the path to the upload folder needs to be a setting

The PDF feature works by prepending https://via.hypothes.is to links in posts that point into the media upload folder, by default wp-content/uploads. But if your WP system refers to a different place, you're out of luck. So, the path to that folder should be a setting.

Support custom post types in settings page

The list of post types which users can enable Hypothesis on is limited to Posts and Pages, with a not-well-documented "hypothesis_supported_posttypes" hook which can be used to override this. This means that custom post types added using tools such as Custom Post Types UI will not appear automatically.

It looks to me like it should be possible for the plugin to enumerate all registered post types automatically using get_post_types.

Context: https://hypothesis.zendesk.com/agent/tickets/1314

UI Shouldn't Render on OEmbed Posts

Now that WP supports oembed for blog posts, the Hypothesis toolbar is being rendered multiple times, both on the sidebar, and in each oembed post.

If possible, the toolbar shouldn't be present in the oembed template because one wouldn't read annotations in that smaller viewport.

Add some tests

Add some integration/unit tests that allow further changes to the plugin with a lower risk to break something.

https://make.wordpress.org/cli/handbook/misc/plugin-unit-tests/

Add a static analysis tool like PHPStan

Introducing a static analysis tool would allow to have a layer similar to TypeScript's type checking.

PHPStan is a good option, but we would need to make sure it does not detect WordPress core functions as undefined.

Find an opinionated code formatting tool, like prettier in the JS world

Prettier has an official plugin to format PHP code which might be a good option: https://github.com/prettier/plugin-php

It has some considerations:

• We need to check if it does not conflict with Wordpress coding standard, and if it does, we may want to move to PER-2/PSR-12 instead
• Prettier is a JS tool. Since the project already has a package.json, we could incorporate a JS package manager to the toolbelt and workflow without a lot of effort, but may be easier to introduce a PHP-based tool if such thing exists.

Consider setting-up class autoloading via composer

This plugin currently has just one class, which is manually required for convenience.

However, if we want to split it into multiple classes, using composer autoloading capabilities would be useful.

There's one consideration though. If this plugin also starts using more dependencies, then we have to resolve #60 before.

Feature request: create an option to hide hypothesis from people who don't have accounts in WP

We are looking into adding functionality that would hide the hypothes.is functionality from people who didn't have accounts on the wordpress site.

Our use case is for people who are reading/accessing material on the site as part of a learning community/class. They would all have accounts on the WP site.

For this use case, we would want to hide the Hypothesis tab from people who did not have accounts, and show it to everyone else.

This functionality could be toggled on the Pressbooks Textbooks admin screen.

We'll gladly write the code for this, but before we dug in we wanted to check that this functionality makes sense/aligns with what you would want to support down the road.

Select which pages hypothes.is should / should not be on

Add additional options for resizing and CSS changes

Hi plugin owners--
I've been working with some local users who are very excited about adding Hypothesis to their WordPress sites (and to their Pressbooks books) and have activated the plugin and begun using it. There are, however, a few commonly requested features for the plugin, and I was wondering if you'd be open to a pull request incorporating them into the existing core plugin. I've started making a very experimental "Hypothesis Modifications" plugin to do two of them here: https://github.com/SteelWagstaff/hypo-mods.

1. Many users would like to make it so that whenever possible, the annotation pane does not lay on top of (obscure) page content when it expands. In my plugin, I add an option called 'adjust page width' that uses javascript to adjust the width of the page body when the annotation pane expands. See https://github.com/SteelWagstaff/hypo-mods/blob/66024097d266d6cea2dcc736d63c186429a9e0c4/hypo-mods.php#L187-L191 and https://github.com/SteelWagstaff/hypo-mods/blob/66024097d266d6cea2dcc736d63c186429a9e0c4/js/resize.js for a very rough implementation.
2. Several of our users have suggested that the color of the highlights appear too faint on their screen, and that it's difficult to visually distinguish text that has been highlighted/annotated multiple times from text that has been highlighted just once. Essentially, they want to darken the yellow color used to depict annotations. See https://github.com/SteelWagstaff/hypo-mods/blob/66024097d266d6cea2dcc736d63c186429a9e0c4/hypo-mods.php#L204-L209 and https://github.com/SteelWagstaff/hypo-mods/blob/66024097d266d6cea2dcc736d63c186429a9e0c4/css/darken.css to see one example implementation.
   Would you consider adding either of these 'functionalities' to the core plugin, and if so, would someone be willing to work with me on preparing a pull request to add them to the plugin?

Bring plugin back online

Relates to hypothesis/product-backlog#1527

This is the reason the plugin was closed, and the steps to follow to bring it back:

Reason

The email associated with the plugins owner's user account bounced. As such, all plugins associated with the account were closed, because we do require your email to be functional.

What to do next

• Make sure the email on the user account is valid
• If the email is a group mail or mailing list, make sure it can receive email from external domains or non-members (Google changed their defaults in 2019 due to GDPR laws)
• If the email forwards, check all addresses to make sure they're valid and do not forward bounces
• If the ownership of the plugin is in doubt, let us know what accounts are supposed to have access and be the official owners so we can transfer them appropriately
• You must update the plugin readme to confirm it is compatible with the current release of WordPress. This is to ensure people can actually find your plugin.
• Perform a full security and guideline check of your own work. Look for sanitization, remote loading of content, and any other minor bug.
• Update all the code and upload it to SVN.
• Reply to this email that you are ready for a review

widget that displays recent annotations

appears in sidebar and streams annotations like a twitter feed--could be from WP install itself (URL, w/in a URL), a user, groups, tag, etc.

Ship scoped production dependencies installed with composer

This plugin is currently using composer only to install development dependencies, which should present no problem.

If at some point we want to install production dependencies and ship them with the plugin, we'll have to explore some tool like https://github.com/humbug/php-scoper, to avoid collisions with other dependencies from other plugins.

TL;DR

Composer is the de-facto official package manager for PHP.

On top of allowing the installation of production and development dependencies, it also provides autoloading capabilities for all the symbols in those packages.

Autoloading is a mechanism that other programming languages resolve differently. In PHP, you have to explicitly require the file containing a class in order to be able to use that class somewhere else.

// src/Hypothesis/MyClass.php
class MyClass
{
    // ...
}

---

// src/Hypothesis/OtherClass.php
use MyClass; // This is similar to Java imports, but does not bring the other class into this file's scope

class OtherClass
{
    public function foo()
    {
        // This will throw unless we do `require __DIR__ . '/MyClass.php';` somewhere before this line
        new MyClass();
    }
}

Since this can become cumbersome as a codebase grows, as you need both the use statement and also the explicit require of the file, PHP provides a function that gets automatically invoked when an unknown class is used, to give you a last opportunity to require it before failing.

Composer builds some utilities on top of that, which allow package maintainers to provide some config that will make class files to be properly autoloaded, without forcing applications to know the dependency's file structure.

It also lets applications themselves to take advantage of this mechanism.

With this explained, there's one problem if you try to make use of this in a WordPress plugin. This is that the autoloading triggers only if the symbol/class does not exist in memory, but if some other plugin has already required the same class but from a different version of the plugin, your plugin will end-up using that same version and potentially fail if there are incompatibilities.

That's where PHP-Scoper might make sense, as it allows to "rename" the classes for all the dependencies you ship, ensuring there won't be name collisions if other plugins, or WordPress itself, are also using composer to install the same dependency.

This problem does not usually occur when an app is fully managed with composer, as you end up with a flat dependency tree, but WordPress and its plugin system predates composer.

Activity notifications

Dear all,

Thank you very much for your work on this excellent plugin!

I want to use hypothesis to allow users on a Wordpress blog to add extra information to a text.

It would be great if I as the blog owner could receive a notification if someone has added a note or annotation highlight.

Is this technically possible?

Thankfully,

Robert

Publish package in packagist.org

As discussed in #40, publishing this in the standard composer registry (AKA packagist.org) would allow people to install it as a regular dependency with composer.

It needs to have "type": "wordpress-plugin", and I would suggest we rename it to hypothesis/hypothesis-wp-plugin, or something in those lines.

allow users to choose configurations for h in WP

following @JakeHartnell great update that allows you do add hypothes.is to specific pages in a WP instance, i think it would be great to allow them to choose how h appears as well:

sidebar default open/closed
highlights default visible/in-

Moderation queue or restricted access to annotate

Love your work!

I would like to use this plugin on a WP page with a longer text to add my own annotations to the text and let some others help out with the annotations, without letting the whole world add to it.

I guess this is not perfectly within your scope, but I don't know of any other tool that would work better for this. All I need is for you to add an option to let me choose either:

1. that all new annotations be put in a moderation queue for the site owner to allow or deny before they are published, or
2. only let specific Hypothesis accounts annotate a specific WP page.

Would this be possible?

Thank you!

lack of updates making people hesitate to install plugin

Placeholder for now - but I've gotten a number of tickets in support asking us if the plugin is defunct because it hasn't been updated in >3yrs. Common "wisdom" in the WP community is to only install plugins with recent updates. We might consider a somewhat frequent update schedule going forward.