• Creating a page in Session mode to list products.
• Creating a product form page in Session mode.
• Adding and modifying products.

	Estimated time: 50 mn

• how to use WEBDEV to create pages in Session mode,
• how to access the database.

• Open the "Full WEBDEV Site" training example:
  1. Start WEBDEV if necessary.
  2. Go to the WEBDEV home page (Ctrl + <).
  3. On the home page, click "Tutorial", then in "Parts 3 to 6", double-click "Full WEBDEV Site (Exercise)".
     

     	Answers	A completed project is available. This project contains the different pages created in this lesson. To open the completed project, go to the home page and click "Tutorial", then in "Parts 3 to 6", double-click "Full WEBDEV Site (Answers)".

Creating a page with a template

• To create a blank page:
  1. Click in the quick access buttons (or press Ctrl + N).
  2. The new element window appears: click "Page" then "Page".
  3. The page creation wizard appears.
  4. Select the "Menu" preset template.
     
     
     

     	Note	A page template allows you to group different processes and part of the interface in a single element. It is recommended to use page templates to obtain a consistent, easily reusable interface.
  5. Make sure the option "Create: a page and its template" (in the lower section of the window) is checked.
  6. Validate the wizard ("OK").
  7. The new page is appears in the editor.
     

     	Note	When the page creation wizard is validated, WEBDEV automatically creates: the page that will be displayed in the browser. This page is immediately displayed in the editor and can be modified. the associated page template, which corresponds to the preset template we chose previously. You can make changes to the page template. We will see how to do so later in this lesson.
  8. The page save window appears. Type the page title: "List of products". The page name "PAGE_List_of_products" is automatically filled in.
     
  9. Validate.

• This page contains different controls in a preset layout. In this case, we will remove these controls:
  1. Select the controls in the page (press Ctrl + A).
     

     	Note	In the editor, only the page controls are accessible. The controls and events of the template cannot be edited. All the controls in the page (including the controls from the template) are selected by pressing Ctrl + A. However, the controls from the page template are not modified.
  2. Delete the controls (Del key).
  3. Only the controls of the page template remain in the page.
  4. Save the changes made to the page: click in the quick access buttons (or press Ctrl + S).

Creating controls

	Note	What is a Looper control? A Looper control displays a list of elements in a web page. A Looper control includes a series of rows that can contain multiple controls and be repeated a given number of times. Each row can hold different data.

• To create the Looper control:
  1. On the "Creation" tab, in the "Data" group, expand "Looper" and select "Looper".
  2. Click in the upper-left corner of the page, just below the menu: the Looper control creation wizard opens.
  3. The wizard asks how the Looper control will be populated:
     • from a data file or query,
     • from a WLanguage variable,
     • programmatically (we will see this option in another lesson).
     In this case, the Looper control will display all products: select "Display the data coming from a file or from a query".
     
  4. Go to the next step (click "Next" in the wizard).
  5. The next step of the wizard shows the different data files and queries in the current project. Expand "Analysis" if necessary and select the "Product" data file.
     
  6. Go to the next step.
  7. The wizard shows the list of items in the data file. By default, all items are checked in order to be displayed in the Looper control. In our case, we will display all the items EXCEPT the product description.
     Uncheck "Description":
     
     Go to the next step.
  8. Then, the wizard prompts you to select the search key, which defines the default order of data in the Looper control. The items displayed in the wizard are the ones defined as key items in the analysis. We will set the order of the items based on their caption.
     
     Select "Caption" and go to the next step.
  9. We will define additional settings for the new Looper control:
     • The Looper control will be is in Server mode: all data will be displayed when the page loads.
       In "Operating mode", select "Server".
     • The Looper control will have an unlimited number of rows. All products must be accessible directly in the page. The page will be enlarged to display all the products.
       In "Maximum number of rows per page", select "No limit".
       
  10. Go to the next step. The Looper control will display the products on 3 columns.
      • Keep the default option: "Fixed number of columns, Fill by rows".
      • In the "Number of columns" field, replace 1 with 3.
  11. Validate the wizard. The Looper control is automatically created in the page.

• We will change the position of the control in the page:
  1. Select the control.
  2. Move the control to the upper-left area of the page. When the control reaches the edge of the display area in the page template, green lines are displayed: these lines help you position the control inside the display area.
     
  3. If necessary, reduce:
     • the size of the columns so that the entire control fits in the page.
     • the size of the controls in the columns so that they fit.

• We will hide the control containing the product identifier. Why hide it instead of deleting it? Because this identifier will be useful in the rest of our development project.
  1. Select the "STC_ProductID" control. This control contains the identifier (control with a number at the top of the looper).
  2. Open the control description window (select "Description" in the context menu).
  3. In the "UI" tab, uncheck "Visible".
  4. Validate the control description window.

• We will modify the page menu to show an option to list the products. The menu is in the page template. Therefore, we will modify the page template.
  1. Right-click the menu of PAGE_List_of_products (right-click "HOME", for example) and select "Open template".
     
  2. The page template appears in the editor. Select the menu of the page template.
  3. Right-click to open the context menu and select "Edit menu". A yellow outline appears around the menu. This outline indicates that the menu is in "Edit" mode: it can be modified.
     
  4. Open the option description window (select "Option description" in the context menu).
  5. In the "General" tab:
     • Type the option caption: replace "Home" with "List of products".
     • In "Action of the option":
       • Select "Display a site page".
       • Select "PAGE_List_of_products".
     • Validate the option description window.
  6. If necessary, enlarge the control so that the text of the option appears on a single line (use the control handles).
  7. Press Esc to exit from the edit mode.
     

     	Note	We have modified the menu of the template. You can also modify other elements such as the logo or the "Company" label.

• To update the pages that use the template:
  1. In the template bar, click : this button applies the changes made to the template to all the pages that use it.
     

     	Note	If you don't apply the changes to the pages, you will be asked to synchronize the templates before testing or deploying a page.
  2. In our case, only one page is proposed.
     
  3. Validate the template update window ("OK" button).
  4. Close the page template.

• In the "Menu" page template we are using, the "ITEMS" menu option is selected: this menu option appears in blue. However, the page we have just created displays the list of products. We need to set "LIST OF PRODUCTS" as the option selected by default.
  To do so, we will override the menu option in the page template to change the selected menu option. To make this change, we will override the menu, then the desired menu option.

• Perform the following actions:
  1. Open the context menu of the menu (right-click "LIST OF PRODUCTS", for example) and select "Override control".
  2. Open the context menu of the menu again and select "Edit menu". The menu switches to edit mode: a yellow outline appears around the menu.
  3. Open the context menu of "LIST OF PRODUCTS" and select "Override control".
  4. Open the context menu of "LIST OF PRODUCTS" and select "Put this menu option into the selected status".
  5. Press Esc to exit edit mode.
  6. Save the page (Ctrl + S).

Page test

• We will test the page that we have just created.
  1. Click in the quick access buttons.
  2. The page is automatically displayed in the browser.
     
  3. You can scroll through the products with the scrollbar of the page.

• Close the browser. The WEBDEV editor appears again.

Creating the page

• To create the page that shows the product details:
  1. Create a new blank page.
     • Click in the quick access buttons.
     • The new element window appears: click "Page" then "Page".
     • The page creation wizard starts.
     • In "Based on a project template", choose "PAGETPL_Menu" and validate the wizard.
  2. The page save window appears. Type the page title: "Product form". The page name "PAGE_Product_form" is automatically filled in.
  3. Validate.

What is this page for?

• To declare a parameter in the page:
  1. Press F2. The code editor displays the different page events.
  2. In the "Global declarations" event, replace the existing WLanguage code with the following:
     
     PROCÉDURE MyPage(NumProductToDisplay is 8-byte int)
  3. Let's take a look at this WLanguage code:
     • The PROCEDURE keyword in the "Global declarations" event is used to associate a procedure to the opening of the page.
     • The name of the procedure is "MyPage". At runtime, this keyword will be automatically replaced with the name of the current page.
     • The procedure expects the NumProductToDisplay variable (8-byte integer) as parameter. This variable corresponds to the product identifier that will be displayed in the page. This variable is of the same type as the corresponding ProductID item described in the Product data file.
  4. Close the code editor.

Creating Edit controls

• To create the controls in the page:
  1. Open the "Analysis" pane if necessary: in the ribbon, on the "Home" tab, in the "Environment" group, expand "Panes", click "Panes", and then select "Analysis". The different data files defined in the "Full_WEBDEV_Site" analysis are displayed in the pane.
  2. Click the arrow on the left of the "Product" data file: the items in the data file appear.
     
  3. Use the mouse to select all the items displayed in the pane (except "ProductID"). You can select multiple elements by holding the Ctrl key down.
  4. Drag the items and drop them onto the page you created previously.
     
  5. Different controls are automatically created in the page. These controls are bound to the corresponding item in the data file. To check this:
     • Select the "Reference" control for example.
     • Right-click to open the context menu and select "Description".
     • Go to the "Binding" tab in the description window:
       
       This tab shows that the current Edit control is bound to the "Reference" item in the "Product" data file.
  6. Close the description window ("OK" or "Cancel").
  7. Save the page (Ctrl + S).

• Move the controls in the page to get the following UI:
  

• Enlarge the Image control used to display the image associated with the product.

• We will align the Edit controls and make them the same size:
  1. Select the "Caption" control then all the Edit controls of the page (hold the Ctrl key down while clicking the different controls). The first selected control will be used as reference to set the size of the other controls.
  2. Go to the "Alignment" tab of the WEBDEV menu. This tab contains all alignment options available for the controls.
     
  3. We will align the outside and inside borders of the controls. Click "Justify (Ins. and Out.)".
     
  4. Save the page.

Displaying data in the page

• find the product to display.
• display data in the page.

• To search for data and display it in the page:
  1. Click the page in the editor.
  2. Press F2. The code editor displays the different page events.
  3. In the "Global declarations" event, write the following code below the code previously written:
     
     Product.ReadSeekFirst(ProductID, NumProductToDisplay)
     IF Product.Found() = False THEN
     // Display the list of products
     PAGE_List_of_products.Display()
     END
     FileToPage()
  4. Let's take a look at this WLanguage code:
     • <Data file>.ReadSeekFirst searches for the first record in the Product data file for which the ProductID item is equal to the value of NumProductToDisplay. NumProductToDisplay corresponds to the parameter passed to the page.
     • <Data file>.Found checks if a record has been found. This function is mainly used in sites accessed by multiple users. It allows you to avoid errors caused by other users (deleted records, etc.). In this case, if the record is not found (<Data file>.Found returns False), the list of products is displayed again.
     • FileToPage displays the data from the data file in the controls, for the current record. In our case, the current record is the record found by <Data file>.ReadSeekFirst.
  5. Close the code editor.

Creating Button controls

• The "Cancel" Button control will simply display the previous page again.
• The "OK" Button control will check the entered data and save changes.

• To create the "Cancel" Button control:
  1. On the "Creation" tab, in the "Usual controls" group, click "Button".
  2. Click below the Edit controls to create the Button control.
  3. Change the control text (press Space to edit the text): type "Cancel".

• Enter the WLanguage code of the "Cancel" button:
  1. Select the control and press F2. The different events associated with the control are displayed.
  2. Enter the following WLanguage code in the "Click xxx (server)" event of the Button control:
     
     PageDisplay(PreviousPage())
  3. Let's analyze this code:
     • PageDisplay displays a specific page.
     • PreviousPage gets the name of the previous page.
     • This line of code displays the previous page.
  4. Save changes ( or Ctrl + S).
  5. Close the code editor.

	Note	By default, the Button controls created in a page send the values of the controls to the server ("submit" button). This is the most common case. Two other options are available: Reset the page controls. No action. This mode must be used when the button performs an action on the browsers side only. These options can be selected in the "General" tab of the Button control description window ("During the action" option).

• To create the "OK" Button control:
  1. On the "Creation" tab, in the "Usual controls" group, click "Button".
  2. Then, click on the left of "Cancel" button to create the new control.
  3. Change the control text: type "OK".
     
     The "OK" button will be used to:
     • check the data typed: this consists in checking whether the user has filled in the various fields of the page. This check doesn't require any server access and can be done in Browser code.
     • save the data entered in the Product data file. This operation is performed in Server code. The data is sent to the server, and then saved in the data file.

• Write the code of the "OK" button:
  1. Select the "OK" button and press F2. The events associated with the Button control are displayed.
  2. In the "Click xxx (browser)" event of the Button control, write the following code for checking the data entered:
     
     IF EDT_Reference ~= "" THEN
     Error("Enter a reference.")
     SetFocusAndReturnToUserInput(EDT_Reference)
     END
     IF EDT_Caption ~= "" THEN
     Error("Type a caption.")
     SetFocusAndReturnToUserInput(EDT_Caption)
     END
     IF EDT_Description ~= "" THEN
     Error("Enter a description.")
     SetFocusAndReturnToUserInput(EDT_Description)
     END
     IF EDT_PriceBT = 0 THEN
     Error("Type a price.")
     SetFocusAndReturnToUserInput(EDT_PriceBT)
     END
  3. Let's take a look at this WLanguage code:
     • For each Edit control in the page, we check if a value has been entered.
     • The '~=' operator checks whether the values are equal ignoring the case and punctuation.
     • If no value is entered, an error message prompts the user to enter a value (Error). The code execution is stopped and the input focus is set on the relevant Edit control with SetFocusAndReturnToUserInput.
  4. In the "Click xxx (server)" event of the Button control, write the following WLanguage code for saving the data:
     
     PageToFile()
     Product.Modify()
     PAGE_List_of_products.Display()
  5. Let's take a look at this WLanguage code:
     • PageToFile updates the items of the current record with the data from the bound controls. This function is equivalent to the following lines of code:
       
       Product.Reference = EDT_Reference
       Product.Caption = EDT_Caption
       Product.Description = EDT_Description
       ...
       
       Our page uses less than 10 controls and the advantages are clear. Think of the pages that contain many more controls: a single line of code assigns all the values!
     • <Data file>.Modify updates the current record in the data file.
     • <Page>.Display displays another page. In our case, "PAGE_List_of_products" is redisplayed.
  6. Save changes ( or Ctrl + S).
  7. Close the code window.

Managing the product image

	Note	The upload consists in copying a file from the client computer to the server. On the contrary, the download consists in copying a file from the server to the client computer.

	Note	WEBDEV includes two specific controls to upload files: an Upload control to upload a single file, an Upload control to upload multiple files. In this example, the user will upload a single file at a time, therefore we will use a single-file Upload control.

• To create the Upload control:
  1. On the "Creation" tab, in the "Usual controls" group, expand "Button". The list of preset buttons is displayed.
  2. Select "File upload".
  3. Click at the desired location to create the control in the page (below the Image control, for example).
     

	Note	The Upload control includes: a cell containing: a Static control, a Looper control used to display the characteristics of the files to upload. a button allowing the user to select the file to upload, a button allowing the user to send the files to the server.

• To configure the Upload control:
  1. Open the code of the "ADD" Button control: select the control and press F2.
  2. Different WLanguage events are associated with the Upload control. We will modify the "Receive files uploaded" event to copy the image to the site data directory.
  3. Write the following code in the "Receive files uploaded" event (ignore compilation errors, we will correct them later):
     
     UploadCopyFile(MySelf, fDataDir(), UploadFileName(MySelf, False))
     ImagePath = fDataDir() + [fSep()] + UploadFileName(MySelf, False)
     IMG_Visual = ImagePath
  4. Let's analyze this code:
     • UploadCopyFile saves the file uploaded by the user on the server. In our case, the file is copied to the data directory (returned by fDataDir). The file name is kept.
     • The path of the uploaded image is then stored in a global variable named ImagePath.
       

       	Note	Why use a global variable? A global variable is required here because the image path will be used in the code of the "OK" button, to save the new image in the data file. For more details, see the appendices about the use conditions of local and global variables.
     • fSep gets the separator to be used on the server's operating system ("\" for Windows and "/" for Linux). Therefore, your site is independent of the server where it is installed!
     • Then, the uploaded image is displayed in the IMG_Visual Image control.
  5. In the code editor, the ImagePath variable is displayed in red and a compilation error appears in the error pane: "The 'ImagePath' identifier is unknown or inaccessible". We have not declared this global variable yet.
  6. To declare the global variable:
     • Go to the "Global declarations" event of the page (for example, in the Code editor, go to the "Code" tab, and select "Global declarations" in the combo box that lists all the events).
       
     • Type the following code after the procedure declaration:
       
       ImagePath is string
  7. Save changes by clicking in the quick access buttons. The compilation errors disappear.
  8. Close the code editor.

• To save the image in the Product data file:
  1. Open the code of the "OK" Button control:
     • Select the "OK" button.
     • Press F2.
  2. In the "Click xxx (server)" event of the Button control, enter the following code AFTER the call to PageToFile:
     
     IF ImagePath<>"" THEN
     Product.Visual = fLoadBuffer(ImagePath)
     END
  3. Let's take a look at this WLanguage code:
     • This code checks the content of the ImagePath global variable. If this variable does not correspond to an empty string, it means that the image was uploaded by the user. In this case, the "Visual" item of the Product data file is updated with the binary content of the image. This content is retrieved with fLoadBuffer.
     • <Data file>.Modify (already used in the code) saves changes in the data file.
  4. Save changes ( or Ctrl + S).
  5. Close the code window.

Opening the form from the list of products

• We will modify "PAGE_List_of_products" to create a Link control:
  1. Select the "List of products" page: click "PAGE_List_of_products" in the open document tabs:
     
  2. On the "Creation" tab, in the "Usual controls" group, click "Link".
  3. Then, click inside the Looper control (bottom right, for example) to create the Link control.
     
  4. Change the text of the Link control (press Space to edit the text): enter "Modify".

• The "Modify" Link control must open "PAGE_Product_form". We will open this page programmatically.
  1. Select the "Modify" Link control and open the associated WLanguage events (F2).
  2. In the code window that appears, write the following code in the "Click xxx (server)" event:
     
     PAGE_Product_form.Display(ATT_ProductID[LOOP_Product])
     
     

     	Note	Let the code completion guide you: when you type the opening bracket "(", a drop-down list shows the names of all the pages in the project. Simply select the page with the keyboard or mouse. If the name of the desired page does not appear in the list, it means that it has not been saved yet.
  3. Let's take a look at this WLanguage code:
     • <Page>.Display opens "PAGE_Product_form".
     • The opened page expects as a parameter the identifier of the product to be displayed. This identifier corresponds to the identifier of the product selected in the Looper control. To get the identifier, the attribute that contains the identifier (ATT_ProductID) for the current row is specified. The square brackets are used to specify the row and LOOP_Product gets the current row in the Looper control.
       

       	Note	By default, ATT_ProductID returns the value of the attribute for the clicked row. The code can be written as follows: PAGE_Product_form.Display(ATT_ProductID)
  4. Save changes ( or Ctrl + S).
  5. Close the code window.

• Test the project (click in the quick access buttons).
  1. The editor prompts you to select the first page of the Session mode. In our case, select "PAGE_List_of_products" and validate.
     

     	Note	The first page of the Session mode corresponds to the first page opened when starting the site in Session mode. The first project page in Session mode can be defined: when testing the project. in the "Project explorer" pane: simply select the desired page, open the context menu and select "First page of the project in session mode". When you define the first page of the Session mode, a small red "1" appears to the left of the page name in the "Project explorer" pane.
  2. The site opens.
  3. In the list of products:
     • Click the "Modify" link.
     • The page with the product details opens.
       
     • Change the price of the product and validate.
     • The new price of the product appears in the list of products.

• Close the pages to stop the test.

• First, we will change the opening mode of "PAGE_Product_form":
  1. Select the "Product form" page: click "PAGE_Product_form" in the open document tabs.
  2. Press F2 to open the different WLanguage events of the page.
  3. In the "Global declarations" event, we will assign a default value to the parameter passed to the page. When a record is modified, the parameter passed always corresponds to the identifier of the product to be modified. But when a record is added, the element does not yet have an identifier. To handle this case, we will set "-1" as the default value.
  4. Replace the following line of code in the "Global declarations" event:
     
     PROCÉDURE MyPage(NumProductToDisplay is 8-byte int)
     
     with the code:
     
     PROCÉDURE MyPage(NumProductToDisplay is 8-byte int=-1)
  5. We will now handle the "-1" value (when a record is added). Replace the following code:
     
     Product.ReadSeekFirst(ProductID, NumProductToDisplay)
     IF Product.Found() = False THEN
     // Display the list of products
     PAGE_List_of_products.Display()
     END
     FileToPage()
     
     with the code:
     
     IF NumProductToDisplay = -1 THEN
     Product.Reset()
     ELSE
     Product.ReadSeekFirst(ProductID, NumProductToDisplay)
     IF Product.Found() = False THEN
     // Display the list of products
     PAGE_List_of_products.Display()
     END
     END
     FileToPage()
     
     Let's analyze this code:
     • If the product identifier is set to -1, it means that a product is added. In this case, Reset is executed. This function initializes the item variables in the "Product" data file with the default values to add a new record.
     • If the product identifier has a value different from -1, we use the code to open the form in edit mode.
  6. Close the code window.

• The "OK" Button control must also add the record.
  1. Select the "OK" button in "PAGE_Product_form".
  2. Open the WLanguage events associated with the control (F2).
  3. The code in the "Click xxx (browser)" event must not change: the checks to perform are the same. Only the server code must be modified.
  4. In the "Click xxx (server)" event, replace the existing code with the following code:
     
     PageToFile()
     IF ImagePath <> "" THEN
     Product.Visual = fLoadBuffer(ImagePath)
     END
     IF Product..NewRecord THEN
     Product.Add()
     ELSE
     Product.Modify()
     END
     PAGE_List_of_products.Display()
     
     Let's analyze this code:
     • The NewRecord property indicates whether the current record should be created.
     • If <Data file>.Reset has been called previously, the property returns True (new product) and the record is created using <Data file>.Add.
     • If the current record already exists, it is modified with <Data file>.Modify.
     • <Data file>.Add adds the record to the data file. This function takes the values in memory and writes the contents of the items to the data file itself. The indexes are immediately and automatically updated. In this case, the "Product" data file is updated.
       

       	Note	The test code of the new record can be replaced with <Data file>.Save. This function checks whether the record is already in the data file, and allows you to add it or modify it if necessary. The WLanguage code becomes: PageToFile() IF ImagePath <> "" THEN Product.Visual = fLoadBuffer(ImagePath) END Product.Save() PAGE_List_of_products.Display()
  5. Save changes ( or Ctrl + S).
  6. Close the code window.

• We will modify the page menu to allow users to add a new product.
  1. Select the "List of products" page: click "PAGE_List_of_products" in the open document tabs.
  2. Right-click a menu option to open the context menu and select "Open template".
  3. In the page template, select the menu.
  4. Click the "ITEMS" option. A yellow outline appears around the menu. This outline indicates that the menu is in "Edit" mode: it can be modified.
  5. Open the option description window ("Option description" in the context menu).
  6. In the "General" tab:
     • Type the option caption: replace "ITEMS" with "ADD A PRODUCT".
     • In the "Action" section:
       • select "Display a site page".
       • select the "PAGE_Product_form" page.
  7. Validate. The menu option appears:
     
  8. In the template bar, click to apply the changes made to the template to all the pages that use it.
  9. In our case, the two project pages are proposed. Validate the page template update window.
  10. Close the page template.

Testing the addition of a product

• To test the addition of a product:
  1. Test the project (click in the quick access buttons).
  2. Click "ADD A PRODUCT".
  3. Enter a new product with the following characteristics:
     • Reference: REF-337
     • Caption: Surf 25
     • Description: Surf with WEBDEV colors
     • Price: 150
       
  4. Validate. The new product appears in the list of products.
  5. Click "ADD A PRODUCT" again.
  6. Enter a new product with the following characteristics:
     • Reference: REF-337
     • Caption: Surf 25
     • Description: Surf with WEBDEV colors
     • Price: 150
  7. Validate. A specific page is appears:
     
     This page indicates that a duplicate has been found: the reference (which is a unique key) is the same for two products. This page allows you to change the reference value (displayed in a red area): type "REF-338", for example.
     This page handles HFSQL errors automatically.
     

     	Note	Several errors may occur when adding or modifying a record: duplicate errors, integrity errors, password errors, etc. WEBDEV includes multiple error handling modes: automatic mode: for each error encountered when handling database records, a specific page is displayed to the user. This page allows users to modify the data directly. the advanced programming mode: a procedure or a custom error handling page is called for each error encountered when handling the database records. The "WW_Auto_Management_Errors" example provided with WEBDEV allows you to test these different error handling modes. This example can be opened via the WEBDEV home page ("Open an example" option).

Viewing records