Making sense of components II

There are some confusing things about components. My personal approach to figuring out how a system works without manuals is to poke around the system looking at menus, the database, and source code files looking for patterns and consistencies. Gotta admit it didn't help much this time. Going to dig a little deeper, like right into the guts of the code, I guess. Trying to find patterns, here's what I found:

There are 14 components in the component directory:

com_banners
com_contact
com_content
com_frontpage
com_login
com_messages
com_newsfeeds
com_poll
com_registration
com_rss
com_search
com_user
com_weblinks
com_wrapper

But only 10 of the 14 components are used in the jos_components table:

com_banners
com_weblinks
com_contact
com_frontpage
com_poll
com_newsfeeds
com_login
com_search
com_syndicate
com_massmail

And it is not one row per component as you would expect like it is in the modules table, so how do I know if the component install was successful? Isn't the component officially recorded somewhere in the db at install time?

The even more important question is: what do I do with the component after I install it? Connect it to the main menu would be a reasonable thing to do.

Menu -> Main Menu -> New -> [check component] Next

Gets you to: Add Menu Item :: Component

How do you get your new component to show up in the little list of components on this screen? Only 7 of the 14 components can be found there:

Contacts
FrontPage
Login
News Feeds
Polls
Search
Web Links

It's also worth noting that only x of the 14 components display on the Components menu in Administration:

Banners
Contacts
Mass Mail
News Feeds
Polls
Syndicate
Web Links

Making sense of Joomla! components I

What was I thinking? I want to create my first new component. What do I do? Clone it, of course. Take com_content let's and change everything to com_content2. Immediately there's a problem. No content.xml install file, so I clone one I already have.

I zip the three files together using this free zip utility, a Winzip clone. Then I get error messages indicating that I got to stick the xml file in the directory ../joomla/media/ so I do this and no error messages, so I guess it's installed, but how do I really know. There doesn't seem to be a master list of all the components anywhere, not in the administration menus or in the tables themselves...

Mambo -> Joomla 1.0 -> Joomla 1.5

Mambo tutorials seem to help somewhat, but sometimes they are way off. Like Joomla! components added an extra presentation layer, e.g. hello.html.php gets added to hello.php.

I'm confident about finishing my little Jambla I mean Joomla customization quickly and I will post haste contribute to documentation, but the budding Joomalateer has to carefully navigate between the Scylla of Mambo and Charybdis of Joomla 1.5 with the new Joomla Framework API (everything prefixed with a J, JExec, JGetParam, etc...thought Joomla and Java were getting together there for a moment).

The tutorials at Joomla Development Wiki (Tutorials seem to all use the new API so they are Joomla 1.5 which I would like to master here shortly, but I got to get a reliable production system running quickly. Joomla 1.5 appears to only be in the Alpha stage.

Joomla!-Mambo Help Videos

Mambodemo has a full set of videos that help you step through Joomla! tasks. The list of tasks is itself informative, a sort of list of all the things you can do with Joomla! :

Add a Category
Add a Contact
Add a Content Item
Add a Menu Item - Blog Category
Add a Menu Item - Component
Add a Menu Item - Link URL
Add a Menu Item - Table Category
Add a Menu Item - Wrapper
Add a Section
Add Content from the Frontend
Approve a Submitted Item
Archive Manager
Assign a Template
Change Access Level of Content
Change Menu Orientation
Change the Frontpage Layout
Change the Home Page
Change the Installed Directory
Create a Module
Database Backup with phpMyAdmin
Edit the Content Layout
Edit the Template
Email Users
Enable SEF URLs
Install a Component
Install a Component Manually
Install a Language
Install a Language Manually
Install a Mambot
Install a Mambot Manually
Install a Module
Install a Module Manually
Install a Template
Install a Template Manually
Install Joomla with cPanel
Manage the Global Configuration
Publishing Control of Content
Setup RSS
Updating Users - Backend
Updating Users - Frontend
Using the Media Manager
Using the Menu Manager
Using the Module Manager
Using the Trash Manager
Using the User Manager

The Mambo legacy, tutorials, etc...

Got to remind myself to look at Mambo examples, tutorials, too.

Joomla! has just recently forked from Mambo.

Mambohut's basic module and component is about as simple as you can get. Get info from database, display info web page:

1. Module tutorial
2. Component tutorial

Content items = articles

I think I'm starting to understand Joomla!. The articles you publish everyday are called content items. Here's a meaty definition:

"A content item is a discrete piece of content within the Joomla! hierarchy. A content item may be associated with a particular Section/Category combination or a Static Content Item. Usually content items are displayed in the main body of your page. Content item is the last in the Section/Category/Content Items hierarchy or it can be a separate Static Content Item."

1. Joomla! hierarchy = Section/Category/Content-Items hierarchy, for example: business/marketing/how to sell people things they don't need, the section is business and the category is marketing.

[Observation: Joomla!'s hierarchy is a tree, but forests like folk taxonomies in del.icio.us allow for different categorizations, different ways of looking at the same thing. The tree versus forest distinction has been around for a long time though. I used to deal with trees all the time as a COBOL-CICS General Ledger computer consultant in corporate America. For example, better designed General Ledgers for corporations have corporate reporting structures built into the hierarchy of accounts and these hierarchies are forests, not trees. The various reports of a company will break down the same information in different ways.]

2. Main body of page = center, so...

3. Components must display content items.

4. An ItemId must be the unique identifier of a content item, right?

[No, if you look at the menu manager screen under administrator, ItemId is in one column and CID which must mean content id is in another. Not the same.]

ItemId, the definition?

One day I will discover what an ItemId is.

It gets tacked on to the end of almost every Joomla! URL I've seen.

Like Home, the mother of all URLs:

http://127.0.0.1/joomla/index.php?option=com_frontpage&Itemid=1

Or News, another important destination:

http://127.0.0.1/joomla/index.php?option=com_content&task=section&id=1&Itemid=2

But as this thread at Joomla! Forums tells me, there may be no easy definition, but I'm not losing hope.

I am creating my own little Joomla! Glossary to celebrate when I discover simple definitions for complicated little things like ItemId!

Parameters II

Where do parameters come from mommy?

Playing around with the Joomla front page. Clicking on something and seeing what URL it gives me. Inside the URL I can see parameters ($REQUIRE, $GET) being passed to a component that will display in the center of the page. Still doesn't tell me how or why they got there, but it's a start in unravelling the logic of Joomla! code.

Hit the Register link on the Joomla front page and I get this URL:

http://127.0.0.1/joomla/index.php?option=com_registration&task=register

On the Main Menu:

1. Home:

http://127.0.0.1/joomla/index.php?option=com_frontpage&Itemid=1

2. Joomla! License:

http://127.0.0.1/joomla/index.php?option=com_content&task=view&id=5&Itemid=6

3. News:

http://127.0.0.1/joomla/index.php?option=com_content&task=section&id=1&Itemid=2

4. Blog:

http://127.0.0.1/joomla/index.php?option=com_content&task=blogsection&id=0&Itemid=9

5. Links:

http://127.0.0.1/joomla/index.php?option=com_weblinks&Itemid=23

6. Contact Us:

http://127.0.0.1/joomla/index.php?option=com_contact&Itemid=3

7. Search:

http://127.0.0.1/joomla/index.php?option=com_search&Itemid=5

8. News Feeds:

http://127.0.0.1/joomla/index.php?option=com_newsfeeds&Itemid=7

9. FAQs:

http://127.0.0.1/joomla/index.php?option=com_content&task=category§ionid=3&id=7&Itemid=25

10. Wrapper:
http://127.0.0.1/joomla/index.php?option=com_wrapper&Itemid=8

11. Joomla! Home:

http://www.joomla.org/


Some generalizations:

1. Option is the component being called like com_registration. So after you click on the frontpage something is mapping your click to a component call. Must be the infamous template I've been hearing so much about.

2. Task comes from a limited set: view, section, register, blogsection... It selects the thing to do once you reach the component.

3. ItemId ??????????????

4. Id I guess would be a user Id, maybe?

Parameters I

What I need to understand next about modules is how they get input parameters like $task, $option, or $id. For example, from mod_relcontent:

$option = trim( mosGetParam( $_REQUEST, 'option', null ) );

Or from mod_latestnews :

$type = intval( $params->get( 'type', 1 ) );

mosGetParam must be the preferred to the raw PHP $params->get() since it is in the Joomla! API.

mod_login also has to get user supplied parameters like username and password. What are all the parameters defined in mod_login.xml used for?

Where do parameters like $task come from? Where do they go? What are the calling conventions in modules? Which parameters are required and which are optional?

Time to hit the code again.

Modules vs. Components in Joomla! III

Joomla! Modules are written differently from components. They use different function calls and variables, so they need different example programs.

For example, take login and user registration. If a user can't login, then she registers first. We login to a module on the left, right, or top. We register in a component in the center.

Compare the login code with the registration code. The login code is in one file: mod_login.php. The registration code is in the directory: com_registration. There are two registration program files:

1. registration.html.php : displays data
2. registration.php : makes decisions about what to display (does logic).

Both files get data from the database. Right now I'm going to stick with figuring out modules, even though my goal is to modify user registration. My user registration customization will require the user to supply an 8-digit subscriber id checked against a table of ids added to Joomla.

Joomla! cookbook anyone?

Surprised to see that the PHP cookbook is only 2.9% finished at PLEAC, the repository of code snippets for programming (PLEAC = Programming Language Examples Alike Cookbook). Why?

Maybe PHP is different from other programming languages so it needs its own special list of code snippets?

Maybe it's better to start thinking at the level of applications, like a Joomla or Content Management System cookbook.

Programming in small doses?

Maybe programming in small doses is the antidote to this Joomla! user's problems:

"I found Joomla very frustrating though. I installed the dummy template site that comes with the distribution, a site about soccer teams. I wanted to remove the frames in the site, change the background images and colors, and otherwise set up a small publishing site with news and blogs. I was unable to do a lot of this without digging in directly to the css, which is of course far too much to ask a common user. I spent several hours with this, learning how the interface work and making backend changes, and mostly gave up out of frustration and lack of time to devote."

That's why I'm focusing on code snippets. Little pieces of stand alone code that do a small task that you can learn from.

A forum or library of code snippets does seems to be in the making over at the official Joomla org.

From database to web page

Here's a tiny module to get data from the Joomla database and display it on the front Joomla! page. Take the zip file and install the module. It will will list the published modules and their positions, one per line. The file contents is given below.

[Note: There's a Mambo module tutorial that has almost the same thing.]

mod_getandgive.php:

<?php

defined( '_VALID_MOS' )
or die( 'Direct Access not allowed.' );

$query = "SELECT * FROM jos__session";
$database->setQuery( $query );
$result = $database->loadResult();
echo "result: " . $result;

?>



getandgive.xml:

<?xml version="1.0" ?>
<mosinstall type='module'>
  <name>getandgive</name>
  <creationDate>19/Jun/2006</creationDate>
  <author>Mr. Hello Smiley</author>
  <copyright>This template is released 
under the GNU/GPL License</copyright>
  <authorEmail>blackhole@saynotospam.com</authorEmail>
  <authorUrl>http://readbangkokpost.com/business/</authorUrl>
  <version>1.0</version>
  <description>To get something from the Joomla database
 and display it in a box on the front of Joomla</description>
  <files>
    <filename module='mod_getandgive'>mod_getandgive.php</filename>
  </files>
</mosinstall>

Installing a Module

The following steps will make your module the last thing on the right-hand sidebar.

1. Download a zip file with the two files mod_mymodulename.php and mymodulename.xml inside.

2. From the administrators panel in Joomla select: installers -> modules.

3. Then browse and select the zip file.

4. Then select "Upload file and install".

5. There shouldn't be any error messages.

6. Then select from the navigation bar running along the top of the administrators panel: Modules -> Site Modules.

7. Then click on the name of your module.

8. Now you are editing the settings for your module.

9. Choose position: Right.

10. Choose Access Level: at-the-very-bottom-of-everything.

11. Choose: Public.

12. Then save.

13. Then check the box in the left column next to your module name and publish.

14. Go to the front of Joomla (http://joomla/index.php).

15. Hit the browser refresh button.

16. You should see a box with your module's name on it on the bottom with whatever your module displays inside of it.

17. I know this descrption is overkill, but didn't want to leave anything out.

There are other descriptions of how to do this here.

A very, very simple module

Whoopee! I can display text in a Joomla box. Use the two files listed below or this zip file and install the module. Here is the contents of the two files in the zip file:

helloworld4.php:


<?php

defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );

echo "Hello World!";

?>



helloworld4.xml:

<?xml version="1.0" ?>
<mosinstall type='module'>
  <name>helloworld4</name>
  <creationDate>19/Jun/2006</creationDate>
  <author>Mr. Hello Smiley</author>
  <copyright>This template is released under the GNU/GPL License</copyright>
  <authorEmail>blackhole@saynotospam.com</authorEmail>
  <authorUrl>http://readbangkokpost.com/business/</authorUrl>
  <version>1.0</version>
  <description>To display some text in a box on the front of Joomla</description>
  <files>
    <filename module='mod_helloworld4'>mod_helloworld4.php</filename>
  </files>
</mosinstall>

Pretty printing PHP for documentation examples

How do I format php and html properly to provide examples in documentation?

Prettyprint of course! How could I forget that?

Here's an online PHP pretty printer that indents html properly also.

It maps plain text file space ("_") to html file space ("&nbsp;") using GNU's Indent and plain text file angle brackets ("<", ">") to html angle brackets ("&lt;", "&gt;").

Here's an example.

Modules vs. Components in Joomla II

There's a complete set of tutorials in the Developers Manual at help.joomla.org. Mastering these tutorials should be the first step to learn programming in Joomla, it seems.

One of the tutorial pages makes one difference between modules and components very clear. As you can see in this tutorial page on templates "The Layout File", modules (mosLoadModules) go on the top and into the left and right sidebars. Components go into the center (mosMainBody):


<table cellspacing="0" cellpadding="5" border="0">
22:   <tr>
23:     <td colspan="3">
24:       <?php echo $mosConfig_sitename; ?>
25:     </td>
26:   </tr>
27:   <tr>
28:     <td colspan="3">
29:       <?php mosLoadModules ( 'top', 1 ); ?>
30:     </td>
31:   </tr>
32:   <tr>
33:     <td width="20%" valign="top">
34:       <?php mosLoadModules ( 'left' ); ?>
35:     </td>
36:     <td width="60%" valign="top">
37:        <?php mosMainBody(); ?>
38:     </td>
39:     <td width="20%" valign="top">
40:       <?php mosLoadModules ( 'right' ); ?>
41:     </td>
42:   </tr>
43:   <tr>
44:    <td colspan="3" valign="top">
45:      <?php mosLoadModules ( 'bottom' ); ?>
46:    </td>
47:  </tr>
48: </table>

Installing Modules and Components

If you are confused about installing Joomla! components or modules like I was initially (or getting error messages) do the Joomla! tutorial "Writing a Simple Module" and you'll get to do a module install.

Watch out for closing XML tags like:

<mytag> </mytag>

That turned out to be the problem in this thread.

Modules vs. components in Joomla?

Was just flipping through some easy to read stuff on Php-Nuke modules in the book Php Nuke Garage. Joomla components sure seem similar to Php Nuke modules, the way they take those HTTP POST values from the Apache server:

http://joomla/index.php?module=mymodule&op=one

Do a switch statement on them, and then execute something. Same basic structure. Well from the Joomla! glossary:


Modules:

1. Extend the capabilities of Joomla! giving the software new functionality.
2. Are small content items that can be displayed anywhere that your template allows it to be displayed.
3. Include: Main Menu, Top menu, Template Chooser, Polls, Newsflash, Hit Counter, etc.

Components:

1. Are Joomla!’s content elements or applications that are usually displayed in the center of the main content area of a template.
2. Depend on the design of the template in use.
3. Are core elements of Joomla!’s functionality.
4. Include Banners, Contact, News Feeds, Polls and Web Links.

So modules are minor things that go in the left and right sidebars of a three column layout and components are major things that go in the center? The plot thickens. I'll find out tommorrow!

My Joomla! Glossary

Component - the PHP program controlling content in the center of the Joomla! frontpage

Module - the PHP program controlling a content box on the left, top, or right of the Joomla! frontpage

ItemId - ???????????

[Warning: As I become smarter and know more (become less dumb) these definitions will become shorter and more precise.]

My Joomla! Rules of Thumb

1. Install a Module

[Only just begun...]

My Joomla! Examples

This is a list of Joomla examples I have created to teach myself Joomla!

1. A very, very simple module: Displays text in a box on the left, right, or top.

2. mod_getandgive.php: A module that gets data from the database and gives it to the front page.

[Examples from this blog will be put here]