Minicomponents
From Jomres v4 manual
Contents |
Minicomponents
This section describes minicomponents, what they do and how they work. See the Advanced section of this site for more indepth information on customising Jomres.
If you're just looking for information on how to customise Jomres and retain your changes over different versions of the software, please see How to edit the Jomres core code and still upgrade.
What are mini-components and why are they needed?
Mini-components are actually separate files that Jomres can call that either replace or add to existing Jomres functionality. They are very useful if you have modified existing Jomres code to suit your own requirements. If you simply edit the standard Jomres code then when you upgrade you will need to make sure that you have backed up your changes otherwise you will lose them. They also make it very easy for me to provide extra code to enhance the current Jomres functionality without bloating the standard Jomres install.
Mini-components are structured in such a way that they can be installed using the standard Mambo installer, and uninstalled the same way.
Whilst it's still possible to install minicomponents this way, the majority of minicomponents have been converted to remote plugins and are installed using the Plugin Manager.
How do they work?
Without going into too much detail, Jomres has many core mini-components that it knows are kept in the /components/com_jomres/core-minicomponents folder. When Jomres starts it will scan this folder for these files. Next, it will look in the /components/com_jomres/remote_plugins folder for more plugins. After that it will look in the CMS components table for any other components that start jomcompXXXX. If it finds any it will look in these other folders for any files that start jNNNNN and make a note of them. If a file exists with the same name as a Jomres core mini-component, (e.g. j00013dashboard) then this file and it's contained functionality will be used instead of the core Jomres file.
So, first core-minicomponents, then remote_plugins, then finally other directories in the components/ directory.
Give me an example of why I'd use them
In the days before mini-components, if you wanted to change how Jomres worked, you had to modify the core Jomres code and make sure you had a backup of your changes. When it came to upgrading you had to install the upgrade and look at your old files and make again the changes you'd made before. This was very frustrating and time consuming. Using mini-components this is no longer a problem.
So, how do I use them?
We will use the dashboard as an example. Let's say that I want to change the dashboard so that instead of showing the standard dashboard view, it doesn't show anything. First, I'd download j00013dashboard.class.php and save it locally. I'd edit it to use it as a base for building my own mini-component. Now I need to decide on a name for this mini-component. There are no strict rules on what it is called, so you can name it pretty much what you like, however there are certain places in the naming of the mini-component installer files where they all need to be the same. I'll go through each of these files in turn: jomcompXXXX.xml When Mambo installs a component it uses the name of the xml file to decide where to put the files, therefore inside the xml file where it says <name>jomcompXXXX</name> you should replace the XXXX with what you're calling the file, e.g. 'myminicomp'. Note, that you must keep the 'jomcomp' part of the name intact, as this is what Jomres looks for when searching for mini-components in the Mambo components table. Where is says <description>Base mini-component installation files </description> you should enter a description of what your mini-component does. Try not to use any special characters or html in here otherwise the installer may fail (encase them in CDATA if you need to). Where it says <installfile>install.jomcompXXXX.php</installfile> and <filename>install.jomcompXXXX.php</filename> you should change the XXXX again to the name of your mini-comp, e.g. 'myminicomp'. <menu>jomcompXXXX</menu> is required by the installer but not actually used. Again, change XXXX Finally, but just as important as the other xml tags is this one: <filename>j00013XXXX.class.php</filename>. This is the file that will replace the standard Jomres functionality.
install.jomcompXXXX.php
This file should have the same name as that in the xml file, so if you've changed <filename>install.jomcompXXXX.php</filename> to <filename>install.jomcompmyminicomp.php</filename> then your install.jomcompXXXX.php should now be named install.jomcompmyminicomp.php
Inside this file there's a line: $componentname="jomcompXXXX"; Change it so that the $componentname reflects the name of your new mini-component ($componentname="jomcompmyminicomp";)
All this file does is remove the Mambo backend and front-end menu options, we don't want to add this mini-component to Mambo or use Mambo to configure it. If this mini-comp offers configuration it'll be done through Jomres.
j00013XXXX.class.php
This is the actual file that will replace/enhance the core functionality. If we are replacing the original dashboard then we will call it j00013dashboard, if we are adding to the dashboard functionality without replacing the current code then we need to come up with a slightly new name. For example we might want to display a welcome message for the admin underneath, in which case we could call it j00013welcomemessage. What's important here is that the trigger point (00013) must refer to one already existing in Jomres. If the trigger point doesn't exist then this file will not be used.
In this instance we want to replace the core mini-comp j00013dashboard.class.php with one of our own, so the first thing to do is copy j00013dashboard.class.php and drop it into our new mini-component's folder. Once we've done that we can make the changes we need to make to it to do what we want.
For each file you want to replace (in theory, you could replace nearly all of the core mini-components in this way) you need a tag in the xml file and the corresponding file needs to exist in the folder before you zip it up.
If you've done everything correctly you should now be able to zip this entire folder up (call it anything, the name of the zip doesn't matter) and use the Mambo installer to install the files.
There you go, your first mini-component.
Notes: If you want to include your own template files instead of using the standard Jomres ones you can do that, but you need to tell patTemplate that you're looking in this folder instead of the Jomres folders. This is done by using the $ePointFilepath; variable. First make it global, then when you set the root of the template do it like this: $tmpl->setRoot( $ePointFilepath); This tells Jomres that instead of looking in the standard template folders, look here instead. Don't forget to add the template to the xml file so that that's also uploaded to your mini-component's folder.
Don't be shy about looking at existing minicomponents. This is a very short tutorial on a very powerful subject within Jomres, there's a lot more to learn.
