apex pageblocktable, commandlink, commandbutton, actionRegion, actionStatus, actionFunction, param

here is my recent experience in salesforce visualforce page development...

Requirement 

• to insert a new section to add/remove items to an order in an existing order entry page... 
• based on the item price, the order totals, tax, shipping etc. should get updated..

Design

• item description & price are captured through Input Text fields. 
• "add item" action triggered when a command button is clicked, 
• the item description & price are added to the pageblock table along with a "remove" commandlink in the last column. 
• The totals section is updated to include the item price.
• "remove" action is triggered when the commandlink is clicked in any of the pageblock table row, the corresponding item is removed. 
• the totals section is again updated to exclude the removed item price.

Catch
looks simple right, the catch is the recalculation of the totals was already done using javascript. so i need to hook into the existing javascript/jquery functions once the item is added/removed from the pageblock table.

also, the re-rendering of the pageblock table and the totals section is done using ajax.

Code
<apex:pageBlockSection title="Add/Remove Items" columns="1" collapsible="false" rendered="{!(Order.Type == 'CargoItems')}">
<apex:actionRegion immediate="true">
<apex:actionStatus id="updateTotals" onstart="block('{!$Component.MainForm}');" onstop="recalcTotals(); unblock('{!$Component.MainForm}');" />
<apex:actionFunction name="addItems" action="{!addCargoItem}" status="updateTotals" reRender="itemsTable"/>
<apex:actionFunction name="removeItems" action="{!removeCargoItem}" status="updateTotals" reRender="itemsTable">
<apex:param name="rowId" value="" />
</apex:actionFunction>
<apex:pageBlockSection columns="3" showHeader="false">
<apex:pageBlockSectionItem >
<apex:outputLabel value="Item Description"></apex:outputLabel>
<apex:inputText value="{!itemDesc}" styleClass="itemFields itemDescField" />
</apex:pageBlockSectionItem>
<apex:pageBlockSectionItem >
<apex:outputLabel value="Item Price"></apex:outputLabel>
<apex:inputText value="{!itemPrice}" styleClass="itemFields itemPriceField" />
</apex:pageBlockSectionItem>
<apex:pageBlockSectionItem >
<apex:commandButton value="Add Item" onclick="addItemRow(); return false;" >
</apex:commandButton>
</apex:pageBlockSectionItem>
</apex:pageBlockSection>
</apex:actionRegion>

<apex:pageblockTable id="itemsTable" styleClass="itemTable" value="{!CargoItems}" var="cItem" >
<apex:column headerValue="Item Description">
<apex:outputText value="{!cItem.Description}"/>
</apex:column>
<apex:column headerValue="Item Price">
<apex:outputText value="{!cItem.Price}" styleClass="cargoItem" />
</apex:column>
<apex:column headerValue="">
<apex:commandLink value="Remove" onclick="removeItemRow('{!cItem.Id}'); return false;">
</apex:commandLink>
</apex:column>
</apex:pageblockTable>
</apex:pageBlockSection>

please be mindful in placing the actionRegion... it should just surround your input value controls that needs to be passed in an ajax request. if you place the pageblocktable inside the apexRegion, then the table rows will not be rendered properly.

Flow

• "add" commandbutton and "remove" commandlink both calls javascript functions,
• run any validations in the javascript functions & then call the actionFunctions
• actionFunctions are tied to the controller methods which adds/removes records to the collection
• pageblock table is binded to the cargotItems collection in the controller
• when the call returns back from controller to actionFunction, actionStatus is fired which calls the existing javascript recalculate method to update totals section & also re-renders the pageblock table 

hope this helps someone who has a similar sceanrio...