Difference between revisions of "Freeside:2.1:Documentation:Developer"

From Freeside
Jump to: navigation, search
(New page: = Introduction = Please consider sharing your modifications with the community and helping integrate them into the standard code! [http://freeside.biz/cgi-bin/mailman/listinfo/freeside-d...)
 
(Services)
 
(9 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
Please consider sharing your modifications with the community and helping integrate them into the standard code!
 
Please consider sharing your modifications with the community and helping integrate them into the standard code!
  
[http://freeside.biz/cgi-bin/mailman/listinfo/freeside-devel/ Subscribe] to the freeside-devel mailing list.  Send your changes as unified diffs (diff -u).  If possible, send changes against current CVS HEAD and also any branch they should be applied to (i.e. FREESIDE_1_9_BRANCH, FREESIDE_1_7_BRANCH).  However, if all you have is diffs against a release, well, probably best to send what you have rather than waiting.
+
[http://freeside.biz/cgi-bin/mailman/listinfo/freeside-devel/ Subscribe] to the freeside-devel mailing list.  Send your changes as unified diffs (diff -u).  If possible, send changes against current CVS HEAD and also any branch they should be applied to (i.e. FREESIDE_2_3_BRANCH).  However, if all you have is diffs against a release, well, probably best to send what you have rather than waiting.
  
 
Also note that the [http://www.fsf.org/licensing/licenses/agpl-3.0.html license] requires that you provide source code if you provide hosted access to a modified Freeside instance.
 
Also note that the [http://www.fsf.org/licensing/licenses/agpl-3.0.html license] requires that you provide source code if you provide hosted access to a modified Freeside instance.
Line 17: Line 17:
 
== New customer page ==
 
== New customer page ==
  
You can link to the new customer page (<code><nowiki>https://billing.example.com/freeside/edit/cust_main.cgi</nowiki></code>) with parameters set to lock or pre-select the agent and/or first package.  ''(Note: version 1.9.5+ or 2.2.2+)''
+
You can link to the new customer page (<code><nowiki>https://billing.example.com/freeside/edit/cust_main.cgi</nowiki></code>) with parameters set to lock or pre-select the agent and/or first package.  ''(Note: version 1.9.5+ or 2.1.2+)''
  
 
* lock_agentnum: Locks the agent selection to this agent, even if the current user would otherwise be able to select other agents.  For example:
 
* lock_agentnum: Locks the agent selection to this agent, even if the current user would otherwise be able to select other agents.  For example:
Line 47: Line 47:
 
== Services ==
 
== Services ==
  
Service tables are fully "plug-in" able - just create the table (see "Schema changes" below) and define the %info hash.
+
Service tables are fully "plug-in" able:
 +
 
 +
* Create the table (see "Schema changes" below) and define the table_info subroutine.
 +
* Create a new ACL for the service in AccessRight.pm (Services: New service name)
 +
* Optionally, grant the ACL on upgrade in access_right.pm
  
 
= Additional developer information =
 
= Additional developer information =
Line 53: Line 57:
 
== Schema changes ==
 
== Schema changes ==
  
[[Freeside:1.9:Documentation:Developer:Schema changes|Schema changes]] - Quick documentation on how to make schema changes
+
[[Freeside:Documentation:Developer:Schema changes|Schema changes]] - Quick documentation on how to make schema changes
  
 
== Agent virtualization ==
 
== Agent virtualization ==
Line 62: Line 66:
  
 
[[Freeside:1.9:Documentation:Developer:Tax data vendor support|Tax data vendor support]] - Notes on how to support a new vendor of tax data
 
[[Freeside:1.9:Documentation:Developer:Tax data vendor support|Tax data vendor support]] - Notes on how to support a new vendor of tax data
 +
 +
= Git usage notes =
 +
 +
== Committing to both master and FREESIDE_2_3_BRANCH ==
 +
 +
=== Mark's method ===
 +
 +
==== Setup ====
 +
 +
* git clone git.freeside.biz:/home/git/freeside.git freeside
 +
* cd freeside
 +
* git branch --track 2.3 origin/FREESIDE_2_3_BRANCH
 +
* and then use "git checkout master"/"git checkout 2.3" to access the two branches.
 +
 +
==== Committing ====
 +
 +
* make some changes on master, or merge them in from a topic branch, then commit them
 +
* git checkout 2.3 (or "git checkout FREESIDE_2_3_BRANCH", etc. according to how you've named it)
 +
* '''git show master -U5 |patch -p1''' ''#-U5 for more context, to avoid committing things in the wrong place ala #16114''
 +
* and then do the same commit
 +
* (the one catch is that you have to "git add" any new files after patching)
 +
* any conflicts will show up when doing the patch--if it's something complicated I like to patch --dry-run first
 +
* then you do a "git checkout master" to go back
 +
 +
=== Mike's method ===
 +
 +
* make some changes on master, or merge them in from a topic branch, then commit them
 +
* '''git format-patch -1 -U5 [sha1 of commit] >filename.patch''' ''#-U5 for more context, to avoid committing things in the wrong place ala #16114''
 +
* git checkout 2.3 (or "git checkout FREESIDE_2_3_BRANCH", etc. according to how you've named it)
 +
* '''patch -p1 <filename.patch'''
 +
* and then do the same commit
 +
* (the one catch is that you have to "git add" any new files after patching)
 +
* any conflicts will show up when doing the patch--if it's something complicated I like to patch --dry-run first
 +
* then you do a "git checkout master" to go back
 +
 +
=== Ivan's (deprecated) method ===
 +
 +
* Requires separate freeside/ and freeside2.3/ trees
 +
* 23add filename filename
 +
* 23commit 'commit message' filename filename
  
 
= API documentation =
 
= API documentation =
  
 
[[Freeside:1.9:Documentation:Developer/FS|1.9 API documentation]]
 
[[Freeside:1.9:Documentation:Developer/FS|1.9 API documentation]]

Latest revision as of 16:28, 7 September 2013

Introduction

Please consider sharing your modifications with the community and helping integrate them into the standard code!

Subscribe to the freeside-devel mailing list. Send your changes as unified diffs (diff -u). If possible, send changes against current CVS HEAD and also any branch they should be applied to (i.e. FREESIDE_2_3_BRANCH). However, if all you have is diffs against a release, well, probably best to send what you have rather than waiting.

Also note that the license requires that you provide source code if you provide hosted access to a modified Freeside instance.

Signup and self-service

You can of course customize the signup and self-service templates as well as plug into the self-service API from Perl, PHP or any other language via XML-RPC. See the SelfService API.

There are notes for the existing signup.cgi, signup.html or success.html as well.

Backoffice

New customer page

You can link to the new customer page (https://billing.example.com/freeside/edit/cust_main.cgi) with parameters set to lock or pre-select the agent and/or first package. (Note: version 1.9.5+ or 2.1.2+)

  • lock_agentnum: Locks the agent selection to this agent, even if the current user would otherwise be able to select other agents. For example:
 https://billing.example.com/freeside/edit/cust_main.cgi?lock_agentnum=2
  • lock_pkgpart: Locks the package select to this pkgpart. Can be set to a single pkgpart or a comma-separated list of pkgparts. For example:
 https://billing.example.com/freeside/edit/cust_main.cgi?lock_pkgpart=6
 https://billing.example.com/freeside/edit/cust_main.cgi?lock_pkgpart=6,2

An example with both lock_agentnum and lock_pkgpart:

 https://billing.example.com/freeside/edit/cust_main.cgi?lock_agentnum=2;lock_pkgpart=6,2

Backend plugins

The backend code is structured to make it easy to add "plugins" of various types. You can easily add new price plans, new exports, event plugins (conditions and actions) and new kinds of service tables.

Price plans

Price plans

Exports

Exports

(Invoice) Events

Invoice events have been refactored in 1.9.x and are now just events. The new events have "Condition" and "Action" plugins.

Services

Service tables are fully "plug-in" able:

  • Create the table (see "Schema changes" below) and define the table_info subroutine.
  • Create a new ACL for the service in AccessRight.pm (Services: New service name)
  • Optionally, grant the ACL on upgrade in access_right.pm

Additional developer information

Schema changes

Schema changes - Quick documentation on how to make schema changes

Agent virtualization

Agent-virtualized config - Quick notes on how to agent-virtualize new parts of the configuration tables

Tax data vendor support

Tax data vendor support - Notes on how to support a new vendor of tax data

Git usage notes

Committing to both master and FREESIDE_2_3_BRANCH

Mark's method

Setup

  • git clone git.freeside.biz:/home/git/freeside.git freeside
  • cd freeside
  • git branch --track 2.3 origin/FREESIDE_2_3_BRANCH
  • and then use "git checkout master"/"git checkout 2.3" to access the two branches.

Committing

  • make some changes on master, or merge them in from a topic branch, then commit them
  • git checkout 2.3 (or "git checkout FREESIDE_2_3_BRANCH", etc. according to how you've named it)
  • git show master -U5 |patch -p1 #-U5 for more context, to avoid committing things in the wrong place ala #16114
  • and then do the same commit
  • (the one catch is that you have to "git add" any new files after patching)
  • any conflicts will show up when doing the patch--if it's something complicated I like to patch --dry-run first
  • then you do a "git checkout master" to go back

Mike's method

  • make some changes on master, or merge them in from a topic branch, then commit them
  • git format-patch -1 -U5 [sha1 of commit] >filename.patch #-U5 for more context, to avoid committing things in the wrong place ala #16114
  • git checkout 2.3 (or "git checkout FREESIDE_2_3_BRANCH", etc. according to how you've named it)
  • patch -p1 <filename.patch
  • and then do the same commit
  • (the one catch is that you have to "git add" any new files after patching)
  • any conflicts will show up when doing the patch--if it's something complicated I like to patch --dry-run first
  • then you do a "git checkout master" to go back

Ivan's (deprecated) method

  • Requires separate freeside/ and freeside2.3/ trees
  • 23add filename filename
  • 23commit 'commit message' filename filename

API documentation

1.9 API documentation