bradyvercher/gistpress

WordPress plugin to add Gist oEmbed and shortcode support with caching.

gistpress's Issues

Refactor render() method

The debug bar panel class render() method does too much.

It:

• gets the logs.
• adds wrapping markup, and loops through the logs.
• loops through each item in the log, echoing with markup.
• echos out CSS.

That is far too much responsibility for one method and couldn't easily be unit tested. It should be split into smaller methods, with render() pretty much making calls to those other methods.

Add toolbar button for dialog

Something like the top image on http://wordpress.org/extend/plugins/gist-github-shortcode/screenshots/ may help when the author wants to insert a more advanced shortcode.

There could be fields / checkboxes for each option we support.

Add querystring option for forcing refresh

This was mentioned in #1 (comment) - allow a client-side option on single post / pages to force refresh the cache for that post / page.

Won't display the code, just the pasted url

Hi,

I've tested Gistpress before without any issues, but now I can't get it to display the gists on the site frontend. In the backend shows the loading animation when I paste the URL, but on the front-end it just displays the URL:

http://intangible.life/modern-wordpress-workflow-task-automation/

What should I look before to debug this?

lines_start attribute causes extra line number to appear

Compare [gist id=3207635 show_meta=0] and [gist id=3207635 show_meta=0 lines_start=1] - the latter has four line numbers, even though there are only three lines of code. Extending this to something like lines_start=583 means that an extra line still appears as well.

Path to Gist style sheet

The JSON data now only includes the relative path to the Gist style sheet, so our style method needs to include the https://gist.github.com prefix.

Urgent fix.

Improve appearance of gists in feeds

Since we've usually cached the gist content, we should look how we can output this in a way that makes sense in feeds. This should be for feeds used pulled in and shown with RSS clients, but also in RSS-to-email services too.

Plugin doesn't activate

I'm not sure why, but on one multi-site install, on one site, GistPress refuses to activate.

On subdomain 1, it doesn't activate - although the "Plugin activated" message appears, it's is neither highlighted as being active, nor parses shortcodes / oembed correctly.
On subdomain 2, GistPress is already active.
On subdomain 3, GistPress is not active, but has no issues with being activated and deactivated.

As it's a live site, I've not yet disabled other plugins or custom theme to see if there's a conflict.

ignore_first_line attribute

Syntax highlighting for a PHP gist can be added, by adding the <?php at the start. However, this may encourage folks to also copy that delimiter into the middle of their theme or plugin file, and adding a code comment or note about not copying it gets tedious.

One tip I like to do is [gist id="..." lines="2-9999" lines_start=1] so that the snippet does not show the first line, but still shows the line numbers counting from 1.

Would it make sense to have a boolean attribute that handles this? i.e.

[gist id="..." ignore_first_line=1]

... or ...

[gist id="..." ignore_first_line]

... is the shorthand for ...

[gist id="..." lines="2-9999" lines_start=1]

... or after #59 ...

[gist id="..." lines="2-" lines_start=1]

Use short color code

The current hex colour code for highlighting can be shortened from #ffffcc to #ffc in the shortcode default attributes array, and when documenting for #16.

Refactor process_gist_html() method

The process_gist_html() method currently does too much.

It:

• removes line number cell if line numbers have been disabled.
• removes the meta section if meta has been disabled.
• pulls out the an array of lines of code from the HTML.
• restricts the line numbers being displayed, if necessary.
• further tidies up the array of lines for further processing.
• removes lines of code if they are not to be displayed.
• adds classes to each line.
• joins all the html back together.

That is far too much responsibility for a single method, and should be split into several smaller protected methods that would be more easily testable and easier to read and maintain.

Check line-highlighting logic

See http://d.pr/i/caiS - not sure that the line highlighting logic is quite right for ranges, since lines 9 and 11 should also be highlighted in the screenshot.

Debug comes out as:

highlight: Array
(
[0] => 1
[2] => 5
[1] => 10
[3] => 12
[4] => 13
)

(Using my rewritten dev branch, which adds a couple of trim()s in, so might be something I've screwed up.)

Stylesheet not loaded properly

The stylesheet does not load properly. Developer tools shows that it is loading a badly formed URL

https://gist.github.comhttps//assets-cdn.github.com/assets/gist-embed-7346e9a735aaeeacede51d1efaad6208f95d9edbc222155878bfddc2da28fa87.css?ver=4.4.2

Add Shortcake support

Shortcake is a visual interface for crafting shortcodes. It would be interesting to have that for Gists, and have it show up as a preview in the editor.

Duplicate IDs

If you look at the source for http://www.poststat.us/automating-i18n-wordpress-themes/ you'll see that the gists produce duplicate IDs, where the same gist has been used (but showing different lines).

This <div id="gist..."> comes from the GitHub JSON, but we should find a way to fix it, since we're the ones allowing multiple uses of it. We can't use line-numbers as a suffix, since that wouldn't cover when the whole of a gist is shown twice (i.e. start and end of a tutorial).

We might need to count the gist references (whether by shortcode or oembed) during the request (request, not post, so it can cover the same gist being shown multiple times in full-content post archive) and add an index accordingly.

Store unprocessed HTML in a transient

Take an example where you have a WP Post, and in it you display a single file from a single Gist, and then break that code down to show certain lines as you explain it.

As things stand, the processed HTML is stored under an md5 hash of all of the shortcode attributes. However, showing the complete code, then 5 portions of it means currently making 6 JSON calls.

Consider making a JSON call and storing the unprocessed HTML in a transient with a key hashed from just the id and file (may be empty) attributes, and then processing the HTML (showing certain lines, highlighting certain lines, removing meta, removing line numbers etc.) and storing that in transients with a key hashed from all shortcode attributes, as per now? Before running off to Github for each snippet, check if the unprocessed HTML is already retrievable from a transient.

Post updates will have an extra lot of transients / post meta to delete but the benefit is potentially far fewer JSON calls when the post is viewed after the transients have naturally expired.

Allow for namespaced gists

See https://github.com/blog/1406-namespaced-gists

Should just be a case of amending the URL regex to have an optional .*/ before the gist ID number.

Suggest adding a class to determine whether the gist has any highlighted lines

G'day

I've just come up against the need to target the embedded gists based on whether or not they contain highlighted lines. My goal is to fade any non-highlighted lines out, but only when there are highlighted lines to emphasize.

I can see that the table element gets a class of highlight, even when there are no lines highlighted, but if there could be a class that indicates the presence of highlighted lines, then I could easily target specific gist embeds.

Change hook for clearing cache

Currently, we hook to post_updated for clearing caches. I've been having trouble with this working (not fully investigated yet), but wondered if we could use save_post hook instead. Presumably, this fires once the Update button is pushed, not after checking to see if some title, content, custom field etc. fields have actually changed? (If not save_post, then some similar pre_* hook instead?)

Stray doctype html validation error when using gistpress

When using gistpress - it is inserting a stray doctype html and body tags generating errors in the validator. Issue seen on multiple websites including your own site http://www.cedaro.com/

See this line in your code: https://github.com/bradyvercher/gistpress/blob/develop/includes/class-gistpress.php#L472

https://validator.w3.org/nu/?doc=https%3A%2F%2Fjackiedelia.com%2Fadding-svg-logo-utility-pro-theme%2F

Allow unlimited max lines

https://github.com/bradyvercher/gistpress/blob/develop/includes/class-gistpress.php#L310-L319 handles parsing of the lines attribute, for only showing a limited portion of the Gist.

If there's no hyphen (lines="5"), then only one line is shown as min and max are the same.

Otherwise the value is exploded on the hyphen, and the min and max values are set accordingly. However, that can mean knowing the number of lines in the gist, or supplying 2-9999 as the value.

I'd like there to be a condition that handled that automatically i.e. 2- would allow a check for max value being empty, and if so, assign it to a filterable high value such as 9999. That way, if the Gist ever gets updated to include more lines, the display of it won't end up being cut off.

Think substr() with no third argument.

Style sheet URL is broken

GitHub is now including the full URL to the style sheet in their JSON response, so the resolved URL is https://gist.github.comhttp://gist.github.com... which breaks the appearance of gists.

Plugin throws fatal error when used with WP-CLI

thrown in /vagrant/www/salferrarello/htdocs/wp-content/plugins/gistpress/gistpress.php on line 63
Fatal error: Uncaught Error: Call to a member function set_logger() on null in /vagrant/www/salferrarello/htdocs/wp-content/plugins/gistpress/gistpress.php:63

To recreate this error

• using an installation with WP-CLI available (e.g. in VVV)
• install and activate the gistpress plugin
• from the command line (within VVV if that is the environment you're using) run wp

I experienced this error on my Siteground account and on my local installation.

Content Editor Preview

As reported at #53 (comment) the updated content editor that previews embedded media shows an Internal Error. It would be good to either show a rendering, or otherwise avoid the obvious error.

Promote use of highlight class in Readme

To support a basic install-and-go, we currently add the only style not in the GitHub default style sheet, that of highlighted lines, as a style attribute with a background-color.

We also add a class however, and developers should be made aware, via the README.md file, that they could add something like:

.pre-line-highlight {
    background: #ffc;
}

...to their theme style sheet and:

add_filter( 'blazersix_gist_oembed_highlight_color', '__return_false' );

...to their theme functions.php to avoid that style attribute, and potentially pick a highlight colour that suits their theme.

Starting Line Number

Feature request - add a shortcode attribute which allows the choice of starting line number.

That would allow a post such as http://code.garyjones.co.uk/genesis-grid-loop/ to breakdown the large gist into smaller code snippets for easier explanation (using the lines attribute), but to also match the equivalent line numbers from the large gist.

My initial thinking would be along the lines of grabbing the .line-numbers <td> and adding the <span> elements to an array. Then flipping them around and start replacing the id and rel attributes and plain number, from the highest first, so that numbers like 21 are replaced wholly before 1 and 2 are.

Remove globals

There are a couple of global $post in the main class, which are only used to access the post ID. These could be dropped in favour of get_the_ID(), which then lets WP handle the population of the global if it's empty etc.

Standardize blazersix versus blazer-six

GitHub project name, class names, and file names all use blazer-six or Blazer_Six.

Text domain, filter names, function names, package name, style sheet option name all use blazersix or BlazerSix.

These should ideally be standardized to use a separator or not.

As a non-employee, my preference would be to keep the vendor prefixes and identifiers as a single word (capitlized where suitable), otherwise PSR-0-compatible directory structure would have folders called Blazer with a subfolder of Six, which isn't logical in this case.

Add filter for line classes

The classes for each <pre> should be filterable, so that other developers can add in extra classes for their own conditions.

Add missing `@since` tag

Add missing @since tag to blazersix_gist_oembed_add_debug_bar_panel in main plugin file.

Bug when regular expression replacement in Gist

Try embedding the following:

https://gist.github.com/GaryJones/c2b4fa187066489729cb

That uses preg_replace() with a backreference in the replacement string. PHP-wise, it works. However, from the embedded view of the gist, you'll see it gets mangled.

Looking in the database, the raw transient seems to be fine, but by the time it gets to the html transient, the $1 is gone. Presumably something in process_gist_html() is the culprit.

Trying with ${1} as the backreference seemed to make no difference.

Any ideas @bradyvercher?

Split up main class

The main class is getting too big and needs to be split up.

There are several groups of methods emerging. I'd like to see all of the processing and display of given HTML, split up from the URL determination and fetching / API calls, split up from the oembed stuff, and shortcode stuff. That is, we should be able to:

• just have the shortcode, without the oembed support to turn it into a shortcode
• formulate a URL and fetch results from it, but do nothing with it.
• process some HTML, whatever the source (API results, transient, unit test string)

The process_gist_html() method, for instance, is 50+ lines long, and while it defers to process_gist_line_numbers() for another 30+ lines, both could be split up into ~4 methods each for code that is far easier to understand, and having a separate class would allow this.

Add instructions for GistPress on custom post meta fields

Some folks store content in custom fields (post meta), so it would be handy for them to have instructions and a code snippet they can drop in so that GistPress (in fact, any oembed parsing) can run on their particular post meta key content.

See WP_Embed::__construct() for a starting point.

Cache the style sheet

The cache for Gist HTML mostly removes the dependency on loading resources from GitHub, but the style sheet is still an external request. Ideally, it should be cached as well.

Send username with API calls if available?

As per @bradyvercher's suggestion.

https://gist.github.com/a8cd3a1066d8047a6187.json#file-foo-bar-php

^ That automatically gets redirected to https://gist.github.com/GaryJones/a8cd3a1066d8047a6187.json#file-foo-bar-php

While quick, if we already have the username available, the API call URL should include it to avoid that small delay.

One drawback worth mentioning though - should two posts reference the same Gist, but one with a namespace and one without, then the results will be stored under different transient keys. If that takes priority, then we can stay as we are, not including the username at all, and let GitHub handle any redirects it wants to now or in the future.

Fix $logs exemplar format code

The documentation for the $logs property in the logger class has array items ending with ; instead of ,.

Oops.

Use delete_transient()

In expire_gist_transient(), set_transient() is being used with a negative timeframe, instead of the correct delete_transient() function.

Link element needs itemprop attribute

Since the stylesheet <link> element is in the <body>, it needs an itemprop attribute.

Expected Behavior

No errors when HTML is validated.

Current Behavior

The validator gives a slightly obscure warning about property attribute, as it is parsing it as HTML5 + RDFa.

## Possible Solution

As per http://w3c.github.io/html/single-page.html#the-link-element the link element must have an itemprop attribute, (or rel if only being used in the <head>).

See http://stackoverflow.com/questions/18549726/element-link-is-missing-required-attribute-property for an explanation of the error message.

Steps to Reproduce (for bugs)

1. Insert a gist into a WordPress post or page with GistPress.
2. Run the post URL through https://validator.w3.org
3. See the error entitled: "Element link is missing required attribute property."

Context

Valid markup on pages using GistPress.

Your Environment

• Version used: develop branch

Cache does not clear when using oEmbed

Steps to reproduce:

1. Embed the gist using oEmbed format in a Post
2. View the Post
3. Update the Gist at GitHub
4. Update the Post
5. View the Post ( the Gist will not be updated )

Create demo gists

See #22 (comment)

Add support for feeds

Disabling show_line_numbers and show_meta would probably be the ideal route for actually displaying code in feeds, but that complicates the caching a bit and styling

The next best option would seem to be to add a note and link directly to the Gist in the post.

Line highlighting not working with WP 4.2.2

Used:
[gist id="..." highlight="1" highlight_color="#ffffcc"]

Rendered HTML:
https://gist.github.com/nurtext/1642405725de2fa8ed3f

As far as I can see no inline-style attribute is set as it should be…

Use Time Constants

We have a couple of transient times using numbers - we could use constants from http://codex.wordpress.org/Easier_Expression_of_Time_Constants and make the code a little easier to read.

Refactor shortcode() method

The shortcode() method currently does too much.

It:

• rebuilds the original shortcode as a string with raw attributes, for the purposes of debugging.
• parses the shortcode attributes with defaults, then sanitizes them.
• includes a short-cut hack to delete transients, used during development of the plugin.
• handles feed output.
• conditionally enqueues a style if there is HTML to show.
• debug logs the attributes and HTML.

A few of these should be split into their own logical methods.

Gist's updated content does not appear

I have created a gist (id of 7502706) and used the following shortcode in a Post:

[gist id="7502706" file="style.css"]

I then updated style.css of that gist and made changes.

Upon refreshing my WP post, it still shows the old content of that gist's style.css. Is there a way to have shortcode always render its current content?

Refactor transient key

Strings like the transient key, {{unknown}} and other strings used across multiple methods should be refactored into protected functions e.g.

protected function transient_key( $hash ) {
    return 'gist_html_' . $hash;
}

This ensures consistency, easy unit testability, and a single place to make changes if needed in the future.

gistpress in WordPress plugin repo

Just did a search in WordPress plugin repo and it seems that this plugin is not available there. Any specific reason why this plugin is not available in WordPress repo?

Style method hook priority

Since the run() method of the main class is now hooked to init, the line inside run() that also hooks the registering of the style script to init needs to run at a later priority, e.g.:

add_action( 'init', array( $this, 'style' ), 15 );

Document Hooks

We should document our hooks as per WP core.

http://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/#4-hooks-actions-and-filters

Add file-level documentation to uninstall.php

Add file-level documentation to uninstall.php so it is consistent with the other .php files.