J1.5

Adding view layout configuration parameters

From Joomla! Documentation

(Redirected from Adding view layout configuration parameters)

Background[edit]

When creating views for a custom component, you can create a series of .xml files that will both describe the view and allow administrators to configure the view as they require. The .xml files are used by the com_menu core component (ilink.php) to create the menu trees that are shown when an administrator creates a new menu item.

View title and description[edit]

First give a title and description to your view. This is done by including a metadata.xml file in the view directory:

<?xml version="1.0" encoding="utf-8"?>
<metadata>
        <view title="CAST_VIEW">
		<message><![CDATA[CAST_VIEW_DESC]]></message>
	</view>
</metadata>

The 'title' element is shown as the 1st level entry under your component name when a new menu item is created. The 'message' element is the descriptive tool tip that is shown when the mouse hovers over the 'title' element. The example is using JText placeholders for the title and message. Just add the corresponding tags to your language definition files. You did create them didn't you?

Hiding a view from the menu[edit]

If you don't want this view to be selectable for a new menu item, then add the hidden="true" parameter to the view element (e.g. <view title="CAST_VIEW" hidden="true">). You can also hide a view by using an underscore '_' in the name. Be careful with naming your views or you can spend hours trying to figure out why it doesn't appear in the new menu item tree!

Template names, description, parameters[edit]

You can also create .xml files for the individual files in the tmpl folders. This is a cool way to have a name other than 'default' show up in the new menu item tree. Make sure that the name of the .xml file is the same as the name of your template file. I.E. if your file name is default.php, then your xml file name is default.xml. Its probably more productive to name your template files something other than default. That way, when you have 10 of them open in your favorite IDE, you won't get totally confused as to which file you are editing. That also avoids the nightmare of uploading the wrong file to the wrong directory!

These will also be hidden by including an underscore '_' in their name. This is a bit of a gotcha. Also ensure the filenames for these and the layotus are in lower case. CamelCase does not work for these.

Note: To use a temp/layout file name other than 'default', pass a configuration array to the __construct function parent in the view.html file. EG:

	function __construct() 	{
		$config = array();
		$config['layout'] = 'bookslayout';
		parent::__construct($config);	
	}

The .xml file for the template can be very simple with just a title and message or very complex with basic and/or advanced parameters:

<?xml version="1.0" encoding="utf-8"?>
<metadata>
	<layout title="STANDARD_CATEGORY_LAYOUT">
		<message>
			<![CDATA[STANDARD_CATEGORY_LAYOUT DESC]]>
		</message>
	</layout>
	<state>
		<name>STANDARD_CATEGORY_LAYOUT</name>
		<description>STANDARD_CATEGORY_LAYOUT_DESC</description>
		<url>
		</url>
		<params>
		</params>
		<advanced>
		</advanced>
	</state>
</metadata>

See components\com_content\views\frontpage\tmpl\default.xml, or components\com_content\views\section\tmpl\default.xml for examples of how to specify both basic and advanced parameters for your views. See also J1.5:Standard parameter types for information on defining parameters.

You can also add the hidden="true" to the layout element if you don't want this particular template file to be selected as a new menu item.

Final touches[edit]

Remember to create JText language definitions for your titles and messages so they can be easily translated. Have fun giving your views cool names and descriptions for that final bit of polish on your custom component!