Actions

J1.5

Difference between revisions of "Adding view layout configuration parameters"

From Joomla! Documentation

m (Fixed typo & corrected name->title)
 
(11 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{review}}
 
 
==Background==
 
==Background==
 
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.   
 
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.   
Line 16: Line 15:
 
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?
 
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====
 
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!
 
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!
  
<h2>Template names, description, parameters</h2>
+
==Template names, description, parameters==
 
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.
 
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!
 
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:
 +
<source lang="php">
 +
function __construct() {
 +
$config = array();
 +
$config['layout'] = 'bookslayout';
 +
parent::__construct($config);
 +
}
 +
</source>
  
 
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:
 
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:
Line 45: Line 56:
 
</source>
 
</source>
  
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 [[Standard parameter types]] for information on defining parameters.
+
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|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.
 
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.
Line 51: Line 62:
 
==Final touches==
 
==Final touches==
 
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!
 
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!
[[Category:Development]]
+
 
 +
 
 +
[[Category:Archived version Joomla! 1.5]]

Latest revision as of 14:08, 23 May 2013

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

Contents

Background

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

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

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

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

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!