Joomla! Documentation - User contributions [en]

Rules form field type

2011-04-25T17:41:45Z

Cullenlinn: Added in just the basic information for the control.

The '''rules''' parameter type provides a matrix of group by action options for managing access control.

* '''type''' (mandatory) must be ''rules''.
* '''name''' (mandatory) is the unique name of the parameter.
* '''label''' (mandatory) (translatable) is the descriptive title of the field.
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.
* '''component''' (mandatory) indicates the component to which the action options will apply.
* '''section''' (mandatory) indicates the section of the access.xml actions the control should apply to. For example, "component" or "my_item_type".

=== See also ===
* [[Standard form field types|Table of all standard form field types]]
[[Category:Standard form field types]]

Talk:Creating a basic Joomla! template

2009-09-11T05:01:28Z

Cullenlinn: /* Some Additional File Layout Notes */ new section

OK, something has gone wrong here. I edited the "creating an index.php file" and it went wrong - renamed itself 404.shtml. It refused to allow editing of the "creating" file so I tried making a new one "create". Now I can't access either to edit them.

Yeah, okay, I know why this is happening. There is a mod_rewrite rule that looks for "index.php" and rewrites the URL in its SEF form. This fails if "index.php" appears as part of the page name and so you get redirected to 404.shtml which is MediaWiki's "page not found" page. I think the quick and easy fix is to simply avoid having "index.php" in page names. [[User:Chris Davenport|Chris Davenport]] 10:29, 2 May 2008 (EDT)

==A bit of craziness?==
What's happening toward the bottom of this page after "Finish it off - one last bit:"? It seems like a bunch of code might have gotten accidentally pasted or something. [[User:Corsulian|Corsulian]] 14:36, 1 June 2008 (EDT)
:That ''bunch of code'' is the full template source explained in this tutorial and was included from ''another'' page but not wrapped in a PRE element to preserve the white space. I fixed all affected pages. --<span class="plainlinks">[[User:CirTap|CirTap]] <small>([[User talk:CirTap|talk]] • [[Special:Contributions/CirTap|contribs]])</small></span> 10:23, 2 June 2008 (EDT)

== How to edit ==

I was going to make a basic proof reading change to the text, but all the edit screens do not show any text, only the headings between wouble curly brackets. Is this because I am new, or because I am not too swift??

Dave

== How to edit ==

I was going to make a basic proof reading change to the text, but all the edit screens do not show any text, only the headings between double curly brackets. Is this because I am new, or because I am not too swift??

Dave

(sorry for the double post - veeerrry slow browser!)

It's because you're new. ;-) The titles in double curly brackets are links to "transcluded" pages; that is, other wiki pages that are being embedded in the page. If you scroll to the bottom of the edit page you will see a list of the transcluded pages (they're called "templates" in wiki parlance; not to be confused with Joomla templates of course). If you click on one of those links you will be taken to the page with the text on it. From there you can click "Edit" and make your changes. For more information about using the wiki see: [[Help:Contents]]. [[User:Chris Davenport|Chris Davenport]] 12:31, 21 August 2008 (EDT)

Thanks Chris - thought it was something like that.

== index.php header stylesheet ==

I'm new to Joomla! and still trying to get my head around the templates. Thanks to the author(s) so far on a clear and concise tutorial on a basic template.

I was just wondering if the following:

<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/'''mynewtemplate'''/css/style.css" type="text/css" />

would not be better served as:

<link rel="stylesheet" href="<?php echo $this->baseurl ?>templates/'''<?php echo $this->template ?>'''/css/style.css" type="text/css" />

Regards
Pierre

== Is doctype "transitional" really neccessary within joomla templates? ==

Layout of modern templates usually try to use stricter definitions like "-//W3C//DTD HTML 4.01//EN" or even "-//W3C//DTD XHTML 1.1//EN". I would prefer it, if developers try to succeed with these w3c recommendations.

This is a user question, because i don't know the dependencies on joomla code

regards gorgonz

You can use whatever DocType you like in your template. However, bear in mind that all your components and modules will also need to be Strict-compliant if you use Strict in your template. You should only use Strict if you can guarantee that that will happen. This includes "user-generated" content, so you need to be certain that the WYSIWYG editor is also outputting Strict code too. It is for that reason that the core templates are set to the more conservative Transitional. [[User:Chris Davenport|Chris Davenport]] 17:30, 1 September 2009 (UTC)

== $this->baseurl ==

Why is $this->baseurl used when it is invalid and doesn't work in the context of index.php template files? From my understanding it should be JURI::root(). If you try and use $this->baseurl in an index.php template file, you will find that nothing happens.
--[[User:Vcardillo|Vcardillo]] 17:24, 1 September 2009 (UTC)

Looks like there was a code change and nobody noticed. ;-). Would you like to help us out and amend the page appropriately? Thanks. [[User:Chris Davenport|Chris Davenport]] 17:32, 1 September 2009 (UTC)

I might be wrong. I am reading through this thread: http://forum.joomla.org/viewtopic.php?f=231&t=230710 and trying to figure out whether $this->baseurl should be used, or JURI::base() should be used. --[[User:Vcardillo|Vcardillo]] 17:41, 1 September 2009 (UTC)

Okay, I delved into this a bit further. $this->baseurl is still valid and is equivalent to JURI::base( true ). So the tutorial is correct as far as I can see. You can find further information on JURI::base() here: [[JURI/base]]. You'll see I've added a note on that page. Thanks for pointing it out. [[User:Chris Davenport|Chris Davenport]] 18:08, 1 September 2009 (UTC)

I still don't think things are right. Sometimes the method returns a trailing slash, and sometimes it doesn't? Doesn't this make it impossible to properly code a template file? You never know if this method is going to end with a slash or not, so how can you properly and safely reference images or JS files? You could end up with a double slash.
--[[User:Vcardillo|Vcardillo]] 18:22, 1 September 2009 (UTC)

I checked your corrections to [[JURI/base]] and they do seem to be correct. Well done. $this->baseurl will behave consistently (ie. it will never add a trailing slash) because it is explicitly set to JURI::base(true). You can see that in /libraries/joomla/application/component/view.php around line 178. [[User:Chris Davenport|Chris Davenport]] 20:12, 1 September 2009 (UTC)

Great. Thanks for the help and confirming! This all makes much more sense now. $this->baseurl would seem to be the best practice. --[[User:Vcardillo|Vcardillo]] 22:22, 1 September 2009 (UTC)

== Some Additional File Layout Notes ==

Here are some more topics for inclusion:

(1) Template style overrides for "component.php", "error.php", "offline.php", and other custom templates for "tmpl" query parameters. By default:
- the error page (the "404 component not found" page) displays a default template located in /templates/system/error.php
- the component page (what displays when "tmpl=component" is supplied in the query string) displays a default template located in /templates/system/component.php
- the offline page (what displays when the site is set to "offline" in the global configuration) displays a default template located in /templates/system/offline.php

Each of these can be overridden in a custom template by placing a file of the same name in the root of the individual's template directory. For example, to supply a custom error page for a template called "myfirsttemplate", an error.php file would be placed in /templates/myfirsttemplate/error.php. Likewise, to supply a custom offline page, one would place an error template in /templates/myfirsttemplate/offline.php. In addition, any other type of template can be created to be displayed when the URL is formed with the "tmpl" query string parameter (e.g., http://mysite.com/index.php?tmpl=someothertemplate) by placing a template in the templates base directory with the same name - such as /templates/myfirsttemplate/someothertemplate.php.

(2) Component and module overrides can be supplied for any component or module which makes use of Joomla! 1.5 mvc system's tmpl file (/components/com_mycomponent/views/someview/tmpl/default.php). To provide an alternate layout / template for a component, such as the contact (com_contact) component's contact detail view we can look at the component's natural front end layout (/components/com_contact/views/contact/tmpl/default.php) and create a file in the template directory at /templates/mytemplate/html/com_contact/contact/default.php which overrides the component's default.php file. This is really useful for creating custom views of components without changing the components themselves. A module's display can be modified in the same way, e.g., the /modules/mod_feed/tmpl/default.php file can be overridden by creating /templates/mytemplate/html/mod_feed/default.php.

(3) Module styles can be added such that using <jdoc:include type="modules" name="module_position" style="mynewstyle" /> would employ an alternate module content layout. For example, to create a new module style "mynewstyle" which displayed module content in a double bordered box we could create a new file /templates/mytemplate/html/modules.php with contents:
<pre>
function modChrome_mynewstyle($module, &$params, &$attribs) {
if (!empty($module->content)) {
?>
<div style="border:1px solid #000;padding:3px;" class="moduletable<?php echo $params->get('moduleclass_sfx'); ?>">
<div style="border:1px solid #000;padding:3px;">
<?php echo $module->content; ?>
</div>
</div>
<?php
}
}
</pre>
The formatting of the function name determine the style name (or visa versa). For example, for a new style "someotherstyle" the function would be named "function modChrome_someotherstyle(..."

--[[User:Cullenlinn|Cullen]] 05:01, 11 September 2009 (UTC)

J1.5:Creating a simple module

2008-06-24T07:44:46Z

Cullenlinn: This is the beginning of the article. It will still need some screen shots and possibly some better formatting.

{{review}}

== Basic Hello World Module ==

A Joomla! 1.5 Module is in its most basic form two files: an XML configuration file and a PHP controller file. The XML configuration file contains general information about the module (as will be displayed in the Module Manager in the Joomla! administration interface), as well as module parameters which may be supplied to fine tune the appearance / functionality of the module. The PHP file provides the controlling logic for the module. A very simple "Hello World" module might looking something like this.

'''/modules/mod_hello_world/mod_hello_world.xml:'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">

<name>Hello World - Hello</name>


<author>Ambitionality Software LLC</author>


<creationDate>2008-06-23</creationDate>


<copyright>All rights reserved by Ambitionality Software LLC 2008.</copyright>


<license>GPL 2.0</license>


<authorEmail>info@ambitionality.com</authorEmail>


<authorUrl>www.ambitionality.com</authorUrl>


<version>1.0.0</version>


<description>Provides a basic "Hello World" notice</description>


<files>

<filename module="mod_hello_world">mod_hello_world.php</filename>
<filename>index.html</filename>
</files>


<params />
</install>
</source>

Basically, this XML file just lines out basic information about the module such as the owner, version, etc. for identification by the Joomla! installer and then provides optional parameters which may be set in the Module Manager and accessed from within the module's logic to fine tune it's behavior. Additionally, this file tells the installer which files should be copied installed. Notice that we DO NOT include a references in the files section for the XML file.

'''/modules/mod_hello_world/mod_hello_world.php:'''

<source lang="php">
<?php
//don't allow other scripts to grab and execute our file
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
?>
<p>
Hello World
</p>
</source>

What happens when this module is loaded is that Joomla! includes (via the PHP include directive) the mod_hello_world.php file and stores the output into an output buffer which is then rendered onto the page output. This file would simply produce <p>Hello World</p> to the final page.

'''/modules/mod_hello_world/index.html:'''

<source lang="html4strict">
<html><body bgcolor="#FFFFFF"></body></html>
</source>

This really just helps to ensure that a default page is displayed if direct access to the directory is attempted without listing all of the other files in the directory. It's not necessary, but is good practice.

To package this module for distribution and installation, simply zip the files together, e.g.,

<source lang="text">
% cd mod_hello_world
% zip mod_hello_world.zip mod_hello_world.php mod_hello_world.xml index.html
</source>

The resulting mod_hello_world.zip file may be uploaded and installed through the standard Joomla! 1.5 Extension Manager.

== Real Joomla! 1.5 Style Module Implementation ==

Now that was easy...too easy. In fact, that was pretty much the simplest form of a module possible. In reality a module will probably be doing something much more substantial. Let's assume that our modules are going to be more complex - we need to take advantage of the MVC (Model View Controller) design pattern and consider using the following file layout for a "Hello World 2" module instead:

<source lang="text">
/modules/mod_hello_world2/index.html
/modules/mod_hello_world2/mod_hello_world2.php
/modules/mod_hello_world2/mod_hello_world2.xml
/modules/mod_hello_world2/helper.php
/modules/mod_hello_world2/en-GB.mod_hello_world2.ini
/modules/mod_hello_world2/tmpl/index.html
/modules/mod_hello_world2/tmpl/default.php
</source>

The differences to note here are that there are three additional files beyond what the "Hello World" module had, namely helper.php, tmpl/default.php, and the en-GB.mod_hello_world2.ini file. The purpose in adding the first two files is two-fold. Firstly, we separate the module's logic into the helper.php file to ensure that all of the thinking and data access is performed here and separate out the module's presentation / template into the tmpl/default.php file (the (X)HTML). I argue that this is just good programming - separating logic from presentation. There is a second advantage to this, however, which is that it will allow the HTML / presentation to be overridden easily by any Joomla! 1.5 template for optimal integration into any site. (Overriding module and component presentation in templates is beyond the scope of this article, however it should be addressed as it's really useful).

Let's take a look at what these files might look like and discuss what's going on.

'''/modules/mod_hello_world2/mod_hello_world2.php:'''

<source lang="php">
<?php
//no direct access
defined('_JEXEC') or die('Direct Access to this location is not allowed.');

// include the helper file
require_once(dirname(__FILE__).DS.'helper.php');

// get a parameter from the module's configuration
$userCount = $params->get('usercount');

// get the items to display from the helper
$items = ModHelloWorld2Helper::getItems($userCount);

// include the template for display
require(JModuleHelper::getLayoutPath('mod_hello_world2'));
</source>

The important differences to note are that (1) we include a helper file which will be the work-horse of our logic and data access and (2) once we have our data, we just load a template which will use our data and render it as it sees fit.

'''/modules/mod_hello_world2/mod_hello_world2.xml'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">

<name>Hello World 2 - Hello</name>


<author>Ambitionality Software LLC</author>


<creationDate>2008-06-23</creationDate>


<copyright>All rights reserved by Ambitionality Software LLC 2008.</copyright>


<license>GPL 2.0</license>


<authorEmail>info@ambitionality.com</authorEmail>


<authorUrl>www.ambitionality.com</authorUrl>


<version>1.0.0</version>


<description>Provides a random listing of registered users</description>


<files>

<filename module="mod_hello_world2">mod_hello_world2.php</filename>
<filename>index.html</filename>
<filename>helper.php</filename>
<filename>tmpl/default.php</filename>
<filename>tmpl/index.html</filename>
</files>

<languages>

<language tag="en-GB">en-GB.mod_hello_world2.ini</language>
</languages>


<params>

<param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" />


<param name="@spacer" type="spacer" default="" label="" description="" />


<param name="usercount" type="text" default="5" label="LABEL USER COUNT" description="DESC USER COUNT" />
</params>
</install>
</source>

The main differences to note here are that we have added a language file reference (we could have added more) and we added some parameters.

'''/modules/mod_hello_world2/helper.php:'''

<source lang="php">
<?php
defined('_JEXEC') or die('Direct Access to this location is not allowed.');

class ModHelloWorld2Helper
{
/**
* Returns a list of post items
*/
public function getItems($userCount)
{
// get a reference to the database
$db = &JFactory::getDBO();

// get a list of all users
$query = 'SELECT a.name
FROM `#__users` AS a'
;
$db->setQuery($query);
$items = ($items = $db->loadObjectList())?$items:array();

// create a new array and fill it up with random users
$actualCount = count($items);
if ($actualCount < $userCount) {
$userCount = $actualCount;
}
$items2 = array();
$rands = array_rand($items, $userCount);
foreach ($rands as $rand) {
$items2[] = $items[$rand];
}

return $items2;
} //end getItems

} //end SimplestForumLatestPostsHelper
</source>

This helper class (note that it is named for the module name so that it doesn't collide with other class names) simply retrieves a a list of all users in the database and randomly selects a subset of those based upon the number supplied as $userCount.

'''/modules/mod_hello_world2/tmpl/default.php:'''

<source lang="php">
<?php defined('_JEXEC') or die('Restricted access'); // no direct access ?>
<?php echo JText::_('RANDOM USERS'); ?>
<ul>
<?php foreach ($items as $item) { ?>
<li>
<?php echo JText::sprintf('USER LABEL', $item->name); ?>
</li>
<?php } ?>
</ul>
</source>

Here we simply create an unordered HTML list and then iterate through the items returned by our helper (in mod_hello_world2.php) printing out a message with each user's name.

'''/modules/mod_hello_world2/en-GB.mod_hello_world2.ini:'''

<source lang="text">
LABEL USER COUNT=User Count
DESC USER COUNT=The number of users to display
RANDOM USERS=Random Users for Hello World2
USER LABEL=%s is a randomly selected user
</source>

Here we simply identify strings which appear in the module configuration file and the module template which appear in JText::_ or JText::sprintf statements. This allows someone to easily write a new language file without editing any of the HTML or code for the module.

Now all we have to do is zip up these files, as in:

<source lang="text">
% pwd
/somesite/modules/mod_hello_world2
% zip -r ../mod_hello_world2.zip *
% ls ..
mod_hello_world2.zip
</source>

The resulting mod_hello_world2.zip file is ready for installation and distribution. When the ZIP file is installed, the en-GB.mod_hello_world2.ini file is copied to /language/en-GB/en-GB.mod_hello_world2.ini and is loaded each time the module is loaded. All of the other files are copied to the /modules/mod_hello_world2 subfolder of the Joomla! installation.

--03:44, 24 June 2008 (EDT)[[User:Cullenlinn|Cullenlinn]]