Merge branch 'pull-request-182'

QuickstartGuide/en/images/readme.txt

@@ -0,0 +1 @@
+Placeholder

devGuide/en/chapters/01-introduction.markdown

@@ -110,7 +110,9 @@ Hook plugins are the recommended method of customizing the the core functionalit
 Ext plugins provide the largest degree of flexibility in modifying the Liferay core, and allow replacing essentially any class with custom implementations. This flexibility comes at a cost, however, as it is highly unlikely that an Ext plugin written for one version of Liferay will continue to work in the next version, without modification. For this reason, Ext plugins are only recommended for cases where an advanced customization is really needed and there is no other way to accomplish the same goal. Also you should make sure that you are familiar with the Liferay core to assure the Ext plugin doesn't have a negative effect on existing funcitonalities. Even though Ext plugins are deployed as plugins, the server must be restarted for their changes to take effect. For this reason, Ext plugins should not be combined with other types of plugins.
 
 ---
+
 ![tip](../../images/tip-pen-paper.png) If you have developed for Liferay 5.2 or before, you may be familiar with what was known as the *Extension Environment*. Ext plugins were introduced in Liferay 6.0 to replace the extension environment in order to simplify development. It is possible to automatically convert any existing Extension Environment into a plugin. Check the *Migrating old extension environments* section of the *Ext plugins* chapter for detailed instructions.
+
 ---
 
 ## Choosing the best tool for the job

devGuide/en/chapters/02-plugins-sdk.markdown

@@ -3,7 +3,9 @@
 Java developers have a wide variety of tools and development environments. Liferay makes every effort to remain tool agnostic, so that you can choose the tools that works best for you. For that reason, we provide a Plugins Software Development Kit (SDK) which is based on Apache Ant and may be used along with any editor or Integrated Development Environment (IDE). The chapters of this guide will use the Plugins SDK and a text editor, but you may use whatever tool you are comfortable with. In a later chapter we also introduce Liferay IDE, a plugin for eclipse that simplifies development for Liferay.
 
 ---
+
  ![tip](../../images/tip-pen-paper.png)**Tip**: If you are an Eclipse user and prefer to start working with it from be very beginning, you can read that chapter first before reading the rest of the guide.
+
 ---
 
 We discuss the following topics in this chapter:
@@ -22,7 +24,9 @@ Setting up the Plugins SDK is easy. Let's get to it.
 Setting up your environment for Liferay development is straightforward. First, you will need Liferay Portal. If you have yet to install Liferay with an application server, follow instructions in chapter *Installing Liferay* of our *Using Liferay Portal 6.1* document [http://www.liferay.com/documentation/liferay-portal/6.1/user-guide](http://www.liferay.com/documentation/liferay-portal/6.1/user-guide). Many people use the Tomcat application server for development, as it is small, fast, and takes up less resources than most other servlet containers. Although you can use any application server supported by Liferay Portal for development, our examples use Tomcat.
 
 ---
+
  ![note](../../images/tip-pen-paper.png)**Note:** In Liferay Developer Studio, the SDK is already installed and ready to use. Liferay Portal Enterprise Edition (EE) comes with Liferay Developer Studio and much more (see  [CE vs EE](http://www.liferay.com/downloads/liferay-portal/overview)). Download a [free trial](http://www.liferay.com/c/portal/register_trial_license?redirect=/products/liferay-portal/ee/30-day-trial) of Liferay Portal EE today.
+
 ---
 
 Installation steps:
@@ -38,7 +42,9 @@ Installation steps:
 2.  Unzip the archive to a folder of your choosing. Avoid using a folder name that contains spaces because some operating systems have problems running Java applications in folders with spaces in their name.
 
 ---
+
  ![tip](../../images/tip-pen-paper.png)**Tip**: By default Liferay Portal Community Edition comes bundled with many plugins. It's common to remove them to speed up the server startup. To do this, in the `liferay-portal-[version]/tomcat-[tomcat-version]/webapps` directory, delete all the directories except for `ROOT` and `tunnel-web.`
+
 ---
 
 Now that you have Plugins SDK installed, let's configure Apache Ant for use in developing your plugins.

devGuide/en/chapters/03-portlet-development.markdown

@@ -42,15 +42,19 @@ Alternatively, if you will not be using the Plugins SDK to house your portlet pr
 To resolve the dependencies for portlet projects, see the classpath entries in the `build-common.xml` file in the Plugins SDK project. You will be able to determine from the `plugin.classpath` and `portal.classpath` entries, which `.jar` files are necessary to build your newly created portlet project.
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Tip:** If you are using a source control system such as Subversion, CVS, Mercurial, Git, ... etc., this might be a good moment to do an initial check-in of your changes. After building the plugin for deployment, several additional files will be generated that should *not* be handled by the source control system.
+
 ---
 
 ### Deploying the Portlet
 
 Liferay provides a mechanism called auto-deploy that makes deploying portlets (and any other plugin types) a breeze. All you need to do is drop the plugin's WAR file into a directory and the portal will take care of making any necessary changes specific to Liferay and then deploy the plugin to the application server. This will be a method of deployment used throughout this guide.
 
 ---
+
 ![note](../../images/tip-pen-paper.png)**Note:** Liferay supports a wide variety of application servers. Many of them, such as Tomcat and Jboss, provide a simple way to deploy web applications by just copying a file into a folder and Liferay's auto-deploy mechanism takes advantage of that ability. You should be aware though, that some application servers, such as Websphere or Weblogic require the use of specific tools to deploy web applications; so Liferay's auto-deploy process won't work for them.
+
 ---
 
 Open a terminal window in your `portlets/my-greeting-portlet` directory and enter this command:
@@ -320,7 +324,9 @@ Deploy the portlet again by entering the command **ant deploy** in your `my-gree
 ![Figure 3.3: The *edit* page of My Greeting portlet](../../images/portlets-edit-my-greeting.png)
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Tip:** If your portlet deployed successfully, but you don't see any changes in your browser after refreshing the page, Tomcat may have failed to rebuild your JSPs. Simply delete the `work` folder in `liferay-portal-[version]/tomcat-[tomcat-version]` and refresh the page again to force them to be rebuilt.
+
 ---
 
 There are a few important details to notice in this implementation. First, the links between pages are created using the `<portlet:renderURL>` tag, which is defined by the `http://java.sun.com/portlet_2_0` tag library. These URLs have only one parameter named `jspPage`, which is used by MVCPortlet to determine which JSP to render for each request. You must always use taglibs to generate URLs to your portlet. This restriction exists because the portlet does not own the whole page, only a fragment of it, so the URL must always go to the portal responsible for rendering, not only your portlet but also any others that the user might put in the page. The portal will be able to interpret the taglib and create a URL with enough information to be able to render the whole page.

devGuide/en/chapters/04-theme-development.markdown

@@ -97,7 +97,9 @@ Best practice recommends that you make all your custom theme styles using only t
 Whenever you make modifications to your theme, redeploy it by opening a terminal in `themes/deep-blue-theme` and entering the command **ant deploy**. Wait a few seconds until the theme deploys, and then refresh your browser to see your changes.
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Tip:** If you wish to see changes even more quickly, it is also possible to modify your theme directly in your Liferay bundle. In our example, `custom.css` is located in `liferay-portal-[version]/tomcat-[tomcat-version]/webapps/deep-blue-theme/css`. However, for modifications made here to appear in your browser as soon as you refresh the page, you must enable Liferay Developer Mode. See the Liferay wiki for more information.
+
 ---
 
 Also make sure that you copy any changes you make back into your *_diffs* folder, or they will be overwritten when you redeploy your theme.

devGuide/en/chapters/05-hooks.markdown

@@ -136,7 +136,9 @@ First, inside `example-hook/docroot/WEB-INF/src/com/liferay/sample/hook` create
     }
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Note:** the wrapper class (`MyUserLocalServiceImpl` in this example) will be loaded in the hook's class loader. That means that it will have access to any other class included within the same WAR file; but it *won't* have access to *internal* classes of Liferay.
+
 ---
 
 Next, edit `liferay-hook.xml` inside `example-hook/docroot/WEB-INF` and add the following after `</custom-jsp-dir>`:
@@ -170,7 +172,9 @@ In addition to the capabilities of hooks already discussed thus far, you can als
     </hook>
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Tip:** as always, please check the DTD of each Liferay XML file you modify for the elements and attributes that can be included in the XML and the specified order for those elements.
+
 ---
 
 ## Other hooks

devGuide/en/chapters/06-ext-plugins.markdown

@@ -113,7 +113,9 @@ By default, several files are added to the plugin. Here are the most significant
     -   `struts-config-ext.xml` and `tiles-defs-ext.xml`: Can be used to customize the struts actions used by Liferay's core portlets.
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Tip:** After creating an Ext plugin, remove all of the files added by default that are not necessary for the extension. This is important because Liferay keeps track of the files deployed by each Ext plugin. To avoid collisions, it won't allow deploying two Ext plugins if they override the same file. Removing any unnecessary files from an ext plugin makes it easier to use alongside other Ext plugins.
+
 ---
 
 You've now created an Ext plugin and have become familiar with its directory structure and its most significant files. Now, it's time to customize Liferay Portal by developing your Ext plugin.
@@ -153,7 +155,9 @@ Your `app.server.zip.name` property should specify the path to your Liferay bund
 For example, let's specify `C:\work` as our `ext.work.dir` value. Let's say we have a Liferay bundle `.zip` file `C:\downloads\liferay-portal-tomcat-6.1.0-ce-ga1-20120106155615760.zip` which we set as the value for our `app.server.zip.name` property. We discover the *relative path* to the application server *within* our Liferay bundle `.zip` file is `liferay-portal-6.1.0-ce-ga1\tomcat-7.0.23`. So we must specify `C:\work\liferay-portal-6.1.0-ce-ga1\tomcat-7.0.23` as our `app.server.dir` property value.
 
 ---
+
 ![tip](../../images/tip-pen-paper.png) Note: Some Liferay bundles, come installed with a sample website for a fictional company called 7-Cogs. This sample website is useful for showcasing certain features of Liferay. However, once you've removed it, you don't want the Ant targets to reinstall it every time your bundle is unzipped again. To make sure this doesn't happen, unzip your bundle, delete the `{work}/liferay-portal-6.1.0-ce-ga1/tomcat-7.0.23/webapps/sevencogs-hook` folder, and then re-zip your bundle.
+
 ---
 
 Next, we'll make some changes to the Ext plugin we created and deploy it.
@@ -181,7 +185,9 @@ Here are instructions for deploying your plugin from the commandline, Liferay De
 -	*Liferay IDE / Studio:* Drag-and-drop the Ext plugin onto the Liferay server in the *Servers* view
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Tip:** The `direct-deploy` target deploys all the plugin changes directly to the appropriate directories in the Liferay application. If instead you deploy the plugin using the `deploy` target, the Liferay server needs to apply the changes from the resulting `.war` file at startup, possibly slowing down your development process. For this reason, using `direct-deploy` is the usually preferred method for deploying Ext plugins during development. But note, `direct-deploy` does not work with WebLogic Server or WebSphere application server environments.
+
 ---
 
 Upon deployment, you should get a `BUILD SUCCESSFUL` message, which means that your plugin is now being deployed. If you switch to the console window running Liferay and wait for a few seconds, you should see the message:
@@ -493,7 +499,9 @@ If you really need to change a core portal-impl class and this class cannot be r
 This strategy will help you determine what you will need to merge in the future when a new version of Liferay is released.
 
 ---
+
 ![tip](../../images/tip-pen-paper.png) This is a very advanced technique that, especially if abused, may have a high impact on the maintainability of your code. Try to look for alternatives and if you confirm that this is your only alternative try to apply it only for the short term and get in touch with Liferay's developers to apply the necessary changes to the product source code.
+
 ---
 
 ## Deploying in production
@@ -529,7 +537,9 @@ Once you have the aggregated `.war` file follow these steps on the server:
 Ext plugins have been created as an evolution of the extension environment provided in Liferay 5.2 and previous versions of Liferay. Because of this, a common need for projects upgrading from previous versions is to migrate Extension environments into Ext plugins. The good news is that this task is automated and thus relatively easy.
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Tip:** When migrating an extension environment, it's worth considering if all or at least some of the extension environment's features can be moved into other types of plugins such as portlets and hooks. Portlets and hooks are designed to meet specific needs and they are easier to learn. Additionally, they are cheaper to maintain since they often require fewer changes when upgrading to a new version of Liferay.
+
 ---
 
 The process of migrating consists of executing a target within the `ext` directory of the Plugins SDK, pointing to the old extension environment and naming the new plugin:

devGuide/en/chapters/08-apis.markdown

@@ -66,7 +66,9 @@ So, now that you know how to look up the service classes, let's look at the foll
 This JSP code invokes static method `getOrganizationStatsUsers()` on the `-LocalServiceUtil` class `BlogsStatsUserLocalServiceUtil`.
 
 ---
+
 ![note](../../images/tip-pen-paper.png)**Note:** Invoking the services in this way avoids permission checks. So, if you want to ensure permission checks are performed, even from a local context, then you should use the remote variant of the API.
+
 ---
 
 We'll look at invoking services remotely, next.
@@ -92,7 +94,9 @@ If the IP address of the machine on which the batch job is running is listed wit
 ![Figure 8.1:  Liferay SOA's first layer of security](../../images/soa-security-layer-1.png)
 
 ---
+
 ![note](../../images/tip-pen-paper.png)**Note:** The `portal.properties` file resides on the portal host machine and is controlled by the portal administrator. Portal administrators can configure security settings for the Axis Servlet, the Liferay Tunnel Servlet, the Spring Remoting Servlet, the JSON Servlet, the JSON Web Service Servlet, and the WebDAV Servlet. The [Configuring Liferay's Properties](http://www.liferay.com/documentation/liferay-portal/6.1/user-guide/-/ai/configuring-liferay-s-properties) section of *Using Liferay Portal 6.1* describes these properties.
+
 ---
 
 The **second layer of security** is Liferay's *security model* that it uses for every object in the portal. The user ID that accesses the services remotely must have the proper permission to operate on the objects it will be accessing. Otherwise, a remote exception will be thrown. The Portal Administrator will need to make use of Liferay's usual means of granting users access to these resources. For example, say that a Documents and Media Library folder called *Documents* has been set up in a site and that a role has been created called *Document Uploaders* which has the rights to add documents to this folder. Your batch job will be accessing Liferay's web services in order to upload documents into this folder. In order for this to work, you will have to call the web service using the user ID of a user that is a member of this group (or the user ID of a user that has individual rights to add documents to this folder). Otherwise, the user will be prevented from using the Web Service.
@@ -112,7 +116,9 @@ For example, to get Organization data using a user that has the ID of *2* and a
 	http://2:test@localhost:8080/api/secure/axis/Portal_OrganizationService
 
 ---
+
 ![note](../../images/tip-pen-paper.png)**Note:** In old Liferay versions you could access those services by using `http://localhost:8080/tunnel-web/axis`, however in Liferay 6.1 this path has changed and when you type it, you are redirected to the new one.
+
 ---
 
 The authorization type specified for your portal's company dictates the authorization type you must use to access your web service. The portal administrator can set the security authentication type to either of the following:
@@ -161,7 +167,9 @@ You can view a listing of the services deployed on your portal by opening your b
 ![Figure 8.3: UserGroup Web Service listing](../../images/wsdl-summary-listing.png)
 
 ---
+
 ![note](../../images/tip-pen-paper.png)**Note:** Liferay's developers use a tool called Service Builder to expose their services via SOAP automatically. If you are interested in using this tool for your own services, find out more about Service Builder in chapter *Liferay Frameworks*.
+
 ---
 
 Each web service is listed with its name, operations, and a link to its WSDL file. The WSDL is written in XML and provides a model for describing and locating the web service.
@@ -740,7 +748,9 @@ To pass inner parameters, just specify them using a 'dot' notation. That is, spe
 Inner parameters are not counted as *regular* parameters for matching methods and are ignored during matching.
 
 ---
+
 ![tip](../../images/tip-pen-paper.png)**Tip:** Use inner parameters with object parameters to set inner content of created parameter instances!
+
 ---
 
 ### Returned values