Add a Custom TGMPA Generator to the website. #519

Merged
merged 1 commit into from Feb 12, 2016

Projects

None yet

4 participants

@jrfnl
Contributor
jrfnl commented Jan 10, 2016

The Custom TGMPA Generator takes the zip file from the latest release (for now: needs to be uploaded after each release as I can't find a hard link to the zip on GitHub) and adjusts the contents based on settings provided by the end-user in a form in the download page of the website and then serves the customized .zip file to the user.

screenshot

Changes made to the website to support this:

  • removed most links to the GH downloads and redirected them to the download page to encourage the use of the form.
  • added a number of javascript libraries used by the custom generator which will conditionally load - i.e. only on the download page.
  • added octicons font for new download icon
  • added the v2.5.2 release zip file to use as base for the generator.
  • added a blogpost announcing the custom generator (tentative post date January 15 - to be adjusted based on when this will be merged)

This PR presumes the related pull requests to the TGMPA library: #520, #521 and #522 will be merged for the 2.6.0 release, but will already function as is for the v 2.5.2 release.

If Theme developers who publish via wp.org use the Generator to create their package, the Theme Check plugin should (will) no longer trigger warnings on the use of TGMPA.

This should also reduce the number of end-user support requests I've come across in the fora caused by too aggressive search-and-replace actions by theme authors on the class-tgm-plugin-activation.php file.

The Generator will apply the following changes to the TGMPA release package:

Adjustment Affected files WP.org Theme ThemeForest Theme Other Theme Plugin
Replace text domain in translation functions in the example file and the class in the example file only in the example file only in the example file only
Adjust the file include call to the most appropriate one example file
Adjust the file path for the bundled plugin to the most appropriate one example file
Prefix the function name for the function providing TGMPA, including adjusting the hook in example file
Adjust the config id for the notices example file
Adjust menu location & capability config variables example file variables removed variables removed (no adjustment needed)
Adjust add_admin_menu() function - only have the add_theme_page() call in there class file
Remove load_textdomain related hook-ins and functions (PR #521) class file
Remove /languages/ directory
Remove development related files

If the file was adjusted, the @version tag at the top of the file will also be adjusted to read @version x.x.x for plugin/theme Theme Name/Plugin Name so it will be easy to spot a file which was adjusted using the custom TGMPA generator.
[Update] The version tag will now read @version x.x.x for plugin/theme Theme Name/Plugin Name for publication on WordPress.org/ThemeForest if either of those two has been choosen as publication channel.

@Stephen-Cronin Are there any specific requirements for the Themeforest themes using TGMPA which are not covered yet ? If so, please let me know and I'll see what I can do.

/cc @otto42

Resolves #475, resolves #476, resolves #460, resolves #462, resolves #186

@GaryJones GaryJones was assigned by jrfnl Jan 10, 2016
@GaryJones GaryJones and 1 other commented on an outdated diff Jan 10, 2016
_includes/generator-form.html
+ <input type="text" id="tgmpa-text-domain" name="tgmpa-text-domain" placeholder="text-domain" value="" pattern="[A-Za-z0-9_-]+" title="Allowed characters: alphanumeric and dashes" autofocus required />
+ </fieldset>
+
+ <fieldset>
+ <label for="tgmpa-prefix">Function Prefix:</label>
+ <input type="text" id="tgmpa-prefix" name="tgmpa-prefix" placeholder="function_prefix" value="" pattern="[A-Za-z0-9_]+" title="Allowed characters: alphanumeric and dashes" />
+ </fieldset>
+
+ <fieldset>
+ <label for="tgmpa-name">Name:</label>
+ <input type="text" id="tgmpa-name" name="tgmpa-name" placeholder="Theme or Plugin Name" value="" pattern="[A-Za-z0-9 _-]+" title="Allowed characters: alphanumeric, space, underscores and dashes" />
+ </fieldset>
+
+ <fieldset id="tgmpa-form-wporg">
+ <input type="checkbox" id="tgmpa-wporg" name="tgmpa_wporg" value="1">
+ <label for="tgmpa-wporg">Do you intend to distribute the theme via wp.org ?</label>
@GaryJones
GaryJones Jan 10, 2016 Member

Expand to the full wordpress.org, since wp.org redirects to wpbeginner.com.

@jrfnl
jrfnl Jan 10, 2016 Contributor

Oh dear, I though that battle had been fought (and won by Automattic). Will change.

@GaryJones GaryJones commented on an outdated diff Jan 10, 2016
_includes/generator-form.html
@@ -0,0 +1,63 @@
+{::options parse_block_html="false" entity_output="as_input" /}
+<div class="tgmpa-generator-form">
+ <form id="generator-form" method="POST">
+ <input type="hidden" name="tgmpa_generate" value="1" />
+
+ <section class="tgmpa-form-primary">
+ <label for="tgmpa-flavor">I'm going to use TGMPA in a:<span class="required">*</span></label>
@GaryJones
GaryJones Jan 10, 2016 Member

For accessibility, don't make this a label, since it has no direct field, but use a legend inside of the fieldset instead. See http://webaim.org/techniques/forms/controls#radio as an example.

@GaryJones GaryJones commented on an outdated diff Jan 10, 2016
_includes/generator-form.html
@@ -0,0 +1,63 @@
+{::options parse_block_html="false" entity_output="as_input" /}
+<div class="tgmpa-generator-form">
+ <form id="generator-form" method="POST">
+ <input type="hidden" name="tgmpa_generate" value="1" />
+
+ <section class="tgmpa-form-primary">
+ <label for="tgmpa-flavor">I'm going to use TGMPA in a:<span class="required">*</span></label>
+ <fieldset>
+ <input type="radio" id="tgmpa-flavor-theme" name="tgmpa-flavor" value="parent-theme" required />
@GaryJones
GaryJones Jan 10, 2016 Member

Use required="required" for the XML form of HTML5.

@GaryJones GaryJones and 1 other commented on an outdated diff Jan 10, 2016
_includes/generator-form.html
+ <label for="tgmpa-flavor">I'm going to use TGMPA in a:<span class="required">*</span></label>
+ <fieldset>
+ <input type="radio" id="tgmpa-flavor-theme" name="tgmpa-flavor" value="parent-theme" required />
+ <label for="tgmpa-flavor-theme">Theme</label>
+ <br />
+ <input type="radio" id="tgmpa-flavor-child-theme" name="tgmpa-flavor" value="child-theme" required />
+ <label for="tgmpa-flavor-child-theme">Child Theme</label>
+ <br />
+ <input type="radio" id="tgmpa-flavor-plugin" name="tgmpa-flavor" value="plugin" required />
+ <label for="tgmpa-flavor-plugin">Plugin</label>
+ </fieldset>
+ </section>
+
+ <section class="tgmpa-form-secondary">
+ <fieldset>
+ <label for="tgmpa-text-domain">Text Domain:<span class="required">*</span></label>
@GaryJones
GaryJones Jan 10, 2016 Member

Consider using the word required in the label, so it's read out as such in screen readers. See http://usability.com.au/2013/05/accessible-forms-2-required-fields-and-extra-information/

Text Domain (required):

@jrfnl
jrfnl Jan 10, 2016 Contributor

I've added the aria-required attribute instead, support when having both the HTML5 as well as the WAI attribute is reasonable. http://john.foliot.ca/required-inputs/

@GaryJones GaryJones and 1 other commented on an outdated diff Jan 10, 2016
_includes/generator-form.html
+ <input type="text" id="tgmpa-name" name="tgmpa-name" placeholder="Theme or Plugin Name" value="" pattern="[A-Za-z0-9 _-]+" title="Allowed characters: alphanumeric, space, underscores and dashes" />
+ </fieldset>
+
+ <fieldset id="tgmpa-form-wporg">
+ <input type="checkbox" id="tgmpa-wporg" name="tgmpa_wporg" value="1">
+ <label for="tgmpa-wporg">Do you intend to distribute the theme via wp.org ?</label>
+ </fieldset>
+ </section>
+
+ <section class="tgmpa-form-ternary">
+ <div class="generator-form-submit">
+ <input type="submit" class="tgmpa-form-submit" name="tgmpa_generate_submit" value="Generate" />
+ </div>
+
+ <div id="spinner"></div>
+ <div class="generator-feedback">
@GaryJones
GaryJones Jan 10, 2016 Member

If this section uses JavaScript to appear, then some use of aria-live is needed so screen reader users' attention is drawn to it.

@jrfnl
jrfnl Jan 10, 2016 Contributor

Adjusted for that and the wporg fieldset. Hope I got it right.

The wporg fieldset only appears when either parent theme or child theme has been selected, and disappears again if plugin is selected. State on load is hidden.

FYI: Other usability js: - when the user fills in the 'Text domain' field, the 'Function prefix' and 'Name' field will be filled out automatically if they haven't been filled out yet.
Function prefix will be the text domain value with dashes replaced by underscores.
Name will be the text domain value with spaces instead of dashes and written in Title Case.

Validation of all three text fields is done via an HTML5 pattern if the browser supports it and additionally via js on submit.

@GaryJones GaryJones commented on an outdated diff Jan 10, 2016
_includes/generator-form.html
+ <div class="generator-form-submit">
+ <input type="submit" class="tgmpa-form-submit" name="tgmpa_generate_submit" value="Generate" />
+ </div>
+
+ <div id="spinner"></div>
+ <div class="generator-feedback">
+ <p id="generator-feedback"></p>
+ <p id="report-generator-error">Please try again. If the error persists, please open a <a href="https://github.com/TGMPA/TGM-Plugin-Activation/issues">bug report</a> quoting the error message.</p>
+ </div>
+ </section>
+ </form>
+
+ <div class="generator-notes">
+ <ul>
+ <li>This generator works on Firefox, Chrome, Opera &ge; 15 and IE &ge; 10 (but NOT in compatibility view).</li>
+ <li>No data is saved by us, all the processing is done via javascript in the browser.</li>
@GaryJones
GaryJones Jan 10, 2016 Member

javascript => JavaScript.

@GaryJones GaryJones and 1 other commented on an outdated diff Jan 10, 2016
_includes/header.html
@@ -61,15 +62,16 @@
</hgroup>
<div class="download">
- <a href="{{ site.tgmpa.github }}/archive/{{ site.tgmpa.version }}.zip" class="latest-zip">
- <img border="0" width="90" alt="Download latest release zipfile" src="{{ site.tgmpa.zipimage }}">
- </a>
- <a href="{{ site.tgmpa.github }}/archive/{{ site.tgmpa.version }}.tar.gz" class="latest-tar">
- <img border="0" width="90" alt="Download latest release tarball" src="{{ site.tgmpa.tarimage }}">
- </a>
+ <p class="download-icon">
+ <a href="{{ '/download/' | prepend: site.tgmpa.url }}" title="Download the latest release">
@GaryJones
GaryJones Jan 10, 2016 Member

Don't use the title attributes - they are all but worthless. Use plain text (may be visually hidden with CSS (not display: none;)) with the icon. Relying on an icon alone is not sufficient for screen readers.

@jrfnl
jrfnl Jan 10, 2016 Contributor

Okidoki, this does mean the icon will be an image, not a font-icon, but I'm ok with that. I will leave in the title as well as for those users who don't recognize the icon and don't use screen readers, it gives a semi-useful mouse-over comment.

@GaryJones
GaryJones Jan 10, 2016 Member

If you've got it in plain text (good), remove it the title attribute. It serves no purpose. For those who have got title attributes being read out in screen readers (not the default), it would read the same thing out twice.

Really, this is all a done deal in the accessibility expertise. Title attributes should not be used except on iframe elements.

@jrfnl
jrfnl Jan 10, 2016 Contributor

Ok, removing it is then. My front-end accessbility knowledge is a bit out of date it seems ;-)

Title attributes should not be used except on iframe elements.

Though this sounds out of date too - title should be used on input elements which have the HTML5 pattern attribute set as that will allow the browser to display as an error hint.
http://www.w3.org/TR/2011/WD-html5-20110525/common-input-element-attributes.html#the-pattern-attribute

@GaryJones
GaryJones Jan 13, 2016 Member

Unless screen readers have an override for reading out title attributes on input elements with pattern attributes, even when their settings say not to read out title attributes, I'd rather see this pattern described within the label, or even placeholder text (i.e. "1ABC" for the spec example), or some other visual description. http://www.deque.com/blog/accessible-client-side-form-validation-html5/ has a few suggestions.

cc @afercia @rrwd

@GaryJones GaryJones commented on an outdated diff Jan 10, 2016
_posts/2016-01-15-custom-tgmpa-generator.md
+
+### Custom TGMPA Generator released
+
+If you are a theme designer and publish themes on wordpress.org, you may have come across feedback from the Theme Check plugin and/or the Theme Review team along the lines of _"You are only allowed to use add_theme_page(), please remove the call to add_submenu_page()."_ or _"You are only supposed to use one text-domain."_.
+
+So you go and do a search-and-replace and then get users reporting fatal errors because the search and replace also replaced some strings which shouldn't have been changed.
+
+And then when TGMPA is updated, you have to do it all over again.
+
+<p class="align-right">
+ ![screenshot-1]({{ '/images/screenshots/tgmpa-generator-medium.png' | prepend: site.tgmpa.url }})
+</p>
+
+Well, no more. We've heard you and we've worked hard to make this easier for you.
+
+So today, we are releasing an _**Custom TGMPA Generator**_. You can find it on the [Download] page.
@GaryJones
GaryJones Jan 10, 2016 Member

an => a.

@GaryJones GaryJones commented on an outdated diff Jan 10, 2016
_posts/2016-01-15-custom-tgmpa-generator.md
+
+If you are a theme designer and publish themes on wordpress.org, you may have come across feedback from the Theme Check plugin and/or the Theme Review team along the lines of _"You are only allowed to use add_theme_page(), please remove the call to add_submenu_page()."_ or _"You are only supposed to use one text-domain."_.
+
+So you go and do a search-and-replace and then get users reporting fatal errors because the search and replace also replaced some strings which shouldn't have been changed.
+
+And then when TGMPA is updated, you have to do it all over again.
+
+<p class="align-right">
+ ![screenshot-1]({{ '/images/screenshots/tgmpa-generator-medium.png' | prepend: site.tgmpa.url }})
+</p>
+
+Well, no more. We've heard you and we've worked hard to make this easier for you.
+
+So today, we are releasing an _**Custom TGMPA Generator**_. You can find it on the [Download] page.
+
+Just tell the form the _text-domain_ of your theme or plugin, what sort of WordPress add-on you will be including TGMPA in and, if it's a theme, whether you intend to publish it on wordpress.org and we'll generate a custom download of the current version of TGMPA for you with all the relevant code already adjusted.
@GaryJones
GaryJones Jan 10, 2016 Member

"tell the form" is an odd choice of wording. "Fill out the form with" would be better.

@GaryJones GaryJones and 1 other commented on an outdated diff Jan 10, 2016
css/style.css
display: inline-block;
}
+.download a:hover {
+ color: #5490ca;
+}
+
+.download .mega-octicon {
+ font-size: 112px;
@GaryJones
GaryJones Jan 10, 2016 Member

Indentation.

@jrfnl
jrfnl Jan 10, 2016 Contributor

Spaces from a copy/paste will get me every time ;-)

@GaryJones GaryJones and 1 other commented on an outdated diff Jan 10, 2016
css/style.css
display: inline-block;
}
+.download a:hover {
+ color: #5490ca;
+}
+
+.download .mega-octicon {
+ font-size: 112px;
+ text-align: center;
+ text-shadow: 2px 2px 5px #666666;
@GaryJones
GaryJones Jan 10, 2016 Member

Use short form of hex codes where possible.

@jrfnl
jrfnl Jan 10, 2016 Contributor

The actual site uses the minified version of the css which has the short form. For the dev version of the css, long form is fine.

@GaryJones
Member

Great job!

@jrfnl
Contributor
jrfnl commented Jan 10, 2016

Changes all committed. Let's give @Stephen-Cronin and @otto42 a few days to respond before I squash & we merge.

@Stephen-Cronin

Looks exciting! I'll have a look into this and try to get back to you tomorrow.

@Stephen-Cronin

I have a question about what happens when the "Do you intend to distribute via wordpress.org" checkbox is selected. Is the only difference that the code allowing the menu item to be moved from Appearance is removed?

If that's the only difference, then we actually want that for ThemeForest themes as well. They need to pass Theme-Check, including the 'add_submenu_page' check. I'm not sure what that means for the option name - "Do you intend to distribute via wordpress.org or ThemeForest" is a bit clunky.

The only other thing is the text domain issue. From the table above, the text domain won't be replaced in the class for either .org or non .org themes. Have you had any feedback from @otto42 or someone else from the .org Theme Review Team on this? I believe that language packs are coming at some point and that using more than one text domain will not be allowed on .org. Various people have mentioned this in the past (eg #474, #218), but now may be a good time to get an update from official sources on when this may be happening.

As for ThemeForest themes, I know that translations under the tgmpa text domain are on the roadmap for 3.0 and I agree that that's the neatest solution. However, we are still discussing whether we may or may not prefer the text-domain replaced in the class (even though we don't have the technical driver that .org has). I'll try to get that discussion wrapped up asap. Thanks!

@jrfnl
Contributor
jrfnl commented Jan 13, 2016

Hi @Stephen-Cronin, thanks for having a look.

what happens when the "Do you intend to distribute via wordpress.org" checkbox is selected. Is the only difference that the code allowing the menu item to be moved from Appearance is removed?

No, see the table. (Strange, seems the headers for the columns had gotten mixed up, corrected now - the more extensive changes are for org themes, the minimal ones for plugins)

The only other thing is the text domain issue. From the table above, the text domain won't be replaced in the class for either .org or non .org themes.

Actually it will be. For non-org themes and for plugins, the text domain will only be replaced in the example file.
For org themes, the text domain will be replaced in both the example file as well as the class file.

Similarly, for org themes, the load textdomain call we intend to add, will be removed to prevent conflicts with Theme Check.

Sorry for the confusion.

@GaryJones
Member

Actually it will be. For non-org themes and for plugins, the text domain will only be replaced in the example file.
For org themes, the text domain will be replaced in both the example file as well as the class file.

Any reason they couldn't be replaced under both conditions? What benefit is there for keeping tgmpa within a theme or plugin with a different text domain?

@jrfnl
Contributor
jrfnl commented Jan 14, 2016

Any reason they couldn't be replaced under both conditions? What benefit is there for keeping tgmpa within a theme or plugin with a different text domain?

No reason why we couldn't replace. The current benefit is that we've already got translations ready for some languages.

Then again, just thinking, you can have two load_..._textdomain() calls for the same domain in a theme/plugin. The second time, WP will just merge the new translation with the previous one, so we could even choose to replace the textdomain in all translation calls in all versions and leave the code that handles the loading of the textdomain in, just point it to the native textdomain.

Not sure how Theme Check deals with two load_.._textdomain() calls within one theme though. @otto42 ?

Anyway, this would mean we also wouldn't need to remove the languages subdirectory. However, we would need to rename all the .mo files within it to either {locale}.mo for themes or {textdomain}-{locale}.mo for plugins.
Or maybe even better: instead of the renaming of the files (which may be iffy from within js with it being binary data which I'd be reading out from the zip and writing back under a different name), I can just add a low-level filter to manipulate the file name. Hmm.. actually no, I can't, as I won't know the path the theme or plugin will use for TGMPA, so I won't be able to distinguish between 'our' load_textdomain call and 'theirs'.
So to make this viable, I'd need to test if the renaming of the binary .mo files from within js will work and won't mangle the files. If I can get it to work, browser support for the Generator will probably be even more limited than it is now.

All together, it's easier not to (replace the textdomain) as that particular rabbit hole has got quite some twists and turns.

@Stephen-Cronin

Hi @jrfnl

Thanks! That makes a lot more sense now (ie the table column headers being mixed up). :)

We've finished our discussion and decided that we're all good with the 'tgmpa' text domain remaining in the class (if you decide to keep it that is!) and being loaded (when you add that), etc. It's great you are planning to provide translations and it does make more sense to provide them centrally, rather than having thousands of different themes having to replicate them and keep them up to date etc.

However, as mentioned above, we would like the menu location & capability config variables removed and the add_admin_menu() function adjusted to only have add_theme_page().

Which means we don't fit either the .org or non .org columns above - hope that doesn't cause too many problems!

@jrfnl
Contributor
jrfnl commented Jan 14, 2016

Hi @Stephen-Cronin,

That shouldn't be too hard, let me have a quick look how that'll work out user interface-wise, but the principle of it is easy enough to implement.

I'll ping you when I have updated the branch.

@jrfnl
Contributor
jrfnl commented Jan 14, 2016

@Stephen-Cronin All done. I've updated the screenshot & the table to reflect the changes made.

@jrfnl
Contributor
jrfnl commented Jan 14, 2016

Ok, made some more adjustments.

If anyone wants to see what the output of the Generator looks like, I've uploaded the 7 different flavours of output for you to peruse: https://adviesen.stackstorage.com/index.php/s/24rI27wv7p60vyr

(will leave them online until this PR is merged)

@Stephen-Cronin

@jrfnl - Thanks. Table and screenshot look great! Will check out the downloads.

@Otto42
Otto42 commented Jan 16, 2016

Language pack support for all themes and plugins already exists on w.org. We don't currently "enforce" it, but we will eventually. Soft sell while we ramp it up, basically.

@Otto42
Otto42 commented Jan 16, 2016

Note that we would want themes to use one text domain. Replication of strings is not an issue, since all translations for language packs are centrally managed at translate.w.org. Translate once, everybody gets the benefit.

@jrfnl
Contributor
jrfnl commented Jan 16, 2016

Note that we would want themes to use one text domain. ... Translate once, everybody gets the benefit.

@Otto42 Thanks for taking the time to have a look at this and confirming we're on the right track as that's exactly what the Generator is about. For those people publishing their themes via wp.org, we're trying to make it as easy as possible to include TGMPA and still use only one text-domain. The Generator will automatically adjust the TGMPA code to match the current requirements for using the language packs as well as sorting out the add_theme_page() issue.

For those people not publishing on wp.org (and therefore not getting the benefit of translate.w.org), having TGMPA native translations available will be more efficient.

Maintaining different versions of the same (main) repository for different purposes, makes maintenance really hard. This way, we can still cater to the specific needs of wp.org (and Themeforest), without the need for different branches for different uses/publication channels.

@jrfnl
Contributor
jrfnl commented Jan 24, 2016

@GaryJones @Stephen-Cronin @Otto42 Just checking: anything which would still need to change ? If not, I'll squash the commits so we can merge.

@jrfnl jrfnl Add a Custom TGMPA Generator to the website.
The Custom TGMPA Generator takes the zip file from the latest release (for now: needs to be uploaded after each release as I can't find a hard link to the zip on GitHub) and adjusts the contents based on settings provided by the end-user in a form in the download page of the website and then serves the customized .zip file to the user.

The output will be different depending on whether TGMPA will be used within a parent/child-theme or a plugin and the chosen publication channel: wordpress.org, Themeforest or other.

Other changes made to the website to support this:
* removed most links to the GH downloads and redirected them to the download page to encourage the use of the form.
* added a number of javascript libraries used by the custom generator which will conditionally load - i.e. only on the download page.
* added the v2.5.2 release zip file to use as base for the generator.
* added a blogpost announcing the custom generator
a93cd5b
@jrfnl
Contributor
jrfnl commented Feb 12, 2016

Ok, time to get this baby going I'd say ;-)

Rebased, squashed & blogpost date updated. Ready for merge.

@GaryJones GaryJones merged commit 42ecf00 into gh-pages Feb 12, 2016

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@GaryJones GaryJones deleted the feature/custom-tgmpa-generator branch Feb 12, 2016
@jrfnl
Contributor
jrfnl commented Feb 23, 2016

If anyone wants to see what the output of the Generator looks like, I've uploaded the 7 different flavours of output for you to peruse: https://adviesen.stackstorage.com/index.php/s/24rI27wv7p60vyr

FYI - I'm taking the examples down now the generator is online. If anyone feels they should stay online for whatever reason, let me know.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment