[SYNCOPE-1009] added documentation about customization of enduser form, minor code cleansing
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/107e51f5 Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/107e51f5 Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/107e51f5 Branch: refs/heads/SYNCOPE-808 Commit: 107e51f5bb5063a1fd2078dbf3583508980ec913 Parents: 5221e60 Author: Andrea Patricelli <andreapatrice...@apache.org> Authored: Thu Apr 13 11:02:37 2017 +0200 Committer: Andrea Patricelli <andreapatrice...@apache.org> Committed: Thu Apr 13 11:02:37 2017 +0200 ---------------------------------------------------------------------- .../resources/META-INF/resources/app/index.html | 1 - .../app/js/controllers/UserController.js | 1 - .../enduser/src/test/resources/customForm.json | 48 +----- .../workingwithapachesyncope/customization.adoc | 161 ++++++++++++++++++- 4 files changed, 159 insertions(+), 52 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/107e51f5/client/enduser/src/main/resources/META-INF/resources/app/index.html ---------------------------------------------------------------------- diff --git a/client/enduser/src/main/resources/META-INF/resources/app/index.html b/client/enduser/src/main/resources/META-INF/resources/app/index.html index 7378236..21a7984 100644 --- a/client/enduser/src/main/resources/META-INF/resources/app/index.html +++ b/client/enduser/src/main/resources/META-INF/resources/app/index.html @@ -99,7 +99,6 @@ under the License. <script src="js/services/groupService.js"></script> <script src="js/services/anyService.js"></script> <script src="js/services/saml2IdPService.js"></script> - <script src="js/services/configurationService.js"></script> <!--controllers--> <script src="js/controllers/HomeController.js"></script> <script src="js/controllers/LoginController.js"></script> http://git-wip-us.apache.org/repos/asf/syncope/blob/107e51f5/client/enduser/src/main/resources/META-INF/resources/app/js/controllers/UserController.js ---------------------------------------------------------------------- diff --git a/client/enduser/src/main/resources/META-INF/resources/app/js/controllers/UserController.js b/client/enduser/src/main/resources/META-INF/resources/app/js/controllers/UserController.js index d49032f..e741524 100644 --- a/client/enduser/src/main/resources/META-INF/resources/app/js/controllers/UserController.js +++ b/client/enduser/src/main/resources/META-INF/resources/app/js/controllers/UserController.js @@ -299,7 +299,6 @@ angular.module("self").controller("UserController", ['$scope', '$rootScope', '$l if ($scope.user.mustChangePassword) { $location.path('/mustchangepassword'); } else { -// initConfiguration(); initProperties(); } }, function (e) { http://git-wip-us.apache.org/repos/asf/syncope/blob/107e51f5/client/enduser/src/test/resources/customForm.json ---------------------------------------------------------------------- diff --git a/client/enduser/src/test/resources/customForm.json b/client/enduser/src/test/resources/customForm.json index 0a8b4d3..9e26dfe 100644 --- a/client/enduser/src/test/resources/customForm.json +++ b/client/enduser/src/test/resources/customForm.json @@ -1,47 +1 @@ -{ - "PLAIN": - { - "show": true, - "attributes": { - "firstname": { - "readonly": true, - "defaultValues": ["defaultFirstname"] - }, - "surname": { - "readonly": false, - "defaultValues": [] - }, - "fullname": { - "readonly": false - }, - "loginDate": { - "readonly": false - }, - "additional#loginDate": { - "readonly": false - }, - "additional#ctype": { - "readonly": false, - "defaultValues": ["ctypeDefault"] - }, - "additional#cool": { - "readonly": false, - "defaultValues": ["true"] - } - } - }, - "DERIVED": - { - "show": false - }, - "VIRTUAL": - { - "show": true, - "attributes": { - "virtualdata": { - "readonly": true, - "defaultValues": ["defaultVirtualData"] - } - } - } -} \ No newline at end of file +{} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/107e51f5/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc index 9430ccc..97e2e72 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc @@ -110,6 +110,7 @@ $ mvn clean verify \ $ cp core/target/classes/*properties /opt/syncope/conf $ cp console/target/classes/*properties /opt/syncope/conf $ cp enduser/target/classes/*properties /opt/syncope/conf +$ cp enduser/target/classes/customForm.json /opt/syncope/conf .... After downloading all of the dependencies that are needed, three WAR files will be produced: @@ -404,10 +405,10 @@ Add the following dependencies to `enduser/pom.xml`: Copy `enduser/src/main/resources/all/saml2sp-agent.properties` to `enduser/src/main/resources/saml2sp-agent.properties`. -[[customization-enduser-translations]] -===== Translations +[[customization-enduser-i18n]] +===== i18n -The <<enduser-application>> comes with a native translation mechanism. +The <<enduser-application>> comes with a native internationalization mechanism. Under the `enduser/src/main/webapp/app/languages/` directory, a sub-directory for each supported language is available; each language sub-directory contains two JSON files: @@ -459,6 +460,160 @@ as and modify the JSON files under the new directory ==== +===== Form customization + +User self create/edit form could be customized in order to: + +* Hide/show some attributes +* Deny/allow attribute write + +Under the `enduser/src/main/resources` directory you can find `customForm.json` file. +This specifies the rules about form customization, in particular it allows to customize `PLAIN`, `DERIVED` and `VIRTUAL` +attributes forms. + +[TIP] +==== +The file provided with the archetype contains an empty json: `{}`. +If such file is deleted or contains empty or not parseable json, customization will be simply ignored and all attributes +will be shown. +==== + +Here is an example: + +``` +{ + "PLAIN": + { + "show": true, + "attributes": { + "firstname": { + "readonly": true, + "defaultValues": ["defaultFirstname1", "defaultFirstname2"] + }, + "surname": { + "readonly": false, + "defaultValues": [] + }, + "fullname": { + "readonly": false + }, + "email": { + "readonly": false, + "defaultValues": ["t...@apache.org"] + }, + "userId": { + "readonly": false + }, + "cool": { + "readonly": true, + "defaultValues": ["true"] + }, + "additional#loginDate": { + "readonly": false + }, + "additional#cool": { + "readonly": false, + "defaultValues": ["true"] + } + } + }, + "DERIVED": + { + "show": false + }, + "VIRTUAL": + { + "show": true, + "attributes": { + "virtualdata": { + "readonly": true, + "defaultValues": ["defaultVirtualData"] + } + } + } +} +``` +As you can see the file has two main levels: + +* Schema type: `PLAIN`, `DERIVED`, `VIRTUAL`. +* Attributes: list of attributes (by schema type) to be shown in the form. + +====== Schema type + +The schema type level allows to define customization of the three sub-forms available in the wizard. +An user can specify one or each of the three sections in order to customize only what is really needed. +Though enable/disable of schema forms can be configured also from the `app.js` file of the enduser, form customization +json provides an attribute `show` to hide/show attributes input fields. +If `show` is set to `false` info contained into `attributes` will be ignored and nothing is displayed in the form section. + +====== Attributes + +Attributes level contains a map of attributes to show. + +[TIP] +==== +Attributes map is meant to be populated, i.e. empty `attributes` field means "do not filter at all and show all attributes". +For example: +``` +{ + "PLAIN": + { + "show": true, + "attributes": {} + } +} +``` +shows all attributes. +If you want to hide all attributes please use `show` field: `show: false`. +==== + +As you can see from the sample json each attribute has: + +* A name: the name of schema from which the attribute has been generated. +* A body: specifies if attribute should be readonly and its default values. + +Here is an example of attribute specification: + +``` +"firstname": { + "readonly": true, + "defaultValues": ["defaultFirstname","defaultFirstname2"] + } +``` +In the example `firstname` is readonly and has two default values defined by a (comma separated) array of strings. +Default values section can be omitted if there are not default values to assign to that attribute. + +[CAUTION] +==== +There are some clarifications to be made about form customization: + +* Default value of `show` (about schema sections) is `true`, i.e. if not specified the section is visible. +* `readonly` field must not be confused with schema `readonly` information. In form customization `readonly` +means a front-end readonly, i.e. the attribute is not modifiable from the enduser, but it can be fully accessible +from the administration console. +It does not provide info about the schema, but about the specific attribute of the USER. +* If `readonly` is not specified it is considered `false` by default. +* `defaultValues` is an array of strings; this means that also date values should be specified as strings, in particular +in dates must be provided into timestamp format in milliseconds (this behavior will be improved further). +* `defaultValues` (obviously) do not averride populated fields, an attribute is filled with default values +only if it is empty (in create and update). +==== + +====== Hot deploy + +Form customization supports "hot deploy" feature. This means that `customForm.json` could be edited and reloaded +without stopping and re-starting the application server. +Obviously to see "hot" modifications to the form you must refresh the page of the browser. + +[TIP] +==== +When running Syncope into embedded mode you should edit `fit/enduser-reference/target/test-classes/customForm.json` +file. + +While running, instead, Syncope in a real environment you should edit the file under `conf.directory`. Please refer to <<deployment-directories>> section. +==== + + [[customization-extensions]] ==== Extensions
