HOWTOS.txt

= How Upgrading the Help =

   * cd doc/src
   * edit the files
   * cd ../../scripts
   * ./makehelp

= Code Starting Points =

The database schema with annotations is described in

  config/schema.yml

The

  apps/asterisell/config/app.yml

contains many annotations on how configure Asterisell.

The application has on-line help, useful for understanding important concepts.

  apps/asterisell/lib/jobs/RateCalls.php

is the job rating all the calls.

  apps/asterisell/lib/jobs/invoices/GenerateInvoiceDetails.php

is the job calculating the invoices.

== Customizations ==

= Developer Annotations =

== Add a Custom Rate Method ==

  > cp -r apps/asterisell/modules/custom_demo_rate apps/asterisel/modules/my_custom_rate

  * add the rate in the "apps/asterisell/config/app.yml";
  * clear the Symfony cache ("./symfony cc");
  * adapt the content of "my_custom_rate";

== Retest ==

Apply instructions in MANUAL_TETING.txt

== Create New Module ==

  > ./symfony init-module asterisell <module-name>

Make sure to add "security.yml" for each new module in order to prevent the accessing from normal users.

With current version of Asterisell replace the header of "apps/asterisell/modules/<module-name>/actions/actions.class.php from something like

  > class web_accountActions extends ... {

to 

  > class web_accountActions extends autoweb_accountActions {

NOTA: update both class name and parent name.

Remove the content of "executeIndex" function.

== Modify Database ==

Modify 

  > config/schema.yml

Execute

  > cd scripts
  > sh makedb.sh

In some cases you must substite `Type=InnoDB;`  with `Engine=InnoDB;`,
inside file `data/sql/lib.model.schema.sql`.
In case of problems during database creation (initial installation of Asterisell), you must update manually this file.

== Freeze Symfony Framework ==

How to create a new Symfony FREEZE from scratch.

  * symfony unfreeze
  * update Symfony project.
  * apply "symfony-patch" to the symfony project.
  * symfony cc
  * symfony freeze

Otherwise

  * rm -r -f web/sf
  * rm -r -f data/symfony
  * rm -r -f lib/symfony
  * remove config/config.php
  * remove symfony.php
  * remove symfony
  * create an empty Symfony project using "symfony init-project some_name"
  * copy removed files from new empty project to Asterisell application
  * symfony freeze

== Code Snippest ==

=== Load Helpers inside Actions / Modules ===

From action

  sfLoader::loadHelpers(array('I18N', 'Debug', 'Asterisell'));

from Template

  use_helper('Asterisell');

== Custom Fields in Forms ==

Supposing to have a custom ar_params.vat_tax_perc field.

Create inside "lib/model/ArParams.php" the get and setter methods

  public function getVatTaxPercAsPhpDecimal() {
    return from_db_decimal_to_php_decimal($this->getVatTaxPerc());
  }

  public function setVatTaxPercAsPhpDecimal($d) {
    $this->setVatTaxPerc(from_php_decimal_to_db_decimal($d));
  }

and add the field inside "generator.yml"
      vat_tax_perc_as_php_decimal: { name: Tax %, type: input_tag, help: "VAT Tax % to apply in invoices. Something like '19.5' without the '%' symbol and '.' as decimal separator." }

     Company legal information (used on invoices): [vat_tax_perc_as_php_decimal, legal_address, legal_city]

== Low Level Access to DB ==

  http://creole.phpdb.org/trac/wiki/Documentation/CreoleGuide

  GenerateInvoiceDetails for an example of SQL Query.

  RateCalls for examples of UPDATE Queries.

== Adding User Messages ==

In Action code:

  $this->setFlash('notice', $message);
  $this->setFlash('error', $message);

Copy the 

  _list_header.php 

template of apps/asterisell/rate_by... in order to support the error message.

== Adding Debug Log Messages ==

Inside an action

  $this->logMessage('help me!', 'info');

Outside an action

  sfContext::getInstance()->getLogger()->info($message);
  sfContext::getInstance()->getLogger()->err($message);

Inside a template if the error must be viewed on the web toolbar

  echo log_message(...);
  
== Simple Queries ==

This retrieve the first record:

    $c = new Criteria();
    $c->add(ArParamsPeer::IS_DEFAULT, TRUE);
    $params = ArParams::doSelectOne($c);

This retrieve all the records:

    $c = new Criteria();
    $c->add(ArParamsPeer::IS_DEFAULT, TRUE);
    $results = ArParamsPeer::doSelect($c);

== Create Queries directly in SQL ==

$connection = Propel::getConnection();
$query = 'SELECT id FROM ar_rate';
$stm = $connection->createStatement();
$rs = $stm->executeQuery($query);

while($rs->next()) {
  echo $rs->getInt("id");
  echo "\n";
}

Date inside "..." and respect SQL syntax.

== Create Complex Custom Queries ==

See 

  apps/asterisell/modules/report/template/_list_header.php

that creates a complex query.

== User and Security Management ==

Study 

  apps/asterisell/lib/myUser.class.php

Access user data at run-time using:
  * always: sfContext::getInstance()->getUser()
  * in forms: $sf_user

== Adding a New Job ==

  * "apps/asterisell/lib/jobs" contains all Jobs;
  * create JobData (eventually);
  * create a JobProcessor following the schema of other JobProcesorrs;
  * register the JobProcessor inside app.yml;

= Common Errors in Code =

  * mismatched PHP variable names, not detected because in code-path that are not executed often, especially error signal;
    * PhpStorm signals many of these problems. Check always the source code with it.
    
= Sorting On Complex Columns =

See module office like an example:
  * ArOfficePeer
  * customized generator query

Unfortunate Choices inside Code
===============================

DestinationType is both used for managing the list of CDRs to rate (unprocessed state),
and the call-direction. This complicates some system rates interaction: everything is put
inside this field is lost... The best choice is using a distinct field.