WordPress.org

Ready to get started?Download WordPress

Review WordPress Themes

Updates from November, 2012 Toggle Comment Threads | Keyboard Shortcuts

  • Chip Bennett 6:40 pm on November 26, 2012 Permalink | Log in to leave a Comment
    Tags:   

    WordPress 3.5 Guidelines Revisions 

    It is that time of year again: with the upcoming release of WordPress 3.5, the Theme Review Team conducts its periodic review of the Theme Review Guidelines, and proposes any changes, either as necessitated by the new WordPress version, or otherwise as-needed.

    The 3.5 release has little impact on Themes, and as such will be mostly invisible to Theme developers. One minor change will be support for HiDPI (i.e. “Retina”) screenshots. If there are any other 3.5-related changes that we need to account for, please post in the comments.

    Here is the starting point for the discussion regarding changes to the Guidelines:

    • Change Theme Screenshot (screenshot.png) maximum dimensions from 300x225px to 600x450px. (Fixed per comment below)
    • New guideline under presentation-vs-functionality: Themes must not bundle custom post-content shortcodes
    • Change guideline: reduce criticality for Content Sidebar feature from required to recommended. (Themes would still be required to implement core Settings API if Theme incorporates content sidebar feature.)
    • Change criticality of add_theme_support( ‘automatic-feed-links’ ) from required to recommended. (Modified per comments below)

    Please discuss in the comments, and recommend any additions or changes to these proposed Guidelines revisions.

     
    • Andrew Nacin 6:45 pm on November 26, 2012 Permalink | Log in to Reply

      Could you explain the reasoning behind automatic-feed-links?

      • Chip Bennett 6:49 pm on November 26, 2012 Permalink | Log in to Reply

        Sure. I have no particular preference one way or the other. That one is there for discussion, primarily.

        It was suggested to me – and I would tend to agree – that inclusion of RSS feed links is a) not exactly *presentational*, and b) easily enabled via Plugin. So, I’m throwing it out there for the Theme developer community to discuss and to decide. That way, we’ve documented our reasoning for keeping it or removing it.

        • Andrew Nacin 7:15 pm on November 26, 2012 Permalink | Log in to Reply

          I need to do some research to verify my recollection here, but as far as I know, the only reason why it is a theme-support thing is because prior to that line of code, themes would add them into header.php directly. This would cause a double-up. If it weren’t for that, we never would have had the opt-in, and we’d just always do it. I’m game for revisiting this in the future, but I think it makes sense for themes to continue to add the line.

          • Chip Bennett 7:18 pm on November 26, 2012 Permalink | Log in to Reply

            I would consider header RSS feed links to be analogous to the WP version generator and other similar meta data. I’m sure you’re right about the reasoning behind the add_theme_support() implementation. Perhaps a criticality bump from *required* to *recommended* (or *optional*), to help make the point that this functionality lies very close to the presentation-vs-functionality line?

            • Samuel Wood (Otto) 7:53 pm on November 26, 2012 Permalink

              I would say that you could put this in the category of if you use them, then you must use them correctly by using the theme support bit instead of putting them in the header.php manually yourself. But we would definitely say that using automatic-feed-links is recommended.

              I would also say that it is definitely not plugin territory. If anything, core should be doing it automatically, all the time, period. However, because themes traditionally used hard-coded feed links, there was no way to do that and be backwards compatible.

            • Samuel Wood (Otto) 7:55 pm on November 26, 2012 Permalink

              In other words, ban hardcoded RSS links in theme headers, and require use of automatic-feed-links for themes that add feed links (which, IMO, should be all of them).

            • Chip Bennett 8:17 pm on November 26, 2012 Permalink

              I’m with you, Otto. I don’t think anyone is advocating *prohibiting* automatic feed links; but rather more like what you said: adding feed links is *recommended*, *must not* hard-code feed links, and if adding feed links, *required* to use add_theme_support().

            • Vicky Arulsingam 1:03 am on November 27, 2012 Permalink

              I’d prefer it be bumped down to recommended.

              If a user has a plugin for this feature and feed links are added in the theme, would this result in the links being displayed twice?
              If this is the case then a recommendation/requirement to perform a ‘current_theme_supports’ check would be helpful

            • Andrew Nacin 2:49 am on November 27, 2012 Permalink

              They should remain required. Think about it this way: The theme *must not* hard-code feed links, and the theme *must* tell core that they are not hard-coding feed links. That’s really the only meaning of automatic-feed-links.

            • Samuel Wood (Otto) 2:49 am on November 27, 2012 Permalink

              Vicky: If both the theme and the plugin are using automatic-feed-links, then no, they would not be added twice.

            • toscho 11:19 am on November 27, 2012 Permalink

              Core should ask for opt-out and apply the feed links automatically. Legacy themes should not force theme authors to use non-presentational functions in their new themes.

            • Edward Caissie 3:19 pm on November 27, 2012 Permalink

              Quoting Otto:

              I would say that you could put this in the category of if you use them, then you must use them correctly by using the theme support bit instead of putting them in the header.php manually yourself. But we would definitely say that using automatic-feed-links is recommended.

              I agree this is the best method going forward on the implementation of automatic-feed-links

      • mrwweb 7:05 pm on November 26, 2012 Permalink | Log in to Reply

        I moved automatic-feed-links to my functionality plugin a year ago for this reason. If a site needs them, they shouldn’t disappear and reappear depending on the theme.

    • Chip Bennett 7:13 pm on November 26, 2012 Permalink | Log in to Reply

      Other things I’d like to discuss:

      • Timing for making do_settings_sections() required (as opposed merely to recommended) as part of Settings API implementation
      • Removing public-facing credit links, or making them follow Plugin rules: user-configurable, and disabled by default
      • Reformatting the Guidelines as a checklist (either replacing the existing Guidelines entirely, or creating a companion tool to aid reviews)
      • Ian Stewart 7:54 pm on November 26, 2012 Permalink | Log in to Reply

        Removing public-facing credit links, or making them follow Plugin rules: user-configurable, and disabled by default

        Can you elaborate on some of the reasoning behind this?

        • Chip Bennett 8:07 pm on November 26, 2012 Permalink | Log in to Reply

          I’m curious what the Theme developer community thinks about the idea. I think that there is an argument to be made that the negatives far outweigh the positives with respect to displayed-by-default footer credit links. It attracts an inordinate share of of Bad Things, and leads to an inordinately high number of headaches for reviewers and developers alike, under the false premise that such footer credit links help developers’ SEO.

          Obviously, there *is* real benefit to be gained, through actual humans seeing and following those links, but I have long-questioned whether that benefit outweighs the volume of crud Themes that get submitted solely in an attempt to spread footer credit links.

          I’m really just interested in finding out if the Theme developer community would be even partially amenable to the idea, or if it’s something that remains completely off the table for discussion.

          • Emil Uzelac 8:24 pm on November 26, 2012 Permalink | Log in to Reply

            As developer and TRT admin I strongly believe that this is not necessary. Credit Links are the “connection” between the site and the author and many of us here are making a living out of that.

            • Chip Bennett 8:41 pm on November 26, 2012 Permalink

              Agreed, and I don’t want to give the idea of wanting to throw the proverbial baby out with the bath water.

          • CyberChimps 1:16 am on November 27, 2012 Permalink | Log in to Reply

            I think it is a good thing that we are not letting themes into the repo that were submitted on the premise of generating SEO. If we remove the credit links we will be punishing honest authors, and lose the ability to spot the spammers more quickly. It is a lose-lose situation.

            The rules do not matter to spammers, there will always be spam submissions no matter what the rules are we shouldn’t punish honest authors from having a connection to their work.

          • Edward Caissie 3:30 pm on November 27, 2012 Permalink | Log in to Reply

            I would say we leave the credit links in, as is.

            My concerns are not so much in the continued efforts of spammers trying to “game the system” but more so for the developers and designers who may lose interest in updating and/or submitting new themes to the repository without any credit for their works.

            An option to “turn off” credits may be feasible, or even something to be suggested, but I would never get to the point of it being recommended.

            If “Code is Poetry”, how can you expect the poet to not openly sign their work?

        • Ian Stewart 8:18 pm on November 26, 2012 Permalink | Log in to Reply

          I think it’s an interesting idea. My two cents: I think an option is too much cruft for a problem that doesn’t really affect the user and that not allowing public facing credits will probably discourage submissions from designers — especially ones that aren’t quite aware that a theme developer community exists. I don’t think designers do it for the SEOs. I just think it’s natural for them to want to put a credit line on their work in the same way that an artist naturally tends to sign their work.

          • Ian Stewart 8:21 pm on November 26, 2012 Permalink | Log in to Reply

            I don’t think designers do it for the SEOs

            Though obviously some spammers with not-the-best themes are. :)

          • Chip Bennett 8:22 pm on November 26, 2012 Permalink | Log in to Reply

            Is there a way to provide the benefit (which is certainly deserved), without attracting the bad?

            • Ian Stewart 8:34 pm on November 26, 2012 Permalink

              Probably not.

            • Chip Bennett 8:36 pm on November 26, 2012 Permalink

              Is it something worth further consideration, to try to come up with a better alternative, or is it just something that we just have to continue to deal with, because it can’t be fixed?

            • Ian Stewart 8:40 pm on November 26, 2012 Permalink

              There may be some way to make it easier to spot/flag these themes beforehand (automatically diffing against the default themes and coming up with a percentage that flags a theme? Flagging first time themers that have some sort of commonality to theme?). I can’t think of any alternatives to it beyond getting better at spotting the bad guys and just dealing with the fact that there are bad guys.

            • Ian Stewart 8:41 pm on November 26, 2012 Permalink

              … sort of commonality to theme?

              s/theme/them

              For some reason that’s a common spelling mistake with me.

            • Chip Bennett 8:49 pm on November 26, 2012 Permalink

              I often “audit” the Priority #4 queue, for just this sort of review. I look for spammy/inappropriate credit links and landing pages, and obvious knock-offs of known Themes.

              Honestly, child Theme support helps greatly in this regard, since we can spot Twenty Ten and Twenty Eleven derivatives, and require them to be resubmitted as proper child Themes. That’s helped cut down on a good bit of the knock-off Themes. But a lot of the pattern recognition you describe is purely manual, and requires familiarity with Themes prone to being forked.

            • Emil Uzelac 9:29 pm on November 26, 2012 Permalink

              We can reduce the numbers from 4 priorities to only 2. #1 Previously Approved and #2 All others, this way the process would be much faster and we can “scan” for SPAM easier. Does that make sense?

          • Philip Arthur Moore 12:13 am on November 27, 2012 Permalink | Log in to Reply

            Big +1.

        • Daniel 8:40 am on November 27, 2012 Permalink | Log in to Reply

          I have a bad feeling an unintended consequence of this would be many developers not updating theor themes anymore to circumvent this guideline.

        • Konstantin Kovshenin 11:19 am on November 27, 2012 Permalink | Log in to Reply

          Will adding “nofollow” to such links help avoid the “Bad Things”? If it does we can make it a recommendation or even a requirement.

      • Ian Stewart 7:54 pm on November 26, 2012 Permalink | Log in to Reply

        Reformatting the Guidelines as a checklist (either replacing the existing Guidelines entirely, or creating a companion tool to aid reviews)

        I think this is a great idea.

      • kwight 8:08 pm on November 26, 2012 Permalink | Log in to Reply

        I’ve volunteered to help the Documentation team with the Theme Review handbook: http://make.wordpress.org/updates/2012/11/20/docs-team-intro/#comment-22

        I’m a little unclear as to how this relates to the current posted Guidelines; I’m hoping the handbook eventually /becomes/ the posted guidelines. Is this what you’re referring to, or are you suggesting an interim step?

        • Chip Bennett 8:10 pm on November 26, 2012 Permalink | Log in to Reply

          As I understand it, the Theme Review Handbook is more intended to be a “how to get involved with the Theme Review Team” kind of thing?

          • kwight 8:24 pm on November 26, 2012 Permalink | Log in to Reply

            Ah, perhaps I’ve misunderstood; so the Handbook is more of an onboarding tool, while the Guidelines exist separately in the Codex?.. Either way, I’m in, the current format could certainly be improved.

            I think it would be more effective for each guideline to have a What Why How approach: “What” is the guideline, “Why” is it required/recommended, and “How” is it implemented (actual code example). I think it would reduce a lot of confusion both for reviewers and submitters.

            • Chip Bennett 8:27 pm on November 26, 2012 Permalink

              I like that approach; the problem is that the Codex doesn’t necessarily present the best means to implement such an approach. We would have to have separate entries for the Guidelines themselves (essentially what we have now), and for the What/Why/How information; otherwise, it would be even *more* difficult for new Reviewers to read/parse the Guidelines.

              But, I am absolutely in favor of providing more code examples, wherever we can.

            • kwight 8:51 pm on November 26, 2012 Permalink

              True; in my fancy designer head, each of the What Why How would be a tab for each guideline, but AFAIK, that’s not possible with the Codex. If only the Codex was WordPress :|

              The best thing I guess, could be having a “more detail” link for each guideline that goes to a more lengthy What Why How page, with code examples.

    • Ian Stewart 7:41 pm on November 26, 2012 Permalink | Log in to Reply

      Change guideline: reduce criticality for Content Sidebar feature from required to recommended. (Themes would still be required to implement core Settings API if Theme incorporates content sidebar feature.)

      Could explain this one a bit more? I’m not quite clear what it refers to.

      • Chip Bennett 7:48 pm on November 26, 2012 Permalink | Log in to Reply

        In other words: Themes don’t *have* to include dynamic-content sidebars (whether as a traditional sidebar, or a footer sidebar, etc.) .

        This came out of a discussion about Appearance -> Widgets no longer displaying if Themes don’t call register_sidebar(). Dynamic Sidebars would thus be treated as analogous with Custom Backgrounds or Custom Header Images.

      • Ian Stewart 7:49 pm on November 26, 2012 Permalink | Log in to Reply

        Awesome. Thanks.

      • kwight 8:11 pm on November 26, 2012 Permalink | Log in to Reply

        +1. It would be great (particularly for stripped-down/minimalist themes) to not be forced in to implementing widget areas.

      • Danielx64 3:57 am on January 24, 2013 Permalink | Log in to Reply

        -1 for the sidebar removal, like I said on the mailing list, I wouldn’t be happy to download a theme only to find out that it doesn’t support widgets.

    • kwight 7:57 pm on November 26, 2012 Permalink | Log in to Reply

      Ack! I already changed the guidelines re: screenshots, after noticing the new hiDPI screenshot for Twenty Twelve works in 3.4.2. Since it’s stating a maximum, would be a problem keeping it like that unless something comes up?.. Let me know if I’ve really jumped the gun, I’ll set it back.

    • shawn 8:09 pm on November 26, 2012 Permalink | Log in to Reply

      New guideline under presentation-vs-functionality – anyplace I can get more info on these guidelines

    • shawn 8:11 pm on November 26, 2012 Permalink | Log in to Reply

      New guideline under presentation-vs-functionality: Themes must not bundle custom post-content shortcodes

      Any place I can get more info on this???

      • Chip Bennett 8:16 pm on November 26, 2012 Permalink | Log in to Reply

        What sort of information are you looking for? This is probably the best place to get it. :)

        • shawn 8:38 pm on November 26, 2012 Permalink | Log in to Reply

          Are we talking just shortcode(s) or any custom post content code….

          A clearer definition of presentation vs functionality guidelines standard for either themes or plugins in WP are not exactly up to common PHP standards. I would love to know what exactly the guidelines are.

          • Chip Bennett 8:45 pm on November 26, 2012 Permalink | Log in to Reply

            Are we talking just shortcode(s) or any custom post content code

            What other post-content code do you have in mind? As a general rule, if you’re manipulating post content in any way other than presentationally, that manipulation probably belongs in a Plugin.

            A clearer definition of presentation vs functionality

            In some regards, that is the million-dollar question. But for the purposes of Themes, 99% of the time it isn’t difficult to determine whether something is functional or presentational.

            Do you have any specific examples where you’re unclear about whether something is one or the other?

            • Sayontan Sinha 9:13 pm on November 26, 2012 Permalink

              Themes that are framework-based (like Hybrid) have a lot of bundled shortcodes. Are those acceptable? What exactly differentiates a “custom post-content” shortcode from a regular shortcode?

              Along the lines of the Hybrid question, is it acceptable if the author provides a shortcodes plugin which is simultaneously offered with the theme (I do so, mainly to help users transition out of the theme without impact).

            • shawn 12:36 am on November 27, 2012 Permalink

              Most of my custom post-content runs from generic class located in a theme plugin toolkit, themes decided what is run, when, on a case by case basis, this allow me to customize post types based on the needs the theme.

              The problem with this method as far as I am aware is that themes with dependencies like these cannot function in the theme repository, now that it is policy, has this changed?

              Do you have any specific examples where you’re unclear about whether something is one or the other?

              I am unclear about everything here, since most theme developers already separate presentation from functionality what I see happening is the creation of another theme dependency and I not sure I like it.

            • shawn 2:23 am on November 27, 2012 Permalink

              Since the purpose of Themes is to define the presentation of user content, Themes must not be used to define the generation of user content, or to define Theme-independent site options or functionality.

              Sorry if I sound confused but this new guideline completely caught me off guard, theme dev/designers agreed to this???

            • Chip Bennett 2:28 am on November 27, 2012 Permalink

              The presentation-vs-functionality criterion is not a new guideline. It has been an operating principle since the beginning of the Theme Review Team’s efforts.

              What part of it do you disagree with?

            • Chip Bennett 2:30 am on November 27, 2012 Permalink

              Themes that are framework-based (like Hybrid) have a lot of bundled shortcodes. Are those acceptable? What exactly differentiates a “custom post-content” shortcode from a regular shortcode?

              As far as I’m aware, Hybrid does not bundle post-content shortcodes, but rather uses a custom shortcode for user configuration of footer text, etc. Such “shortcodes” are perfectly acceptable.

              The differentiation is post-content. If the shortcode is used in the post content – i.e. if it is added by the user to the post content editor, such as or [ref] or [two-columns] – then it belongs in a Plugin rather than in the Theme.

            • Sayontan Sinha 6:09 am on November 27, 2012 Permalink

              As far as I’m aware, Hybrid does not bundle post-content shortcodes, but rather uses a custom shortcode for user configuration of footer text, etc. Such “shortcodes” are perfectly acceptable.

              The shortcodes that come with Hybrid are entry-title, entry-author, entry-terms and several others, which to me seem very much like post-content shortcodes. These are by design to be run where the global $post is available. Where else would you invoke these if not in the post content? Hybrid has a host of other shortcodes that can be used in comments.

              So if this is made a requirement, then all themes that have such existing shortcodes have to pull them from the theme, risking sites breaking as as a result.

              I see no reason for any Theme ever to bundle post-content shortcodes.

              Except that, as I mentioned, several themes already include them, and they are in very heavy use. Trying to cull the shortcodes from such themes will only result in frustration for the users of the themes. I thought the aim of the theme review team is to make things easy for users, while disallowing what already exists only serves the opposite purpose.

              Of course, one way could be to disallow new shortcodes, but forcing theme authors to remove every existing post content shortcode is going to the extreme.

            • Chip Bennett 12:49 pm on November 27, 2012 Permalink

              The shortcodes that come with Hybrid are entry-title, entry-author, entry-terms and several others, which to me seem very much like post-content shortcodes.

              Those sound like template shortcodes to me. Key point: where does the user use those shortcodes: in the Visual/Text post editor, or elsewhere?

              These are by design to be run where the global $post is available. Where else would you invoke these if not in the post content?

              You are misunderstanding “post-content” shortcodes. A “post-content” shortcode is one that the user places in the post Visual/Text editor, that lives in the database in $post->post_content, and that is parsed by do_shortcode() upon display.

              Hybrid has a host of other shortcodes that can be used in comments.

              And Justin explicitly says that the Theme’s shortcodes are not intended to be used in the post content:: “These shortcodes are not meant to be used with the post content editor. Their purpose is to make it easier for users to filter hooks without having to know too much PHP code and to provide access to specific functionality in other (non-post content) shortcode-aware areas.

            • shawn 2:49 pm on November 27, 2012 Permalink

              What part of it do you disagree with?

              Practically all of it, with so much discussion and advances in development and understanding of UI/UX, to state the the purpose of a theme is to define the presentation of user content is shallow at best. What even worse is the intent of the statement (Themes must not used to…).

              Simply change a couple words in the statements purpose to read

              Since the purpose of Themes are to define how users interact with a websites content…

              We are having a different discussion about the rule(s) of what themes should be used for, presentation now becomes functional as functionality, as it should be is now defined by the theme!

              New old or whatever this is just sooooo wrong Chip!

            • Chip Bennett 2:56 pm on November 27, 2012 Permalink

              with so much discussion and advances in development and understanding of UI/UX, to state the the purpose of a theme is to define the presentation of user content is shallow at best.

              No. That is precisely the purpose of a Theme. WordPress is designed such that the Theme is the content presentation abstraction layer.

              What even worse is the intent of the statement (Themes must not used to…).

              Simply change a couple words in the statements purpose to read

              Since the purpose of Themes are to define how users interact with a websites content…

              We are having a different discussion about the rule(s) of what themes should be used for, presentation now becomes functional as functionality, as it should be is now defined by the theme!

              Perhaps it would be helpful to shift your paradigm from functionality to content. Properly designed Themes will support most functionality out-of-the-box.

              Asked a different way: what functionality do you think Themes should be defining?

            • Sayontan Sinha 10:34 pm on November 27, 2012 Permalink

              And Justin explicitly says that…

              So in summary it is okay to state something like “Don’t use these in your post content” in the comments, but it is not okay to state, “If you decide to stop using this theme you can use this alternative plugin”.

              The point that I have been trying to get you to see is that there are active themes with huge user-bases that have shortcodes built in them. Some theme authors actively try to make the transition out of their themes painless by providing plugins for various modules. Forcing them to pull the shortcodes out will affect a LOT of users. If this isn’t sufficient for getting an exception on existing themes with existing shortcodes, I don’t know what is.

            • Frank Klein 11:34 pm on November 27, 2012 Permalink

              As a general rule, if you’re manipulating post content in any way other than presentationally, that manipulation probably belongs in a Plugin.

              Exactly. I can see why this new proposed guideline is controversial, since a lot of developers think of themes as “website packages”, that bundle a very custom design with the necessary functionality – custom post types, short codes, etc. But the sole fact that this is practiced by a lot of themes shouldn’t matter for putting a guideline in place for future themes.

              I wonder how many of the heavy shortcode users will get the shock of their life when they switch themes and suddenly all their posts are littered with shortcodes that no longer work.

              It seems to me that most users don’t care about what comes with a theme and what comes with a plugin, all they care about is that it is there. So as developers we should make their life easier by allowing them to switch themes freely without losing any functionality.

              It isn’t that difficult to point users to the right plugin that adds the desired functionality to a theme. If someone is smart enough to use shortcodes, then he will get this too.

              Besides I hope that this will lead developers towards leveraging more existing plugins.S o instead of whipping up your own crappy SEO optimization code in functions.php, why not simply point users toward a great plugin like WordPress SEO? How different can the functionality of your portofolio post type be from that offered by Justin’s plugin?

              Relying on production-hardened, specialized plugins instead of cooking up your own is the way of the future. Not only will this free up time for theme developers so that they can focus on building the best theme possible, but it also over time improve portability and establish de facto standards.

            • shawn 3:58 pm on November 28, 2012 Permalink

            • Justin Tadlock 5:35 pm on November 29, 2012 Permalink

              Just a note about Hybrid Core: Its shortcodes are intended for use in templates. This is stated in the file listing the shortcodes as well as in my theme documentation on my site. Most users aren’t even aware that there are shortcodes in the themes because they are not advertised as a feature. Basically, to even know the shortcodes exist, you must read the notice that they’re not to be used in the post content.

              With that said, I do have some ideas about de-registering the shortcodes specifically when the_content() is called just to outright avoid any potential issues. Not once have I had an issue with this from my users though.

      • kwight 8:31 pm on November 26, 2012 Permalink | Log in to Reply

        Content shortcodes should be plugin territory, so that users don’t lose the shortcode functionality when changing themes.

        • Rizqy Hidayat 3:30 am on November 27, 2012 Permalink | Log in to Reply

          So what ‘s the actual meaning of *content shortcodes*? is it shortcodes in the editor or somekind like what?

          • Chip Bennett 12:51 pm on November 27, 2012 Permalink | Log in to Reply

            Yes: a “post-content” shortcode is a code that the user places in the post content, via the post Visual/Text editor. Shortcodes used elsewhere in the template are fine, because they don’t affect user content upon switching Themes; they’re merely Theme customizations.

      • Sami Keijonen 6:53 am on November 27, 2012 Permalink | Log in to Reply

        What comes to Hybrid Core shortcodes, they are only used in template files. Never in post editor. There is a big difference for me at least.

        • Sayontan Sinha 6:06 pm on November 27, 2012 Permalink | Log in to Reply

          Do you mean “they are only used” or do you mean “they are only *supposed* to be used”? I don’t believe there is anything preventing a user from going ahead and using these shortcodes in the post content.

          • Sami Keijonen 9:39 pm on November 27, 2012 Permalink | Log in to Reply

            Basic, non developer user don’t even know these shortcodes exists. And there haven’t been any question about using them in post content in themehybrid support forum or having problems when changing theme. Chip already pointed out all the others aspects about “post-content” shortcodes.

            But yes you can use them in post content like any other shortcode.

          • Chip Bennett 10:08 pm on November 27, 2012 Permalink | Log in to Reply

            Intended use is what matters here. The shortcodes included with Hybrid are not intended to be used in the post content. End users can do myriad things with any Theme outside of the developer’s intent; such is not our concern (see: software freedoms).

            • Sayontan Sinha 10:53 pm on November 27, 2012 Permalink

              Basic, non developer user don’t even know these shortcodes exists. And there haven’t been any question about using them in post content in themehybrid support forum or having problems when changing theme.

              This argument can be made for any theme. Bear in mind that I am not suggesting that the shortcodes be removed. I am merely saying that shortcodes either don’t matter to users at all because they aren’t aware of them, or the users make fully conscious decisions to use them.

              End users can do myriad things with any Theme outside of the developer’s intent; such is not our concern

              If that is the case, then a simple disclaimer somewhere (like the options panel) should suffice, telling users that some shortcodes are distributed with the theme and that if the users use those shortcodes they run a risk of a lock-in. After all, that takes care of the theme author’s intention. Maybe this could even be built into the core: the way it states on the themes page that a theme uses widgets, there could be something to state that a theme uses shortcodes.

              Not to belabour my point, but nobody seems to be getting that there are themes out there that have shortcodes in active use. Pulling the plug on the shortcodes simply leaves all users of such features in the lurch. And not allowing shortcodes even if there is a separate plugin offering all of them seems even more counter-intuitive.

            • Chip Bennett 11:37 pm on November 27, 2012 Permalink

              …or the users make fully conscious decisions to use them.

              I question whether such decisions are truly “fully conscious”; I don’t think most users realize what will happen to their post content if and when they switch Themes.

              Not to belabour my point, but nobody seems to be getting that there are themes out there that have shortcodes in active use. Pulling the plug on the shortcodes simply leaves all users of such features in the lurch.

              Of course we know that there are approved Themes that bundle shortcodes. Changing the Guideline doesn’t mean that those Themes are suddenly going to get suspended or anything. (Our aim is to *improve*, not to *degrade*, the user experience.) But that doesn’t mean that we shouldn’t or can’t say, “henceforth, no more.”

              And not allowing shortcodes even if there is a separate plugin offering all of them seems even more counter-intuitive.

              I don’t think there is any need to “grandfather” Themes that currently have shortcodes. I don’t see any problem with providing a transition for existing Themes with shortcodes. In your next update, make them pluggable in your Theme, and instruct users to install/activate the Plugin. Then in the subsequent update, you can safely remove them from your Theme.

            • Sayontan Sinha 11:57 pm on November 27, 2012 Permalink

              I question whether such decisions are truly “fully conscious”; I don’t think most users realize what will happen to their post content if and when they switch Themes.

              Themes are supposed to prefix their custom functions with a slug. I have always extended this to mean that their custom shortcodes should be prefixed with a slug. At least that is what I have practised always and I have even made a suggestion to this effect on the WPTRT list. If that is the case, using a shortcode from the theme becomes a very conscious choice, particularly since there is no UI provided to insert the shortcode.

              In your next update, make them pluggable in your Theme, and instruct users to install/activate the Plugin. Then in the subsequent update, you can safely remove them from your Theme.

              You are assuming that all users upgrade whenever a new version is available. I am pretty sure that there are several users who skip 5-6 versions before upgrading even if a theme is stable and from an active developer (I have even seen instances where people wait several months before upgrading).

              Regardless, if a rule is being set, there should be clear cut distinctions in the review guidelines between what is a permissible shortcode vs. what isn’t, with specific examples. Very often with other vague requirements I have had to go back and forth with a reviewer because his/her interpretation didn’t match mine.

            • Chip Bennett 12:25 am on November 28, 2012 Permalink

              If that is the case, using a shortcode from the theme becomes a very conscious choice, particularly since there is no UI provided to insert the shortcode.

              That still doesn’t make it a “fully conscious” choice, unless the user has been explicitly told “your post content will not display properly if you switch Themes”.

              You are assuming that all users upgrade whenever a new version is available.

              As a matter of principle, we do not facilitate users who choose not to keep their core, Theme, and or Plugin code current. Users are fully within their rights not to update, but that doesn’t mean we must accommodate that decision.

              Regardless, if a rule is being set, there should be clear cut distinctions in the review guidelines between what is a permissible shortcode vs. what isn’t…

              I’m not sure how much more explicit we can be with respect to shortcodes.

              If the Theme instructs or implies to users that bundled shortcodes are to be used in the post content, they are not allowed. If the shortcodes are intended to be used for other purposes (extending the Theme via hooks, or for user-configuration of template elements, etc., then they are allowed.

            • Sayontan Sinha 1:24 am on November 28, 2012 Permalink

              That still doesn’t make it a “fully conscious” choice, unless the user has been explicitly told “your post content will not display properly if you switch Themes”.

              I disagree. Regardless, I did make recommendations for this on this very thread:

              1. Make the users specify explicitly in their options page or in the readme.txt file that the shortcodes are not portable. You take your pick where you want them to specify this.
              2. Or make a modification to the core to show that a theme is defining shortcodes in the Appearance → Themes page. I am willing to write a patch if if this has takers, because that way it will not matter where a user has got a theme – the message will give the user fair warning even if the theme author hasn’t put it in.

              I’m not sure how much more explicit we can be with respect to shortcodes.

              Sorry, but this is not at explicit from any point of view:

              Themes must not bundle custom post-content shortcodes

              It makes no effort to define what a post-content shortcode is and to say that it leaves itself open to misinterpretation is an understatement. To me something like entry-title is a post-content shortcode, simply because it is defined in the context of a post. But you interpret this differently. I have multiple shortcodes of this sort, which if I went with my definition, I would have to pull from the theme, but based on your description they are fine because most of them don’t need to be executed in a post’s content.

              You could consider appending your own text from the above to the messaging:

              If the Theme instructs or implies to users that bundled shortcodes are to be used in the post content, they are not allowed. If the shortcodes are intended to be used for other purposes (extending the Theme via hooks, or for user-configuration of template elements, etc., then they are allowed.

            • Chip Bennett 2:31 am on November 28, 2012 Permalink

              You could consider appending your own text from the above to the messaging

              Oh, I certainly will.

              In case it hasn’t been apparent, I do try to go back to the OP and update the list based on the outcome of discussion in the comments. But, I try to wait until some consensus becomes clear, or until all questions have been answered regarding clarity/intent/etc. (For example, I think it would be more clear to refer to $post->post_content or the_content() rather than “post-content”, to indicate the shortcodes to which the guideline will apply.) I just want to make sure everything is clear before I edit the OP.

      • shawn 3:50 pm on November 28, 2012 Permalink | Log in to Reply

        Perhaps it would be helpful to shift your paradigm from functionality to content. Properly designed Themes will support most functionality out-of-the-box.

        Asked a different way: what functionality do you think Themes should be defining?

        I think we should all shift our paradigm not to content but its content usability and consumption, realizing that themes are more that just a presentation layer but the UI, disseminating and distributing content.

        The role of the theme while understated by its definition in the rule is very important to not only the success of the application but the site it powers. Themes should therefore be able define all “non out of the box” functionality or at least have a role in saying how it affects functionality of the theme.

        No. That is precisely the purpose of a Theme. WordPress is designed such that the Theme is the content presentation abstraction layer.

        That maybe so, but the design and implementation of the layer is functional and requires functionality. What abstraction does is hide that functionality from the end user, attempt to remove then the applications becomes static, useless.

        The problem I am having is that WordPress has now officially separated presentation from functionality, so the installation of a WP blog / site is becoming more and more windows-esque Drivers (plugins) Required, taking 100 year (computer years) step backwards.

        Look I get the problem mixing design and code is bad, but lets fix it the standard way by encouraging devs to separate design from data and code and not by penalizing theme dev/designers for their innovation!

        • Chip Bennett 4:21 pm on November 28, 2012 Permalink | Log in to Reply

          Shawn, that is a discussion, and a paradigm shift, that is far outside the scope of this periodic guidelines review process. Such a shift would fundamentally alter the underlying principles of the guidelines, and not something that we’re going to consider as part of this exercise.

          If you do feel passionately enough about it, though, I would recommend starting a discussion on the Theme-Reviewers mail-list, where the discussion can be given a more full and proper treatment.

          • shawn 5:20 pm on November 28, 2012 Permalink | Log in to Reply

            I not sure I understand why, if a guideline is fundamentally flawed it should be automatically reviewed or at least redefined.

            You simply cannot separate presentation from functionality, it would be like trying to create a graph without the data.

          • Chip Bennett 5:27 pm on November 28, 2012 Permalink | Log in to Reply

            I disagree that the presentation-vs-functionality guideline is “fundamentally flawed”. Again: if you do feel passionately about the matter, please start a discussion on the Theme-Reviewers mail-list, and we can discuss it at length, with all interested parties.

            • shawn 5:48 pm on November 28, 2012 Permalink

              I will seriously consider putting aside some time for it!

              Thanks for your time and patience Chip.

      • wpweaver 6:51 am on December 1, 2012 Permalink | Log in to Reply

        I missed the start of this discussion, but I do have a few thoughts on this. My theme, Weaver II, does indeed include a quite a few shortcodes, and certainly some of them could be unbundled and put into a plugin.

        But at least two of them, and they are both heavily used by my theme’s users, really would not work outside the context of the theme’s support framework. One is almost an integral part of how users can present content – a show post shortcode. The main reason it can’t go outside of the theme is that it relies on theme settings and display functions to format posts – picking up all the theme local layouts, how to display post information, etc. It truly is integrated with theme design. One could remove it to a plugin, but that plugin would only work when integrated to the theme.

        The other is a shortcode to conditionally display content depending on the if the view is mobile. While my theme is fully responsive, it also can dispay things differently depending on the user agent – so it is really more than responsive. How does one separate the plugin from the mobile display model of the theme? Even if using just the responsive parts, there are still theme settings to determine when various display items switch.

        And as been mentioned before, updating an existing theme that had been forced to eliminate included shortcodes, would mean that literally tens of thousands of sites would instantly be broken upon update.

        I do appreciate the goal of switching theme and having things still work. But my theme does things that no other themes can do, and part of the capability is to provide an integrated environment for the site developer.

        So – I think there needs to be some kind of grandfathering of existing themes. It just would not be reasonable for thousands of existing sites to break just to enforce a rule.

        One possible aid to solving the theme switch problem would be to require themes with built-in content side shortcodes to provide some kind of plugin that provided near-equivalent functionality upon theme switch. This might be difficult in some cases (e.g., my post shortcode or conditional display on mobile devices), but I suppose one could come close. I’ve even had this on my development list to help my own users who might want to switch.

        And not to shoot myself in the foot, but what about Page Templates? My experience is that switching themes that don’t have similar page templates is actually harder than some shortcodes.

        But at the heart of it, I still believe that there is room in the free repository for higher level themes that represent more of a complete environment that includes tightly integrated widgets, page templates, and shortcodes. Not every user is ready to develop their own child-theme, or spend hours hunting through plugins to find the functionality that fits just right with some theme – if they can add their own CSS rules to make the plugin’s styling consistent with the rest of the theme.

        • Chip Bennett 11:58 pm on December 1, 2012 Permalink | Log in to Reply

          Given that Weaver already has an associated Plugin, I don’t see any reason that the bundled shortcodes can’t easily be shunted off to that Plugin. In any case, there are other ways to implement a “show_posts” shortcode (which is really just a wrapper for a custom WP_Query() call) in a custom page template) than having users put the shortcode in $post->post_content.

    • Philip Arthur Moore 12:09 am on November 27, 2012 Permalink | Log in to Reply

      Change Theme Screenshot (screenshot.png) maximum dimensions from 300x225px to 600x480px.

      Should this read 600x450px?

    • Vicky Arulsingam 12:59 am on November 27, 2012 Permalink | Log in to Reply

      Shouldn’t custom post types fall under the “presentation-vs-functionality” rule?

      In terms of exceptions, if the theme author provides a plugin for shortcode/custom post type functionality, is that acceptable?

      • Chip Bennett 2:25 am on November 27, 2012 Permalink | Log in to Reply

        CPTs are a separate discussion, and are already handled by the “special use-case” Theme exception.

        If shortcodes can be placed in a Plugin, and the user directed to install the Plugin if/when he switches away from the Theme, then why not short-circuit the Theme altogether, and just release the shortcodes in Plugin form to begin with?

        Asked another way: what is the compelling reason for a Theme to bundle post-content shortcodes?

    • Sayontan Sinha 1:22 am on November 27, 2012 Permalink | Log in to Reply

      +1 for accepting themes that offer bundled shortcodes/CPTs as plugins.

      • Chip Bennett 2:23 am on November 27, 2012 Permalink | Log in to Reply

        CPTs are a separate discussion, and already handled by the “special use-case” Theme exception.

        I see no reason for any Theme ever to bundle post-content shortcodes.

    • Danielx64 4:02 am on January 24, 2013 Permalink | Log in to Reply

      Can we please add remove “wp_enqueue_script( ‘comment-reply’ )” to the list and make it recommended? One reason is that some people (like me) wants to add a quote button and therefore they don’t need to use the above function.

  • Jen Mylo 5:10 am on February 16, 2012 Permalink | Log in to leave a Comment
    Tags: checklist, description   

    Every time I browse new, featured, or recently updated themes in the dashboard, I cringe because there are always instances of WordPress, wordpress, and Word press in the descriptions of the themes provided by the authors. In the absence of capital_p_dangit, could you guys add it to the checklist to do a quick proofreading of the description in style.css to make sure they spell WordPress correctly? It will help prevent my crow’s feet from getting worse. :) Thanks!

     
    • Nitin Reddy 5:27 am on February 16, 2012 Permalink | Log in to Reply

      Perhaps I should write a plugin that auto-corrects the casing of “WordPress” in the descriptions, assuming there’s a hook for it, if course :-)

    • Emil Uzelac 5:46 am on February 16, 2012 Permalink | Log in to Reply

      @Nitin Autocorrect will not work in style.css, nothing will unfortunately. This is something we need to do manually and it can be a requirement. http://codex.wordpress.org/Function_Reference/capital_P_dangit.

      As one of the admins/reviewers I think that this is very important, therefore it’s added in Theme Review as well: http://codex.wordpress.org/Theme_Review#Capitol_.22P.22_in_WordPress_.28capital_p_dangit.29

      If anyone else have better wording, feel free to change it. But that should be all right for now.

      Cheers,
      Emil

    • Edward Caissie 1:42 pm on February 16, 2012 Permalink | Log in to Reply

      There may be more significant consistency issues to address in the Theme Review process, but having WordPress spelled correctly is a rather straight forward request to be followed through with.

      Although I must admit I may not necessarily “not-approve” a theme for inclusion into the Extend repository if the only issue was misspelling WordPress in the theme description but it would be a required correction to be made in future releases of the theme.

      PS: @emiluzelac I did adjust the text and title of the new guideline you added … http://codex.wordpress.org/Theme_Review#Capital_.22P.22_in_WordPress_.28capital_p_dangit.29

    • Chip Bennett 2:41 pm on February 16, 2012 Permalink | Log in to Reply

      IMHO this is completely a bikeshed issue, and I think that the reviewers have far more important matters to worry about. If it must be a consideration, then put it in Theme Check, and make it a blocker in the upload script, so that the reviewers don’t have to bother with it.

      • Jane Wells 6:27 pm on February 16, 2012 Permalink | Log in to Reply

        Yes and no. It’s not a functional issue in terms of theme quality, but is in an issue in terms of trademark and quality control for wordpress.org. A code-based solution would be ideal and I can ask @otto42 if he can come up with something, but in the meantime, taking 2 seconds to look at that paragraph in the style.css file and shooting an email a la “Hey, you may not have realized, but you misspelled WordPress in your theme description. Could you please update it so that it is always spelled ‘WordPress’ in your description? Thanks!”

        It’s not really something to occasion worry, but it is a quality control issue.

        • Emil Uzelac 7:31 pm on February 16, 2012 Permalink | Log in to Reply

          If we do this let’s say, e-mailing the author’s and ask them to modify capital_p_dangit, will you be giving us @wordpress.org e-mail addresses, at least for admins? The reason why is simple, people don’t even respond when we e-mail them from our own addresses. I don’t blame them, I wouldn’t even bother responding to an e-mail address that doesn’t comes from WordPress itself because it’s looks and sounds like either SPAM or some type of phishing.

        • Edward Caissie 7:34 pm on February 16, 2012 Permalink | Log in to Reply

          If @otto42 is going to be tasked with finding a “code-based solution” to this issue, I would also suggest someone is tasked with finding a “code-based solution” to scraping the repository theme descriptions etc. and sending out a bulk email requesting theme authors make these “required” corrections.

        • Chip Bennett 7:49 pm on February 16, 2012 Permalink | Log in to Reply

          Wait: why would we need to send emails when we can just post a comment in the review ticket?

          If you’re referring to a retrospective review of descriptions of currently approved Themes: not going to happen. Especially considering that we still cannot clear the current review queue, such effort would be alarmingly counter-productive.

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel