The document provides steps to create a new module in TomatoCMS called "Contact" that allows users to manage contact information. The key steps include: 1. Creating the basic module folder structure and config files 2. Defining the database schema and queries needed to install and uninstall the module 3. Creating the administrative menu item and setting permissions for users to access the new functionality. 4. Connecting to the database by implementing the required model, interface and DAO classes. 5. Retrieving, displaying and editing contact data by writing the necessary controller and view code.

1. TomatoCMS : How to Create Component www.tomatocms.com

2. Table of Content TomatoCMS : How to Create Module TomatoCMS : How to Create Widget TomatoCMS : How to Create Plug-in TomatoCMS : How to Create Hook

3. TomatoCMS : How to Create Module

4. How to Create Module? Refer from http://docs.tomatocms.com/index.php/Develop_new_module_-_Part_1_-_Module_directory_structure TomatoCMS support modular architecture with more than 10 built-in modules. In this series, I will help you how to create new module from “ scratch” . Step to create module (for v.2.0.6 to v.2.0.8) Create Module Module Permission Connect Database Improve Module’s code

5. Example: Contact Module Requirement Create contact form : Display on web page for capture e-mail and inquiry information Admin site: able to inquiry and view inquiry information (And also, maintenance information) From above requirements: - Need to make new module for maintain inquiry information in back-end Need to create new Widget for capture inquiry information

6. 1) Create New Module : Contact Step 1: Create Module folder New folder is located: <tomato root>\application\modules\ e.g. D:\php\tomatocms\application\modules

7. 1) Create New Module : Contact Step 2: Add module information By create “ about.xml ” in “ config ” folder (under new folder) e.g. \modules\contact\config <?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?> <!DOCTYPE module SYSTEM &quot;http://schemas.tomatocms.com/dtd/module_about.dtd&quot;> <module> <name>contact</name> <description langKey=&quot;about_contact_description&quot;><![CDATA[Manage contacts]]></description> <author>TomatoCMS Core Team</author> <email>core@tomatocms.com</email> <version>2.0.8</version <license>free</license> <requires> <requiredModules> <requiredModule name=“mail&quot; /> </requiredModules> </requires> </module> More detail: http://docs.tomatocms.com/index.php/Develop_new_module_-_Part_2_-_Create_module

8. 1) Create New Module : Contact Step 3: Add database queries This file also defines SQL queries for your module. For simply illustration, I assume that our contact module has only one database table named contact : SEQ Field Name Data Type NULL Remark 1 contact_id INT(10) NOT PK & Auto-increase 2 contact_name VARCHAR(50) NOT 3 email VARCHAR(100) NOT 4 website VARCHAR(200) NOT 5 contact_text VARCHAR(1000) NOT 6 contact_date DATE NOT

9. 1) Create New Module : Contact Let's add SQL queries including database creation queries, data initializing queries, etc to our about.xml file: <?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?> <!DOCTYPE module SYSTEM &quot;http://schemas.tomatocms.com/dtd/module_about.dtd&quot;> <module> ... <install> <db adapter=&quot;mysql|pdo_mysql&quot; > <query> <![CDATA[DROP TABLE IF EXISTS `###contact`]]> </query> <query> <![CDATA[CREATE TABLE `###contact` ( `contact_id` int(10) unsigned NOT NULL auto_increment, `contact_name` varchar(50) NOT NULL, `email` varchar(50) NOT NULL, `website` varchar(200) default NULL, `contact_text` varchar(1000) NOT NULL, `contact_date` date NOT NULL, PRIMARY KEY (`contact_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;]]> </query> </db> < /install>

10. 1) Create New Module : Contact And create drop statement when uninstall module <?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?> <!DOCTYPE module SYSTEM &quot;http://schemas.tomatocms.com/dtd/module_about.dtd&quot;> <module> ... <install> … <uninstall> <db adapter=&quot;mysql|pdo_mysql&quot;> <query><![CDATA[DROP TABLE IF EXISTS `###contact`;]]></query> </db> <db adapter=&quot;pgsql&quot;> <query><![CDATA[DROP TABLE IF EXISTS ###contact;]]></query> </db> <db adapter=&quot;sqlsrv&quot;> <query><![CDATA[IF EXISTS (SELECT NAME FROM SYSOBJECTS WHERE NAME='###contact' AND TYPE='U') DROP TABLE ###contact;]]></query> </db> </uninstall>

11. 1) Create New Module : Contact Step4: Create task list on Admin’s menu Need to define activities in “ about.xml ” <?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?> <!DOCTYPE module SYSTEM &quot;http://schemas.tomatocms.com/dtd/module_about.dtd&quot;> <module> ... <install> … <uninstall> … <admin> <task langKey=&quot;task_list_contacts&quot; route=&quot;contact_index_list&quot; /> </admin>

12. 1) Create New Module : Contact Step5: Create language pack for explanation By create “language” directory under module folder Then create language file (following default languages). Mostly default is “en_US” Language file format: lang.<language code>.ini e.g. lang.en_US.ini

13. 1) Create New Module : Contact Example of language file (lang.en_US.ini) [about] about_contact_description = &quot;Manage contacts&quot; task_list_contacts = &quot;Contacts list&quot;

14. 1) Create New Module : Contact Finally, need to install module by go to “System”  “Extend”  “Module” You can click Install to install module and vice versa, you can click Uninstall to uninstall a module. As I said in step 2, after clicking Install (or Uninstall ), all SQL queries defined in install (uninstall) tag from about.xml file also were already executed. But from now, you can’t see the new menu in “Admin menu”. You need to create permission & assign resources (see next chpater)

15. 2) Module permissions Procedure Define routes Define Permission Add resources

16. 2) Module permissions Step1: Create route files in \modules\<module name>\config\routes\ Route file must in format: <any name>.ini Note that , you should write the route name in order moduleName_controllerName_actionName, to ensure that routes are difference. In backend section, you should write route start with admin to distinguish from frontend section.

17. 2) Module permissions Step2: How to manage access permission of users, we will create permissions.xml file to solve this issue Note , name of resource is name of controller, and name of privilege is name of action correspond to contact.ini file. At here, we see langKey again, so at lang.en_US.ini file, we have to add following code

18. 2) Module permissions Step3: Add resources by see in Admin menu  select “System”  “Privilege” Click on Contact

19. 2) Module permissions Click on “Add” for show this Menu’s Group Click on “+” for add resources/action to system (After Add Menu & action completely)

20. 2) Module permissions Refresh web-page or click on Dashboard, you will see new menu

21. 2) Module permissions Menu Header Task under menu Menu Setup

22. 2) Module permissions Re-cap for Module-permission After Add resource and menu appear. It’s work “Admin” user-group only. Another group need add permission to access

23. 2) Module permissions Try to play with new menu? Click on “Contacts List” This error is came from no code in Controller & view (refer to TomatoCMS/ZF MVC) Next step, we need to create controller & view for this resources

24. 2) Module permissions Create controller code Rule for coding are present in “TomatoCMS in A Nutshell” Make skeleton code for controller

25. 2) Module permissions Create view (matched with Controller) Rule for coding are present in “TomatoCMS in A Nutshell”

26. 2) Module permissions Try to play with new menu again…. Click on “Contacts List” From now, you can code module by following rule in “TomatoCMS in A Nutshell”

27. 3) Connect the Database Retrieve Data Display Data Edit Existing Data Delete Existing Data

28. 3) Connect the Database Step1: Retrieve Data Refer to “TomatoCMS in A Nut shell”, we need to create: - Model Interface DAO Start from create “Model” At model section, we implement most of operations with database. Assume that we have a table t_contact with its fields are: contact_id, contact_name, email, website, contact_text, contact_date. Note: - I define pre-fix of table name as “ t_ ” in “ application.ini ”

29. 3) Connect the Database First, create file Contact.php inside model folder with content like this: Code inside: - This file describe properties ( or fields) of this table. You can see this class extend from Tomato_Core_Model_Entity , this is a already library which we was created and ready to use.

30. 3) Connect the Database Then, create “Interface” for implement methods of each DAO Start from create folder “interface” under “models” in module Then create new file: Contact.php for declare interface of DAO Code inside: - All methods will show/explain in next chapter

31. 3) Connect the Database To use difference database, you must create difference folder for corresponding database as In this sample, I will show implement code for MySQL with PDO only. So, I will create new file: Contact.php under “ \pdo\mysql ” Always implement method “convert” in DAO

32. 3) Connect the Database Implement code for methods getContact()  search data with specified criteria

33. 3) Connect the Database Implement code for methods count()  count record with specified criteria (for paging purpose)

34. 3) Connect the Database Implement skeleton code for other methods Just make it’s able enough to run 

35. 3) Connect the Database Step2: Display Data At controller section, at here, controller is Index and action is list , so insert following code into list action

36. 3) Connect the Database Explanation of Controller code Database connection statements Parsing submitted parameters Get data from Database Pass values into View

37. 3) Connect the Database and at view , insert following code into list.phtml file View has contained HTML/javaScript and PHP code In this PPT file will show only code that related to PHP Full source code: - Pls see in attachment. Load javaScript & CSS

38. 3) Connect the Database View code (continue) Render values that pass from controller and show on HTML

39. 3) Connect the Database After that, you need to add following parameters to lang.en_US.ini file

40. 3) Connect the Database See a result No result display when start up this page

41. 3) Connect the Database Make some sample data in database and see result again Display only 15 rows from tables (need to modify more for display correct data)

42. 4) Improve Module’s code Display with pagination CRUD page Advance AJAX integration Reduce Duplicated Code (DRY/DIE principle)

43. 4) Improve Module’s code Pagination Display Currently, our page can display but can’t Searching Display more than 15 rows We will start from “Searching” first Improve code in “View” Improve code in “Controller”

44. 4) Improve Module’s code Improve code in “View” Add javascript code for button

45. 4) Improve Module’s code Because in view, we’ve implement AJAX for query data. We need to improve code in controller too.

46. 4) Improve Module’s code Add more lines AJAX display

47. 4) Improve Module’s code Explanation of new code in “Controller” If user has submit query (by press filter button) Disable view-render & layout Get files from “/index/_filter.phtml” to render Send contents to response object Similar to code in View file

48. 4) Improve Module’s code See the result Result is matched with your filter criteria.

49. 4) Improve Module’s code Debugging on AJAX passing parameters & response I use FireBug (Fixfox Exentension) for see how it’s work Send request to search/filter via AJAX

50. 4) Improve Module’s code See AJAX response (result of sending contents of _filter.phtml)

51. 4) Improve Module’s code More improve: Add pagination (for display more than 1 page) TomatoCMS provide Utilities Class : Tomato_Utility_PaginatorAdapter Implement in View & Controller Controller’s code

52. 4) Improve Module’s code Add paginator in View list.phtml _filter.phtml

53. 4) Improve Module’s code Then, see the result again

54. 4) Improve Module’s code CRUD page C : Create R : Refer (in this case, meant to searching) U : Update D : Delete I will 3 cases for make you clear in your mind: - Update Delete Refer : Just show in previous slides

55. 4) Improve Module’s code Update screen : How to & Procedure? Requirements Display new page with existing data Captures changing detail and store back into Database. Procedure: start from…. Define routing for update page Create new method in Controller Add new key for languages Create new view for display result Create new method in DAO Integration with listing page

56. 4) Improve Module’s code Define routing for Update page Modify file: /config/routes/contact.ini We use other type of routing (“Regex” routing) for.. Dynamic URL RESTFul format Add new routing for edit page

57. 4) Improve Module’s code Try to run by typing URL directly in Address bar And we got… For error message, it’s mean… URL is correct (match with routing file) Controller is existing View can’t load (sure, we didn’t do it)

58. 4) Improve Module’s code Create new method in controller: editAction() Why this name? Match with action name that defined in routing Controller method’s naming format: <actionName>Action() Code are… Note: the parameter always named “ contact_id ” because we’ve declare in routing file like this

59. 4) Improve Module’s code Create new view: edit.phtml Why this name? Match with action name in Controller View’s naming format: <viewName>.phtml View code is similar to listing but I think it’s simpler than… More detail, please check in source code Create new method in DAO : getById($id) make SQL statement for get data from Database

60. 4) Improve Module’s code Add new language’s key in language file Add in “lang.en_US.ini” Need to add every times IF you’ve modify the view file Try to run it again

61. 4) Improve Module’s code Play with it and you will found: - Contact Name is required E-mail is required When save changing, nothing happen! Now, we will make it’s able to save change: Modify controller code to accept changing values Modify DAO to support update method

62. 4) Improve Module’s code Improve Controller code Then, improve DAO code in update method

63. 4) Improve Module’s code Try again on browser Now, Everything is perfect. Finally, we will integrate 2 parts (list & update)

64. 4) Improve Module’s code Integrated with listing page It’s very simple, just make link for edit in view  list.phtml _filter.phtml Then, try it again by click on “List of Contact” (in edit page) or all from menu directly.