The Journal portlet is used to create all CMS content. Without creating content through the Journal portlet, the Journal Articles and Journal Content portlets are useless. This portlet allows writers to easily edit content displayed on web pages without having to sort through complex code.
Before getting into the details of how to use the Journal portlet, it is useful to understand structures, templates, and articles; they are the backbone of the Journal portlet's functionality.
Structures define the type and number of content pieces (e.g. text, text area, images, selection lists, etc.)
Templates determine how content pieces will be arranged or laid out
Articles are where each content piece is populated with actual text and images
The point of a structure is to unify journal articles with the same numbers and types of items. For example, a Management Bio section of a website might have ten biographies, each requiring an image for the executive headshot, a text for the headline, and a text area for the main biography. A structure would be created with one image, one text, and one text area, each named accordingly. This allows writers to create the individual bios and other texts without needing to recreate the page structure for each biography.
Designers can create several templates for one structure to allow for a variety of presentations or they can give writers discretion in deciding the best layout.
All specific text and images are entered when a user adds or edits an article. This is also where a user chooses the layout based on the templates affiliated with a structure. Since multiple templates can be associated to a structure, the user can select the template that formats their article the way they want. Though articles normally have an associated structure and template (see SAMPLE-XSL-ARTICLE), it can also be a simple article without any associations (see SAMPLE-SIMPLE-ARTICLE).
Below is an example clarifying the definitions given above:
The structure in this case lists out the six content pieces:
One text element named "headline" (1)
Three text area elements named "body-text" (4), "caption-1" (2), and "caption-2" (6)
Two image elements named "image-1" (3) and "image-2" (5)
The XSL template for this example would specify where the headline, text areas, and images should go. It places the captions to the sides of the images. Another template can be made for the same structure that has the captions below the images.
The article is the actual content that uses the template and structure. This particular article is about the alleged effects of professional football broadcasts on the behavior of the children who watch them. Two photos are uploaded and body text and headline are filled in. Another article may be generated using the same template and structure discussing the equipments used for fly fishing.
It should be noted that the proper order for creating an article from start to finish is:
Create the structure to set the fields that content will be entered.
Create the template to associate with the structure to define the layout of the content in question.
Create the article with the hard-coded content that will be displayed on the page, choosing the proper structure and template to be used for the article.
To add a structure, first click on the Structures tab, then click on the Add button. The structure creation page will be displayed.
Give your structure an ID or have it auto-generate one. It is recommended that you choose your own ID so that the structure will be easier to identify when associating it with templates and articles. Please note that the ID must be unique. The convention is to separate words in the ID with a hyphen, e.g., “BASIC-STRUCTURE-NAME.‿ The structure ID can not be changed once your structure has been saved, so be sure that the ID is exactly how you would want it to appear.
Give your structure a clear name and description because these fields are also used for identification of the structure.
To start adding fields to the structure, click the Add Row button. This will show a new field where you can enter a name and a content type for this field (image, text, boolean flag, etc.). Those comfortable with XML or HTML can edit the XSL directly by clicking Launch Editor. Both methods of adding/editing elements will work, and both can be used in the same session. One simple approach is to add a few elements using the GUI and then to edit the XML directly (which will contain the syntax for the already added elements and can be copy-pasted).
Keep in mind that all names of fields must be one word—a description such as “Content Title‿ would not be allowed. To name a field using multiple words, put a dash in between words to prevent confusion, such as “content-title.‿
From the Selection List and Multi-Selection List, press the
button to add extra options to the lists, and use the 
and 
buttons to move the options up and down on the display for the article.
Once all the fields have been added to the structure, click the Save button, located above the XML Schema Defintion tab. If no error messages appear, the structure has now been created and can be associated to templates.
To edit an existing structure, go to the Structures tab. There you will see a list of existing structures with pagination and an area to search for structures by ID, name, and/or description. You can use either method to locate the structure you wish to edit. Before editing the actual structure, it is advisable to view the associated articles and templates because they can potentially be affected by any changes made to your structure. You can view associated articles (
) and templates (
) by clicking on their respective icons. When you are done viewing associated articles and templates, find the structure again using either method above. Click on the Structure ID, description, or the Edit icon (
) to display the editing screen, shown below.
In the edit screen, you can edit anything in the structure except for the structure ID, which can not be changed once the structure has been created.
Editing the name and description will not affect other features of the Journal portlet, but adding, deleting, and modifying fields will affect the templates and articles that are associated with the structure. It is advisable to backup the current XML file first by clicking the Download button so that it will be easy to revert to your old structure if necessary.
If you add fields, the articles associated will have extra fields for additional content. If you delete fields, associated content and articles will be deleted. For example, notice that the structure above has a “content-title‿ field. Now look at the article below that uses a structure that has something in that field.
When you delete the field from the structure (content title in this case), either by deleting the row or deleting it through the editor, the associated article will not show the field. See figure below.
So when you delete fields, be certain that associated articles no longer need those fields. This also applies if you rename a field; there will be a new field inside the article with that name and field type, but the content that was in the old field will be gone. For an article to display properly, the template layout must also be changed when fields are added or modified.
When all changes have been made, click the Save button to save your changes.
To delete a structure, you must first delete all articles and disassociate or delete all templates associated with that structure. First search for the structure you wish to delete, such as COMPANY-CASE-STUDIES, using the same method as step 1 of section 3.2.2. To delete all articles, first click the View Articles icon (
), which takes you to a view of all associated articles, shown below.
The screen above shows what filter was used to find the articles. Edit or delete all of these articles. To delete, click the Delete icon (
) next to the article you wish to delete.Once all articles have been edited or deleted, go back to the Structures tab and find the structure you wish to delete. Click on the View Templates icon (
) to take you to a view of all associated templates.Edit or delete all of these templates. To delete, click the Delete icon (
) next to the template you wish to delete. To edit, begin by clicking the Edit icon () next to each template. Inside the edit template screen, change the structure by clicking the Select button next to the Structure field so that it no longer uses the structure you wish to delete. Click the Save button when you have selected a new structure for the template to be associated with.
Once all articles and templates have been disassociated from the structure, search for the structure once again in the Structures tab, then click the Delete icon (
) next to that structure.
To add a template, first click on the Templates tab, and then click the Add button. If you already know which structure this template is associated with, you can create the template by clicking the Structures tab, finding the associated structure, and then clicking the Add Template icon (
). Both examples are shown below.
The template creation page appears. Give your template an ID or have it auto-generate one. Refer to step 2 of section 3.2.1 for template ID recommendations. Template IDs must be unique.
Give your template a clear name and description because these fields are also used for identification of the template.
Since articles have to select a structure before choosing a template (further described in section 3.4.1.), all created templates have to be associated with a structure. If you have already associated this template to a structure, the structure name will appear in the Structure field. Otherwise, click the Select button to find the structure that this template will be associated with. This will open up a screen with all the structures. Click the Choose button next to the structure that you wish to associate this template with.
To edit the actual template layout content, you can use one of two methods. To start a completely new template, click the Launch Editor button to open up the editor shown below.
If you have an existing template on your local machine, click the Browse button to search for the file, and load that file as the code for this template.
Note that you can choose the template to be in either XSL or VM format, so a working knowledge of one of these is required for creating templates. One way to make simple templates is to look at the existing templates that Liferay provides out-of-the-box and follow the syntax. If the template is loaded from your local machine, make sure you choose the correct language type in the menu.
If you want a small image to represent the template in the description field, you can link the image URL or upload it from your local machine. Be sure to select Yes in the menu in the “Use Small Image‿ field.
Click Save when you are finished creating your template. If no error messages appear, the template has been created and can be used as layouts for articles.
To edit an existing template, go to the Templates tab. You will see a list of existing templates with pagination and an area to search for templates by ID, name, and/or description. You can use either method to locate the template you want to edit. Before editing the actual template, it is advisable to view the associated articles because their layout will be affected by any changes made to your structure. After editing the template, you can view these articles with the new template layout. You can click on the View Articles icon (
) to view associated articles. When you are done viewing associated articles, find the template again using either method above, and then click on the Template ID, description, or the Edit icon () to enter the editing screen, shown below.In the edit screen, you can edit anything in the template except for the template ID, which can not be changed once the template has been created.
Editing the name and description will not affect any other features of the Journal portlet but modifying the script will affect the articles that are associated with the template. It is advisable to backup the current XSL or VM file by clicking the Download button so that it will be easy to revert to your old template script if necessary. To prevent unexpected behavior in the design, it is advised that only users with good working knowledge of XSL or VM modify these scripts.
When all changes to the template have been made, click the Save button to save your changes.
To delete a template, you must first disassociate or delete all articles associated with that template. First search for the template you wish to delete using the same instructions from step 1 of section 3.3.2. To disassociate/delete all the articles, click the View Articles icon (
). A view of all associated articles will be displayed.
To delete an article, click the Delete icon (
) next to the article you wish to delete. To edit an article, begin by clicking the Edit icon () next to each article. Inside the edit article screen, change the template by using radio buttons. If there are no other templates associated with the structure used, you must either create a new template for that structure or delete this article. Click the Save button when you have selected a new template for the associating article.Once all articles have been disassociated from the template, search for the template again in the Templates tab, then click the Delete icon (
) next to that template.
To add an article, click on the Articles tab, and then click the Add button.
If you already know which structure or template this article is associated with, you can create the article by going to the Structures or Templates tab. Find the corresponding structure or template, and click the Add Article icon (
).
The article creation page appears as shown below. Give your article an ID or have it auto-generate one. Refer to step 2 of section 3.2.1. for article ID recommendations. Article IDs must be unique.
Give your article a title. This field is also used for easier identification of the article, so a clear, concise explanation is recommended.
In the article tab screen shown above, choose the Type category that the article will reside in. This will help make it easier for users to make manual searches of articles and organize articles.
Next, pick a display and expiration date. The default setting does not set an expiration date.
Next, choose the structure and template that this article will be associated with. If none are selected, the article will be a simple article by default, and the display will be what is written in the content box. If you added the article through the structure or template tab, there will already be a structure and template choices, which you can further edit if you choose. To choose the structure, click the Select button next to the Structure field. If you have a pop-up blocker installed, you may need to turn it off because it can prevent the Structure list from appearing.
Once the structure and template has been chosen (if at all) the content fields will show up, and you can fill in the content in the fields given. Once all the content has been filled out, click the Save button to create the article.
Once you save the article, it will return you to the main Articles tab. To approve the article and allow the Journal Content article to display it, search for the article you just created. Click the Edit icon (
) for that article, and then click the Approve button.
To edit an existing article, go to the Articles tab. You will see a list of all existing articles with pagination and an area to search for articles by ID, Version, Title, Content, Type, and/or Status. You can use any of these methods to locate the article you want to edit. When you find the article , you can either click on the article ID or click on the fields to view a preview of the article.
Click on the Edit icon (
) to enter the editing screen. In this screen you can edit anything in the article except for the article ID, which can not be changed once the article has been created. You can choose to increment the version every time you edit the article to help all users see how often an article has been changed. If you feel that the changes you are making are very minor, you can choose not to increment it. Note that if you change the expiration date before the current date, you will no longer be able to select that article for use in the Journal Content portlet.When you are done editing the changes, click the Save button to finalize any changes you have made. To preview your changes, search for the article again and click on the article, or go to the article edit screen and click the Preview button, shown in the picture above.
To delete an article, search for the article as instructed in step 1 of section 3.4.2. Once you have found the article, click the Delete icon (
).If you do not wish to delete the article but do not want the article to be available for display through the Journal Content portlet, you can edit the expiration date of the article so that it is set to before today’s date. Refer to section 3.4.2. to edit the expiration date of an article.