Creating a new module: basic steps?

[Guido1982]

I took a look at this link for creating a new module and have some questions. First off let me explain what my module should do:

• It'll create a connection to Exact Online accounting software via their API. For this I only need a settings template where a user can set the client ID, client secret, division, return url and maybe some options.
• I'm going to create some workflow tasks that will read the credentials from the database and use them to connect with Exact Online. On every invoice save, for example this will be used to establish the connection and send the invoice.
• Later on I'd like to create a cron that reads from exact if invioces are paid (it has a bank link so in Exact this is automated) and set invoices in coreBOS to paid as well.
  

Now for the questions:

• I understand the vtlib module creation will auto-create tables and include the module name here. The only table I need is one where I can store the values in the settings page. Can I use the auto-created one for this? Or better to create table manually?
• I'm guessing the TPL files for the settings page go in the same folder as normal TPL file templates, but how do I create a link in the settings page?
• What exactly are the modules' 'event handlers'? This seems like a workflow task?
  

EDIT: Add attachment PDF with original vTiger tutorial for creating module

[Guido1982]

One thing I already found was this: http://corebos.org/documentation/doku.php?id=en:devel:corebos_hooks

[joebordes]

(11-28-2015, 09:45 AM)Guido1982 Wrote: I understand the vtlib module creation will auto-create tables and include the module name here. The only table I need is one where I can store the values in the settings page. Can I use the auto-created one for this? Or better to create table manually?

You can create a normal module with the fields you need and have the user configure the access as a new record, just like any other module. You could even add a preSaveCheck to avoid creating more than one record. That is the easy way.

If you want to do it in Settings (which is a little more in line with the application) you have to create your own Settings.php file in your module. Simply adding this file to your module will give it access to layout editor and workflows, if you modify it you can add your own entries and your own templates. The problem with this is that you have to manually do all the work, you have to create the table, setup the form, recover and edit all the data.

There are a few examples lying around but I will point you to the Payment module that has a simple example:

https://github.com/tsolucio/corebos/blob/master/modules/CobroPago/Settings.php#L68

(11-28-2015, 09:45 AM)Guido1982 Wrote: I'm guessing the TPL files for the settings page go in the same folder as normal TPL file templates, but how do I create a link in the settings page?

All templates for a new module go inside it's own template directory. For example for Payment module which is called CobroPago, you will have Smarty/templates/modules/CobroPago. When you create your module you create a "templates" directory and they will copied to the correct place during installation.

Look at the structure in some of the online modules:

https://github.com/tsolucio/Timecontrol
https://github.com/tsolucio/coreBOSPackingSlip

(11-28-2015, 09:45 AM)Guido1982 Wrote: What exactly are the modules' 'event handlers'? This seems like a workflow task?

I understand you are talking about the vtlib_handler() method. These are a set of events that are launched when installation related things happen. For example, when you install a module the module.postinstall event is launched so you can do some additional administration tasks. The most normal ones is to relate your new module with other modules in the system.

[Guido1982]

Thanks, I'll start refacturing my files and code to try and make an actual module.

[Guido1982]

(11-28-2015, 03:55 PM)joebordes Wrote: You can create a normal module with the fields you need and have the user configure the access as a new record, just like any other module. You could even add a preSaveCheck to avoid creating more than one record. That is the easy way.

a PreSaveCheck on creation of each record? Or a presave check on creation of the module?

(11-28-2015, 03:55 PM)joebordes Wrote: If you want to do it in Settings (which is a little more in line with the application) you have to create your own Settings.php file in your module. Simply adding this file to your module will give it access to layout editor and workflows, if you modify it you can add your own entries and your own templates. The problem with this is that you have to manually do all the work, you have to create the table, setup the form, recover and edit all the data.

I've done this, but haven't spent enough time researching it yet. I would like to do it this way to have a neater result.. I'll take a look at the payment module but I have a lot of methods for the database stuff (the settings piece, with the OAuth parameters and other Exact Online specific settings) already written so I think I'll take this approach.

(11-28-2015, 03:55 PM)joebordes Wrote: All templates for a new module go inside it's own template directory. For example for Payment module which is called CobroPago, you will have Smarty/templates/modules/CobroPago. When you create your module you create a "templates" directory and they will copied to the correct place during installation.

You mean templates inside Smarty folder right?

Anyway I'm also thinking about using some record saving in the module, but I'll explain this in the thread about the actual module.

[joebordes]

a preSaveCheck() is a method you can add to your module. it will get called right before saving and if it returns an error status and message the user will be redirected to the edit screen with the error message and no record will have been saved.

You can see examples of this in GlobalVariables where we check that only one record is set to default per variable and in Documents where we make sure the attachment can be saved before saving the record details.

In your case you could check if a record already exists and stop the creation of other records so there could only be one record in the module.

[Guido1982]

Just a sideway question now that I'm studying the PDF file from the vTiger team:

I see here on page 12 the following:

Code:

$moduleInstance->setEntityIdentifier($fieldInstance);

It doesn't really specify in what stage of the process you can (or should) do this, but if I understand correctly, you can either do this before you fire the initial

Code:

$moduleInstance->save();

, or reïnitiate the module instance after it already exists with:

Code:

$moduleInstance = new Vtiger_Module();
$moduleInstance->name = 'Payslip';

And add the EntityIdentifier later? Or will it not save the module without an entity identifier? And if you never specify one, will the column be create automatically?

---

I don't really understand this: two related modules on a single UI10 field?

Code:

$fieldInstance->setRelatedModules(Array('OtherModule1', 'OtherModule2'));

How will it know which records to load? Or will it just load all records from both modules?

---

Okay, I've been looking at the URL's for some existing module by just browsing through the system. Correct me if I'm wrong:

• module parameter: tells the system which folder in the file system to look for.
• action parameter: tells the system which PHP file in the system to use for handling.
  

Clicking on the name of the module (the ParentTab or just Tab?) will automatically invoke the index.php file inside the indicated module folder, which for instance in the case of assets invokes the list view.

The record parameter is used inside the detaliview.php to indicate which record should be loaded. Every php handler file ends up in displaying a Smarty template that handles the actual rendering of the view.

[Guido1982]

About the manifest.xml:

ASm I correct to assume I could include the complete installation (including tables that are outside of the 'normal' entity module scope) in here? And could I create an 'after install event/handler' that could point to a script file that automatically installs my workflow files?

Also:

PHP Code:

<customlink>
<linktype>DETAILVIEWWIDGET</linktype>
<linklabel>Stopwatch</linklabel>
<linkurl><![CDATA[module=Timecontrol&action=TimecontrolAjax&file=StopWatch&return_module=$MODULE$&record=$RECORD$]]></linkurl>
<linkicon><![CDATA[]]></linkicon>
<sequence>0</sequence>
<handler_path><![CDATA[]]></handler_path>
<handler_class><![CDATA[]]></handler_class>
<handler><![CDATA[]]></handler>
</customlink> 


I think the variables like '$MODULE$' are automatically available? Or should I do something to create them? And could I skip writing an install script using this?

---

Quote: I understand you are talking about the vtlib_handler() method. These are a set of events that are launched when installation related things happen. For example, when you install a module the module.postinstall event is launched so you can do some additional administration tasks. The most normal ones is to relate your new module with other modules in the system.

Do you have an example of this on github?

[joebordes]

1.1- Yes you can create additional tables in manifest.xml:
https://github.com/tsolucio/corebos/blob/master/modules/Calendar4You/manifest.xml

1.1.- Yes, you can create the workflows in vtlib_handler

2.- $MODULE$ and $RECORD$ are directly available on the custom links, no need to do anything.

3.- Examples:
https://github.com/tsolucio/coreBOSAddress/blob/master/modules/cbAddress/cbAddress.php#L494
https://github.com/tsolucio/corebos/blob/master/modules/CobroPago/CobroPago.php#L536

[Guido1982]

Quote: 1.1.- Yes, you can create the workflows in vtlib_handler

Ah, I see now the handler is in the main PHP file of the module, so in my case ExactOnline.php...