WebPart Training Example: WebPart A
After creating a WebPart and familiarizing yourself with the WebPart Canvas, you are ready to use the tools you have learned about.
Adding Section to WebPart
Look at the panel on the left side. The Toolbox should be the default tab selected at the bottom. This allows you to view all the containers and fields that can be placed on your WebPart. Find the Containers category which has all the Sections. Drag and drop a Section from container controls. Practice dropping sections inside section, outside of it, etc.
Try to create the images below by practicing section add. (Tip: To roll over a section to next row, use “NoOfColumns” property of the Section)
Clear all of them using delete key or right click and delete. (Tip: If you delete the outer-most section, it will delete all the sections inside of it as well)
Adding Labels to Sections
Now look at the “Controls” category within the Toolbox in the left panel. Add Labels to the Sections you have created by dragging the Label control to a desired Section.
Before scrolling down to see the specific steps to recreating the screenshot below, try to create a canvas layout as shown below. Use the following properties to accomplish your task:
Be default, all the labels you add to your WebPart will have a generic value in the “Description” property. This is the value that will display on the page, so make sure to change it to something meaningful. For Labels, make all the descriptions match the name, but with spaces between words. Remember that Descriptions can contain spaces unlike the Name property.
Once Description is Changed
The WebPart itself also has a “Description” property. Make sure this is also something meaningful. For now, make sure it reads “Training: WebPart A”. Just giving the WebPart a description, does not guarantee it will show on the page. We need to turn it on by changing the “Show Header” property to “True”.
Sections also have a description, but just like the WebPart, it does not show by default and needs to be turned on. Click on your created Sections and look for the “Show Header” property. Notice it is set to “False”.
WebPart (Set to “True”)
Section (“False” by Default, leave as “False”)
For each Section created, by default a skin is selected to choose the styling. For our purposes, we are going to select a skin called “WithBorder” so that you can clearly see where the sections begin and end. The WebPart also has a “WithBorder” skin. Select this option for all sections and the WebPart.
Test the webpart (click “Test” tab at top of the WebPart Design page) to see the output. Output should match with the picture below (the styling may be different).
Adding Data to Fields
Our next goal is to add value to the web fields so that they display it to the web page. Try to create the WebPart as shown below.
To set a value for text in a label, select the label. Then on the Properties/Appearance, click the browse button next to “Text” property. Then type in a value as shown below in the static value.
Repeat it for every field. Test the WebPart. It should appear as shown below.
Adding Data to Sections
Sections can be given descriptions just like fields and WebParts, but you must turn on the ShowHeader property for it to display, just like the WebPart. Remember that Descriptions can contain spaces unlike the Name property.
If you notice, our sections have default descriptions, but they do not show when we view the WebPart in the “Test” tab because the “ShowHeader” property is set to “False” by default.
To change a section description, click on the section, and in the properties, edit the “Description”.
In the screenshot below we have turned both section “ShowHeader” properties to “True”.
Adding a Tabbed Section
Add a Tab section by dragging TabSection from the Containers section of the Toolbox on the left side of the WebPart Design page. Then create a new tab by dragging a normal Section into the Tab Section along the top. Let’s call the tab section "My Tabs" and the Tab "Hardcoded Data". See below. Rename the sections by changing their “Description” property.
The Descriptions will change on the WebPart Canvas, so even if the descriptions are not set to show on the page since the “ShowHeader” property is set to “False”, it is still good practice to name them.
Just like when you are initially placing a Section on the WebPart Canvas, Sections can be rearranged by clicking on the Section you which to move and dragging it to a new location. This could be anywhere on the WebPart Canvas and inside other Sections as long as they do not already contain fields. As you begin to drag the section a cursor will appear to show where the Section will be placed.
We will be rearranging our sections by dragging the "Name" and "Details" sections we created earlier into the "Hardcoded Data" tab. The result should be as the image below.
What is a Data Source?
Data Source is a utility by which you can fetch tabular data either from a local source or a remote source.
In EASYProcess WebParts can have Data Sources. Sections and Labels can pull from the information retrieved in those Data Sources.
A WebPart can have multiple Data Sources with each pointing to a different source i.e. MSSQL, Oracle etc.
Adding a Data Source (Database Related Data)
Let's get started by adding a new tab to the WebPart. Let's call it "Datasource Data"
Create the new tab as shown below. This is done by dragging another “Section” from the “Containers” in the Toolbox and dropping it when the cursor is directly to the right of our existing tab.
We're going to add a process data source. These can be used to give us non-database and database related data as well as database. We will be examining both options.
Drag a Process Data source from the Data Sources section of the toolbox into the DataSource section of the webpart as shown below.
Double click on the process Data Source and it should open a process canvas.
In this example we will be using a RunQuery service to perform a SQL query. There are other services that can be used to accomplish this which we will also learn later.
Under the “Database Services”, expand “RunQuery”. You will see some options related to the saved database configurations.
Drag over the JDEData option to the Process Canvas (grid area in the middle). This will create a Service on the Process Canvas. Grab one of the connector nodes from the “Start” service and connect it to your newly added “RunQuery”. Now double click the service to configure it.
Since we dragged the RunQuery from a saved Database Configuration, the DBType and ConnectionString are already filled out with variables pointing to the option we selected.
The RunQuery’s Query parameter takes the full SQL query as input.
In order to configure the service, only the DbType, ConnectionString, and Query needs to be entered. In the future, as you use the RunQuery service more, you could type out your query without using additional tools.
For now we are going to be using the Query Builder tool to generate the SQL query and help you view it visually.
Using Query Builder
To open the query builder, select the “Query” node in the top half of the RunQuery service canvas. Then, click in the bottom half of the screen, which is currently empty, to place your cursor. Right-Click and select “Query Builder”.
The Query Builder screen will open and look like below:
At the right, you will see the tree view of the Configuration Variables. From the list of Configurations on the right, find “Database”. Under the “Database” Configuration, find the “JDEData” Instance and expand it.
Double-click (or drag and drop) “DbName” under the JDEData Instance. If your “JDEDbType” and “JDEDbConnectionString” Variable values were correct, the panel directly to left of this one, will be populated with the JDE data library.
Because we are doing an Address Book Inquiry, highlight F0101 and double-click (or drag and drop) to add the table to the query builder canvas. Notice that the query that will be used is automatically typed in for you in the bottom left corner.
Click on “Use this Query” button. You will be redirected to the DataSource Canvas which now contains the query (or rather, the source).
If you wanted to go back into the Query Builder screen, you would have to select the text you want to feed into the query builder for it to display just as it did before you clicked the “Use this Query” button. This is because when queries get to be complex you may want the query builder to only work on a portion of your query, like a subquery or the first half of a union. This gives the developer control over what is represented visually on the Query Builder canvas.
Adding Parameters to a RunQuery
The benefit of using a RunQuery to an Inquire (another service that can be used to query a database), is that you can type out your query and do complex queries with unions and subqueries. Inquires build the query for you given the select clause and where clause, but it will generally follow the pattern: SELECT [select clause] FROM [table] WHERE [where clause] [order by clause]. When you want to break from this pattern, a RunQuery can be more useful.
The drawback of a RunQuery is that EASYProcess isn’t aware of the pattern you are following. EASYProcess is in charge of maintaining the query pattern in an Inquire, so it is able to do things for us, like parameterize the query. In RunQuery, the developer is responsible for the parameterization of the query.
A parameterized query is a query in which placeholders are used for parameters and the parameter values are supplied at execution time. The most important reason to use parameterized queries is to avoid SQL injection attacks. These can happen when a value used in the query comes from the page in user entered data. In our example, we are just typing in a hard coded value for the address number to filter our query, but it is good practice to parameterize all the values in the query, even the static values. It will also be good practice for when this is not always the case.
In the end we want the query to resemble this:
SELECT * from <xsl:value-of select="$EP_Profile_Database_JDEData_DbName"/>.F0101 WHERE ABAN8='4242'
Note: Replace “4242” with a JDE address book number you know exists and will return records.
- Add the “WHERE ABAN8=” to the end of the query that was created by the Query Builder in the “Query” parameter of the RunQuery.
- Right click “Parameters” and select “Add New Parameters”. This will create a parameter with the nodes Name, Value and Datatype below it.
- Type “Address” in Name
- Type “4242” in Value
- Click into Datatype and look in the right panel under “Recommended Values”. Expand it to reveal “Valid Db Data Types”. Expand that and find “String”.
- Drag the “String” type onto the service canvas value input area.
- Now the RunQuery is almost complete. It has most of a query and one parameter (named Addess) defined.
- Finish the WHERE clause of the Query with “@Address”.
- The final result will be: WHERE ABAN8=@Address
The “@” character in the RunQuery Query signals EASYProcess to replace it with a parameter with a name matching the text that comes after the “@” symbol.
Note: if the JDEData database is iSeries, instead of @Address, type a question mark. The Where clause will then read: “WHERE ABAN8=?”. All parameters are denoted by a question mark, so EASYProcess is not able to map the ? to the corresponding parameter. For this reason, with iSeries, the order of the parameters is very important because they are mapped in order of occurrence.
This query will access the database “JDEData” (using the saved database configuration data). It will run the given query and return a record from the JDE Address Book table where the Address Number is equal to 4242. The RunQuery could be configured to query a local database and other tables or joined tabled. We could also select specific values from the table instead of “*” which selects all. These possibilities will be explored in further chapters.
Click the Save icon by the “RunQuery” tab and close the service. Save and Build the Process Canvas with the buttons by the “Canvas” tab. Return to the “WebPart/View” tab where we will use this newly created Data Source.
Add/Link fields from Data Source
Adding fields from Data Source
In the Web Part Canvas, you can click the "Datasource" tab on the bottom left to see the new datasource that you have added. (If it doesn't show click the refresh button).
You will notice that the output may not be found from the RunQuery node. This is another drawback of the RunQuery in comparison to another service like the Inquire. Because the RunQuery is very configurable, EASYProcess is not yet aware of what columns are returned from this query. Once the query is run, EASYProcess stores what columns are returned, so they can be available to the developer in tools like this.
Return to the Process Canvas of the Process Data Source and click the button “Run”. The output will show in the left panel of the Process Canvas. EASYProcess will now know what columns can be returned from the RunQuery. Return to the WebPart canvas and the Data Source tab in the left-hand panel. Click the “Refresh” button at the bottom. The RunQuery will now display all the columns returned.
If you expand your datasource, you can see the fields associated with the datasource. You can drag and drop fields into a datasource section which will automatically tie the new field to that column of the datasource. A "Choose Field Type" display will come up, just choose label.
Use this method to add a Label named “ABAN8” in the “Name” Section within the “Datasource Data” Section.
After the Label is created, the Name, Description, and Text properties will be auto-filled with data. The Name and Text properties are how we want them to be, but the Description property needs to be edited. Change the Description to “Address Number”.
Linking Field to Data Source
Alternatively, you can add a field from toolset and link it to DataSource manually.
On the bottom left, select the Toolbox tab.
Then find “Label” control and drop it to the desired section.
Select field and change the Name property to “ABALPH” and the Description property to “Name”. Then select the “Text” property. Click browse button (...) in the property. We will be adding data to this label using the “Dynamic Value” tab of the Field Property Editor. In the property window, go to tab, Dynamic value and select your Datasource from the Data Source list.
From here you can select our Process Data Source. We then need to reference the node within the Process Canvas that we want to tie to this Label.
You can use the magnifying glass button to view the process canvas in a tree view and select the node you wish to select.
Doing this, EASYProcess will auto-fill the Data Source Node text box with the correct reference to the ABALPH value returned from the RunQuery.
Your WebPart should now look like this:
Adding a Data Source (Non-Database Related)
We can have multiple services in a Process Canvas and reference different nodes within the Process Canvas from the WebPart. We can also create an entirely separate Data Source and follow the same steps from before.
To practice having one Data Source with links to multiple services, let’s use our existing Process Data Source. Open the Data Source again so that it creates the Process Canvas tab for us to edit.
Add the “GetCurrentDateTime” service from the “Date and Time Services” Workshop and connect it as shown below.
This is not a service that needs configuration. Double click the service and notice that it only takes one input “Separator”. When the service runs it outputs the date and time in a variety of formats. The default “Separator” is a slash, but a hyphen or a colon could also be used.
Close the GetCurrentDateTime service without making any changes and save your process canvas. Now, if you go to the Data Source tab on the bottom left of the web part canvas and click refresh, you should see the same process, but with a new node to reference. This tree view will show all the output from the recently added service, GetCurrentDateTime.
Add a section called “Time” and then drag the GetCurrentDateTime/DateTime node from the Data Source tree view into the section and select Label as the field type as shown below
You can also manually tie the datasource node to a field just as with a Database Related Data Source example (in the dynamic values section of the text/data property of a field).
Repeat adding/linking Fields to Data Source
Using either of the methods described above, add remaining fields to the WebPart:
- The “Details” Section within the “Datasource Data” should contain 3 Labels: ABAT1, ABMCU, ABSIC
- Link the Labels to pull their information from the RunQuery in the Process Data Source
- ABAT1 should have a description of “Search Type”
- ABMCU should have a description of “Branch Plant”
- ABSIC should have a description of “SIC Code”
Save web part, test and verify/compare the result to the image below.
Remember that we will refer to this web part as “WebPart A” in subsequent chapters.