Entando: an unexpected journey
Hello, Trumbitta here. You can find me on GitHub or Twitter.
So you heard about Entando and thought:
Finally an enterprise portal framework which is at the same time powerful, extensible, and not [Liferay|Oracle Portal|WebSphere]-difficult to use!
But then you looked left, and then you looked right, and then you looked around and thought:
Right. How do I am supposed to use Entando to get my new shiny portal up and running, exactly?
Hey! That's exactly the reason why I'm writing this guide for you to enjoy!
Also known as prerequisites.
This journey through Entando is especially tailored for a Linux development environment but if you know the moves, you could also follow me from a Mac OS X or Windows machine easily enough.
We will be using Entando 4, which comes with an awesome lot of improvements we'll take advantage of.
Also, let me suggest you not to skim through this guide like a squirrel looking for acorns. Take your time, read carefully, relax, and enjoy the ride.
There's nothing really difficult on the road ahead.
In your backpack, you will need:
- Maven 2.2.1 or 3.x
- OpenJDK 7
- Your favorite text editor and / or IDE
I use Sublime Text 2 and Eclipse, while the lead developer of Entando - Eugenio Santoboni - prefers Netbeans.
Pro Tip
In Ubuntu Linux, you can usually install Maven and OpenJDK with a simple:
sudo apt-get install openjdk-7-jdk maven2
Here we go. Go find yourself a comfortable spot in the filesystem, like:
mkdir ~/entando/ && cd ~/entando
And create your new, barebones, portal bundled with the awesome Bootstrap, version 2:
mvn archetype:generate -Dfilter=entando
If this is the first time you use Maven, first of all stop reading right now and go read an intro to Maven.
Maven will ask you the good 'ole questions, to which you'll answer like so:
Choose archetype:
1: remote -> org.entando.entando:entando-archetype-portal-bootstrap (Twitter Bootstrap Portal Archetype for Entando: an agile, modern and user-centric open source portal-like platform.)
2: remote -> org.entando.entando:entando-archetype-plugin-generic (Generic Plugin Archetype for Entando: an agile, modern and user-centric open source Portal platform.)
3: remote -> org.entando.entando:entando-archetype-portal-generic (Generic Portal Archetype for Entando: an agile, modern and user-centric open source portal-like platform.)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :
<Choose 1 or whatever number points to org.entando.entando:entando-archetype-portal-bootstrap>
Define value for property 'groupId': : com.mydomain
Define value for property 'artifactId': : myportal
Define value for property 'version': 1.0-SNAPSHOT:
Define value for property 'package': com.mydomain:
Confirm properties configuration:
groupId: com.mydomain
artifactId: myportal
version: 1.0-SNAPSHOT
package: com.mydomain
Y:
Then of course enter the root directory of myportal:
cd myportal
Cool. Let's see if it worked.
- Start Entando:
mvn clean jetty:run
- Relax until you see these ending log lines by Jetty:
[INFO] Started Jetty Server
[INFO] Starting scanner at interval of 5 seconds.
Those two lines mean that Entando is up and running and Jetty is now ready to accept connections.
That is, point your web browser to http://localhost:8080/myportal and behold the mostly empty placeholder page, stating that It Worked!.
So we are ready to move on to the next checkpoint; but first be sure to stop Jetty:
CTRL C
entando-archetype-portal-bootstrap comes with a handy Page Bundle, some Widget Bundles, and a Content Bundle.
We'll see how to activate and use them in a minute, but before that it's now time to stop and think of what you need for myportal.
As you may - and should - already know, Entando sports a bunch of key concepts: Content Types, Page Models, Widgets, and so on.
If you're familiar with Entando, you already know how to configure Content Types, manage Pages, put Widgets in place. Since version 3.2, using Bundles you can configure and customize your Entando based application even faster.
Adding a Bundle to myportal is as simple as inserting an XML snippet at the very top of the dependencies section of the pom.xml.
Let me repeat this: you have to insert the XML snippets for Bundles at the very top of the dependencies section, and exspecially before any other dependency related to Entando.
Really.
It's mandatory.
Ok, so you thought about it and are almost sure that Generic Content won't be enough for myportal because - hey - everybody likes News!
Open pom.xml, locate the very top of the dependencies section and insert this XML snippet:
<dependency>
<groupId>org.entando.entando.bundles.contents</groupId>
<artifactId>entando-content-news</artifactId>
<version>${entando.version}</version>
<type>war</type>
</dependency>So far, the freshly generated myportal has already activated in its first run the awesome and flexible entando-page-bootstrap-hero Page Model which is loosely based on the famous Hero Unit example from Twitter Bootstrap.
Sure enough, you could argue that adding a slightly different Page Model with its default Widgets would be useful.
So add the proper XML snippet to the pom.xml, maybe just near entando-page-bootstrap-hero for increased order, like this:
<!--
This one is already in the pom.xml and it's here in this XML snippet
just to show you a good place where to put the next one
-->
<dependency>
<groupId>org.entando.entando.bundles.pages</groupId>
<artifactId>entando-page-bootstrap-hero</artifactId>
<version>${entando.version}</version>
<type>war</type>
</dependency>
<!--
This is the NEW Page Bundle, and the ONLY one you actually are
supposed to add to myportal right now
-->
<dependency>
<groupId>org.entando.entando.bundles.pages</groupId>
<artifactId>entando-page-2columns-left</artifactId>
<version>${entando.version}</version>
<type>war</type>
</dependency>Still with me?
Fine, Widget Bundles come as dependencies of Page Bundles so let's say we don't need any added Widget nor Misc Bundle.
Time to finalize the work done so far, and activate the newly added Bundles.
... that is: just start Entando with Jetty!
Well done! From now on, you will proceed using and customizing myportal until it's exactly how you want it.
Ok, actually it will be exactly how I want it. But if everything goes as expected, at the end of this journey you will be able to get your own myportal up and running and to get it how you want it for real.
Pro Tip
I wrote a bunch of useful Bash aliases, which you can find here: https://gist.github.com/trumbitta/2312873
I, for one, use
entando-startevery time, and with tab-completion it feels like heaven.
First of all, sign in to enter the Administration Area.
There's a fairly big green button just front and center in the placeholder page your browser is currently showing.
It's there to ease the very first access to the Administration Area, and soon it will be gone, so use it while there is time!
Pro Tip
The Administration Area can always be reached from
http://localhost:8080/myportal/do/login
and since version 4 it has been renewed, or I should say rebuilt almost from scratch and made responsive and — wherever applicable — mobile-first.The following are the default credentials of the hard-coded admin user:
username: admin
password: adminadmin
PLEASE PLEASE PLEASE change the password before going out in the big scary wild web!
At any time, you can change the password going in the Administration Area asadmin, opening the top right dropdown menu, and choosingMy Profile.
But wait, there's another one.
Pro Tip
While you are exploring that
My Profilethingy, insert your full name (yes, The Boss is a perfectly fine full name, but your real name might be a better choice) and an email address, then save. If that email address is a real one, and you have a Gravatar linked to it, it will show up in various places making your experience with Entando a little more personal.
Proceed to the Pages section, select Home from the Page Tree and then Edit.
Change the Page Model to one of the two coming from the installed Bundles: Bootstrap - Hero Unit, check Apply default widgets, then Save.
In another browser tab, go back to http://localhost:8080/myportal to see what has changed.
But don't linger there too much because we are not yet done with the Home.
Go back to the Administration Area, Pages, select Home again but this time choose Configure.
See that fairly long panel? It sports all the positions available in the current Page Model, and some of them are already filled with the Widgets you placed when you checked Apply default widgets.
One of those is described as Hero Unit. Follow its link.
Still with me? It gets easier, just follow these steps:
- Choose the Widget
Contents - Publish a Content Confirm-
Choosethe Content to publish:
You have two sample Contents of type Generic Content, thanks toentando-content-genericbeing a dependency ofentando-page-bootstrap-herowhich comes with the archetype you used to createmyportal.
Long story short, chooseSample - Hero UnitandConfirm - Under
Publishing settings, as the Content model, chooseHero Unit + PictureandSave
See? That's how you deal with Widgets on a Page:
- Choose a Position on the Page
- Choose a Widget
- Configure the Widget
Some Widgets don't even need to be configured!
Anyway. Time to go back to the public side of myportal and bask in the light of the freshly published Content.
Do it now, then come back for the next step.
Pro Tip
From the Administration Area, you can reach the public side in three major ways:
The general utility dropdown menu in the header of every section (which at this time should read "The Boss [you avatar]") has a handy
Go to the portallinkWhen managing Pages: the
Configure,Details, andEditinterfaces have a breadcrumbs recap of where the current Page is in the Page Tree; in that recap, next to every public Page in the path from Home to the current one, there's a planet-shaped icon which links to the public side of that PageOf course, you can always use the address bar of your browser and point it to
http://localhost:8080/myportal
Now that you know how to publish a Content, and you also just learned how to put a Widget on a Page, it's time to go for the extra mile and use that knowledge to get a fancy Latest News on the homepage of myportal.
I'll keep it straight and short this time, to help you feel like you really just learned something valuable and are able to accomplish the new mission.
- Administration Area -->
Pages - Home -->
Configure - Put the Widget
News - Latest NewsinSide 1 - Beer
Back to the public side of myportal you'll find a list of News ordered by descending Date, each with its own View Details button, the whole thing ending with an Archive button.
Take mental note of the actual presence of the two buttons, because you are going to use them pretty soon.
Supplying proper target Pages for those buttons, it's the goal of the next section.
Pro Tip
News - Latest Newscomes fromentando-content-newsand it is a User Widget: a pre-configured logical Widget created as a saved configuration from aCustom,Plugin, orStock Widget.In fact,
News - Latest Newsis created fromContents - Publish a List of Contents.
Thus, if you're feeling confident enough, you could go on experimenting by putting aContents - Publish a List of ContentsinSide 2and tinkering with its configuration by yourself, this time without going theUser Widgetroute.
In this section you'll create two new Pages, and configure them to properly act as target pages for the View Details and Archive buttons from the previous section.
This mythological animal is one of the smartest guys in Entando as a platform.
Every Content Type has one of them, and thanks to it - no matter where or if a Content is published - there will always be a Page able to show that Content to a visitor of your portal (once the authorization policies are applied).
- Administration Area →
Pages - Home →
New - Code:
read_the_news
Title:Read the News(repeat at will for each configured language)
Model:2 Columns - Left
Check:
Apply default Widgets
Configure for on-the-fly publishing
Show this page in menus
SEO: When available, use extra titles Save
If you want, take a look at Configure on the new Page and you'll see that by checking Configure for on-the-fly publishing you told Entando to put a specially pre-configured Contents - Publish a Content in the Main Position marked by a different "gears" icon and colored in green.
And this is exactly how you prepare a Page for the ever honorable job of being a Page for on-the-fly publishing.
Now, instruct the News Content Type on how to use it.
But first, a detour.
- Administration Area -->
Settings-->General - Check
Content types - Save
Going back on the main road:
- Administration Area -->
Contents-->Content types-->News-->Edit - Make sure that
Page for on-the-fly publishingis pointing toRead the News(given it's the only page properly configured for the job so far, you should find it selected as expected when you arrive there) Save
Hey, done!
Go back to the public side of myportal, reload the Home to let Entando update the links for the View Details buttons, and try to use one.
You'll end up in a Page with the following interesting characteristics:
- Page Model
2 Columns - Leftwith proper default Widgets such asNavigation - BreadcrumbsandNavigation - Vertical Menu - The Content you wanted to publish on-the-fly, rendered with the
Default content model - Document
<title>(it wasRead the News, remember) overridden on-the-fly by the title of the Content, thanks toSEO: When available, use extra titles
One button down, one left to go.
Go take a look at the configuration of News - Latest News, in order to get the expected code for the Page you are going to create:
- Administration Area -->
Widgets - Follow the link on
News - Latest News - Search until you spot
pageLinkand copy the value (it should benews)
That's the expected code for the Page to which the Archive button from News - Latest News is supposed to point.
So, now create the Page:
- Administration Area -->
Pages - Home -->
New - Code:
news
Title:News Archive(repeat at will for each configured language)
Model:2 Columns - Left
Check:
Apply default Widgets
Show this page in menus Save
That's it.
Just go back to the public Home, reload, and use the Archive button...
Bummer! The Page is empty!
Fret not, my dear, for you have to go and configure your own luck!
- Administration Area -->
Pages - Home --> News Archive -->
Configure - Put the Widget
News - ArchiveinContent 1(because it is often a very good idea to saveTop Storyfor a possible future introductory Content) Confirm
Go back to that ugly empty page, reload & rejoice for its new fulfillment.
Pro Tip
Looking lazily at the Breadcrumbs, you may have noticed that
Read the NewsandNews Archiveare sister Pages living in the same level of the Page Tree.
You may also have started wondering if havingHome-->News Archive-->Read the Newswouldn't have been a better choice.Well, as it happens, you are right.
It is better and much more clean and elegant; also, it is even better to change the titleNews Archiveto justNews, thus ending up with:
Home→News→Read the NewsSo - if you're feeling brave - it's now up to you as an exercise to delete those two sister Pages (check the Page Tree for the
Deleteoption on a Page) and re-do the steps described in this section applying the proper tiny modifications in order to get that fancier Page Tree layout.
In the previous section you learned how to take care of a Content Type (News): you created, configured, and set a Page for on-the-fly publishing.
Cool. Now go and do it all also for the Generic Content.
No need to hurry, take your time.
You'll find me here when you come back.
Seriously :) this is not optional. Laters.
Entando has always cared about Web Accessibility.
This is why we chose not to activate the great CKEditor by default.
But it is just a few clicks away. Go ahead and activated it now:
- Administration Area -->
Settings-->General -
Miscellaneous-->Choose the Hypertext Editor:-->CKEditor Save
As you may have noticed wandering through the public side of myportal, when you are logged in and a Content is directly or on-the-fly published via Contents - Publish a Content, a nice purple Edit button appears on the top left of the Content.
Using it, will gracefully land you in Administration Area --> Contents --> Edit, where you can - wait for it - edit that Content.
Pro Tip
That happens because you are in as
admin, also known as The Almighty Superuser. In real world scenarios, it's not unusual to have someEditorrole assigned to users who can only access the Administration Area and edit Contents.
Check Administration Area -->Settings-->UsersandUser Rolesand experiment for a while, if you want.
Now to the real job.
We all know those News have way too long texts when they're grouped in lists, right?
That's because their Abstract is too long.
Go on, edit some of the sample News and strip down their Abstract until you are fine with their length.
You'll find the button for saving your modifications on the bottom of the edit interface; it's the one labeled as Save and approve.
While you are there, it's not a bad idea to also try what the other buttons do.
When you are done, you will have a much nicer News - Latest News and News Archive.
One my favorite features in Entando is the embedded Search Engine.
Now that you got the basics, putting it up and running is a matter of three simple steps:
- Place a
Search Formin a suitable position (and this is already done by the Page Bundles in use, so nothing to do for you) - Create a new Page with code
search_resultand put aSearch - Search Resultin the Main Position (remember? different "gears" icon and colored in green...)
Also remember to always choose one of the Page Models coming from the Page Bundles:Bootstrap - Hero Unitor2 Columns - Left - Initialize the search index:
Administration Area -->Settings-->Reload the content indexes-->Reload contents&Reload indexes
Go back to the Homepage and try a search.
If you didn't edit the sample Contents that much, news could be a good test word.
Pro Tip
In a development environment, the search index is stored in
/target/temp/indexdir.
Thus, whenever your runmvn clean, theindexdiris gone and you'll have to rebuild the index.
Keeping that in mind, and acting accordingly, will contribute in keeping you away from mental hospitals.
In this section you'll learn the basics of overriding some default interfaces and you'all also leverage the presence of Twitter Bootstrap as a Bundle in myportal, to quickly change the look & feel.
To override one file of Entando, one does simply copy it from the sources into myportal.
Say you'd like to customize the Page Model Bootstrap - Hero Unit, currently used for the Homepage, which comes from the Bundle entando-page-bootstrap-hero.
There are a bunch of ways to accomplish this. Here's the easiest one:
- Launch
myportalwith Jetty - Copy
target/tmp/entando-page-bootstrap-hero-4_0_0_war/WEB-INF/aps/jsp/models/entando-page-bootstrap-hero.jsp
into
src/main/webapp/WEB-INF/aps/jsp/models/entando-page-bootstrap-hero.jsp - Stop and relaunch Jetty to make it aware of the new file
- Edit the new file at will and you will see the changes as expected
Do it now, because in the next section you'll be customizing that very file.
Enter the amazing Bootswatch.
Enter the even more amazing Bootswatch CDN.
Choose one swatch from the Bootswatch CDN, say Cerulean, and copy its URL for Bootstrap 2:
//netdna.bootstrapcdn.com/bootswatch/2.3.0/cerulean/bootstrap.min.css
Now open src/main/webapp/WEB-INF/aps/jsp/models/entando-page-bootstrap-hero.jsp and place a new link to that stylesheet right before the closing </head>, just like this:
...
<jsp:include page="inc/lesscss-active/lesscss.jsp" />
<jsp:include page="inc/models-common-utils.jsp" />
<link rel="stylesheet" type="text/css" href="//netdna.bootstrapcdn.com/bootswatch/2.3.0/cerulean/bootstrap.min.css" />
</head>
...Reload the Homepage and behold the switch from the default Entando Bootstrap theme to Cerulean.
Pro Tip
That was the quickest path, and a path also useful for showing you the fundamentals about overriding and customizing.
But if you try the responsive features of Bootstrap now, you'll see that something broke when we added Cerulean.
That's because the best place where to put the new stylesheet is not the file we put it in.
Try this instead:
- Delete the new
<link>element fromentando-page-bootstrap-hero.jsp- Open all the
lesscss.jspfiles you find insrc/main/webapp/WEB-INF/aps/jsp/models/inc/lesscss-activeandsrc/main/webapp/WEB-INF/aps/jsp/models/inc/lesscss-availableand subdirectories.
There must be a total of 5 files to edit.- Put the new
<link>element inside each of those files, just between the<link>forbootstrapand the one forbootstrap-responsive(or justresponsive).
That will override the look and feel of Bootstrap, while preserving the responsive part.
Here we are, at the end of the journey. You learned how to:
- Create a new portal
- Launch it
- Add some Bundles
- Publish a Content and a list of Contents
- Put a Widget on a Page
- Create and configure a Page
- Prepare a Page for on-the-fly publishing
- Activate the embedded search engine
- Quickly go to edit a Content from the public side of a portal
- Override and customize your portal
That's quite a lot of basic concepts, for such a quick journey.
You're just beginning to grasp the amazing power that comes with Entando, and the best is yet to come.
I release thee, go!
And boast a little.
You deserve it.
When you're ready to deploy myportal on a server, go read Entando in production: how to prepare a server, how to deploy your Entando based application.
Ready? Steady... Go!