[keycloak-dev] pluggable templates

Tue Jan 7 07:53:31 EST 2014

----- Original Message -----
> From: "Bruno Oliveira" <bruno at abstractj.org>
> To: "Bill Burke" <bburke at redhat.com>, "Stian Thorgersen" <stian at redhat.com>
> Cc: keycloak-dev at lists.jboss.org
> Sent: Tuesday, 7 January, 2014 12:11:39 PM
> Subject: Re: [keycloak-dev] pluggable templates
> 
> Hi Stian, not sure if I’m following you on this, but most of the companies,
> developers, communities really want to create templates, let alone the fact
> that make it easy to create would open a new possibility to a community of
> web designers too.

Most web designers are very comfortable with CSS so if they can achieve what they want with pure CSS that'll be the simplest for them (just look at zen garden to see what can be achieve with only css if the html structure is "css-friendly"). We should obviously still support changing the HTML as well if required.

> 
> Keep in mind that most of them are not familiar with FreeMarker or deploying
> a JAR, so if possible I would stick with Bill’s suggestion. Build a CSS +
> HTML5, or customize something already existent.

Whatever template engine/syntax we choose not everyone will be familiar with it. What I proposed would allow people to build a pure HTML5 (with whatever JS framework they choose) if that's what they want to.

Deploying a JAR is more if Keycloak is "embedded" within a Java project. In that case bundling the theme as a JAR will be the best approach. But as I said we need to have other options as well.

> 
> Java developers have no clue about how to build a good web design and most of
> the web designers know nothing about Java, it seems like a chicken and egg
> situation.

Hence why I think FreeMarker templates is better than any server-side framework. Same applies for HTML5 (client-side) implementations, web designers have no clue about Java or JS. For HTML5 we can create the required REST endpoints, as well as controllers/services for AngularJS and some default HTML templates. Then users can override individual HTML templates if they need to.

Just to clarify I think that we need to have multiple levels of themes:

1. CSS and config - the simplest approach as it only requires a stylesheet, a few images, and a config file
2. Templates - when there really is a need to change the HTML structure we can support this by creating a template for a specific page. For this we need a template syntax/engine, and FreeMarker is as good as any for server-side
3. Full blown - would let people rip it all out and build their own with JSF, JSP, HTML5 or whatever web framework they want

And it should be possible to package/deploy as:

1. jar - for embedding Keycloak into another project (i.e. this is how we'd do it in LiveOak)
2. zip - uploaded through admin console or copied into some directory
3. editor in admin console - create/edit css/templates through the admin console, as well as upload images

> 
> --
> abstractj
> 
> On January 7, 2014 at 8:48:41 AM, Stian Thorgersen (stian at redhat.com) wrote:
> >  
> > The way things are at the moment is not how we want to have it in the
> > long run.
> >  
> > How it's envisioned to work is that users can create themes. A
> > theme can extend another theme and can specify:
> >  
> > * Config (logo, hide/display fields, etc)
> > * Resources (css and images)
> > * Templates (html)
> >  
> > A theme can be bundled in a JAR and should be automatically discovered
> > if it's on KC's class-path, but it should also be possible to define
> > it through the admin console. In the admin console at first we
> > could just let users upload a zip/jar with all the artefacts required,
> > but in the future we could let them edit css/templates and upload
> > resources directly through the console.
> >  
> > This would make it easy for a user to for example only modify the
> > login forms, while using the default account management. In
> > the default theme we can also make it fairly configurable through
> > config options and making it css-friendly so that most users
> > should be able to do what they want without having to create templates.
> > I would hope that at least 80% of users that want to customize the
> > forms can do so through config and css, while less than 20% would
> > have to create templates to make it do exactly what they want.
> >  
> > Providing a mechanism to do this with a web framework would require
> > users to basically build everything from scratch, which would
> > be a lot more work. Also, if you're talking about JavaEE web apps
> > that's not available in LiveOak. They would still need to understand
> > some basic Freemarker stuff as we need a template engine for emails.
> >  
> > I'm quite convinced that using a template engine is the way to
> > go, and fairly confident that Freemarker is a good choice. End
> > of the day though I think that most things in Keycloak should be
> > pluggable, so we should have a forms SPI, with the default implementation
> > based on Freemaker (and customizable themes) while it would
> > be possible for someone to implement something else by just dropping
> > in a different JAR with an implementation of the forms SPI. That
> > could use JSF, AngularJS or whatever. We could also support both
> > returning html directly from the forms SPI (template style)
> > or a redirect to a url (jsf or whatever style).
> >  
> > ----- Original Message -----
> > > From: "Bill Burke"
> > > To: keycloak-dev at lists.jboss.org
> > > Sent: Friday, 3 January, 2014 5:02:57 PM
> > > Subject: [keycloak-dev] pluggable templates
> > >
> > > Was thinking about pluggable templates for login, oauth screen,
> > user
> > > acct mgmt, etc...
> > >
> > > Why force users to use Freemarker? Why not allow them to create
> > a
> > > directory within the Keycloak Server WAR and use whatever framework
> > they
> > > want to use? Then to choose a template, you just specify the URLs
> > for
> > > login, oauth, user acct mgmt, etc?
> > >
> > > What sucks is, because we're using Freemarker and everything
> > is bundled
> > > up in JARs, there's no easy way for users to copy/paste a template
> > and
> > > create and play with their own on the fly.
> > >
> > > Just food for thought for after Alpha 1 release.
> > >
> > > --
> > > Bill Burke
> > > JBoss, a division of Red Hat
> > > http://bill.burkecentral.com
> > > _______________________________________________
> > > keycloak-dev mailing list
> > > keycloak-dev at lists.jboss.org
> > > https://lists.jboss.org/mailman/listinfo/keycloak-dev
> > >
> > _______________________________________________
> > keycloak-dev mailing list
> > keycloak-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/keycloak-dev
> >  
> 
> 