<div dir="ltr"><div><div><div>Hello Stian,<br><br></div>I believe it is a bit of both; documentation can assist to a certain degree but the codebase holds the <br><br>I find it considerably simpler to make a concept (read "themes", "roles", "workflow") usable if its implementation is somewhat centered in a module, potentially with several subprojects. I was planning to use KeyCloak as an OOTB solution, but found it simpler to dig into the codebase to see how things are implemented to get it going. I can elaborate - if you wish - in another email (private or to the list).<br><br></div>... and while digging into the codebase, I found some things that I wanted to share and possibly contribute, partly because I found it somewhat difficult to understand how the configuration related to the file system. Also, some best practises were not touched upon in documentation or examples - and while that is understandable considering that KeyCloak is a project, I figured I could perhaps submit a suggestion [in the form of a GitHub pull request] for simplifying somewhat.<br><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">2015-08-10 8:56 GMT+02:00 Stian Thorgersen <span dir="ltr"><<a href="mailto:stian@redhat.com" target="_blank">stian@redhat.com</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Is the main issue here that "import" can be a list in theme.properties? If so that's really a documentation issue, not organization of code-base.<br>
<br>
BTW Keycloak is an OOTB solution so you should refer to documentation and examples (I know it's lacking in some places) not the code base. We are targeting non-Java developers and others that just wants something that works without coding. For extending/customization of Keycloak we plan to improve on documentation and clean-up Java APIs that are public.<br>
<span class=""><br>
----- Original Message -----<br>
> From: "Lennart Jörelid" <<a href="mailto:lennart.jorelid@gmail.com">lennart.jorelid@gmail.com</a>><br>
> To: <a href="mailto:keycloak-dev@lists.jboss.org">keycloak-dev@lists.jboss.org</a><br>
> Sent: Sunday, 9 August, 2015 7:00:59 PM<br>
> Subject: [keycloak-dev] Fwd: Concept structure in the VCS?<br>
><br>
> Ah - by mistake, I replied only to Bill. Cross-posting to the list as well.<br>
> Sorry for the spam.<br>
><br>
> ======<br>
><br>
> Hello there,<br>
><br>
> First - I found the current screencasts massively helpful in getting started,<br>
> to be honest. They are something I really have not seen in most projects,<br>
> and they contributed a lot to me making sense of the Keycloak codebase and<br>
> usage scenarios. Kudos.<br>
><br>
> Sedond - I think it would be quite helpful to add additional modularization<br>
> and also harmonize some configuration to make it more evident in how it is<br>
> interpreted. Let me clarify the last bit here (I'll take themes as an<br>
> example, but I believe that the same conclusion stands for other parts of<br>
> the Keycloak codebase):<br>
><br>
> # Import and extend definitions<br>
> parent = base<br>
> import = common/keycloak<br>
> styles = lib/patternfly/css/patternfly.css lib/zocial/zocial.css<br>
> stylesheets/login.css stylesheets/yourOwn.css<br>
><br>
><br>
</span>> 1. The documentation and examples provides something roughly similar to<br>
> the above.<br>
> 2. Turning the attention to the "import" parameter, one could jump to the<br>
<span class="">> conclusion that there would be directory called "common/keycloak" and<br>
> that this directory should contain a lib directory containing the styles<br>
> css documents from the "styles" configuration.<br>
</span>> 3. Reading the codebase, it seems that the semantics of the "import"<br>
<span class="">> property is something completetly different. From the<br>
> ExtendingThemeManager::loadTheme, I can see that the '/' is instead used<br>
> as a list separator implying that we should attempt loading resources<br>
> from several sources. (Snippet pasted below).<br>
><br>
> if (theme.getImportName() != null ) {<br>
> String[] s = theme.getImportName().split( "/" );<br>
</span>> themes.add(findTheme(s[ 1 ], Theme.Type. valueOf (s[ 0 ].toUpperCase())));<br>
<div class="HOEnZb"><div class="h5">> }<br>
> So ... I would believe that the configuration in this case would be clearer<br>
> on a Java Object, JSON or XML form, where one can provide somewhat better<br>
> semantics than what is possible in a properties file (one could use a List<br>
> of theme names instead of a single string value to be parsed and<br>
> interpreted, for example).<br>
><br>
> Mind if I take a stab at implementing a suggestion here?<br>
><br>
><br>
> 2015-08-09 17:25 GMT+02:00 Bill Burke < <a href="mailto:bburke@redhat.com">bburke@redhat.com</a> > :<br>
><br>
><br>
> Only plans right now are to separate our public SPIs and APIs from our<br>
> private ones. This is a requirement by Red hat before we go into product.<br>
><br>
> Also, a massive backlog of requirements and feature requests has made us<br>
> rush documentation. The screencast videos haven't been updated since<br>
> January. It is what it is. Over the next 3-6 months we will catch up<br>
> on this stuff becuase we are required to before we go into Product.<br>
><br>
> FYI, we already autogenerate REST docs.<br>
><br>
> On 8/9/2015 7:38 AM, Lennart Jörelid wrote:<br>
> > Hello all,<br>
> ><br>
> > A month or so ago, I got curious about Keycloak. Downloaded, set up in a<br>
> > dev environment, created some custom themes and took a look at the<br>
> > codebase. I have a few questions, likely because I have missed some<br>
> > developer documentation:<br>
> ><br>
> > * *Codebase concepts*: I frequently try to structure codebases to<br>
> > highlight its big concepts. For example, if we consider 'themes' to<br>
> > be such a concept in KeyCloak we might create a folder called<br>
> > 'themes", with some project wihtin it: (themes-model, themes-spi,<br>
> > themes-impl-jpa, themes-impl-freemarker, ....). Is there a<br>
> > description of the codebase structure or concepts currently?<br>
> > ("mini-SAD")<br>
> > * *Codebase javadoc:* Do we have a policy for JavaDoc'ing the<br>
> > Model/API/SPI but perhaps not the implementation classes, other than<br>
> > with implementation details?<br>
> > * *Configuration:* Some of the descriptions in the docbook are really<br>
> > good, and some are more shallow. If we create a standard way of<br>
> > configuring the parts of keycloak, we could likely generate standard<br>
> > setup/configuration documentation (somewhat similar to maven plugins<br>
> > where certain parts of a site documentation is generated from<br>
> > annotations or JavaDocs). Are there such plans?<br>
> ><br>
> ><br>
> > --<br>
> ><br>
> > --<br>
> > +==============================+<br>
> > | Bästa hälsningar,<br>
> > | [sw. "Best regards"]<br>
> > |<br>
> > | Lennart Jörelid<br>
> > | EAI Architect & Integrator<br>
> > |<br>
> > | jGuru Europe AB<br>
> > | Mölnlycke - Kista<br>
> > |<br>
> > | <a href="mailto:Email%3Alj@jguru.se">Email:lj@jguru.se</a> <mailto: <a href="mailto:lj@jguru.se">lj@jguru.se</a> ><br>
> > | URL: <a href="http://www.jguru.se" rel="noreferrer" target="_blank">www.jguru.se</a> < <a href="http://www.jguru.se" rel="noreferrer" target="_blank">http://www.jguru.se</a> ><br>
> > | Phone<br>
> > | (skype): jgurueurope<br>
> > | (intl): <a href="tel:%2B46%20708%20507%20603" value="+46708507603">+46 708 507 603</a><br>
> > | (domestic): 0708 - 507 603<br>
> > +==============================+<br>
> ><br>
> ><br>
> ><br>
> > _______________________________________________<br>
> > keycloak-dev mailing list<br>
> > <a href="mailto:keycloak-dev@lists.jboss.org">keycloak-dev@lists.jboss.org</a><br>
> > <a href="https://lists.jboss.org/mailman/listinfo/keycloak-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/keycloak-dev</a><br>
> ><br>
><br>
> --<br>
> Bill Burke<br>
> JBoss, a division of Red Hat<br>
> <a href="http://bill.burkecentral.com" rel="noreferrer" target="_blank">http://bill.burkecentral.com</a><br>
> _______________________________________________<br>
> keycloak-dev mailing list<br>
> <a href="mailto:keycloak-dev@lists.jboss.org">keycloak-dev@lists.jboss.org</a><br>
> <a href="https://lists.jboss.org/mailman/listinfo/keycloak-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/keycloak-dev</a><br>
><br>
> --<br>
> --<br>
> +==============================+<br>
> | Bästa hälsningar,<br>
> | [sw. "Best regards"]<br>
> |<br>
> | Lennart Jörelid<br>
> | EAI Architect & Integrator<br>
> |<br>
> | jGuru Europe AB<br>
> | Mölnlycke - Kista<br>
> |<br>
> | Email: <a href="mailto:lj@jguru.se">lj@jguru.se</a> | URL: <a href="http://www.jguru.se" rel="noreferrer" target="_blank">www.jguru.se</a> | Phone<br>
> | (skype): jgurueurope<br>
> | (intl): <a href="tel:%2B46%20708%20507%20603" value="+46708507603">+46 708 507 603</a><br>
> | (domestic): 0708 - 507 603<br>
> +==============================+<br>
><br>
> _______________________________________________<br>
> keycloak-dev mailing list<br>
> <a href="mailto:keycloak-dev@lists.jboss.org">keycloak-dev@lists.jboss.org</a><br>
> <a href="https://lists.jboss.org/mailman/listinfo/keycloak-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/keycloak-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br><div class="gmail_signature"><span style="font-family:monospace;font-size:medium"><pre>--
+==============================+
| Bästa hälsningar,
| [sw. "Best regards"]
|
| Lennart Jörelid
| EAI Architect & Integrator
|
| jGuru Europe AB
| Mölnlycke - Kista
|
| Email: <a href="mailto:lj@jguru.se" target="_blank">lj@jguru.se</a>
| URL: <a href="http://www.jguru.se" target="_blank">www.jguru.se</a>
| Phone
| (skype): jgurueurope
| (intl): +46 708 507 603
| (domestic): 0708 - 507 603
+==============================+</pre></span></div>
</div>