[Freeipa-devel] UI plugins

Fri Mar 6 13:58:13 UTC 2015

On 03/06/2015 02:31 PM, Corey Kovacs wrote:
> I almost forgot to ask. Since you don't point it out, I am assuming (yeah I
> know) the plugin code methods have not changed from 3.3 to 4.1? That is to
> day I should be able to use the same techniques?

Same techniques should be applicable, there were no major improvements 
in plugin support in 4.1. But Web UI doesn't have any stable API so 
little things could be different.

Basically plugins interact with Web UI's core code which is not 
perfect(easy to break things) but it's powerful and better than nothing.

>
> Thanks again!
>
> Corey
>
> On Fri, Mar 6, 2015 at 3:51 AM, Petr Vobornik <pvoborni at redhat.com> wrote:
>
>> On 03/06/2015 03:54 AM, Corey Kovacs wrote:
>>
>>> After reading the extending freeipa training document I was able
>>> successfully add  us to meet attributes and add/modify them using the cli
>>> which was pretty cool. Now that I got the cli out of the way I want to add
>>> the fields to the ui. Because of the similarities between what I want to
>>> do
>>> and the example given in the docs I just followed along and changed
>>> variables where it made sense to do so. I cannot however get the new field
>>> to show up.  The Apache logs don't show any errors but they do show the
>>> plugin being read as the page (user details) is loaded. After searching
>>> around I found a document which attempts to explain the process but it
>>> assumes some knowledge held by the reader which I don't possess.
>>>
>>> It looks like I  supposed to create some sort of index loader which loads
>>> all of the modules which are part of the plugin. I can't seem to find any
>>> good documents telling the whole process or least non that I can make
>>> sense
>>> of.
>>>
>>>
>> Plugin could be just one file, if the plugin name is "myplugin" it has to
>> be:
>>
>>   /usr/share/ipa/ui/js/plugins/myplugin/myplugin.js
>>
>> IPA Web UI uses AMD module format:
>> - https://dojotoolkit.org/documentation/tutorials/1.10/modules/
>> - http://requirejs.org/docs/whyamd.html#amd
>>
>> I have some example plugins here:
>> - https://pvoborni.fedorapeople.org/plugins/
>>
>> For your case I would look at:
>> - https://pvoborni.fedorapeople.org/plugins/employeenumber/
>> employeenumber.js
>>
>> Web UI basics and introspection:
>> (this section is little redundant to your question, but it might help
>> others)
>>
>> FreeIPA Web UI is semi declarative. That means that part of the pages
>> could be thrown away, modified or extended by plugins before the page is
>> constructed. To do that, one has to modify specification object of
>> particular module.
>>
>> Here, I would assume that you don't have UI sources(before minification),
>> so all introspection will be done in running web ui. Otherwise it's easier
>> to inspect sources in install/ui/src/freeipa, i.e. checkout ipa-3-3 branch
>> from upstream git.
>>
>> List of modules could be find(after authentication) in browse developer
>> tools console in object:
>>
>>    window.require.cache
>> or (depends on IPA version)
>>    window.dojo.config.cache
>>
>> One can then obtain the module by:
>>
>>    var user_module = require('freeipa/user')
>>
>> specification object is usually in 'entity_spec' or '$enity_name_spec'
>> property.
>>
>>    user_module.entity_spec
>>
>> UI is internally organized into entities. Entity corresponds to ipalib
>> object. Entity, e.g. user, usually have multiple pages called facets. To
>> get a list of facets:
>>    user_module.entity_spec.facets
>>
>> The one with fields has usually a name "details". For users it's the
>> second facet:
>>    var details_facet = user_module.entity_spec.facets[1]
>>
>> IF i simplify it a bit, we can say that fields on a page are organized in
>> sections:
>>    details_facet.sections
>>
>> Section has fields. A field usually represents an editable element on
>> page, e.g. a textbox with label, validators and other stuff.
>>
>> Example of inspection:
>>
>> https://pvoborni.fedorapeople.org/images/inspect_ui.png
>>
>> Your goal is to pick a section, or create a new one an add a field there.
>> To know what to define, just examine a definition of already existing field
>> and just amend name, label, ...
>>
>>
>>   It would help also to understand how to debug such a thing.
>>>
>>>
>> In browser developer tools. There is javascript console (use in the text
>> above), javascript debugger, network tab for inspecting loaded files.
>>
>> For developing RHEL 7 plugin, I would suggest you to install test instance
>> of FreeIPA 3.3 and use "Debugging with source codes" method described in:
>>
>> - https://pvoborni.fedorapeople.org/doc/#!/guide/Debugging
>>
>> Some tips:
>> - if you get a weird dojo loader messegate, you probably have a syntax
>> error in the plugin or you don't return a plugin object or the plugin could
>> not be loaded (bad name)
>> - it's good to use some JavaScript liner - jsl or jshint to catch syntax
>> errors early.
>>
>>
>>   I  running version 3.3 on rhel 7. Any help or pointers to more
>>> documentation would be greatly appreciated.
>>>
>>>
>> --
>> Petr Vobornik
>>
>

-- 
Petr Vobornik