Entando plugin: Address Book
#Entando plugin Address Book
Installation and configuration of the Entando jpaddressbook plugin
The purpose of this guide is to provide a complete description of the Entando Address Book plugin whose code is jpaddressbook for the Entando platform.
This guide is intended for both administrators and developers who wish to explore the capabilities of the Entando Plugin Address Book and are considering a possible integration into a running production environment or in a Development Environment.
In order to take maximum advantage from the present guide, it is necessary to have basic knowledge of the Java platform, the servlet engine Apache Tomcat, PostgreSQL (or MySQL) DBMS and the Entando platform.
Moreover, it's necessary to have read the Plugin Pattern for the installation procedure and an explanation of the standard directory layout.
The jpaddressbook plugin allows to create a shared address book based on the system users profiles; it is also possible to add private contacts and downlead a VCard of the private contacts.
The profile of a given portal user is listed in the address book only if it has been previously declared public; the user's private contacts are always included.
Three new widgets are added to the system:
-
Address Book – Advanced Search Form
-
Address Book – Search Form
-
Address Book – Search Result
Due to its nature, jpaddressbook requires as a prerequisite: Manage User Profile. This information is relevant only for the installations in production environments: the administrator is required to manually provide the prerequisites. For further details on those plugins consult the respective manuals.
For installations in a development environment there are no problems because Maven takes care of the prerequisites automatically; though the plugin installation is not difficult at all, we are going to modify the system tables, so a backup of your database is highly recommended. Furthermore, you may be required to customize the scripts to your needs before installation.
For the purpose of the current guide, a few Maven and Ant commands are shown: your IDE has probably the ability to execute those commands for you in background.
jpaddressbook is a pure plugin, thus it neither affects the core of the system nor the existing functionality.
jpaddressbook directories are organized following the Maven Standard Directory Layout as shown in the Plugin Pattern.
It is worth noting that the plugin installation is greatly changed from the previous releases (thank you, Maven!).
As always when it comes down to install new things, stop your servlet container before moving on.
Open the pom.xml of your project: locate the <dependencies> tag toward the end of the file, after the <build> tag; if the tag dependencies doesn't exist just create a new one just after the closure of the build tag.
Add the following snippet inside the dependencies:
<dependency>
<groupId>org.entando.entando.plugins</groupId>
<artifactId>entando-plugin-jpaddressbook</artifactId>
<version>${entando.version}</version><!-- version. Don't remove this comment. -->
<type>war</type>
</dependency>You are done! You can verify the correct installation of the plugin going to the administration area and checking for the new item in the Plugins menu.
From now we will use the name myportal when referring to your deployed Entando application or, in other words, to the artifact ID of the deployed portal.
All Entando plugins can be downloaded from the Maven Central repository, just filter by code and by version.
To install jpaddressbook in a production environment the file entando-plugin-jpaddressbook-3.2.0.war is needed; we will refer to this file as WAR package.
The WAR package might contain the dependencies of other plugins; when performing copy operations you may accidentally overwrite your previous customizations of the JSP files, so you are warmly recommended to create a backup of your installation.
Note: that the integration activity must be performed after the servlet container has been stopped.
-
Install the plugin Manage User Profile in the production environment (consult the relative documentation for the correct procedure to follow), if it is not already present.
-
copy the content of
WEB-INF/libdirectory of the WAR package, tomyportal/WEB-INF/lib/directory. -
create the directory
myportal/WEB-INF/plugins/if it does not exist. Copy the content ofWEB-INF/plugins/directory of the WAR package, tomyportal/WEB-INF/plugins/. -
copy the content of the directory
resources/pluginsof the WAR package intomyportal/resources/plugins/within the servlet container
Now the servlet container can be restarted.
The only configuration required by this plugin is relative to the format of the VCard which can be generated by the system, as shown in the next chapter.
The configuration page is accessed from the left menu Plugins → Address Book → VCard Configuration
The interface above is used to select which fields are going to be shown in generated cards and how these fields are related to the profile: in the example we chose to export the Name and the Surname ticking the appropriate checkbox. Then, clicking on the Continue button, the following page is shown:
In this page we explicitly associate the field of the card selected previously with a specific field, or attribute, of the profile; the attributes of the profile are listed in the drop down menu. The configuration is completed clicking the Save button; users will be redirected to the Contact Management page showing the list of private contacts.
This section let users manage their private contacts. In the intro page two icons appears in the top right: these are used to create a new contact or to list existing ones, respectively.
Before going on, it's important to remember that it's possible to change the profile fields from the menu Plugins → User Profile → Profile Types.
Users add a new private contacts clicking on the left icon in the Contact Management intro page. (see picture above). The form to insert a new contact is shown below:
Clicking on the Save botton will lead to user to the Contact management interface where it is possible to edit delete and generate the VCard of the various contact.
Users access this page automatically after a new private contact is added or when the upper rightmost icon in the Contact management intro page is clicked.
Contacts are organized in a table similar to the following:
The O, VCard, D and - columns deserve a separate explanation:
-
the *O” column shows the owner of the contact
-
the icon on the VCard column generates the card for the corresponding profile
-
the icon in D displays**a summary of the contact
-
clicking on the remove icon the contact is removed from the, list as soon as the operation is confirmed by the user.
As usual, the list of the installed widgets can be accessed from the Widgets in the left menu:
Address Book – Search Form: this widget allows to perform a search using all the textual attributes of the profile.
Address Book – Advanced Search Form: this widget allows searches using all the fields of the profile.
Address Book – Search Result: results found are placed in this widget for easy consultation. It is also possible to edit or delete private contacts listed.