How Should a <!Doctype> Section Look in Jsf? HTML5 or Xhtml

How should a <!DOCTYPE> section look in JSF? HTML5 or XHTML?

That's the HTML5 doctype and it should work just fine in all browsers, including IE6.

JSF is officially specified to produce XHTML 1.0 compliant markup (with here and there only a few violations in the implementations which is fixed in JSF 2.2 and/or are manageable by context params). JSF can by design not produce non-XML sytnax (e.g. <br> instead of <br/>) and therefore the old HTML4 doctype is in no way compatible with JSF-produced HTML output (that is, when you respect the standards and/or fear the W3 validator; however, most if not all browsers are very forgiving on it). In contrary to the old HTML4 doctype, the HTML5 doctype allows XML syntax and is therefore compatible with XHTML doctypes. JSF pages can therefore be authored with HTML5 doctype.

The doctype is only of importance for how the webbrowser interprets and presents the HTML markup (as produced by JSF in your specific case, but the HTML does not necessarily need to be produced by JSF and thus browser's presentation is technically completely unrelated to JSF). Escpecially Microsoft IE has a major problem with certain doctypes or a complete lack of doctype. At the bottom of this page you can find a concise overview of browser behaviour in combination with certain doctypes. There are three standard behaviours:

Q - Quirksmode. You really don't want to have that. It triggers box model bug in IE. The CSS width and height then incorrectly covers the padding and border.
A - Almost standards mode. Affordable, only vertical sizing of table cells is not as per CSS2 spec. Useful if you want to avoid mysterious gaps of images in table cells.
S - Standards mode. Browser tries to be fully w3 HTML/CSS standard compliant. Preferred mode since it's the only mode you can be less or more certain that your website will look exactly the same in all browsers.

In your particular case, with the change from XHTML 1.0 transitional doctype to HTML5 doctype, Firefox, Chrome, Safari and IE>=8 will go from "A" to "S". So, you should definitely review the browser's presentation of your website as to padding of images in table cells if you intend a pixel-perfect design.

As to the importance of the doctype in IE, here's a piece of HTML which demonstrates the box model bug triggered by "Q" in IE6-9 (note that this does not manifest in IE10 anymore):

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Remove DOCTYPE to trigger quirksmode</title>
        <style>
            #box { 
                background: yellow; 
                width: 100px;
                padding: 20px; 
                border: 20px solid black; 
                margin: 20px;
            }
        </style>
    </head>
    <body>
        <div id="box">box</div>
    </body>
</html>

Copy'n'paste'n'run it. With <!DOCTYPE html> present, you'll see a rectangle. Without the doctype line you'll see a genuine square (in IE10 you need in the webdeveloper toolset (press F12) to change the "Browser mode" to e.g. IE9 in order to see it).

Sample Image

What's the difference between these two HTML DOCTYPE declarations?

A document type declaration (DOCTYPE) tells the browser – or any other tool processing your document – which version of HTML or XHTML your document is using.

There are many DOCTYPEs, because there are many versions of HTML/XHTML (e.g. HTML 4.01 (Transitional), HTML 4.01 (Strict), XHTML 1.0 (Strict), etc. However, as of HTML5, the only DOCTYPE you need to know and use is <!DOCTYPE html>.

The bottom line is you want to trigger standards mode (as opposed to quirks mode) in your browser when processing the document. Among your two options, just use #1, it's shorter and easier to remember.

JavaServer Faces 2.2 and HTML5 support, why is XHTML still being used

It seems that you misunderstood the purpose of XHTML like as many people during the XHTML overhype a couple of years ago. Long story short: check our XHTML wiki page. Carefully read it. In a nutshell, Facelets absolutely doesn't care about the doctype being used in the generated HTML output. You can perfectly fine declare a HTML5 doctype in a Facelets template.

It's indeed unfortunate that Netbeans by default prepares the document with XHTML doctype while HTML5 is these days the recommended doctype. I don't do Netbeans, but in Eclipse you can easily edit those templates and even create your own. You can just replace the whole XHTML doctype by a HTML5 one. You can find/create those templates via Web » HTML Files » Editor » Templates in IDE prefs.

Please note that the HTML5 support in JSF 2.2 has got nothing to do with being able to support specifically the HTML5 doctype. On the contrary, this is supported on all JSF versions, even when legacy JSP is being used. JSP and Facelets are view technologies which allows you to generate HTML output, which can perfectly fine be HTML5 as good. This is also elaborated in the following closely related answer: Is it possible to use JSF+Facelets with HTML 4/5?

Instead, the HTML5 support in JSF 2.2 covers the possibility to define custom JSF component attributes and turning custom HTML elements into JSF components. This was not possible in JSF 2.1 and before. Any custom JSF component attributes (including the HTML5-recommended data-xxx attributes) were simply ignored by the default JSF renderers. See also the following related answer: Custom HTML tag attributes are not rendered by JSF. In JSF 2.2 you can easily specify custom attributes by the new http://xmlns.jcp.org/jsf/passthrough namespace as follows:

<html ... xmlns:a="http://xmlns.jcp.org/jsf/passthrough">
...
<h:inputText ... a:autocorrect="off" />

This will end up in the by <h:inputText> unsupported attribute autocorrect to actually be included in the generated HTML output. Note that I use a XML namespace prefix of a ("attribute") instead of p as shown in the Java EE tutorial, as it would otherwise clash with default XML namespace prefix p of PrimeFaces.

Turning custom HTML elements (including HTML5 elements) into JSF components is a matter of specifying a jsf attribute such as jsf:id.

<html ... xmlns:jsf="http://xmlns.jcp.org/jsf">
...
<header jsf:id="header">...</header>
<main jsf:id="main">...</main>
<footer jsf:id="footer">...</footer>

Those will under the covers be turned into UIPanel (like as <h:panelGroup>). And yes, they are referencable in e.g. <f:ajax render>.

In other words, "HTML5 support" is just again another buzzword for "Custom attribute support".

How to include another XHTML in XHTML using JSF 2.0 Facelets?

`<ui:include>`

Most basic way is <ui:include>. The included content must be placed inside <ui:composition>.

Kickoff example of the master page /page.xhtml:

<!DOCTYPE html>
<html lang="en"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://xmlns.jcp.org/jsf/core"
    xmlns:h="http://xmlns.jcp.org/jsf/html"
    xmlns:ui="http://xmlns.jcp.org/jsf/facelets">
    <h:head>
        <title>Include demo</title>
    </h:head>
    <h:body>
        <h1>Master page</h1>
        <p>Master page blah blah lorem ipsum</p>
        <ui:include src="/WEB-INF/include.xhtml" />
    </h:body>
</html>

The include page /WEB-INF/include.xhtml (yes, this is the file in its entirety, any tags outside <ui:composition> are unnecessary as they are ignored by Facelets anyway):

<ui:composition 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://xmlns.jcp.org/jsf/core"
    xmlns:h="http://xmlns.jcp.org/jsf/html"
    xmlns:ui="http://xmlns.jcp.org/jsf/facelets">
    <h2>Include page</h2>
    <p>Include page blah blah lorem ipsum</p>
</ui:composition>

This needs to be opened by /page.xhtml. Do note that you don't need to repeat <html>, <h:head> and <h:body> inside the include file as that would otherwise result in invalid HTML.

You can use a dynamic EL expression in <ui:include src>. See also How to ajax-refresh dynamic include content by navigation menu? (JSF SPA).

`<ui:define>`/`<ui:insert>`

A more advanced way of including is templating. This includes basically the other way round. The master template page should use <ui:insert> to declare places to insert defined template content. The template client page which is using the master template page should use <ui:define> to define the template content which is to be inserted.

Master template page /WEB-INF/template.xhtml (as a design hint: the header, menu and footer can in turn even be <ui:include> files):

<!DOCTYPE html>
<html lang="en"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://xmlns.jcp.org/jsf/core"
    xmlns:h="http://xmlns.jcp.org/jsf/html"
    xmlns:ui="http://xmlns.jcp.org/jsf/facelets">
    <h:head>
        <title><ui:insert name="title">Default title</ui:insert></title>
    </h:head>
    <h:body>
        <div id="header">Header</div>
        <div id="menu">Menu</div>
        <div id="content"><ui:insert name="content">Default content</ui:insert></div>
        <div id="footer">Footer</div>
    </h:body>
</html>

Template client page /page.xhtml (note the template attribute; also here, this is the file in its entirety):

<ui:composition template="/WEB-INF/template.xhtml"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://xmlns.jcp.org/jsf/core"
    xmlns:h="http://xmlns.jcp.org/jsf/html"
    xmlns:ui="http://xmlns.jcp.org/jsf/facelets">

    <ui:define name="title">
        New page title here
    </ui:define>

    <ui:define name="content">
        <h1>New content here</h1>
        <p>Blah blah</p>
    </ui:define>
</ui:composition>

This needs to be opened by /page.xhtml. If there is no <ui:define>, then the default content inside <ui:insert> will be displayed instead, if any.

`<ui:param>`

You can pass parameters to <ui:include> or <ui:composition template> by <ui:param>.

<ui:include ...>
    <ui:param name="foo" value="#{bean.foo}" />
</ui:include>

<ui:composition template="...">
    <ui:param name="foo" value="#{bean.foo}" />
    ...
</ui:composition >

Inside the include/template file, it'll be available as #{foo}. In case you need to pass "many" parameters to <ui:include>, then you'd better consider registering the include file as a tagfile, so that you can ultimately use it like so <my:tagname foo="#{bean.foo}">. See also When to use <ui:include>, tag files, composite components and/or custom components?

You can even pass whole beans, methods and parameters via <ui:param>. See also JSF 2: how to pass an action including an argument to be invoked to a Facelets sub view (using ui:include and ui:param)?

Design hints

The files which aren't supposed to be publicly accessible by just entering/guessing its URL, need to be placed in /WEB-INF folder, like as the include file and the template file in above example. See also Which XHTML files do I need to put in /WEB-INF and which not?

There doesn't need to be any markup (HTML code) outside <ui:composition> and <ui:define>. You can put any, but they will be ignored by Facelets. Putting markup in there is only useful for web designers. See also Is there a way to run a JSF page without building the whole project?

The HTML5 doctype is the recommended doctype these days, "in spite of" that it's a XHTML file. You should see XHTML as a language which allows you to produce HTML output using a XML based tool. See also Is it possible to use JSF+Facelets with HTML 4/5? and JavaServer Faces 2.2 and HTML5 support, why is XHTML still being used.

CSS/JS/image files can be included as dynamically relocatable/localized/versioned resources. See also How to reference CSS / JS / image resource in Facelets template?

You can put Facelets files in a reusable JAR file. See also Structure for multiple JSF projects with shared code.

For real world examples of advanced Facelets templating, check the src/main/webapp folder of Java EE Kickoff App source code and OmniFaces showcase site source code.

Is it possible to use JSF+Facelets with HTML 4/5?

Since Facelets is a XML based view technology which eats and emits in essence XML markup, you cannot use it with a HTML4 doctype. The HTML4 doctype describes several elements which cannot be self-closing, like <link>, <meta>, <br> and <hr>. However, with XML you're forced to close them like <link/>, <meta/>, etc. So using a HTML4 doctype is absolutely not an option for Facelets (that is, when you respect the standards and/or fear the w3 validator, it will however work perfectly on the most if not all webbrowsers).

HTML5, on the other hand, allows XML markup. This is specified in chapter 3.2.2 - Elements:

Example:
<link type="text/css" href="style.css"/>
Authors may optionally choose to use this same syntax for void elements in the HTML syntax as well. Some authors also choose to include whitespace before the slash, however this is not necessary. (Using whitespace in that fashion is a convention inherited from the compatibility guidelines in XHTML 1.0, Appendix C.)

I myself use <!DOCTYPE html> all the way, also with JSF/Facelets, even without a <?xml?> declaration in top of the page. It works perfectly in all browsers. With a XHTML doctype you should as per the specification be using a Content-Type of application/xhtml+xml which would only make MSIE to choke (it doesn't understand it). And since that's still one of the most widely used browsers... Replacing the XHTML content type by text/html is considered harmful, you also don't want to do this.

As per your arguments:

HTML 5 do not support namespaces.

This doesn't matter. The namespaces are only of interest for the XML based server side view technology (like as Facelets) which in turn can generate pure HTML with those tags. The following example is legitimately valid for Facelets:

<!DOCTYPE html>
<html lang="en"
    xmlns:f="http://xmlns.jcp.org/jsf/core" 
    xmlns:h="http://xmlns.jcp.org/jsf/html">
    <h:head>
        <title>Title</title>
    </h:head>
    <h:body>
        <h:outputText value="#{bean.text}" />
    </h:body>
</html>

This renders legitimately valid HTML5 (for the client side):

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Title</title>
    </head>
    <body>
        Some text
    </body>
</html>

You see, Facelets already removes the XHTML declarations since they have no meaning in the client side.

And,

Also HTML 5 has some new elements that are not available in XHTML

this make also no sense. It's all about the generated output. Which can be HTML5 as good. Your only problem may be the browser support and the availability of 3rd party JSF components which renders HTML5 specific elements. Since JSF 2.2, it's possible to use the new passthrough elements feature to turn custom elements into a JSF component. Simply give the HTML5 element a jsf:id attribute. It'll transparently internally be interpreted as a UIPanel instance in the JSF component tree (like <h:panelGroup>).

<!DOCTYPE html>
<html lang="en"
    xmlns:jsf="http://xmlns.jcp.org/jsf"
    xmlns:f="http://xmlns.jcp.org/jsf/core" 
    xmlns:h="http://xmlns.jcp.org/jsf/html"
>
    <h:head>
        <title>Title</title>
    </h:head>
    <h:body>
        <header jsf:id="header">Header</header>
        <nav jsf:id="nav">Nav</nav>
        <main jsf:id="main">Main</main>
        <footer jsf:id="footer">Footer</footer>
    </h:body>
</html>

You can even reference it from ajax as in <f:ajax render="main">.

Actually, XHTML is overhyped. Its sole intent is to ease HTML development using XML based tools which can manipulate/transform/generate HTML pages on the server side (like as Facelets). But some starters also use it without using any XML tool and output it plain as-is, because it's "so cool" -for some unclear reason.

Don't get me wrong. XHTML is great as server side view technology. But simply not as client side markup technology. It has utterly no value at the client side.

Css styles not applied properly,if use DOCTYPE

The problem is that the div is set to 100% of 100% (the body) this makes sence to us but not to the browser. If you set the body position to absolute and set it's top, bottom, left, right to 0, you get the same effect and the div's height setting will work the way you expect. Here's the code.

<!DOCTYPE html>

<html> 
<head>
<title>Test</title>
</head>
<body style="position:absolute;top:0px;left:0px;right:0px;bottom:0px;background-color:green;">
<div>My Test page</div>
<div style="background-color:red;height:100%;width:10%;"></div>
</body>
</html>

Should I start with HTML or XHTML?

XHTML is pretty much like HTML but non-sloppy. I really can't think of a reason besides laziness not to use it.

How Should a <!Doctype> Section Look in Jsf? HTML5 or Xhtml