User:Cjwillcock.ca/starting-with-wordpress

Doing some initial testing: wp-dev.cjwillcock.ca (begin 2018-06-07)

Moved testing on to primary domain: cjwillcock.ca.

---

This run-through has ended, see 'Aww Snap' for details. See User:Cjwillcock.ca/Starting with WordPress, Take 2 for continuing the adventure.

---

This Wiki

Haven't looked at the Getting Started on WordPress page until now. Whoa. That's a lot of stuff …

ignore most other content, very dated, we are in the process of trying to split the pages one for theme developers, and one for users

jgmac1106 #wordpress 2018-06-07

First impression of this page: lots of 'if' and 'should', I'm already lost, lol

I'll leave it alone because WIP.

Open Question

Are Indieweb plugin and IndieWebify.me meant to be complementary experiences, to the extent that the UX flow is considered on both as one onboarding experience? Or are they loosely coupled (different devs, etc)?

• This was more or less answered in the negative. No, they are not considered a unified, planned experience with intentional feedback for new users at this time.

We really need to do some updates to that tool

Aaron Parecki via #dev 2018-06-09

Observations

Power User / Developer: Run Through IndieWebify.Me using fresh WP install

WP Version: 4.9.6

You all are in for a treat. I'm documenting my first time seeing any of this IndieWeb WP Ecosystem.

I only know of micro_etc_ stuffs and etc. etc. Been here a week or so. Let's see how it goes.

Aww Snap

My oldest child, nine years old, came into my home-office some days ago. He needed me to put my password in so he could fix the sound on his computer. Say what? I went in there and looked at the Windows prompt for admin authorization. Hmm -cancel-. He was running the sound troubleshooter. Interesting, kind of smart, maybe. It was the best he could do with the tools available. I asked him if he had tried restarting the computer yet. No, was his answer. I walked out telling him if it didn't work after he restarted, to come back and ask me for help. Some hours later, I checked in with him. It's working right? Yes, indeed.

I have fallen into a trap, where my expectations didn't match up with what the tools can do for me. I tried the test-driven-(learning,development) approach - where the indiewebify.me website was the test authority and I did the red/green/refactor steps. I wanted to document a fresh WordPress install and what steps would get me on the IndieWeb /correctly/. As it turns out, some discussion followed my shared experience via this wiki journalling of my attempt and I learned that perhaps strictly following the output from indiewebify.me was causing me unnecessary trouble. Thanks goes to Sven Knebel and gRegor Morrill for helping me with some particularly complex (but simply explained, kudos) aspects of what I'm doing.

I also took a too-deep dive past the boundary that I want to test against, that of non-developer picking up WordPress and looking to get on the IndieWeb. I thought it useful to some part of the community to have an all-in attempt documented a little bit (as it was looking not good otherwise). My other mistake was not following the advice of the indieweb/wp-uf2 (microformats2) plugin: "It is better to use a theme that supports Microformats 2 fully."

The remainder of this page is left here for posterity, but I have moved on and won't complete this run through. Those interested may continue following my progress at User:Cjwillcock.ca/Starting with WordPress, Take 2 (start 2018-06-09)

Set up Web Sign In

No changes from vanilla WP install, and I test ... "Something Went Wrong, no rel=me links could be found"

• Can indiewebify.me detect WP as the source and offer specific guidance here, ie: "Have you installed and activated the Indieweb plugin?" smart onboarding for the win

So I start with the primary plugin, Indieweb plugin. How did I know to do this? Found it in the WordPress block far away at the bottom of Getting Started on WordPress.

Search via WP Dash -> Plugins -> Add new -> "IndieWeb" -- huzzah, I recognize the logo, success, installed and activated

• No new custom post types, hmmm. Not what I was expecting, maybe that comes in other plugins (note: very beginner at all things IndieWebCamp) (EDIT: from jgmac1106 via #wordpress: "the themes do not use custom post types, I am using 2016 fork, and it relies on taxonomies for post-kinds, David Shanske describes why in last podcast")
• New IWC Menu in my sidebar. That Icon is on the blurry side though.

Checking out this new plugin -- wow, a page full of info for me under Getting Started. Alright IWC, alright.

• I guess you want me to fill in my user profile. Look at all those new fields. okay. done.
• Side option multi/single author ---- it's already set to single, all good then I suppose. Doesn't seem so critical as to be #2 step on getting started with the IndieWeb.
• rel-me links on my site huh? Confirmed. Cool. I think I can sign in now? Oh yea. Works now. Or does it?

"We found the following rel=me URLs on your site" -> but they don't link back.

• Where is my email based rel=me?
• What the?! Now it recognizes I am from WP. Because of the plugin I just installed? Hmm.

Alright, let's see, I added twitter and github information. I'll temporarily change those backlinks to my wp-dev.cjwillcock.ca address and try it again.

• Still no joy? Sigh ... oh yea this. When I enter my domain without protocol information at indiewebify.me, it defaults to HTTP. However, the HTTP address auto-redirects to HTTPS on my site. Yes, while this trivia is completely discoverable, alas it is not coming to the party, fine fine. I'm in the habit of entering the domain-with-protocol as https but lately (indieweb influence) I am thinking of cjwillcock.ca as my identity token. However, when I enter domain-without-protocol (wp-dev.cjwillcock.ca) on Github or on my WP dashboard it defaults to http, while the same domain-without-protocol entered on Twitter correctly determines the https!

Recap: set my url as wp-dev.cjwillcock.ca on Github, WordPress, Twitter and IndieWebify.me, result of web-sign in test is github works perfectly, while Twitter doesn't link back.

I don't like it. I'm going to set them all to https. And, now it's all green, github & twitter working perfectly. Maybe? I haven't logged into anything yet. Maybe that will come later.

Next!

Check your homepage h-card

Alright I will. Survey says … no h-cards found.

• It seems that my coming from WP is forgotten again. There is no advice specific to making it work with WordPress.
• I followed the green link in the green-background area, and I'm now fully into the microformats wiki. Which is fine, but I'm shifting gears here big time. I went from Maximum Fresh Energy WP Power Install Fresh Spicy Fresh Indie Web to "... h-card is one of several open mf draft standards suitable for embedding data in HTML". Wait a second here. I started at data. It was marked up with HyperText. Now I need a very small format to embed data into it? Haven't I already done that when I put HTML around my content (my data)? I know, I know breath buddy, breath … I think the word I want there is metadata (data about data). But what am I doing here anyway? Okay back from Mercury, and time to hit the browser's back button.

I'm actually a little lost here at step 2. However, I noticed back in my WP dashboard there was an extensions sub-menu on the IndieWeb Plugin sidebar menu, so I'm going back there to look for clues.

I found an extension called Microformats 2.

• As a second step with indiewebify.me, I would expect the MF2 extension to be the first on on this list. I could see folks not finding it within a few seconds at this point and bailing. A few seconds more and there it is, 8th of 10.

Microformats2, installed and activated.

• No new settings, or sidebar items in WP Dashboard. No new menu entries under IWC. k.

How are we doing with this h-card situation? Well it still doesn't work, no h-cards found.

• Check the plugin description, uh-oh: "It is only a very basic implementation, because not every element is accessible through actions or filters. It is better to use a theme that supports Microformats 2 fully." Yikes. So …

Aside Why are all of the microformats tokens in my class attributes? They are data right (or meta-data, whatever). But here's the thing about that, class is entirely for the purpose of styling is it not? Should it not be? Okay, okay. Maybe it's not the case (I am fully aware that it is in-spec usage to use the class attribute for other than styling) but think about this. I don't want microformats in my way when I am working through the cascades of multi-faceted stylesheets operating in tandem in my responsive web design projects that cover a large swathe of my limited capacity to hold details in my mind sufficient to reason and productively express my intention - to adjust the design, not the data in any way whatever! It could easily be in data-* attributes couldn't it? Either data-mu="…" or <element data-h-card data-x-etc>. You know how hard a battle it is to get junior devs to separate the concerns of data & design right? Have you tried getting a senior dev to un-separate them? So positive productive power to bear on this- either I will force my mind to change, or I can kick this discussion around when I eventually become competent with the microformats2 specs. -(EDIT: I'm now shifted over to understanding microformats(2) much better. Thanks again to gRegor Morrill for pointing me to the FAQ on microformats.org, which led me the the HTML spec. I'm going to leave my impressions recorded here as-is.

Okay - I decided I would create a widget to make this h-card I need but ... what's this ... IndieWeb plugin already has such a widget. Hm. Yea, that Getting Started section in the IndieWeb plugin really could have saved me some time here.

K. Widget, on my sidebar, run the test again and ... woo! Success. Sort of? It's saying I should add my email. Hm. It's in my user profile already. I didn't choose, "don't show my email" anywhere. Privacy by default, it's good this way. Now, where is the remove-bandaid button?

• There could be an option in the widget. "[ ] Reveal my email address."

Well that's fine, I'll just put the recommend html inside the biographical information section. Test it and, NOPE. It shows up in the 'note' and isn't detected at IndieWebify.me.

• It is right at this point that I can no longer operate directly from WordPress admin with plugins, settings and options (non-coder), and have true success with indiewebify.me. What a shame.

Whatever, I'll just go make a widget for h-card with email reveal option based on the widget from Indieweb plugin.

• Found a bug
• Reported an issue to the repo GH Issue #106
• Fixing a bug
• Pull Request
• Added my required functionality
• Found an open github issue for this very functionality!
• Pull request for h-card updates
  • doing a pull request to a new repo, without really knowing what the usual process is, is an intimidating thing. Consider, sending a pull-request to the welcoming community at IndieWeb may be, can be(!) a first for many people. Describing how it goes and what to expect may help more people get over the initial hurdles, technical and social. Seeing the automated code climate review gives me a lot more confidence in being willing to try further commits. It's a nice touch.

The WordPress set is particularly sensitive to the boundary that I ran into here. I powered through to sending a pull-request to scratch my itch, which will (if accepted into the main repo) remedy this particular friction for all the WP users out there. There will certainly continue to be these hard boundaries as more people embrace IndieWeb via WordPress. We'll have some that cross into coding a fix that they squirrel away for their own use, some that end up contributing upstream (it's practice) but the majority will be left waiting for upstream to do it for them. A focus on making onboarding as frictionless as possible is absolutely necessary to get more non-technicals through the setup phase. Right so where were we here.

Retest the h-card back at indiewebify.me and it's good! It's … but wait, there's more!

I blew out my installation and started over so I could check my version of the Indieweb plugin with changes, before I sent in a pull request. Somehow, my h-card is no longer my representative h-card.

• I added a trailing slash to my URL in the WP user profile. That could have gone better
• Trailing slash has been removed, now I get the all good, all green. Whew.
• Interesting to note: I went back to step one to ensure I hadn't borked the relmeauth by removing the trailing slash. We are still good, however, I note that the github user profile has my URL with a trailing slash.

Check that posts are marked up with h-entry

(continuing 2018-06-08)

Aside I have seen that I'm falling a little bit into IndieWeb.org as a silo haha. Simply because I did not intend to use an existing framework for my primary domain, but have begun using the wiki quite a lot in a short time. I'm now reworking and re-installing my vanilla WP to my primary domain, so I can get into some selfdogfood from early days. No better way to entreat everyone about WP than to experience it first hand for awhile.

Pre-requisite: write a post. Ka-chow! A Little Adventure Begins Here

I'm really out of practice. It took awhile to write that post. Much longer than I expected. But, you know, that's the whole point right? #selfdogfood

(continuing 2018-06-09)

I run my new post through the test at IndieWebify.me and, good start, it's green. There are a few missing pieces, so let's sort that out.

• This is my reinstall and I have not added the microformats2 extension/plugin (yet)
• I'm missing the author photo, URL, URL of POSSE'd copies, and categories.

But I do have an author photo already - so let's sort this out first. This would be an author photo inside the h-entry then I guess, not simply one on the page somewhere (I already have my photo on this page, marked with u-photo, in my representative h-card in the sidebar). Let's confirm where the h-entry root appears in my DOM on this page.

• We don't actually have a microformats2 h-entry but we do have the microformats(1) hentry. That class is on the WP post inside this page, and so my representative h-card- specifically my u-photo- is not within the hentry and thus the error.
  • indiewebify.me is fudging the facts, ever so slightly here. It is finding 'hentry' and telling me it found 'h-entry'. In particular, this could be another indication that a new WP user (non-microformats2 supporting theme) could benefit from some specific advice.

I guess it would be nice to include my photo again in the footer of my post (hentry). I'm at the mercy of my theme now. I don't have an option to enrich the post-footer metadata from WP admin. For example, the post-footer currently has only categories and tags. I have the option to go searching for plugins that do what I want.

• oh yea, the microformats2 plugin!

I installed and activated microformats2. Re-test at indiewebify.me, no change. Hm. Let's check the markup and see what the plugin tried to do here.

• neat, the hentry is no longer specfied on my post, but has been moved to the <body> of the page. I also now have the 'h-entry' in addition to the 'hentry'. Wait, isn't my h-card with u-photo now inside my h-entry? Hm. I must have misunderstood this microformats2 thing entirely. Or could the checker be a little inaccurate? Self-doubt puts the brakes on my momentum, big time. I wish I was more familiar with the microformats2 spec so I could know what I'm into here.

Well, let's sort this out. Step 1, disable microformats2 plugin to clean up the workspace a bit. That's done. Now, what is the markup telling me?

• Now that I'm a little more familiar with microformats2, I think what I'm seeing here is that WP vanilla theme is using microformats(1). While indiewebify.me testing gave me a 'social pass' with the success on the h-entry test (allowing hentry). The difficulty is that I need microformats2 support and a healthy failure notice on the test with some relevant advice is preferable to me.
  • The easy 'install a plugin' option is not there however. we've tried installing microformats2 plugin and the test still didn't pass. If we can resolve this for end-users of WP, only then would it be generally good to throw a fail for missing microformats2 (speculation).

Alright, I need microformats2 support. Reactivated plugin and diving into the markup again. View source and search for any 'h-*'.

• There's my 'h-entry' on the <body>
• Look at that, now there is an 'h-card' with 'p-author' property inside my post-header. Interesting ... so is indiewebify.me finding that h-card and not looking for another one? Survey says, NOPE. I disabled the output of the h-card token by editing the source of the microformats2 plugin. Even without this h-card, indiewebify.me is still not picking up the representative h-card with u-photo from the sidebar.
• I'm still seeing those microformats(1) tokens on things, and I have already seen the indiewebify.me test allowing a v1 stuff to pass v2 tests. I wonder if the test is picking up the 'author' and 'vcard' tokens from microformats(1)? Time to bring out the big guns.

I could either work in the theme now or work in a for-plugin-purpose style. I'm going to try the plugin route -much more difficult- because any solution I come to that is theme-agnostic will be more useful. The background on this microformats2 plugin is that it does the best it can, given the limited number of WP actions and filters that are available to manipulate outputs. I have a very nice hammer and I'm rather well-accustomed to WP internals, so I'm going to see what else may be done.

• I install and activate the Query Monitor plugin by John Blackbourn & contributors
• Reload the public post, hover over the query monitor info that has been added to the WP admin bar at the top of my screen, and select the Hooks and Actions item.

Whoa. The microformats(2) description is very accurate about the current situation:

… not every element is accessible through actions or filters. It is better to use a theme that supports Microformats 2 fully.

wordpress-uf2 plugin authors

Hypothesis': It may be better to use a different theme but it's not impossible to manipulate this one.

There is the WP action 'get_template_part_template-parts/post/content' which is dynamically created at runtime for the arguments supplied to get_template_part(). This is fragile as old get out (no guarantees it will work with any other theme) but I can work with this. Or can I? The action fires before the template part is included, but there is no corresponding action for after the template part is included. Back to the drawing board (and further up the action hook stack trace).

There is the WP action 'the_post' which is triggered after the database query completes and the post is setup. That's not what I'm after, it only happens in the beginning. Further up again then.

There is the 'loop_start' action hook and corresponding 'loop_end' action hook. That's what I'm after. I'm going to start an output buffer on 'loop start' and do some string replacements on the buffer before outputting it on 'loop end'.

It looks like this:

add_action('loop_start', function(){
    ob_start();
});

add_action('loop_end', function(){
    $result = ob_get_clean();

    $replace_all_of = array();
    $with_nothing = '';

    $result = str_replace($replace_all_of, $with_nothing, $result);

    echo $result;
});

Note: I'm putting this code at the bottom of my theme's functions.php file for R&D purposes

So far, this accomplishes nothing. But it does give me an opportunity to rewrite the contents of the post, before it is sent to the wire. I want to take out the 'author' and 'vcard' tokens from the post-header, and see if indiewebify.me then finds my representative h-card in the sidebar. This is not portable or safe or anything like that, it's a hammer! So I add 'author vcard' to my $replace_all_of array:

...
    $replace_all_of = array('author vcard');
...

Take that twentyseventeen. Let's see how we fair with the test. Well, it's different … but it's still not passing. The microformats2 plugin has added an 'h-card' token in the same area. I can disable the plugin, but I'd rather use my little code to remove the specific token I don't want there:

...
    $replace_all_of = array('author vcard', 'p-author h-card');
...

Test again at indiewebify.me -- yea, that did it alright. I have my u-photo from my representative h-card in the sidebar now showing up as the h-card for my h-entry, and giving me a green light.

Generalizing this technique to a plugin that will work for all themes?

Sadly, no can do Output buffering like this is generally something to avoid, but in some cases it could be alright. For example, transitioning from a non-microformats2 theme as a temporary situation, deferring a robust solution (use a different theme with native microformats2 support) to later. However, manipulating the output of WP in the general case of any theme being used, we can only safely add to the theme, not take away from it. Why? Because the nature of the data which is described by the microformats2 vocabulary tokens applied to HTML elements, is being dual-purposed to describe presentation of that data via CSS. If I remove an 'author vcard', any CSS rules targeting .author.vcard will no longer apply.

Bottom line: human intervention is required to apply this technique to a theme.

But you don't need to remove microformats(1) tokens, to add microformats2 tokens

Exactly right, that is what the microformats2 wordpress plugin does now in a safe, actions-&-filters-only approach.

• If the indiewebify.me tests had a strict mode, which ignored microformats(1) tokens, I (and others) could explore this.
• Alternatively, there may be other self-tests that can be utilized for this development, instead of indiewebify.me.
• Alternatively, someone could roll a new self-test that ignored microformats(1) and only showed the microformats2 relevant things.

Unresolved, pre-requisite question: In general, are consumers of microformats2 also sensitive to microformats(1) tokens? If so, any improvements in microformats2 coverage will fail to convey the intended meaning, because the consumers of microformats are satisfied with the presence of microformats(1) tokens and stop looking for microformats2 details.

Aside This brings up a fundamental gotcha of selfdogfood with WordPress (or any other CMS/app thinger) other than those entirely self-authored (disclaimer: which I have seen to-date). Namely, the tool is communicating on your behalf and with your authority, some things which you have not knowingly intended to include in your own works. Rather than the challenge of implementing what you want, you are stuck into a daunting requirement to dig as-deep-as-necessary into a foreign work, to mute what you don't want to be included. We trade control for speed of getting-started, and this is often a good thing. Furthermore, the third party may, at any time, include new things (following an update) where the onus is on the site-owner to review and respond should further muting of unwanted inclusions be necessary. Removal of desired inclusions by decision of the third-party is another edge on there too. Still, for ease-of-use, and, you know, people must start somewhere, it's a fair trade.

Time to rewind and repack that beastie now. Why am I digging into all that again? Oh yes, because the test at indiewebify.me did not see my u-photo in the h-card it selected for the h-entry. Can I maybe just add the u-photo to the plugin where it is already putting the 'p-author' and 'h-card' tokens? Yes I can. Done.

• I will not do a PR right away with this, because there should be an option about including the photo there, defaulting to 'no'. Also, I'm starting to suspect that these plugin methods are used for many purposes and by, for example, adding an email address or photo, what works in one place will compromise or straight-up break other use cases.

That's done, my version of wordpress-uf2 plugin now includes the gravatr next to the author name, and I have success with indiewebify.me.

        /**
         * Adds microformats v2 support to the author.
         *  with ugly hack by cjwillcock
         */
        public static function the_author( $author ) {
                if ( ! is_admin() ) {
                        $avatar = '';
                        $args = array(
                          'search' => $author,
                          'search_fields' => array('display_name')
                        );
                        $user = new WP_User_Query($args);
                        if(null !== $user){
                                $avatar = get_avatar(
                                        $user->get_results()[0]->user_email,
                                        15,
                                        'default',
                                        '',
                                        array(
                                                'class' => array(),
                                        )
                                ) . ' ';
                        }
                        return "$avatar<span class='p-author h-card'>$author</span>";
                }

                return $author;
        }

What's the next missing thing? URL for my h-entry. I'll need to include the permalink, even when I'm on the single-post template (by default the permalink typically is on the title when looking at a list of posts, and absent when looking at a single post).

Urk. This is likely where some other third party plugin, for customizing my post-footer will be a good fit. Where currently I only have tags and categories there, I may be able to put something else. Various other themes will all do this their own way. I'll see what may work for me.

• I prefer to code something than install third-party by default.

WordPress / Indie Ecosystem

Themes

These are fast, first impressions, by no means thorough, conclusive or even fair!

theme	Is Child Theme?	Install	Custom Post Types	Bundled Plugins	Bundled Widgets	Overall
dshanske/ twentysixteen-indieweb	nope (could be)	it doesn't look any different	nope	nope	nope	I guess it is doing things that I don't need to know about? I wonder why it's a fork and not a child-theme.
dshanske/ mf2_s	nope	worked, but ... errors riding every admin page now about missing plugins, no advice to fix that available in messages or in theme details	nope	nope	nope	suuuuper plain. sharp poke on install re: errors
raamdev/ independent-publisher	nope	not much going on	nope	nope	nope	_seems_ like not much going on, quite plain
pfefferle/ ZenPress	nope	not much going on	nope	nope	nope	i like the jumbotron on /
pfefferle/ SemPress	nope	not much going on	nope	nope	nope	suuuuper plain.

Plugins

T.B.D.