Sample Joomla! library
Sample third parth library for Joomla!
Index
-
- 3.1. Non-namespaced classes.
- 3.2. Namespaced classes.
1. Description
This is a mainly a library bootstrap to be used as reference by 3rd part Joomla! developers.
It includes common libraries requirements:
- Classes autoloading (for namespaced and non-namespaced classes)
- Integrating composer libraries
- Language autoloading
- Media folder + assets management
- Form fields
- Form rules
- JHtml helpers
2. Loading your library.
Load your library adding this on the script you needt to use it:
JLoader::import('sample.library');That doesn't mean that you have to add that line everywhere. You just have to add it in the entry point of your extension:
- Components:
components/com_mycomponent/mycomponent.php(frontend entry point)administrator/com_mycomponent/mycomponent.php(backend entry point)
- Modules:
modules/mod_mymodule/mod_mymodule.php(module entry point)
- Plugins:
plugins/system/myplugin/myplugin.php(plugin class)
If you want to use library fields in view or module settings you have to also add the path to the fields folder to the form XML:
<fields name="params" addfieldpath="/libraries/sample/form/field">Also when fields are used inside view or module settings you will need to add the loader on top of field classes like:
<?php
/**
* @package Sample.Library
* @subpackage Field
*
* @copyright Copyright (C) 2013-2016 Roberto Segura. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE
*/
defined('_JEXEC') or die;
JLoader::import('sample.library');
/**
* Sample list form field
*
* @since 1.0.0
*/
class SampleFormFieldList extends JFormFieldList
{3. Autoloading naming conventions
You can get your classes loaded in two different ways:
3.1. Non-namespaced classes.
This is the "old way" of loading classes. There is a prefix defined in the root folder of your library (Sample for this library). The naming convention for autoloading is that each folder becomes a new word on the class name and the file is the last word there.
The class SampleHelperAsset contains three parts:
Sample(main library prefix)Helper(folder)Asset(file)
And file resides in libraries/sample/helper/asset.php
A model in libraries/sample/model/list.php would use the name: SampleModelList.
Example class usage:
JLoader::import('sample.library');
$result = SampleHelperNumbers::sum(array(4,3));3.2. Namespaced classes.
The concept is the same than prefixes but instead of setting a prefix in your library root folder you are defining a namespace on X folder (src in this library). We will use composer for autoloading because it's more flexible than JLoader.
The global namespace defined in this library is Phproberto\Sample. So a class loaded like:
use Phproberto\Sample\Monolog\PhpfileHandler;Contains 3 parts:
Phproberto\Sample(global namespace defined)Monolog(folder)PhpfileHandler(file)
And resides in: src/Monolog/PhpfileHandler.php
The autoloading magic is done defining a PSR-4 prefix in our composer.json file like:
"autoload": {
"psr-4": {
"Phproberto\\Sample\\": "src/"
}
}You can replace that with your own base namespace.
Sample usage of namespaced classes:
JLoader::import('sample.library');
use Phproberto\Sample\Helper\Dummy;
$dummyClass = new Dummy;
$dummyClass->foo('My message');4. Media folder + asset managements.
Library provides also a base asset manager to easily load assets for your extension based on:
https://gist.github.com/phproberto/4615320
Example:
JLoader::import('sample.library');
/**
* Sample CSS file. It will automatically try to load overrides at template level.
*
* This example will search CSS file in these paths:
*
* `/templates/MY_TEMPLATE/css/sample/sample.css`
* `/media/sample/css/sample.css`
*/
SampleHelperAsset::load('sample.css', 'sample');
/**
* Sample JS file. It will automatically try to load overrides at template level.
*
* This example will search JS file in these paths:
*
* `/templates/MY_TEMPLATE/js/sample/sample.js`
* `/media/sample/js/sample.js`
*/
SampleHelperAsset::load('sample.js', 'sample');5. JHtml classes
Library registers the path to use for JHtml classes in libraries/sample/html
Example usage:
JLoader::import('sample.library');
// Load fontawesome from our media folder
JHtml::_('sample.fontawesome');6. Forms.
Library automatically registers fields + rules paths to be used anywhere.
6.1. Fields.
You can load library's fields with prefix.field. We use a custom prefix for our fields instead of the core fields J prefix. Read why
Sample usage:
<?xml version="1.0" encoding="utf-8"?>
<form>
<fieldset addfieldpath="/libraries/sample/form/field" >
<field
name="list"
type="sample.list"
label="COM_SAMPLE_FIELD_LIST"
description="COM_SAMPLE_FIELD_LIST_DESC"
default="1"
>
</field>
</fieldset>
</form>6.2. Rules.
You can load library's field rules with prefix.rule``. We use a custom prefix for our rules instead of the core fields J` prefix. Read why
Sample usage:
<?xml version="1.0" encoding="utf-8"?>
<form>
<fieldset addrulepath="/libraries/sample/form/rule">
<field
name="username"
type="text"
label="COM_SAMPLE_FIELD_NAME"
description="COM_SAMPLE_FIELD_NAME_DESC"
validate="sample.login"
/>
</fieldset>
</form>7. Integrating external composer libraries.
You can integrate any existing library available on composer/packagist (See https://getcomposer.org/).
To install/require a new library you only need to run from command line something like:
composer require monolog/monolog
To provide an example of how a third party library would be used this library includes an example Monolog integration. Example usage of our Monolog based logger:
JLoader::import('sample.library');
use Phproberto\Sample\App;
$logger = App::getLog();
// This should add a line on a sample.error.php file inside your logs folder
$logger->addError('This is a dummy error');Note about composer libraries and git integration:
This repository is not gitignoring external libraries so you can see the full extension folders tree. Please note that you should do so to avoid tracking them with git. You only need to add this to your gitignore:
/vendors/*
Remember also that your library cannot be distributed without those libraries so before packaging your library you will have to run:
composer install
8. License
This library is licensed under the GPL v2.0 license
Copyright (C) 2013-2016 Roberto Segura - All rights reserved.