Official Guide IN ACTION Richard Sezov, Jr. FOREWORD BY BRIAN KIM MANNING Liferay in Action Licensed to Henrique Simões de Andrade <[email protected]> Licensed to Henrique Simões de Andrade <[email protected]> Liferay in Action The Official Guide to Liferay Portal Development RICH SEZOV, JR MANNING SHELTER ISLAND Licensed to Henrique Simões de Andrade <[email protected]> To my wife: Yo Deborah! I did it! For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact Special Sales Department Manning Publications Co. 20 Baldwin Road PO Box 261 Shelter Island, NY 11964 Email: [email protected] ©2012 by Manning Publications Co. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps. Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid-free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without elemental chlorine. Development editor: Lianna Wlasiuk Manning Publications Co. Copyeditor: Tiffany Taylor 20 Baldwin Road Proofreader: Melody Dolab PO Box 261 Typesetter: Marija Tudor Shelter Island, NY 11964 Cover designer: Marija Tudor ISBN: 9781935182825 Printed in the United States of America 12345678910–MAL–17161514131211 Licensed to Henrique Simões de Andrade <[email protected]> brief contents PART 1WORKING WITH LIFERAY AND PORTLETS ....................... 1 1 ■ The Liferay difference 3 2 ■ Getting started with the Liferay development platform 30 PART 2WRITING APPLICATIONS ON LIFERAY’S PLATFORM ....... 63 3 ■ A data-driven portlet made easy 65 4 ■ MVC the Liferay way 91 5 ■ Designing your site with themes and layout templates 128 6 ■ Making your site social 154 7 ■ Enabling user collaboration 176 PART 3CUSTOMIZING LIFERAY............................................. 209 8 ■ Hooks 211 9 ■ Extending Liferay effectively 241 10 ■ A tour of Liferay APIs 263 v Licensed to Henrique Simões de Andrade <[email protected]> vi BRIEF CONTENTS Licensed to Henrique Simões de Andrade <[email protected]> contents foreword xiii preface xv acknowledgments xvii about this book xx about the cover illustration xxiv PART 1WORKING WITH LIFERAY AND PORTLETS ........... 1 The Liferay difference 3 1 1.1 The Java portal promise: from disappointment to fulfillment 4 The Java portal disappointment 6 ■ Liferay keeps the Java portal promises 8 1.2 Getting to know Liferay 9 Liferay is an application aggregator 10 ■ Liferay is a content manager 12 ■ Liferay is a collaboration tool 14 ■ Liferay is anything you want it to be and any way you want it to look 15 What has this little exercise accomplished? 17 1.3 How Liferay structures a portal 18 The high-level view 18 ■ Adding content to a collection with pages 20 ■ Configuring a portlet’s scope 20 vii Licensed to Henrique Simões de Andrade <[email protected]> viii CONTENTS 1.4 Getting around in Liferay 23 Pin icon 24 ■ Add menu 24 ■ Manage menu 24 Toggle Edit Controls 26 ■ Go To menu 26 ■ User Account 26 1.5 Imagining your site in Liferay 26 Asking the right questions 27 ■ Defining and categorizing collections 28 ■ Designing content 28 1.6 Summary 28 Getting started with the Liferay development platform 30 2 2.1 Installing Liferay and the Plugins SDK 31 Installing the Java SDK 32 ■ Installing a Liferay bundle 33 2.2 A crash course in Liferay server administration 35 Removing the sample web site 35 ■ Setting up a database 35 Connecting Liferay to the SQL database 37 2.3 Setting up the Plugins SDK 38 Installing Ant 38 ■ Installing the Plugins SDK 39 Configuring the Plugins SDK 39 ■ Configuring a non-Tomcat application server 41 2.4 Developing a portlet plugin 42 Creating a portlet plugin: Hello World 43 ■ Deploying the Hello World plugin 43 2.5 Making Hello World into Hello You 45 Anatomy of a portlet project 46 ■ Configuring Hello You 47 Portlet initialization and implementing View mode 49 ■ URLs in portals are different 52 ■ Implementing Edit mode 53 2.6 Deploying and testing your portlet 57 Changing the portlet’s category and name 58 ■ Telling Liferay about a renamed portlet 60 2.7 Summary 61 PART 2WRITING APPLICATIONS ON LIFERAY’S PLATFORM ...................................... 63 A data-driven portlet made easy 65 3 3.1 Introducing Inkwell: a case study 65 Company profile: Inkwell 66 ■ What Inkwell needs in a web site 67 ■ Inkwell’s high-level portal design 67 ■ Inkwell portal phase 1 requirements 68 Licensed to Henrique Simões de Andrade <[email protected]> CONTENTS ix 3.2 Designing the Product Registration portlet 69 A blueprint of the portlet 69 ■ Designing the database tables 70 ■ Defining portlet modes and generating the project 72 3.3 Generating DB code with Service Builder 72 Filling a definite need 73 ■ Creating the service.xml file 75 Running Service Builder 77 3.4 Creating a buffer to the persistence layer 78 Why layering is important 78 ■ Using two layers for persistence 79 ■ Implementing the DTO layer 80 3.5 Service Builder in action 84 Defining table relationships 84 ■ Sharing services 87 Adding registered users and their products 88 3.6 Summary 90 MVC the Liferay way 91 4 4.1 Using Model-View-Controller 92 Edit mode? What Edit mode? 93 ■ MVC according to Liferay 95 4.2 Configuring the portlet project 96 Defining portlets in your deployment descriptors 97 ■ Having one location for JSP dependencies 99 4.3 Creating a form with AlloyUI taglibs 102 Getting started with AlloyUI tag libraries 102 ■ Providing feedback and messages 105 ■ Translating messages to multiple languages 108 ■ Validating user-submitted forms 109 Displaying data with the search container 111 ■ Using the search container to present your data 111 ■ Editing and deleting data 114 ■ Protecting data with Liferay permissions 116 ■ Pointing to the permissions configuration 116 ■ Configuring Liferay permissions 117 4.4 Generating different field types with AlloyUI taglibs 120 Generating date pickers 121 ■ Selecting data with AlloyUI taglibs 122 4.5 Using Liferay’s MVC makes your portlets simpler 124 4.6 Summary 126 Designing your site with themes and layout templates 128 5 5.1 Understanding themes and their structure 129 Generating a theme project 131 ■ Deconstructing a theme 131 Licensed to Henrique Simões de Andrade <[email protected]> x CONTENTS 5.2 Understanding theme markup, CSS, and JavaScript 132 How markup works in a theme 133 ■ Using CSS in themes 134 ■ Using JavaScript in themes 135 5.3 Reaping the benefits of Alloy UI 136 You get components 136 ■ You get good design 137 Using Liferay custom JavaScript 138 5.4 The liferay-look-and-feel.xml file 140 Limiting themes by company 140 ■ Modifying the default paths 141 ■ The <template-extension> tag 142 Conditional settings 142 ■ Theme security and roles 144 Color schemes 144 5.5 Understanding theme conventions 146 Using Liferay’s styling conventions 146 ■ Using Liferay’s CSS coding conventions 148 5.6 Designing a page with layout templates 149 Creating layout template projects 149 ■ Anatomy of a layout template 150 5.7 Inkwell implementation 152 5.8 Summary 152 Making your site social 154 6 6.1 Social networking: why is it important? 155 Allowing users to connect with each other 156 ■ Expanding your reach beyond your own site 156 ■ Creating a dynamic, more positive user experience 157 6.2 Installing Liferay’s social networking portlets 158 6.3 Understanding Liferay’s social features 158 Relating with others 159 ■ Publishing activities 159 Sending social requests 159 6.4 Using profile pages 160 Identifying a portlet 161 ■ Defining content for public and private pages 162 6.5 Friends, Romans, and countrymen: they’re all social relations 164 Social relations aren’t security 164 ■ Coding for relationships 164 6.6 Implementing social activities in your portlets 167 Adding an activity in the service layer 168 ■ Giving the Activities portlet an interpretation of a custom activity 172 Licensed to Henrique Simões de Andrade <[email protected]> CONTENTS xi 6.7 Summary 175 Enabling user collaboration 176 7 7.1 Building a collaborative app: a slogan contest 178 7.2 Adding assets to your applications 179 Adding assets with entities 180 ■ Using asset renderers to publish your data 184 7.3 Running your data through a workflow 188 Understanding the flow of Liferay workflow 189 ■ Workflow- enabling your services 190 ■ Handily handling workflow 191 ■ Portal-wide language properties 193 7.4 Tagging and categorizing content 196 Choosing between tags and categories 196 ■ A tag for tags and a tag for categories 197 7.5 Adding discussions and ratings 199 7.6 Creating custom queries using SQL 200 Crafting your query 201 ■ Making your own finder 202 Displaying custom columns in a search container 204 7.7 Summary 206 PART 3CUSTOMIZING LIFERAY ................................. 209 Hooks 211 8 8.1 What is a hook? 212 An easier customization paradigm 213 ■ Hook basics