Jahia is a platform for managing a variety of digital initiatives in a productive and secure fashion. Initiatives such as building websites, mobile sites, intranets and portals, all of which can interact with visitors in order to deliver the best user experience possible.
This document presents Portal Factory, a portal generation and management interface, available as an Add-on for Jahia.
Portal Factory allows you to create Portal models for your site and give your users access to one or more Portals based on these models. They can also under circumstances customize these portals within the limits you define.
This guide explains the fundamentals of this new module and the usage / function of all menus and major features. Explanations remain simple and factual, so this guide can help users to get acquainted rapidly to the tools they will use.
Some advanced technical features such as creating custom widgets or connecting to the Javascript Portal API are covered in the Portal Factory Technical Documentation that will be available on the Jahia Web Site.
Installation
How to install Portal Factory
Portal Factory is an extension suite for Jahia. In order to use it, you have to install all the Portal Factory modules on your existing Jahia installation.
To deploy the modules, you can use the Studio in Jahia and use the "New > Get module from sources" option in the Toolbar for each module.
For optimal deployment on the platform, they must be installed in the order presented hereafter because of the dependencies existing between some of them.
Required modules
All these modules must be deployed on the platform in that order for Portal Factory to work.
Portal factory - core: https://github.com/Jahia/portal-factory_coreThis is the core module for the portal, it contains the JavaScript Portal API and the portal taglib, all the filters, actions, scripts, and views necessary to the portal to work correctly.
Portal factory - user portal: https://github.com/Jahia/portal-factory_user-portal These are the components related to the portal for end-users. These components rely on the portal JavaScript API and the portal taglib. The user portal contains:
Portal toolbar: This toolbar displays the tabs and the actions available to create and edit portals
User’s portal list: A simple component displaying all the portals accessible by the current user.
Portal widget zap: A component displaying all the drag&droppable widgets in the portal.
Portal factory - widgets: https://github.com/Jahia/portal-factory_widgets This is the portal widgets sample. (twitter widget, rss feed widget, script widget, document browser widget, etc.)
Portal factory - default templates: https://github.com/Jahia/portal-factory_default-templates This is the default template set that can be used directly to start creating portals easily. Note that you can create your own template set or reuse an existing one. But this one offers a simple way to get started with portal creation.
For every module, go to the link indicated. Copy the clone link using the HTTPS clone URL button on GitHub.
In the Studio, click the "New > Get module from sources" option.
Choose the SVN option. Paste the link into the URI field and enter the artefact ID manually, by copying the name of the. git file without the. git extension. Click OK to save. After a few moments, the new module will be installed on the platform.
Creating a Portal
Creating a new Portal site
Now that all the necessary modules are installed on the Jahia platform, the next step is to create a site. The quickest way to set up a portal is to use the Portal Factory Default Templates we installed previously.
Create a New Web Project
On the templates and modules selection screen, choose the template set "Portal Factory Default Templates" and check the boxes to deploy the Portal Factory modules:
Portal Factory – core
Portal Factory User Portal
Portal Factory Widgets
Once the site is created, the Portal Settings are accessible via the Site Settings in a new tab called "Portal Factory".
Using portals in an existing site
To be able to use Portals in an existing Jahia Web Site,
Portal Factory Modules must be activated for this site
Specific portal templates including portal content must be created through the Studio and added to your site.
For more information, please refer to the Portal Factory Technical Documentation and Videos, available on the Jahia website.
Defining a portal model
To enable Portals for your users, you must first create a Portal Model on your new site. Use the Portal Factory entry in the site settings.
A portal model is a sort of "master" template which defines a default Portal for your users to access. Users can use the default portal as is or, if your settings allow it, they can create their own customized instance of the portal, based on that model.
Choose a name for your portal model and a template set that will be used as templates for the portal tabs.
Select a Portal template set. The default template set used to create the site already includes portal content templates for you to use.
It is possible to create your own portal template set using the Studio in Jahia. This will be explained in a dedicated document on the Jahia Web Site. For now we will use the template set contained in the default template module.
On the template selection screen, you must choose the "portal" node. This is the parent of 4 content templates specific to the portal tab type. Please note that due to the Portal validation mechanism, if you choose a template node that doesn’t contain any portal related template, you will see an error message.
Specify a "Portal full template" (optional). This is the template that will be used to display a widget in full view. Typically, the usual setting is the "1 Column" template so the widget can take all space available.
Specify the widget types that are allowed in this portal model. All the Portal instances that will be built by users upon this model will be authorized to use one or more of these allowed widgets only.
At creation, the Portal contains an automatically generated tab. You can specify a name for this first portal tab. You will be able to make changes to this information later in your portal model.
Save the form.
Your Portal Model is now visible in the list of portal models under the "Portal Factory" tab in your site's Site Settings when you choose "Manage Portal models".
Now that the new blank portal model is created, go to Live Mode by clicking the World icon (1st) and start composing your portal by adding widgets to it.
Do not enable the Portal model as long as you haven't finished its widget configuration. Only enable it when it is ready to be used by users.
This is what the blank Portal model looks like in Live Mode:
The toolbar displaying the current tab is the Portal Toolbar component.
Tabs
To add a new tab, click on the personal avatar icon and choose "new portal tab" :
By clicking on the wrench icon , you can edit the current tab.
The (lock/unlock) action will be discussed later.
Widgets
Use the Widget Zap to add widgets to your Portal model.
You can create your custom widgets and custom widget skins using the JavaScript Portal API. This will be detailed in a separate technical documentation available for download on the Jahia website. In this document, we will stay focused on standard widgets.
Widget Zap
On the left you can see this button:
Clicking the arrow will display the Widgets Zap (list for selection):
You can directly drag & drop widgets from the Widgets Zap onto your page. The allowed zone for inserting the widget is indicated by a black line.
As an example, let's drag the RSS Feed widget onto the left column:
The widget appears at desired location. If the widget has an "edit" view, this is the view that will be displayed. Otherwise, the widget will display the default view. For the RSS feed widget, the "edit" view is loaded.
Widget options
At the top of the widget, you can see a small toolbar with various icons:
: load the widget in the full template (if there is one for the current portal, otherwise this icon is not displayed)
: load the "edit" view for the widget (if there is one, otherwise this icon is not displayed)
: minimize/maximize the widget (present in any case)
:delete the widget (when the widget is a reference to a widget model, a confirmation message is displayed)
: load the "model" view for the widget, this icon is only shown when you are configuring the model. This option displays a form containing informations about the behavior of the widget when copied (full copy or reference copy when a user creates their portal from this model – see Customizing the Portal).
Reference copy vs. Full copy
In the Copy by Reference behavior, widget's appearance and parameters in the User Portal are completely defined by their definition in the model. If the admin modifies the widget in the model, the widget in the User Portal will automatically reflect the changes.
Also, if the user tries to delete the widget in their portal, an error message will be displayed.
In the Full Copy behavior, the widget, its appearance and parameters are copied when it is first instantiated and any further changes made to the widget in the model by the Site Administrator are not reflected in the User Portal.
Configuring the Portal model
Let's add some standard widgets to our Portal model.
In this example, we create 3 tabs ('welcome' created automatically, 'social' and 'document').
The 'welcome' tab uses a 2-column template. It contains the RSS Feed widget, which we chose to copy by reference, and one more widget, map. The RSS Feed behavior is set to "Copy by reference".
The 'social' tab uses the template 2 columns 8 / 4 and the purple widget skin and contains a portlet and a script widget.
The 'document' tab uses the 1 column template and contains a document browser widget.
Allow customization
In the Portal Model creation form, you can specify whether customization is allowed or not for this model.
Check the box "Allow customization" to allow users to create custom portals from your model (see below – Customizing the Portal)
If not allowed, the users will not be able to create their own portal. They will only be able to use the Portal model as is.
Enabling the Portal model
Now that the portal model is configured, you need to Enable the portal model for your users to be able to use the Portal.
Go to Edit Mode under the "Portal Factory" tab in your site's Site Settings, "Manage portal models" and click the Enable button.
Portal features for end-users
End-Users can instantiate the Portal Model and use it as-is or customize it (if allowed by the Site Administrator).
To help you understand how the Portal works for End-Users, let's create a sample home page for the site.
Portal List
To display the list of the Portals that the user can access, add a "User's Portal List" component to a page, and publish the site.
As the "R&D" Portal model is enabled and no custom Portal exists, the user will see this in Live Mode:
Using the default Portal model
Clicking on the name will take the user to the R&D Portal model:
The user can use the Portal model as-is and have access to the content but cannot change the configuration of the model.
The icons available for the widgets are:
: load the widget in the full template (if there is one for the current portal, otherwise this icon is not displayed)
: minimize/maximize the widget (present in any case)
No Edit options are available in this view.
If customization is enabled, users can customize their own instance of the model by clicking on the Customize button.
Customizing the portal
By clicking on the Customize button on the Portal model screen, a copy of the model is made under the user node.
In this copy, Edit options appear for the tabs and the widgets.
The icons available for the widgets are:
: load the widget in the full template (if there is one for the current portal, otherwise this icon is not displayed)
: load the "edit" view for the widget (if there is one, otherwise this icon is not displayed)
: minimize/maximize the widget (present in any case)
: delete the widget (when the widget is a reference to a widget model, a confirmation message is displayed)
Within a custom Portal, the user can move widgets, remove widgets, create tabs, edit tabs...
In this example, the RSS feed widget cannot be edited nor removed, as it has been Copied by Reference from the model.
This means that this widget's appearance and behavior are completely defined by their definition in the model. If the admin changes the widget in the model, this widget will automatically reflect the changes.
If the user tries to delete the widget, an error message will be displayed.
Note: when a user chooses to customize a portal from a model, the User's Portal List will no longer display the link to the model. The List will now display the link to the modified Portal.
The user will not see the link to the model again, unless his customized Portal is deleted.
Locking the portal
The Lock portal tab allows the user to lock the portal. This feature hides all the widget toolbars and icons and the drag & drop feature is deactivated. This is useful when the the user doesn't want to make any changes to the portal and simply wants to use it, gaining thus more screen real estate and focusing on relevant content.
The portal can be unlocked it by clicking on the Unlock portal tab.
Portal tab accessibility:
Using the icon in the Portal toolbar tab, users can specify the accessibility policy for their portal tabs. A portal tab and its contents can either be:
private (only visible by the user themselves)
visible by authenticated users
public (visible by everyone, including guests)
By default, all tabs are private.
Portal administration
Managing user portals
As users can create their own portals, it can be useful to have a manage them.
In the "Portal Factory" entry in your site's Site Settings, go to "Manage user portals" to display the list of all existing user portals.
Here you can see for each user portal instance: the model they are based on, when was the last time they used the portal and the creation date.
It is also possible to delete a user's portal. If a custom portal is deleted, the user will be redirected to the Portal model and the link to their custom portal in their Portal list will be replaced by a link to the model.
Managing portal models
In the "Portal Factory" entry in your site's Site Settings, go to "Manage portal models" to display the list of all existing portal models on the site.
For each model, you see the name of the model, the number of user portal instances based on this model, an action bar and a State button allowing you to enable/disable the model for your site.
The action bar icons are:
World icon: compose the Portal model in Live mode using widgets
Edit icon: edit the Portal model's properties
Person icon: edit the Group restrictions
Delete icon: delete the Portal model
Group restrictions
It is possible to restrict access to a Portal model to certain specific user groups only. Only members of these groups will be able to see the Portal model and use it. If no restrictions are defined, all authenticated users can see the portal model.
To edit Group restrictions, click the "person" icon in the action toolbar (3rd icon).
The number of groups that can be displayed on this screen is limited. Use the search field to filter the results if needed.
To add a group to the list of allowed groups, just select it and click on "add selected groups to restrictions".
To remove a group from the list of allowed groups, just select it and click on "remove selected groups from restrictions".
For more information about Portal Factory and other Jahia Products, please refer to the videos and technical documentation available on the Jahia Web Site
