В тази статия ще използваме 'mycomp' като име на компонента, като то трябва да се замени с вашето собствено наименование, а 'installdir' като базова инсталационна директория на Mambo.

Ето обяснение на основните файлове, изисквани за построяването на компонент. Групирани са както следва според използването им:

· Frontend files (Файлове за предното ниво)

o mycomp.php

o mycomp.html.php (optional)

· Administration files (Администраторски файлове)

o admin.mycomp.php

o admin.mycomp.html.php (optional)

o toolbar.mycomp.php

o toolbar.mycomp.html.php (optional)

· Class files (Файлове за класовете)

o mycomp.class.php (optional)

· Installation files (Инсталационни файлове)

o mycomp.xml

o install.mycomp.php (optional)

o uninstall.mycomp.php (optional)

Файловете маркирани като 'optional' технически не са задължителни за Mambo, но имайки ги ще ви е лесно по-късно да управлявате кода си.


Frontend files (Файлове за предното ниво)

Файловете в тази група се използват да се визуализира компонента пред посетителите на сайта. Т.е ако направите линк в менюто (използвайки Menu -> Main Menu -> New -> Component), тези файлове контролират какво ще водят посетителите като кликнат на това меню (както и всички линкове или бутони визуализирани от компонента ви).

Всички frontend файлове трябва да съдържат следния ред срещу зареждане директно в браузъра.

<?php
/** удистоверява, че файла е зареден от родителския файл */
defined('_VALID_MOS') or die('Direct Access to this location is not allowed.');
?>

· mycomp.php
Това е фаилът, който Mambo зарежда по подразбиране при визуализиране на компонент. Можете да имате нещо като switch, който да вика други бутони или да изкарате съдържание от базата данни.

Един прост switch може да изглежда така:

<?php
switch($task) {
case 'show_form':
// Визуализира формата

break;
case 'save':
// Запазва данните от формата
break;
default:
// Може би визуализира форната или нещо такова

break;
}
?>

Откъде идва променливата $task ? Трябва да я дефинирате във вашата форма (като скрита променлива) или да я вържете с линк, така, че да може да бъде пратена на сървъра. Можете да използвате каквото и да е име за променливата, но 'task' е нещо като стандарт в повечето компоненти. Други променливи, които трябва да подадете на сървъра са $option ( името на директорията на вашия компонент , например com_mycomp) и $Itemid (menu ID на вашия компонент). Променливата $Itemid се използва да се генерира pathway(пътека) и да се освети активното меню. Ако я махнете от URL-то, страницата все още ще се заржда коректно, но няма да има осветено меню и пътя няма да се визуализира както трябва.

В тази страница може да използвате също и $mainframe и $database да вземете конфигурационните стойности, да вземете информация за логнатия потребител, да изпълните задача и т.н.

· mycomp.html.php (optional)
В този файл би трябвало да сложите GUI класовете и функциите. Разбира се можете да пъхнете всичко в mycomp.php , но е добре да имате тези неща отделно.

Mambo използва HTML_mycomp като клас за целта. Няма нужда да създавате функция-конструктор, защото няма не се създава искане за този клас.

<?php
class HTML_mycomp {
function displayForm() {
// Сложете формата тук
}

function displayData($db_result) {
// Принтирайте резултата в красива таблица и т.н.
}
}
?>

Всички форми трябва да будат предадени на index.php. Можете да използвате sefRelToAbs() функцията да конвертирате URL в машина за търсене .

<?php

echo '<form method="POST" action="'. sefRelToAbs("index.php?option=$option&Itemid=$Itemid").'">';

?>

Така, как да направим линк на файловете? $mainframe доставя функция наречена getPath(), за да извърши лесно това. Просто добавете следния ред в mycomp.php.

<?php
// Зарежда HTML class-а
require_once($mainframe->getPath('front_html'));
?>

'front_html' е предефиниран ключ на Mambo за зареждане на mycomp.html.php . Има и други ключове , които ще обесня по-късно. За пълен списък с getPath ключовете и къде Mambo търси тези файлове, отидете на Приложение B.

Сега можем да се обърнем към горните функции от mycomp.php както следва:

<?php
HTML_mycomp::displayForm();
HTML_mycomp::displayResult();
?>



Администраторски файлове

Файловете в тази група се използват от компонента да се визуализира в администраторския панел на Mambo . Т.е. ще имате достъп до тези файлове през страницата на администратора.

Отново всички файлове трябва да съдържата кода срещу директно зареждане в бараузъра:

<?php
// удостоверява, че не се зарежда отвън
defined('_VALID_MOS') or die('Direct Access to this location is not allowed.');

// удостоверява, че потребителя има достъп до тук
if (!($acl->acl_check('administration', 'edit', 'users', $my->usertype, 'components', 'all') || $acl->acl_check('administration', 'edit', 'users', $my->usertype, 'components', 'com_dailymessage'))) {
mosRedirect('index2.php', _NOT_AUTH);
}
?>

Изображението отдолу показва къде се зареждат съответно admin.mycomp.php и toolbar.comname.php в администраторския панел. Файловте завършаващи на '.html.php' не се визуализират, но се съдържат като помощни. Малко е трудно да обясня тези файлове разделено така, че ще ви ги представя, а после ще обясня как са свързани

· admin.mycomp.php
Съдържа 'switchboard'(превключвател) който решава, какво действие да се извърши при кликване върху линк или бутон (Add, Delete, и т.н.)

· admin.mycomp.html.php (optional)
Съдържа клас , който да принтира HTML кода (например визуализация на форма, таблица и т.н.)

· toolbar.mycomp.php
Съдържа 'switchboard' , който решава кой бутони да визуализира при натискане на определени бутони

· toolbar.mycomp.html.php (optional)
Съдържа клас за визуализиране на бутони

Предполагам, че най-лесно учите с примери, така че нека предположим, че нашият компонент наречен My Component,има 2 субменюта, Config и Manage Items. Config е да сменя общите настройки на компонента, а Manage Items е да add/delete (добави/изтрие) някакви данни от базата данни. Нуждаем се да дефинираме тези суб менюта в инсталационния XML файл както следва: (XML структурата и файла ще обясня по-късно)

<?xml version="1.0" ?>
<mosinstall>
<administration>
<submenu>
<menu act="config">Config</menu>
<menu act="manage">Manage Items</menu>
</submenu>
</administration>
</mosinstall>

Атрибута 'act' описва какво е основното действие , което искаме да извършим. Както ще видим по-късно, можем да накараме да се вършат повече неща за всяко действие. Съвсем простичко ето го стилизирания код на менюто:

<code class="example">act: Config (config)

act: Manage Items (manage)

</code>

Когато изберем Config, ще се визуализира форма с попълнени конфигурационни стойности и бутон за запаметяване на промените, ако се направят такива:

<code class="example">act: Config (config)

<b>task: default

Виждаме конфигурационната форма

Buttons: Save (save)</b>



act: Manage Items (manage)

</code>

'task: default' означава, че това се появява по подразбиране, когата натиснем Config . Какво става като натиснем бутона 'Save' ? Формата би трябвало да се приеме и да се запази в базата данни. После пак ще искаме да видим формата с новите стойности.

<code class="example">act: Config (config)

<b>task: save

Запазваме формата в базата данни Save form data to the database

Виждаме новата форма с новите данни

Buttons: Save (save)</b>

task: default

Виждаме конфигурационната форма

Buttons: Save (save)



act: Manage Items (manage)

</code>

Това е всичко, от което се нуждаем за Config менюто. Сега да видим Manage Items. По подразбиране искаме да видим списък с обектите в базата данни, бутон за добавяне на нови обекти, и друг за изтриване на обекти.

<code class="example">act: Config (config)

task: save

Запазваме обекти в базата данни

Виждаме конфигурационната форма

Buttons: Save (save)

task: default

Виждаме конфигурационната форма

Buttons: Save (save)



act: Manage Items (manage)

<b>task: default

Виждаме списък с обектите с меню с отметка от ляво

Buttons: Add (add), Delete (delete)</b>

</code>

Когато кликнем върху 'Add' бутона искаме да видим формата за добавяне на новият обект и 'Save' бутона , а като кликнем върху 'Delete' да изтрием избрания обект и после да видим новия списък с обектите.

<code class="example">act: Config (config)

task: save

Запазваме обекти в базата данни

Виждаме конфигурационната форма

Buttons: Save (save)

task: default

Виждаме конфигурационната форма

Buttons: Save (save)

act: Manage items

<b>task: add

Виждаме add формата

Button: Save (save)

task: delete

Изтриваме обект

Виждаме списък с обектите

Buttons: Add (add), Delete (delete)</b>

task: default

Виждаме списък с обектите

Buttons: Add (add), Delete (delete)

</code>

Последното нещо е да дефинираме какво ще стане като натиснем бутона 'Save' .

<code class="example">

act: Config (config)

task: save

Запазваме обект в базата данни

Виждане конфигурационната форма

Buttons: Save (save)

task: default

Виждане конфигурационната форма

Buttons: Save (save)



act: Manage items (manage)

task: add

Виждаме add формата

Button: Save (save)

task: delete

Изтриваме обект

Виждаме списък с новите обекти

Buttons: Add (add), Delete (delete)

<b>task: save

Добавяме нов обект в базата данни

Виждаме списъка отново

Buttons: Add (add), Delete (delete)</b>

task: default

Виждаме списък с обектите

Buttons: Add (add), Delete (delete)

</code>

Готови сме с дизайна и нека сега ко преведем на PHP :

<?php
switch($act) {
case 'config':
switch ($task) {
case 'save':
// Запазваме обектите в базата данни
// Виждаме конфигурационната форма
// Buttons: Save
break;
default:
// Виждаме конфигурационната форма
// Buttons: Save
break;
}
break;

case 'manage':
switch ($task) {
case 'add':
// Виждаме add формата
// Button: Save
break;
case 'delete':
// Изтриваме обект
// Виждаме обновения списък
// Buttons: Add, Delete
break;
case 'save':
// Добавяме нов обект в базата данни
// Виждаме списъка обновен
// Buttons: Add, Delete
break;
default:
// Виждаме списък с обектите
// Buttons: Add, Delete
break;
}
break;
}
?>

Къде да сложим този код? В admin.mycomp.php и toolbar.mycomp.php. Разликата е, че admin.mycomp.php ще се заеме с обработката на данните, а toolbar.mycomp.php с визуализацията на бутоните. Но структурата е напълно еднаква, защото трябва да дефинираме какава форма и бутони ще се визуализират за всяка комбинация от $act и $task.

<?php
// В admin.mycomp.php

switch($act) {
case 'config':
switch ($task) {
case 'save':
// запазваме обектите в базата данни
// Виждаме конфигурационната форма
break;
default:
// Виждаме конфигурационната форма
break;
}
break;

case 'manage':
switch ($task) {
case 'add':
// Виждаме add формата
break;
case 'delete':
// Изтриваме обект
// Виждаме обновената форма
break;
case 'save':
// Добавяме нов обект в базата данни
// Виждаме обновената форма
break;
default:
// Виждаме списъка с обектите
break;
}
break;
}
?>

<?php
// В toolbar.mycomp.php

switch($act) {
case 'config':
switch ($task) {
case 'save':
// Buttons: Save
break;
default:
// Buttons: Save
break;
}
break;

case 'manage':
switch ($task) {
case 'add':
// Button: Save
break;
case 'delete':
// Buttons: Add, Delete
break;
case 'save':
// Buttons: Add, Delete
break;
default:
// Buttons: Add, Delete
break;
}
break;
}
?>

Имаме вече готовата структура и сега е време да я напълним с кода за обработка на процесите. В основата си всички процеси свързани с GUI (HTML) би трябвало да се държат в *.html.php. За admin.mycomp.php те са лесни за откриване – просто всички действия започващи с „Виждаме...”. Отново класът в admin.mycomp.html.php е HTML_mycomp. Пример:

<?php
// В admin.mycomp.html.php

class HTML_mycomp {
function displayConfigForm() {
}
}
?>

След като напишем функциите в admin.mycomp.html.php, свържете ги от admin.mycomp.php с този ред код:

<?php
// В file admin.mycomp.php
require_once($mainframe->getPath('admin_html'));
?>

'admin_html' е ключ за зареждане на admin.mycomp.html.php също както 'front_html' , който видяхме горе за зарецдане на mycomp.html.php.

Визуализирането на бутони в редицата за това изисква mosMenuBar class. Можете директно да го използвате без да добавяте нищо. На база каквото имаме в toolbar.mycomp.html.php, Ще ви дам пример как да използвате mosMenuBar да визуализирате 'Add' и 'Delete' бутони. А за пълен списък с функциии за визуализация на различни бутони вижте Приложение A.

<?php
// В toolbar.mycomp.php

// Include toolbar's HTML class
require_once($mainframe->getPath('toolbar_html'));

// ... (отрязано) ...

default:
// Buttons: Add, Delete
TOOLBAR_mycomp::defaultButtons()
break;

// ... (отрязано) ...
?>

<?php
// В toolbar.mycomp.html.php

class TOOLBAR_mycomp {
function defaultButtons() {
// Отваря таблицата, която съдържа бутоните
mosMenuBar::startTable();

// Визуализира 'add' бутона
mosMenuBar::addNew();

// Визуалзира 'delete' бутона
mosMenuBar::deleteList();

// Затваря таблицата
mosMenuBar::endTable();
}
}
?>

Toolbar button действа като submit button и затова трябва да имаме форма на всяка страница. Тази форма трябва да се нарече 'adminForm', приета от index2.php, и има скрити полета за връщане на променливите $option, $act, и $task. Ето много малък пример за форма.


<?php
// Името на формата трябва да е adminForm
echo '<form action="index2.php" method="POST" name="adminForm">';

// Option е на разположение като глобална променлива

echo '<input type="hidden" name="option" value="'.$option.'">';

// Act също е на разположение като глобална променлива
echo '<input type="hidden" name="act" value="'.$act.'">';

// The value of task will be set by Mambo upon submit,
// depending on which button is clicked
echo '<input type="hidden" name="task" value="">';

echo '</form>';
?>

Ако имате списък от обекти с полета за отметки във формата,Mambo има JavaScript функции за select/deselect . Изискванията за това са::

· checkbox-а, които действа като превключвател за select/deselect трябв ада се казва 'toggle'

· onClick от 'toggle' checkbox-а трябва да вика функция checkAll(n). Заменете 'n' с номера на checkbox-овете които имате в списъка (можете да вземете стойноста например от mysql_num_rows() )

· Всеки checkbox трябва да има свой 'id' атрибут заo 'cb', последван от интегер който почва от 0 ('cb0', 'cb1', 'cb2', ...).

· onClick на всеки checkbox трябва да вика isChecked(this.checked) функцията.

· И Накрая трябва да имате скрито поле 'boxchecked' със стойност 0.


<input type="checkbox" name="toggle" value="" onClick="checkAll(n);">

<input type="checkbox" id="cb0" name="cid[]" value="" onClick="isChecked(this.checked);">
<input type="checkbox" id="cb1" name="cid[]" value="" onClick="isChecked(this.checked);">
<input type="checkbox" id="cb2" name="cid[]" value="" onClick="isChecked(this.checked);">

<input type="hidden" name="boxchecked" value="0">


Class files (Файлове за класовете)

· mycomp.class.php (optional)
mycomp.class.php съдържа други помощни функции , които се споделят между frontend и adminstration files. Например, можете да имате функция която да връща резултата от базата данни тук и друга функция в mycomp.html.php която използвайки резултата да ги визуализира красиво в някоя таблица. Можете да сложите тозу файл в 'installdir/components/mycomp' (Mambo ще провери първо тук) или в 'installdir/administrator/components/mycomp' и да я вкарате от frontend или administration файловете чрез следните редове:

<?php
require_once($mainframe->getPath('class'));
?>

Можете да имате разбира се и други файлове. Тогава ги вкарвате с :

<?php
// Example how to include other helper file
// $mosConfig_absolute_path is the full path
// to Mambo installation directory
require_once($mosConfig_absolute_path.'/components/mycomp/helper1.php');
?>






Installation files(Инсталационни файлове)

Използват се само по време на инсталацията и деинсталацията на компонента да преместят всичко където трябва и да направят базата данни или други неща. Слагат се в: installdir/administrator/components/mycomp folder.

· mycomp.xml
Съдържа детайли за компонента (име версия и т.н.), списък с използваните файлове и картинки, SQL командите за изпълнениеl и списък с менютата в администраторската страница (under 'Components' менюто).

Ето пример:

<?xml version="1.0" ?>
<mosinstall type="component">
<name>My Component</name>
<creationDate>01/02/2005</creationDate>
<author>Your Name</author>
<copyright>© 2005 Company</copyright>
<authorEmail> [email protected] This email address is being protected from spam bots, you need Javascript enabled to view it </authorEmail>
<authorUrl>www.domain.com</authorUrl>
<version>1.0</version>
<description>
Description of this component
</description>

<files>
<filename>mycomp.php</filename>
<filename>mycomp.html.php</filename>
</files>

<images>
<filename>img/img1.gif</filename>
<filename>img/img2.gif</filename>
</images>

<install>
<queries>
<query>
CREATE TABLE #__mycomp_data(
id int unsigned not null,
name varchar(255) not null,
PRIMARY KEY (id)
) TYPE=MyISAM;
</query>
<query>
(another query, etc)
</query>
</queries>
</install>

<installfile>
install.mycomp.php
</installfile>

<uninstallfile>
uninstall.mycomp.php
</uninstallfile>

<uninstall>
<queries>
<query>DROP TABLE #__mycomp_data;</query>
<query>(another query, etc)</query>
</queries>
</uninstall>

<administration>
<menu>My Component</menu>
<submenu>
<menu act="config">Config</menu>
<menu act="manage">Manage Items</menu>
</submenu>

<files>
<filename>admin.mycomp.php</filename>
<filename>admin.mycomp.html.php</filename>
<filename>toolbar.mycomp.php</filename>
<filename>toolbar.mycomp.html.php</filename>
</files>

<images>
<filename>img/img3.gif</filename>
<filaname>img/img4.gif</filename>
</images>
</administration>
</mosinstall>

All files в <files></files> и <images></images> ще бъдат копирани в installdir/components/mycomp докато тези в <administration></administration> ще се копират в installdir/administrator/components/mycomp.

SQL –ите в <install></install> ще се изпълнят по време на инсталацията а тези в <uninstall></uninstall> по време на деинсталацията. Формата на таблиците е #__mycomp_tablename където #_ ще се замести от Mamboв каквото сте избрали по време на неговата инсталация. По-подразбиране е 'mos' така че '#__mycomp_data' ще създаде таблица 'mos_mycomp_data'.

· install.mycomp.php (optional)
Съдържа само една функция com_install(), която ще се повика след успешна иснталация:

· <?php
function com_install() {
return 'Installation successful! Please check my website for the latest update and support.';
}
?>

Моля забележете, че com_install() очаква вие да върнете съобщение!

· uninstall.mycomp.php (optional)
Същата работа, но след успешна деинсталация!

<?php
function com_uninstall() {
return 'My Component is successfully removed from Mambo';
}
?>

Е, това е! Следващите страници са гореспоменатите Приложения А и В . Ако искате да почетете повече Joseph LeBlanc също има добър tutorial на страницата си.

Приложение A. mosMenuBar

Параметрите са:
$task: The task to perform
$alt: The alt text for the icon

Пример

<?php
// Отваря таблица с бутоните
mosMenuBar::startTable();

// Добавя бутон 'add_category'
mosMenubar::addNew('add_category');

mosMenuBar::endTable();
?>

Изображение



Функция





startTable()
Writes the start of the button bar table

(custom)



custom($task = '', $icon = '', $iconOver = '', $alt = '', $listSelect = true)
Writes a custom options & task button for the button bar Parameters: $icon: The image to display (path relative to 'image' folder in the current directory) $iconOver: The image to display when moused over $listSelect: True if required to check that a standard list item is checked



addNew($task = 'new', $alt = 'New')
Text: New



publish($task = 'publish', $alt = 'Publish')
Text: Publish



publishList($task = 'publish', $alt = 'Publish')
Text: Publish



makeDefault($task = 'default', $alt = 'Default')
Text: Default



assign($task = 'assign', $alt = 'Assign')
Text: Assign



unpublish($task = 'unpublish', $alt = 'Unpublish')
Text: Unpublish



unpublishList($task = 'unpublish', $alt = 'Unpublish')
Text: Unpublish



archiveList($task = 'archive', $alt = 'Archive')
Text: Archive



unarchiveList($task = 'unarchive', $alt = 'Unarchive')
Text: Unarchive



editList($task = 'edit', $alt = 'Edit')
Text: Edit



editHtml($task = 'edit_source', $alt = 'Edit HTML')
Text: Edit HTML



editCss($task = 'edit_css', $alt = 'Edit CSS')
Text: Edit CSS



deleteList($msg = '', $task = 'remove', $alt = 'Delete')
Parameter:
$msg: Postscript for the 'are you sure' message
Text: Delete



trash($task = 'remove', $alt = 'Trash')
Write a trash button that will move items to Trash Manager
Text: Trash



preview($popup = '', $updateEditors = false)
Writes a preview button for a given option (opens a popup window)
Parameters:
$popup: The name of the popup file (excluding the file extension). This variable will be used in JavaScript's window.open() as follows:
window.open('popups/t=', 'win1', 'status= no,toolbar=no, scrollbars=yes, titlebar=no, menubar=no, resizable=yes, width=640, height=480, directories=no, location=no'); Text: Preview



help($ref)
Writes a button to open help page from $mosConfig_live_site/help/$ref.xml Parameters:
$ref: help page file name (without extension)
Text: Help



save($task = 'save', $alt = 'Save')
Text: (use $alt value)



cancel($task = 'cancel', $alt = 'Cancel')
Writes a cancel button and invokes a cancel operation
Text: (use $alt value)



back() Writes a cancel button that will go back to the previous page without doing any other operation
Text: Back



media_manager($directory = '')
Parameters:
$directory: The sub-directory to upload the media to
Text: Upload



divider()
Write a divider between menu buttons





spacer($width = '')
Writes a spacer cell





endTable()
Writes the end of the menu bar table

Приложение B. Keys used by getPath()









Ключ



Място

front



installdir/templates/curr_template/components/mycomp.php
installdir/components/mycomp/mycomp.php

front_html



installdir/templates/curr_template/components/mycomp.html.php
installdir/components/mycomp/mycomp.html.php

admin



installdir/administrator/components/mycomp/admin.mycomp.php
installdir/administrator/components/com_admin/admin.mycomp.php

admin_html



installdir/administrator/components/mycomp/admin.mycomp.html.php
installdir/administrator/components/com_admin/admin.mycomp.html.php

toolbar



installdir/administrator/components/mycomp/toolbar.mycomp.php

toolbar_html



installdir/administrator/components/mycomp/toolbar.mycomp.html.php

toolbar_default



installdir/administrator/includes/toolbar.html.php

class



installdir/components/mycomp/mycomp.class.php
installdir/administrator/components/mycomp/mycomp.class.php
installdir/includes/mycomp.class.php


Автор Иван Костов (joomla-bg.com)