Datepicker – dynamically sized container is too narrow

This was my view of a Gravity Forms datepicker, but the problem of the pop-up container being too narrow may affect other instances of the jQuery UI Datepicker too.

Gravity Forms 1.6.5 still uses it’s own jQuery UI 1.6 files, instead of the UI 1.8+ files now included with WordPress core. The width of the container is added as an inline style by the core jQuery UI Datepicker 1.6 code:

Even without knowing what any of the variables are, it’s clear that the width is taken as the product of the number of months shown (usually one, but can be two) and the width of the .ui-datepicker, which is the table of dates inside the container.

Since Gravity Forms was providing the styles for all aspects of the pop-up, including the top dropdowns and table cell appearance, it was sensible to assume that its CSS was fine on it’s own.

Box-sizing

I’d recently added the code from Paul Irish’s box-sizing article, so that all elements would use the border-box layout system.

The solution then, was to revert just the problem element back to using content-box:

With this put into a theme’s style.css file, the container has the same width value applied around its content, padding and border, instead of just its content.

Datepicker – formatting fixed.

Simple enough, but hopefully this post can save someone a little time.

1. Don’t include a @return tag.
2. Include a @return tag with a type of void.

I’m not saying that either is wrong, but the second-one is most definitely as far from correct as you can get.

Let’s look at the reasons.

Logic and Standards

The @return tag documentation for phpDocumentor, the de facto standard for PHP documentation says:

The @return tag is used to document the return value of functions or methods.

In our scenario, there is no explicit return value, so there shouldn’t be a @return tag, just the same as you wouldn’t include a @param tag when there are no arguments, or a @global tag when there’s no global variable being used.

The Wikipedia page for PHPDoc states that the @return tag should not be used for a void / no return value.

Furthermore, the source code examples 2 and 3 on the phpdoc.org website clearly omit the @return tag when there is no return keyword.

The draft PHPDoc PSR, a document which hopes to become the de jure standard, says it is optional, but this is only so that it stays somewhat compatible with the existing (poor) real world practises.

Void !== Null

The PHP Manual clearly states that:

If the return() is omitted the value NULL will be returned.

Null and void are not the same, so by including @return void you’re actually giving wrong documentation, which is worse than no documentation.

Void is not a data type

The phpDocumentor documentation goes on to say:

The datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object returned, or simply “mixed”.

As noted in the PHP manual, void is not a valid PHP type. At best, it’s a pseudo-type, and only used to describe PHP functions for the purposes of documenting the C code that PHP is actually written in. It’s not suitable for documenting PHP code.

Code Dilution

There’s little benefit having a tag that says that nothing is returned, when you can save a line of comment code and assume that the return keyword is not present when the @return tag is not present.

IDEs

An IDE such as Netbeans, Zend Studio, Eclipse, PHPStorm can often generate the basic documentation when a shortcut like /** followed by the Enter key is typed right above an entity that can have documentation. The default behaviour is that these only include the @return tag in the documentation when the return keyword is present.

When doing a Genesis child theme audit for a client recently, I came across the following CSS ruleset:

The standard adopted for CSS at StudioPress is simply to have all properties in alphabetical order – no exceptions. It’s slightly different from the WordPress Coding Standards for CSS, but it’s also far easier to remember and not so ambiguous. From that, I’d previously suggested to this and other clients that vendor prefixed properties should also be alphabetical, and therefore separated from the standard properties, by being at the top.

This does make it trickier to read and as such, it isn’t easy to spot the missing space on that webkit prefixed property value. Go on, admit it, you didn’t spot it either

I recently read a short post from someone (I’m really sorry, I didn’t take note of who it was) that said that they prefer to line up the colon on vendor-prefixed and standard properties, which makes it easier to read. They would have lined up the following (still otherwise keeping rules in alphabetical order) like so (with the missing space added back in):

That is much easier to read, easier to visually scan that it’s consistent across the property variations, and allows text editors that can edit vertically to amend all of the values consistently in one go.

Another variation, and now my currently preferred format, is to line-up the start of the values:

This means that only tabs (or a consistent number of spaces) are used at the start of the line, and extra spaces are added into the middle of the line; this is fine, since some particularly long values may be wrapped onto new lines anyway (exact details of which are outside the scope of this discussion).

Why not give this alignment a go, and tell me how you get on?

Persistent, Preferred and Alternate Style Sheets

Back at the end of 1999, the HTML4 spec defined persistent, preferred and alternate style sheets, and several of the browsers at the time implemented a user interface for users to access these as they wanted.

Several better concepts came along, such as sites doing on-site front-end or back-end style switchers, which solved some of the issues such as persistence on page reloads, supporting browsers which didn’t yet support a user interface, and avoiding downloading multiple style sheets that a user may never actually select.

Persistent style sheets are always loaded by the browser, and the link element does not have a title attribute. The Preferred (default) alternate style sheet has a title attribute, and the other alternate style sheets also have alternate as one of the rel attribute values.

However, the technique is still valid today, and can be implemented when enqueueing style sheets in WordPress. Here’s how you might add a couple of alternative style sheets (with one marked as the default alternative, or preferred) for instance:

On Firefox for instance, a user can pick between these style sheets via the View -> Page Styles menu item:

Selecting between preferred and alternate style sheets in Firefox

Internet Explorer Style Sheets

Another extra is the ability to set a conditional comment, as used for adding IE-specific style sheets. Previously it had to be done by enqueueing the style sheet for all browsers, and then filtering the style_loader_tag for that handle and adding the conditional comments in around it. Now we can just do:

This has the advantage of being significantly less code, and the actual condition could come from a variable or be filterable.

Other Extras

WordPress also appears to support other extras, such as rtl which would allow you to mark an enqueued style sheet as only being referenced if the site was set to use a right-to-left language (the best practice is to create a style sheet called rtl.css which does this automatically). Other extras include suffix and after although these are used more by WordPress internally for setting the reference to a minified / non-minified file, and for setting internal style sheet data to appear after a specific external style sheet reference via wp_add_inline_style().

Since the name of the extra key is not fixed, you could add some of your own arbitrary meta data to associate with an enqueued style sheet (remember to prefix the key so you avoid any potential clashes with WordPress-supported keys in the future).

Here we look at how to allow access for, and get a key for, the Google Web Fonts API.

1. Head to the Google APIs Console. If you’re not already logged in to Google, you’ll need to do that when requested.
2. On the left menu, select the Services item. If the Terms of Service appear, read and accept them.
   

   The Services item in the left menu of the Google APIs Console

3. You should be presented with a list of services provided by Google. Scroll to the bottom and click the button next to the Web Fonts item, so it turns from off to on.
   

   Web Fonts API access button in the Google APIs Console

4. On the left menu, select the API Access item. The API key is near the bottom of that pane, in the section titled “Simple API Access.”
   

   Simple API Access pane in Google APIs Console

You can now enter your personal API key in whichever tool or URL needed it. For example, enter it at the end of https://www.googleapis.com/webfonts/v1/webfonts?key= and you’ll see a full list of web fonts provided by Google.

Jenkins, powered by my Phing build file

On my computer I have Jenkins installed for viewing analysis of code, and as I code with PHP and not Java, I use Phing instead of Ant as the build system. I run several PHP programs against the code I’ve written or auditing, and automate the creation of API documentation using DocBlox, as well as send that documentation via FTP to a docs subdomain.

I’ve refined my build file over time, but it has always been pretty much an identical file duplicated over many projects, and this wasn’t scaling well as I found the need to refine it further. Instead, I discovered the ImportTask in Phing, which meant I could have one generic build file kept outside of my project folders, and import that into each bare bones project build file and amend as necessary.

Here’s my generic build file code (obviously you may have a different set of targets and procedures you want to undertake like unit testing, deploying to git or svn, etc.):

And then each project build file is simply:

If I want to create a tweaked target for a particular project, then I can simply add that to the project build file (as per the commented-out section), and it takes precedence over the generic target of the same name. An example of this is the following, which adds a custom target when parsing the coding standards for the WordPress project, so it can exclude all of the 3^rd party libraries that won’t be expected to follow the coding standards:

That default build file pulls in both a global default properties file, and a per-project properties file too, with the properties in the latter taking precedence. Here’s an example of my global default properties file:

Which leaves a typical per-project properties file down to the bare basics:

That previous post had some shortcomings, especially concerning the number of grid posts and the number of posts as set in Settings -> Reading. If they didn’t match, then WordPress would declare one or more pages at the end of the pagination for those query of posts as being a 404 Not Found. We needed a better solution, and between legendary Genesis developer Bill Erickson and myself, we’ve come up with one.

The Code

Here’s some starting code that you can customise. More explanation is given below the code.

Woah! That’s a ton more code, but it is a more stable solution as a base from which you can customise the how the grid loop works for you. Here’s the breakdown.

Explanation of The Code

child_is_doing_grid_loop()

This first function simply returns true or false. You can use the conditional tags to choose under which situations you want the grid loop to kick in. By default, we want it when it is not a single post (including custom post types), not a single page and not a single attachment. Luckily WordPress has a tag to cover all three of those at once. Every other time we want to use the grid loop.

child_grid_loop_arguments()

The second function is where you’ll want to fine tune how the grid appears. Most of the array values should be intuitively named. If you want to limit a template to show a particular query (i.e., posts from the same category), then you’d amend the $query_args here.

child_prepare_grid_loop()

You shouldn’t really need to touch much in this function. This basically says to swap out the default function for our grid loop function and also amend the post class so we can add some styling later.

child_grid_query()

This amends what the query would have been for this page, with our grid loop and query arguments. After checking that this is the main loop, that we are indeed supposed to be showing the grid loop, and we’re on the front end, then it grabs a copy of our arguments. To allow for featured posts on the first page, and to keep the balance right on pages after the first page, some logic is done, which you probably won’t need to edit. The result of this logic is then set on the main query.

child_do_grid_loop()

This function gets our grid loop arguments, the query arguments (as potentially amended by the logic in the previous function), and merges them together before sending them all off to Genesis, which does the actual database query, and starts echoing the markup and content for this grid posts.

child_grid_loop_post_class()

The previous version of this tutorial also included some styles to paste into your style.css file, to ensure that the grid posts appeared in the correct columns. We now do a bit more work here, and make use of the column classes that have been included with Genesis child themes since Genesis 1.5 was released. If you find the grid isn’t appearing correctly, copy the Column Classes section of the Genesis style sheet into your own theme style sheet.

Sticky Posts

If you amend the query arguments for a grid on the blog archive page to only include posts from a certain category, tag or taxonomy, and find that sticky posts stop working, add the following code to fix it:

A Better and Easier Grid Loop

It should be noted that the grid loop code above is for when you want to create a second loop on the page, or make use of some custom query loop that won’t produce the same posts as what would naturally have appeared there anyway.

If you do just want to style the existing posts, then take a look at a new tutorial from Bill Erickson, as he explains about a better and easier grid loop.

PHP

CSS

The Result

After trying several solutions, the following appears to have solved it for my setup, once and for all – add this to your .htaccess file:

In short, it massively bumps up the allowed memory limit, and also tries to turn off some security aspects for the file that deals with the uploading, under different module setups.

If your theme was written a while ago, your site might not be following all of the current best practices. Here are a few simple alterations you can make to your style.css file.

Theme URI

An easy one to start – in the header info, you’ll likely find a line starting with Theme URL (note the last character). This should now strictly be Theme URI.

License

In your theme, you might see some inconsistent or no license information at all. There are now a couple of specific slugs you can use, License and License URI, to show the same information in a way that WordPress can read from (example):

Tags

Tags haven’t been added to many themes at the moment, yet if you’ve got a lot of themes installed, being able to filter them to just certain features (see Appearance -> Themes -> Feature Filter, right-hand side, next to the Search button) could be useful. Many of the tags could be added by the functionality that a parent theme like Genesis provides, while some would be child theme specific. A theme that could theoretically meet every single tag would include the following:

Trailing Slash

Another easy one – if the Theme URI or Author URI values are the home page of a website, add a trailing slash to it – this typically saves an extra lookup on a server if someone clicks on the link.

Theme Name

Some themes might be named as “… Theme” or “… Child Theme”. The Theme Review guidelines recommend that the term “Theme” is not included (as everyone knows it’s a theme). Since the guidelines also suggest that the fact a theme is a child theme be mentioned in the Description, your theme could drop both terms. Switch to another theme before changing your theme name.

Template Version

Previously there was a suggestion to include a Template Version slug to child themes to indicate what version of the parent theme the child theme was built against. However, this appears to have been removed until such time that WordPress can actually use this information to notify users.

Further Information

Beyond the changes listed above, you can find more information via the theme review guidelines, by following the Theme Review Team discussions, and also by running the Theme Check plugin (the development version has a few extra fixes) on your theme. WordPress also has a set of CSS Coding Standards for the main portion of yout style sheet.