-
Notifications
You must be signed in to change notification settings - Fork 1
Editing HTML and PHP guidance
Ideally the design will be created from a content-first approach anyway but even if it isn't there is a still a benefit to building the HTML this way. In fact it's a good idea to write out the HTML before even considering the styles. That way the content is informing the structure and not the appearance.
A component is supposed to be reusable and could (in theory) exist anywhere on the site (or even other sites) so it's important that they are always written in a self-contained way. This means that the tag you use to create them must be a section tag. (You can also use header, footer, nav, aside and article but please ensure that this usage is appropriate for that component first).
Note: Some components need to be within another component as a parent, these child-components can use any tag that is appropriate but please put in the component.json which parent they belong to.
Again, as you have no idea where the component will be used on the page, it's important that you reset the document flow (which is one of the reasons you must use one of the tags listed above).
This is not acceptable
<section class="c-product-item">
<h3>Header</h3>
</section>This is acceptable
<section class="c-product-item">
<h1>Header</h1>
</section>Similar to the rule above, write your class names based on what is going in the container and not based on how it looks:
This is not acceptable
HTML
<section class="c-product-item">
<h1 class="border-bottom blue bold">Header</h1>
</section>This is acceptable
HTML
<section class="c-product-item">
<h1 class="c-product-item__title">Header</h1>
</section>CSS
.c-product-item {
&__title {
border-bottom: 1px solid $blue;
color: $blue;
font-weight: bold;
}
}Wrapping elements in a div tag isn't usually needed and should only be added where items need to be grouped together. A simple rule of thumb is that if a div tag has been added to a page and doesn't need a class, question if you even need the div in the first place.
This is not acceptable
<div class="c-product-item">
<div>
<h1> Header </h1>
</div>
</div>This is acceptable
<div class="c-product-item">
<h1> Header </h1>
</div>This is also acceptable
<div class="c-product-item">
<div class="c-grouped-items">
<h1> Header </h1>
<span> Sub-header </span>
</div>
</div>This is not acceptable
HTML
<a href="">Read more <img src="/images/arrow-right.svg"></a>This is acceptable
HTML
<a class="read-more-link" href="">Read more</a>CSS
.read-more-link {
&:after {
content: '';
width: 1rem;
height: 2rem;
margin-left: .5rem;
background-image: url(/images/arrow-right.svg);
}
}In fact if possible, don't use an image at all. If the item can be an icon font or even a text character. Use that instead (keep browser compatibility in mind though).
Again a good rule of thumb here is that if the page is still 100% understandable without the image then it's probably a UI element and should be added via CSS.
Caveat: Ensure this does not cause IE7 compatibility issues before taking this approach.
The article and section tags all contain their own internal document flow. This allows these tags to be transplanted to other places on the site (or even other sites) and still maintain the correct document order. In order to utilise this correctly always restart the header levels when using these tags. e.g. Start with a h1 instead of a h2.
This is not acceptable
<h1> Page title</h1>
<section class="c-product-item">
<h2>Product Item Title</h2>
</section>This is acceptable
<h1> Page title</h1>
<section class="c-product-item">
<h1>Product Item Title</h1>
</section>Almost everything on the site is a component, the exceptions to this are utilities, objects, layouts and non-transferrable elements within a component.
The general rules are thus:
-
If it could be reused elsewhere and it has specific content: It's a component.
-
If it can be reused elsewhere and the content is not thematically related (eg a button): it's an object.
-
If it can be reused elsewhere and isn't an element in it's own right but will modify other elements: it's a utility.
-
If it is there only to comparmentalise content within a component or page then it's a layout.
e.g.
Featured news list component
<div class="c-featured-news-list">
<?php get_component('c-article-item', 'featured_news'); ?>
<?php get_component('c-article-item', 'featured_news'); ?>
</div>Article item component
<article class="c-article-item">
<img src="https://placeimg.com/650/433/tech" alt="description of image goes here">
<h1><a href="#">This is an example title</a></h1>
<?php
// If the 'featured_news' value has been passed to $params: Display the excerpt.
if ($params === 'featured_news') { ?>
<div class="c-article-item__excerpt">
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Vero rem cumque aliquam, voluptatibus recusandae velit eos maiores molestiae illum eveniet deleniti magni delectus neque, distinctio sit error laudantium quos porro.</p>
</div>
<?php } ?>
<span class="c-article-item__dateline">11 Jan 2017</span>
<?php
// If the 'blog' value has been passed to $params: Display the byline.
if ($params === 'blog') { ?>
<span class="c-article-item__byline">Simon Quinn</span>
<?php } ?>
</article>As you can see the component above, The items inside the c-article-item component are all unique to that component and so use BEM notation to denote they are a part of it.
All components can contain an unlimited number of other components, just ensure that before you turn it into a component that it is likely to be reusable and also determine if an object would be better.
Hopefully this doesn't need to be said anymore but just in case, tables should only be used for displaying table-based data and never for layouts.
This is not acceptable
<table>
<tr>
<td>
<h1>Header</h1>
<p>This is some text</p>
<p>This is some more text</p>
<ul>
<li>This is a list item</li>
<li>This is too</li>
</ul>
</td>
<td>
<h2>Sidebar</p>
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</td>
</tr>
</table>This is acceptable
<div class="col primary">
<h1>Header</h1>
<p>This is some text</p>
<p>This is some more text</p>
<ul>
<li>This is a list item</li>
<li>This is too</li>
</ul>
</div>
<div class="col sidebar">
<h2>Sidebar</p>
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</div>This is an acceptable use of tables
<table>
<tbody>
<tr>
<th>Year</th>
<th>Movie name</th>
<th>Main Actor</th>
</tr>
<tr>
<td>2013</td>
<td>The Wolf of Wall Street</td>
<td>Leonardo DiCaprio</td>
</tr>
<tr>
<td>1994</td>
<td>The Shawshank Redemption</td>
<td>Tim Robbins</td>
</tr>
</tbody>
</table>Screen-readers and other assistive devices use page semantics to make sense of a page, so using tags like nav, header, footer etc... help. Sometimes though it's not possible to use a semantic tag. In which case a suitable ARIA role should be added:
e.g.
<form action="" class="search" aria-role="search">
<input type="text" value="Search">
<button type="submit">Search</button>
</form>An ALT attribute (also known as an ALT Tag) is a description of an image, it is there to provide context for screen readers and for users who can't/don't see images. It is not a marketing tool or an SEO tool.
If you are not sure what to write in an ALT tag, imagine how you would briefly describe the image to someone who couldn't see it.
This is not acceptable
<a href=""><img src="/images/office-building.jpg" alt="Click to view a bigger version of this image"></a>This is acceptable
<a href=""><img src="/images/office-building.jpg" alt="An external view of our head office."></a>In CSS content positioning can be altered, however without CSS content follows a normal document flow. Always bear this in mind when structuring your HTML. The page should make complete sense without CSS.
This is not acceptable
<div class="right">
<p>
Pursued by the Empire's sinister agents, Princess
Leia races home aboard her starship, custodian of
the stolen plans that can save her people and
restore freedom to the galaxy...
</p>
</div>
<div class="left">
<p>
It is a period of civil war. Rebel spaceships,
striking from a hidden base, have won their first
victory against the evil Galactic Empire.
</p>
<p>
During the battle, Rebel spies managed to steal
secret plans to the Empire's ultimate weapon, the
Death Star, an armored space station with enough
power to destroy an entire planet.
</p>
</div>This is acceptable
<div class="l-left">
<p>
It is a period of civil war. Rebel spaceships,
striking from a hidden base, have won their first
victory against the evil Galactic Empire.
</p>
<p>
During the battle, Rebel spies managed to steal
secret plans to the Empire's ultimate weapon, the
Death Star, an armored space station with enough
power to destroy an entire planet.
</p>
</div>
<div class="l-right">
<p>
Pursued by the Empire's sinister agents, Princess
Leia races home aboard her starship, custodian of
the stolen plans that can save her people and
restore freedom to the galaxy...
</p>
</div>These instructions apply to the main Intranet website system. Please visit https://github.com/ministryofjustice/intranet-base-docker to view the base system for this website.