I've learned a lot while writing Liferay in Action. I'm going through my final edits now before the book goes through its production cycle, tightening up the prose and making sure everything is as clear as I can make it. Once of the things I've had a lot of fun doing is the crutch.

What is a crutch? It's a technique whereby you introduce a concept with an anecdote, a story, or an analogy of some kind that speaks to the topic you're about to discuss. It's supposed to draw the reader in and get him or her interested.

You may not know that though I work for Liferay and have done software development for many years, my degree is not in Computer Science: it's in English. So I like to write. My favorite kind of writing is of the creative sort, and I don't get to do it often. So with Liferay in Action, the concept of a crutch was something that I kind of got really into doing. In fact, you might say that I tended to get carried away with it.

Below is an example of a crutch that I had to cut out of the book. It was intended to introduce the concept of Ext plugins, but instead it took on a life of its own and tended to be a bit distracting. If it were to stand on its own, I would give it the title below. And if you'd like, let me know in the comments if you think this would have worked or if indeed it is distracting.

Enjoy!

The Chocolate Monster

Once upon a time, a man woke up after having a strange dream. In that dream, he found himself face to face with a being he couldn't identify, who was glowing with an odd, brown-mixed-with-gold hue. The being's face was obscured, and its body consisted of an amorphous, flowing robe that hid its actual shape. Before he could react to the presence of such a unique person, the being spoke.

“I am not long for this existence. Before I pass into whatever comes next, I must bequeath my unique ability to someone else. I have chosen you.”

“Uh—wow. Um, thank you,” the man said. “Who are you?”

“Who I am does not matter. What I am giving you does. Use it wisely. Use it well,” stated the being, dramatically.

With that, the man found himself enveloped in a bear hug. That odd brownish-goldish glow surrounded him, and he could smell something—something familiar, but for some reason in the dream, he couldn't figure out what it was. The being squeezed harder and harder, until the man began to have trouble breathing. He tried to choke, “Stop!” but to no avail. As the final breaths of air escaped his mouth, he panicked and started to squirm. The smell—whatever it was—was overpowering. How could he smell when he couldn't breathe? He wasn't sure, but black spots appeared before his eyes, and he knew he was about to pass out due to a lack of oxygen. Gasping violently, he screamed, and—

He woke up. And now he could identify the smell: chocolate. Weird.

The rest of the day proceeded normally, until the man came home from work. Living alone, he was accustomed to keeping pretty much whatever schedule he wanted, so it was rather late when he got back. His stomach growled as he stood in his kitchen pondering what to make himself for dinner, and it occurred him that it might be nice to have a snack. He'd been thinking about that dream all day—and also the smell of chocolate. Boy, it would be nice to have a piece of chocolate right now.

Wait, what was that? He opened his right hand, and inside was a piece of chocolate. How did that get there? He smelled it. Yup, it was definitely chocolate. Gingerly, he bit into it. Tasted like chocolate too. So he ate it.

Of course, once you've had one small piece of chocolate, you sort of want another one, don't you? The man did. Before he could reach for the handle of his refrigerator to find some, however, there was another piece of chocolate in his hand.

“Wha—?” escaped the man's mouth. He put the piece of chocolate down on the counter and stared at it, his heart pounding. What was going on here? He placed his hand out, palm up.

“Okay, let's try something,” he said out loud, though nobody else was in the room. He closed his eyes and thought to himself, I want a piece of chocolate! He opened his eyes. There was a piece of chocolate in his hand.

“No way!” he shouted, again, to nobody in particular. Over the course of the night, he found that he could make any kind of chocolate he wanted. He could make dark chocolate. He could make milk chocolate. He could make liquid chocolate. He could make it in any shape, size, or consistency he wanted.

He was a super hero! Well, not really.

He started making chocolate for his friends—any kind they wanted, as much as they wanted. He made chocolate for his town. He made things out of chocolate that really shouldn't be made out of chocolate—like buildings, statues, and even monuments. He became rich by selling his chocolate. Children loved him. Women adored him. Candy companies despised him.

He married, divorced, and married again. Why? Because his wives initially loved the chocolate and the power and the money—but not him. He wasn't the same man he'd been before he had his chocolate power: when you really got to know him, the man he'd become really wasn't all that lovable. For instance, over the years he grew rather fat as he consumed a lot of his own chocolate, but he wasn't a nice fat, or a jolly fat. Instead, he was a mean fat, unkempt, and unwashed. He was also rather selfish—if he wanted something, he could generally get it through his chocolate power. And he did. When someone he knew needed something, he could give it to them if it could be obtained through chocolate, because that was easy. If it took more work than that, well, he had more important things to do. What was most important was that he was famous as the only man in the world who could make chocolate from nothing.

At least, he thought it was nothing. He started noticing the symptoms after he made his first mountain of pure chocolate, up in the Pocono mountains in Pennsylvania. He started to think that maybe his skin had taken on somewhat of a more golden hue. Over the years it got darker and darker, until his facial features were obscured. He became a recluse, rarely seen. He wore dark, hooded robes so that no one could see the change in him. It seemed that the more chocolate he made, the more he changed, and the weaker he became. It was as though using his power drained his life force prematurely somehow. But still he made chocolate.

His greatest achievement, to his mind, was made during this period of his life. He made a chocolate island, floating in the Pacific Ocean. It was his own world, one which could be used and replenished at his every whim. At first he thought this would gain him praise from the world, but instead he received only criticism. As the mountains of chocolate he'd made elsewhere had begun to melt, the surrounding environment suffered. Birds, toads, rabbits, and other animals became mired in sticky goo as the chocolate melted and flowed down. Streams and rivers were choked with pieces of chocolate. If that was happening with the mountains, what could happen with the island?

His skin went from dark gold to dark brown, the color of chocolate. Then it began to glow in that familiar brownish-goldish hue that he remembered from his dream, and he somehow knew that this signaled the end of his life. It had only been ten years since he'd been given his gift. He sat, in a chocolate castle he'd built for himself, alone on his chocolate island, and pondered the meaning of it all. Why wasn't he happy? Why did people shun him? What could he have changed? He fell asleep.

In his dream, he felt an urgency. He had to give away his power to someone else in the dream—because this wasn't a dream, really. He was being given a glimpse into another dimension, another universe, where other people lived. He zeroed in on one house, in a particular neighborhood, and found the person living there. He didn't have time for niceties; he had to do this quickly.

“I am not long for this existence,” he said to the person. “Before I pass into whatever comes next, I must bequeath my unique ability to someone else. I have chosen you.”

The other person sputtered something, but the man had no time to talk. He had to do this now, before it was too late. He could only give the person one sentence of advice, so it had to be a good one—a better one than he'd been given.

“I am giving you a great power—use it responsibly, and for the good of others.”

With that, he embraced the other person as hard as he could, feeling his power flowing from him into the other person.

The man died in his sleep. The other person woke up. That person is you. The power, however, is not necessarily based on chocolate.

When given a great power, it's wise to consider how best to use it. Can it be used for everything? Probably not, and if you try, you'll almost certainly make a mess. Can it be abused? Definitely. Can it be used for good, and optimally, so that it provides the best benefit for the most people? Absolutely, but that will take a lot of thought to accomplish.

Ext plugins are like this. When I first started working with Liferay, we didn't have all these great plugin types you've already seen. Instead, everything, and I mean everything, had to be done using the Extension environment, or Ext environment for short. Ext plugins, as they are now called, give you unlimited power within Liferay to do whatever you want. You could implement your entire site using only a single Ext plugin if you wanted to. But that is not the best way. In fact, more likely than not, if you do it that way, you'll make a big mess. So Ext plugins need to be used responsibly. We're going to look at two ways you can use Ext plugins responsibly:

1. Customizing Struts actions of internal Liferay portlets

2. Modifying core Liferay behavior that can't be done with hooks

For the first use case, I'll be able to show you an example. For the second, since there is so much core functionality within Liferay, what I'll do is list some common things people do with Ext. Then I’ll give you an overview of Liferay's architecture by tracing exactly what Liferay does from receiving a browser request to rendering a page. Since I can't be sure what exactly you may be wanting to modify, this should hit a lot of internal Liferay code, giving you the tools to determine your strategy for making Liferay do what you want.

Once we've looked at Liferay's architecture, we'll discuss some best practices for Liferay development, to help you decide when to use each plugin type. We'll round out this discussion by helping you decide if your changes would be something you could even give back to the product as open source!

So without further ado, let's jump right into Ext plugins.

[end of crutch, rest of chapter begins]