Setup

Follow the steps below to set up SpsDev.Com's PowerJAX Web Part in your environment.

Scope – Farm

Before you begin installing the PowerJAX Web Part, you first must install AJAX on every web front end in the farm.  You can download ASP.NET AJAX 1.0 from http://www.microsoft.com/downloads/details.aspx?FamilyID=ca9d90fa-e8c9-42e3-aa19-08e2c027f5d6&displaylang=en.   Please note that installing .NET 3.5 is NOT sufficient to meet this requirement.  You must download and install ASP.NET AJAX 1.0 from the link included above.

After you have installed ASP.NET AJAX 1.0 on every web front end on the farm, run the setup program included with your PowerJAX Web Part download on one web front end server in your farm.

NOTE: If you are using the trial version you MUST run the setup program on every web front end in your farm.

After you have completed the setup program, you must add and deploy the sdPowerJAX solution. Do so as follows:

1. Add solution: stsadm -o addsolution -filename sdpowerjax.wsp
2. Deploy solution: stsadm -o deploysolution -name sdpowerjax.wsp -immediate -allowGacDeployment

Scope - Site Collection

For each site collection in which you want to use this you must activate the feature for that site collection.  You can do this with stsadm.exe by using a command line that looks like this:

stsadm -o activatefeature -name "SpsDevPowerJAX" -url http://mySiteCollectionUrl

When you activate the feature a timer job will be created to run on every web front end in the farm.  That job makes the numerous changes required in the web.config file for that SharePoint web application that are needed to support using AJAX.  It also adds a SafeControl entry to the web.config that configures the SpsDev.Com PowerJAX Web Part as a safe control.

NOTE: If you extend a web application into a new zone after you have activated the SpsDevPowerJAX feature, you MUST either manually edit the web.config file for your new zone, or else deactivate and reactivate the SpsDevPowerJAX feature again.  If you manually edit the file, you must add the SafeControl entry found in SafeControl.txt, which is included in the setup directory.  You must also make all of the changes to support AJAX; those steps can be found at http://sharepoint.microsoft.com/blogs/mike/Lists/Posts/Post.aspx?ID=3.

Once the solution has been deployed and the feature activated there is one final step that must be completed before you can add the PowerJAX Web Part to the page and begin using it.  The master page for any site in which the PowerJAX Web Part is going to be used must be modified to include support for AJAX and the custom web service that is installed with PowerJAX.  Here is the text that must be added to the page; it should be added directly below the <WebPartPages:SPWebPartManager> tag in the page:

<asp:ScriptManager runat="server" ID="ScriptManager1">
    <Services>
        <asp:ServiceReference Path="_vti_bin/sdPowerJAXWs.asmx" />
    </Services>
</asp:ScriptManager>

Once the solution has been deployed, the feature activated and the master page updated, you can add the PowerJAX Web Part to a page and begin configuring it to retrieve data.  To add the part you can either click on the Add Web Part link on any SharePoint page that's in design mode and select the web part, or you can import the sdPowerJAXPart.webpart file that is included in the setup directory.  If you select the web part from the web part picker in a SharePoint page, you will find the part in the Miscellaneous section of the picker.  You are now ready to begin configuring the web part.

Uninstall

Uninstalling also requires a few steps to remove the application safely.

Scope – Site Collection

To uninstall PowerJAX Web Part you must deactivate the PowerJAX feature in each site collection in which the feature has been installed. You can do this with stsadm.exe by using a command line that looks like this: stsadm -o deactivatefeature -name SpsDevPowerJAX -url http:// siteCollectionUrl

Scope – Farm

Once you have deactivated the feature from all web applications that are using it, you can retract and delete the solution from the farm. Run the following on one web front end server in the farm:

1. Retract solution: stsadm -o retractsolution -name sdfpowerjax.wsp -immediate
2. Delete solution: stsadm -o deletesolution -name sdpowerjax.wsp

Once you’ve done that you can run uninstall the SpsDev.Com PowerJAX Web Part program from whatever web front end server(s) you originally installed it on.  Note that when you run the uninstall program it will NOT remove any entries from the web.config file, in case you still require AJAX support for other applications in your SharePoint farm.

Configuring A New PowerJAX Web Part

After the PowerJAX web part has been successfully added to a page, click on the web part drop down menu and select Modify Shared Web Part.  That opens up the web part tool pane, including the custom tool pane (property page) add-in developed for the PowerJAX Web Part.  The first step is retrieve all of the lists from the sites from which you wish to render data.  The top of the tool pane looks like this:

In the Site Url edit box, type the Url to a valid SharePoint site in your farm, and click the Get Lists button.  The tool pane will show the "Working..." animation while it uses AJAX to retrieve all of the lists for that site.  It then renders a list with each list name and the number of items that list contains in parentheses.  To add one or more lists, just check the box next to the list name and click the Add Lists button.  The lists you selected will be added to the Saved Lists section below the Add Lists button.

To see the list of fields in any list, just click on the list name.  Again, the tool pane will show the "Working..." animation while it retrieves all of the fields for that list.  Those fields are then displayed beneath the Saved Lists section, as shown here:

To add a field to the list of fields that will be displayed, just check the box next to the field name and click the Add Fields button.  You can also choose to show a summary value for any field by selecting a value from the Summary drop down next to the field.  For non-numeric fields you can only select a count summary; for numeric or currency fields you can also select a sum or average summary.

Whenever you change the collection of lists or fields that are going to be rendered in the PowerJAX Web Part, you should click on the Validate button.  That will verify that all of the fields that have been selected are present in all of the lists that have been selected.  If you have chosen a field that isn't present in all lists, then the lists that do not contain that field will not return any data in the web part.

In the Saved Fields section you can change the summary actions included for a field, delete a field, or change which field the results will be sorted on.  Please note that if you click radio button in the Sort column header, then no sorting will be applied to the results.

Below the Saved Fields section is the Field Filters section.  This is where you can use a simple point and click interface to choose what filters to apply, if any, on the fields being returned.  If the Value edit box next to a field is empty, then no filter will be applied to that field.  PowerJAX Web Part supports a wide variety of filters, including equals, less than, greater than, begins with, contains, and more.  We also allow you to either create filter criteria in which more than one filter is true ("And") or in which any of the filters are true ("Or").

NOTE: The data returned based on the selected filters can often seem odd, unexpected or counter-intuitive.  Before assuming that there is a bug in how the filter is being applied, we recommend that you use a CAML query tool that works with SharePoint and create the same query in it, then compare results.  CAML Query Builder V2 is an example of a free downloadable CAML query tool for SharePoint; see http://www.u2u.info/Blogs/Patrick/Lists/Posts/Post.aspx?ID=1315 for more details about it.

The rest of the PowerJAX Web Part configuration properties are found beneath the Field Filters section, as shown here:

These properties are as follows:

• Sort Direction: The direction in which data will be sorted, ascending or descending

• Animated GIF Url: The animated GIF that should be used when retrieving data

• Use Custom CSS: Check box to use your own CSS file when rendering the results.  If you check this box you can add your own stylesheet to the page, by modifying the master page, adding it at the site level, etc. - and override all of the stylesheet classes that the PowerJAX Web Part uses when rendering data.

• Show List Totals: Check box to show a totals summary for each list

• Show List Totals Only: Check box to show only summary data and no details

• Show Grand Total: Check box to show a grand total summary

• Space Evenly: Check box to space data details evenly across the web part

• Number of Rows: The number of rows to display; use 0 to display all of them

• Format Numbers: Check box to format numbers as #,###

• # Decimal Places: How many numbers to the right of the decimal point to show when formatting numbers

• Date Format:  Select the format that should be used to display dates in the PowerJAX part.  There are over 30 pre-defined date formats that you can choose from.

• Custom Date Format:  If you can't find a date format you like from the Date Format drop down, then you can type in your own date format string.  This string needs to be in accordance with the .NET Custom DateTime Format Strings documentation, currently found at http://msdn.microsoft.com/en-us/library/8kb3ddd4(VS.71).aspx.  NOTE:  If you enter a value in this field the selection in the Date Format drop down will be ignored.  If you no longer wish to use a custom date format, you must delete the value in this field - then whatever has been selected in the Date Format drop down will be used.

• Data Display: If showing data details, choose whether the data container is expanded or collapsed when the page first loads

• Render hyperlinks for items: Check box to have the first column in the data rendered as a hyperlink to the item.  That allows users to click on the item and have it open up directly for viewing and editing.

• Open documents directly:  If you choose to render hyperlinks for items, checking this box configures the links for document libraries so that when you click on an item, it will open the item up directly.  If this box is not checked, instead of opening the item the link opens a page with properties for the item.  That page includes a link to open the item itself.  This option only applies to document libraries, and it takes more server resources to use, which is why it is unchecked by default.

• Custom SPQuery: A custom CAML WHERE clause that is valid with the SPQuery class; you must include the <Where> tag

General Notes

You must install and activate the SpsDev.Com PowerJAX Web Part feature in each site collection before you can use the web part.

We have tested this using Windows authentication ONLY.  If you are trying to retrieve data from a mix of sites that use both Windows and forms based authentication it will likely not work.

We have tested this ONLY with Internet Explorer 6.x and 7.x.  All other browsers are not supported.  They may work, but we have not tested them and thus cannot support them.

Because we are retrieving data asynchronously, there may be times when a page first loads that the grand totals don't add up. If that happens, just click the Refresh button next to any list and it will recalculate the grand totals to update them with the correct numbers. This would only potentially happen when the page first loads.

Known Issues

• The Grand Total field may not add up when the page first loads.  This is because the data is retrieved asynchronously and the individual list totals may be in a state of flux when the Grand Total is calculated.  This is expected behavior.  If the Grand Total appears incorrect, just click the refresh button for any list.
• PowerJAX does NOT SUPPORT fields that have a dollar sign ("$") in the name.  Your PowerJAX configuration information will not be saved if you select a field with a dollar sign in the name.