Component Documentation for Elxis 5.4+

[cjstudio]

Hello again. Apologies if this has already been asked, but my searches turned up empty. I'm working on a new component but I cannot find developer documentation for Elxis 5.4+. Is this available, or should I use existing components as a guide to develop a working framework to get me started? Thanks!

[datahell]

Hi. Elxis Docs website is exactly for that, for documentation. However unfortunately we do not update the site a long time now and recently I accidentally "destroyed" the site's style, especially the style of the coding blocks. Yeah, I did something stupid :-) The reason for abandoning the documentation site is that there is no free time for that. But despite this you will still find many useful information there.

I personally have written many instructions and how-to guide in this forum and if you search the forum you will find a lot of information. Also on each Elxis release we publish a changelog which you can read to see what changed. For a component I will write you below a brief introduction and you can ask me what ever you like.

Part 1 - Elxis filesystem, framework, libraries, helpers and packaging

Elxis filesystem has a small footprint and it is well organized. System folders components, modules and templates are where the corresponding extensions are located. Some other extension types are component specific and you will find them in the corresponding component's folder. So, you will find content Plugins under component Content, Authentication Methods under component User and Search Engines under component Search. In folder includes is where all the system libraries and helpers are located.

We have a factory class to easily load most of system libraries. Elxis Factory uses Elxis registry in the backend and makes sure a library will be loaded and initialized only once. Some common examples:

eFactory::getDB() - Returns database instance. You can use it to query the database.
eFactory::getElxis() - Elxis framework. Tones of core functionality. It also contains shortcuts for other libraries.
eFactory::getLang() - Language instance
eFactory::getDocument() - Document handling. Set page title, META data, add scripts and CSS on page head, etc.
eFactory::getDate() - Date related functions
eFactory::getFiles() - Easy files handling. You provide path relative to Elxis root folder which make your code easy and fully portable.

Example 1 - copy a file
eFactory::getFiles()->copy('modules/mymodule/image.jpg', 'templates/five/images/newname.jpg');

Example 2 - get a transliteration (name of month September)
eFactory::getLang()->get('SEPTEMBER');

Example 3 - Get a general configuration value (eg. default language)
eFactory::getElxis()->getConfig('LANG');

Some other useful libraries do not exist in Elxis Factory. We load them with Elxis Loader.
Example 4 - Elxis form
elxisLoader::loadFile('includes/libraries/elxis/form5.class.php');

Helpers are smaller libraries which are located under folder includes/libraries/elxis/helpers/ and get loaded/initiated by Elxis framework.
Example 5 - Unzip a zip archive
$elxis = eFactory::getElxis();
$elxis->obj('zip')->unzip('/path/to/zipfile.zip', '/destination/folder/');

Example 6 - Send an SMS message
$sms = $elxis->obj('sms');
$sms->setElxisConfigOptions();
$sms->sendMessage('306999000000', 'Hello world');

For creating a ready to install extension read this. It is for modules but it is the same for any type of Elxis extension. You actually zip the interior contents of the extension's folder and that's it!

[datahell]

Part 2 - Creating a component

A component is (usually) the most complex extension type as it provides advanced functionality. A component is what actually builds pages in Elxis. This is a quick and easy way to start developing a component. This guide follows the most common architecture (MVC) but you can use whatever you like, Elxis doesn't force you to follow a specific design standard. Be yourself!

Let's say we want to create component "Sports". We assume you work on your local development computer.

Create this folder: components/com_sports/
Create 2 files: components/com_sports/sports.php and components/com_sports/sports.xml

These are the required by Elxis files, all the rest are optional! sports.php is the component's router, and sports.xml contains information of the extension and optionally configuration parameters. When you visit your component's pages you will see the word "sports" in the URL. Whatever is under "sports" gets handled by your component. Elxis Router  initially will get user's request, validate it and load the corresponding component, language files, etc. So the Elxis router will load file "sports.php". Then you must analyze the rest of the URL to see what you will do with the user's request.

<?php
defined('_ELXIS_') or die ('Direct access to this location is not allowed');

class sportsRouter extends elxisRouter {

   private $controller = 'public';
   private $task = 'frontpage';

   public function route() {
      //code here   
   }

}

?>

From your router you load the proper controller, model and view and execute the proper method inside the controller file. So, create these folders to put your files: com_sports/controllers/, com_sports/views, com_sports/models/

As Elxis is fully multilingual create a folder named language to add your language strings which you want to use within your component. Name language files as en.com_sports.php, de.com_sports.php, it.com_sports.php, etc. Note that Elxis detects and loads the proper file automatically, so you dont have to do anything else with them.

Create also a folder named includes, or inc, or whatever, to add there your helping classes, css, javascript, images, etc. Off course you can have a totally different filesystem structure.

Elxis will install automatically your ready-to-install zip package. However if you want to perform custom actions during install such as creating database tables (or even on update or uninstall), then also add a file named install.php. You will add your spcial code there.

class com_sports_installer {
    public function install() {}
    public function update() {}
    public function uninstall() {}
}

Now, you have created a very basic structure of your component and you have created the request to your component's frontpage (just echo Hello World for now). Let's tell Elxis we have a new component there. Note that the instructions mentioned below are performed by Elxis automatically during install but as you create just now the component and the installer has not run you must do them manually. To be more accurate, we can already zip the component, delete the folder, and install it but better proceed with the manual process below.

Go to PHP My Admin
Table elx_acl (access management)
Add 2 entries for component Sports, one for action view and one for action manage. Set the default values:
category element identity action minlevel gid uid aclvalue    
component com_sports 0 view 0 0 0 1
component com_sports 0 manage 70 0 0 1

Table elx_components (declare component)
Add 1 entry
name component route iscore params
Sports com_sports NULL 0 NULL

We are ready. Open your browser and navigate to component's frontpage:

https://elxis.loc/sports/ (or whatever is your localhost URL)

You should see "Hello world" (or whatever you added). It is very normal to see some error as you might missed something in your component. If you see blank page (php fatal error) enable the display of errors in elxis configuration file. In fact during development have the display of errors always to ON. Open file "configuration.php" and set ERROR_REPORT = 3 (show errors, warnings and notices) and/or ERROR_LOG = 3 (Elxis log files are in Elxis repository folder).

From that point you can continue the development of your component, method by method. See how other components are made and ask below for guidance and help.

[cjstudio]

Wow! Thank you sooo much! I'm still adjusting to how welcoming this community is. I'm rolling up my sleeves to get started. I have a component from Joomla that I need to rewrite - long story short, that project kept breaking major stuff each release so I could never just finish it. I really enjoy how stability and truly important upgrades and fixes are prioritized over using the latest "kewl" technology (that adds heft and complexity without anything significantly better or more useful). I think J! has lost at least a good half of its third-party developers if not more. That includes major development teams with extensions I relied on. That was the final straw for me. Looking forward to just worrying about site dev stuff for a change. :-)