WebSmart PHP USER GUIDE

Transcription

1 USER GUIDE Software Version 2.0. User Guide Build 3. For iseries, Windows 98+, XP and Vista Edition. WebSmart PHP WebSmart PHP is tightly integrated with the System i and includes templates & wizards to guide you through creating PHP applications. Exclusive Distribution Rights: Business Computer Design International, Inc. 950 York Road Hinsdale IL, USA Phone: Fax: sales@bcdsoftware.com Web: Software Development and Technical Support: ExcelSystems Software Development, Inc Fourth Street Sidney, BC Canada V8L 2Y7 Phone: Fax: excel@excelsystems.com Web:

2 Copyright Notice WebSmart is a Registered Trademark of ESDI in the United States and Canada, Trademark in the rest of the world. Program ExcelSystems Software Development Inc. (ESDI). All rights reserved. Exclusive distribution rights Business Computer Design International, Inc. (BCDII) The WebSmart PHP 2.0 User Guide is written and produced by ESDI using Adobe FrameMaker 7.0. Copyright ESDI. All rights reserved. This document many not, in whole or part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine readable form without written consent from ESDI. Conventions In this guide the term iseries is used to refer to the System i, i5, eserver i5, iseries and AS/400 computer systems. System Requirements WebSmart PHP programs can run different platforms. On the iseries, WebSmart PHP requires a minimum OS/400 release level of V5R3 with Zend Core 2.0 or higher installed. The i5 prerequisite programs are listed at knowledgebase.php?kbid=232. If you are hosting WebSmart PHP applications on a server other than a System i (i.e Windows, Unix, Linux), you must have Apache and PHP and all appropriate modules installed and configured correctly and you must ensure that your PHP installation can access the database(s) you need to connect to. If you are using a database for which there are predefined templates you should be able to create functional PHP applications for your environment without needing to make changes to the templates. Otherwise, varying degrees of template modifications may be required. Access to a System i is necessary during development for security purposes (but not at run-time). You also need to have TCP/IP and the IBM HTTP Server (Powered by Apache) correctly configured. WebSmart will initially occupy approximately 50 MB on your iseries, and up to 150 MB at times during the install and until the install libraries are removed from your system. After the install you can manually remove the library XL_WEBINST, if found. WebSmart will run on any PC running at least Windows 98, with IE 4 installed. The minimum recommended processor speed is a Pentium 200. Note that it will run fine on slower machines, just slower! WebSmart ILE and WebSmart PHP WebSmart ILE generates ILE-CGI code. WebSmart PHP is used to create and edit PHP programs. Both types of program are created from the same IDE (Integrated Development Environment). Acknowledgments Throughout this manual, reference is made to several trademarks: ProGen WebSmart, WebSmart and ProGen Plus are registered trademarks of ESDI in the US and Canada, trademarks elsewhere in the world. Clover, Catapult, Spool-Explorer/400, Spool-Explorer, POLCMD and Exodus are trademarks of ESDI. IBM, System i, AS/400, iseries and OS/400 are either registered trademarks or trademarks of International Business Machines in the United States and/or other countries. Windows and Excel are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Adobe, Acrobat, Flash and Macromedia are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are acknowledged as the properties of their respective owners. BCD Printed in Canada. Third Printing (PDF) April 16, 2009

3 About the WebSmart PHP User Guide This is the WebSmart PHP User Guide. This guide includes instructions for getting started with the software as quickly as possible, as well as reference information for using the product on a daily basis. This guide includes the following: An overview of WebSmart PHP, including comparisons between the ILE and PHP versions of WebSmart, and between WebSmart PHP and other PHP editors. Installation and configuration instructions. An overview of some general WebSmart concepts, as well as other concepts that you should be familiar with when designing and building web applications. Tutorial exercises to introduce you to the product. A reference section describing the WebSmart IDE options for WebSmart PHP, the WebSmart program templates and the template wizard design options. WebSmart Online Resources and Teaching Tools In addition to the information available in this guide, you should also visit our web site to review the tools available online. Our web site, at includes these useful resources, among many others: Over 150 example programs illustrating various PML, PHP, HTML and JavaScript coding techniques. The programs include working examples, detailed explanations and downloadable definitions. Hundreds of online Knowledge Base entries. These address a wide variety of challenges and difficulties encountered by the Technical Support team over the last several years. Use the Knowledge Base search to find KB entries on error codes, programming techniques and reported problems. Case studies and stories from customers and business partners on how they have used WebSmart in many different situations within a wide variety of organizations. A Flash product overview and other audio and video resources. There are many other useful resources online that are regularly updated, so take a few minutes to visit the site, you ll find the information available to be very helpful. Using the PDF Version of the Documentation This guide has been designed to be used as either a printed manual or as a PDF. There are a few differences between the two formats: The printed manual may be updated somewhat less frequently than the PDF, usually only in conjunction with significant new versions of the software. The PDF version may be updated as new features are added or changes are made to About this Manual 3

4 existing features. The software release and document build number inside the cover will tell you what version you have. The printed manual is black and white. In the PDF version, the screen shots are in color and the PHP and HTML code samples are also color coded as you would see them in the product. In the PDF version you can click on chapter and section cross references and URLs. These are set up to be active hyperlinks. And finally, as you use this guide to learn to use WebSmart, you can copy and paste sample HTML and PHP code from the PDF version to your WebSmart definitions. To copy content from an Adobe PDF document, click on the Text Select Tool icon in your toolbar, then highlight the sections you want to copy, and type Ctl+C. Then go to the target location and type Ctl+V to paste in the text. It is also theoretically possible to cut and paste sections from the printed guide, but you will likely find that less effective. If you have any questions on how to use the documentation, please phone our support group at (250) [7:30 AM - 5:00 PM PST], or contact us by at excel@excelsystems.com. 4 About this Manual

5 Table of Contents SECTION I INTRODUCTION AND INSTALLATION INSTRUCTIONS Chapter 1 AN INTRODUCTION TO WEBSMART What is WebSmart? WebSmart ILE and WebSmart PHP WebSmart ILE Runtime Model WebSmart PHP Runtime Model Comparing WebSmart ILE and PHP WebSmart PHP vs. Other PHP Editors WebSmart and Clover How Should I Get Started? Chapter 2 INSTALLATION AND CONFIGURATION Step 1: End the EXODUS Subsystem Step 2: Install Zend Core Step 3: Install the WebSmart iseries Components Step 4: Install the WebSmart PC Component Step 5: Configure the WebSmart IDE to Connect to the iseries Step 6: Create an FTP Connection Step 7: Create an ODBC Connection Step 8: Set a Default User Profile for WebSmart PHP Programs Moving On Installation and Configuration Troubleshooting Suggestions More About the WebSmart IBM HTTP Server (Powered by Apache) Instance Chapter 3 WEBSMART PHP CONCEPTS What is WebSmart PHP? Advantages of Using WebSmart to Build Web-Based Applications WebSmart Definitions PHP HTML The WebSmart Programming Model Stateless Programming Table of Contents 5

6 SECTION II GETTING STARTED Chapter 4 BUILDING YOUR FIRST PROGRAM WITH WEBSMART PHP Overview What is a WebSmart Definition? Part 1 - Creating Your First Program Verifying your Configuration Selecting a Template The WebSmart IDE Part 2 - Understanding the HTML The ListHeader Segment The Body Components of the Segment ListHeader The ListDetails Segment The ListFooter, PageFooter, ListPrev and ListNext Segments The RcdDisplay Segment Working with the Record List Fields Understanding the PHP Code Conclusion SECTION III WEBSMART IDE REFERENCE Chapter 5 IDE WIZARDS: DEFINITION CREATION OPTIONS Creating New Definitions and Choosing your Template WebSmart Templates: An Overview Overview of the Main Template Categories The ODBC Connection Required During the Design Process Descriptions of the WebSmart Program Templates A Simple Page Template The CSS, HTML Page and JavaScript Templates The Input Capable Page at a Time Template The Page at a Time Maintenance Template The Record Listing Template The Single Record Maintenance Template Defining the Program Attributes Table of Contents

7 Additional Design Options A Simple Page Template Input Capable List Page at a Time Template The Page at a Time Maintenance Template Record Listing Template Single Record Maintenance Template SQL Page at a Time Maint Template Creating Calculated Fields Defining the Field Attributes Defining the Field Logic Using Functions in Calculated Fields File Maintenance Options Selecting the Files and Fields for your Program Adding New Files Browsing the iseries for Files Selecting a File from the Repository Reviewing File Fields Changing Selected Files Deleting a File from the Definition Synchronizing your Files Viewing File Data Selecting File Fields The WebSmart IDE Chapter 6 IDE GENERAL REFERENCE: COMMON DESIGN FUNCTIONS The IDE Layout Using the Tabbed Interface Changing the Default IDE Layout Working with the Main Window Setting Bookmarks in Your Code Using the WebSmart IDE to Edit Other Files (JavaScript, Style Sheets, etc.) The Fields and Functions Window Placing Fields in PHP Definitions The Functions and Snippets Window Working with PML, PHP and JavaScript Functions Working with HTML, PML and PHP Snippets PHP and PML SmartSnippets WebSmart IDE Menu Options: Overview The File Menu The MRU Files List The Edit Menu Using the Find and Replace Options Table of Contents 7

8 The Attributes Menu Previews Working with Preview Definitions The View Menu Working with the File Repository Repository Options Repository Import Features Validating the HTML, PML and PHP Formatting your Code SQL Prototyping The Help Menu Chapter 7 USING THE HTML DESIGN TOOLS HTML Editing Modes HTML Color Coding PHP in HTML Segments Working with the HTML HTML Segments HTML Right Click Options Inserting Colors Inserting Calendars Inserting HTML Validating Your HTML HTML Wizards Inserting Simple HTML Elements Inserting Tables and Table Components Inserting Table Rows Inserting Table Cells Inserting Forms Inserting Buttons Inserting a Text Input Inserting a Radio Button Inserting a Checkbox Inserting Password Fields Inserting an HTML Select Form Inserting Hidden Fields Inserting Text Areas Inserting Images Adding HTML Links to your Web Page Adding Special Characters Adding Lists to your Web Page Adding Functions Table of Contents

9 Vertical HTML View Editing the HTML in the Vertical View The Visual HTML View Previewing the Page Title HTML Text and Background Colors Manually Editing your Page Title HTML Advanced Formatting Options Chapter 8 USING THE PML AND PHP CODING TOOLS The IDE Code View Working with Multiple Files in the IDE The Functions List Window Using the Functions List Pane The Snippets and Information Tabs The Main Coding Window PHP Color Coding and Auto-Formatting Intelliprompting PHP Prototyping PHP Parameter Tooltips Syntax Checking the PHP PHP in HTML Segments Chapter 9 WEBSMART PROGRAM AND CONFIGURATION DEFAULTS General Program Options IDE Options Confirmations HTML Default Options Server Options iseries Systems Other iseries Settings FTP Servers Working with ODBC Connections (Other Databases) ILE Program Defaults PML Defaults Paths and Repository Options Generator Files PHP Program Defaults PHP Generator Files Table of Contents 9

10 Working with WebSmart IDE Environments When Should I Create an Environment? Configuring Environments Creating New Environments Running Multiple Versions of WebSmart Concurrently The WEBSMART IBM HTTP Server Instance Overview Access to the WAS Configuration and Authentication Directives Did you Make any Changes to the Default Configuration? TCP/IP Communications Configuration and Defaults Configuring the iseries Side of Exodus TCP/IP Implementation of Exodus Configuration Options for TCP/IP The ZCFGTCP (Configure TCP/IP) Command Security Considerations SECTION IV PROGRAMMING REFERENCE TOPICS Chapter 10 BCD PHP FUNCTION REFERENCE wrtseg xl_db2connect xl_decrypt xl_encrypt xl_i5_connect xl_mysql_connect xl_quote_string xl_raw_to_array xl_set_libl xl_set_row_color INDEX Index Table of Contents

11 Section I - Introduction and Installation Instructions SECTION I Introduction and Installation Instructions In this Section: Chapter 1 - An Introduction to WebSmart Chapter 2 - Installation and Configuration Chapter 3 - WebSmart PHP Concepts

12

13 1 - An Introduction to WebSmart C HAPTER 1 An Introduction to WebSmart Read this chapter for a quick overview of the software and some suggestions on how to learn to use WebSmart. The installation instructions are in Chapter 2. Chapter 3 explains in more detail how WebSmart works and what it can do for you. What is WebSmart? WebSmart is a multi-award winning iseries rapid web application development tool that you can use to quickly build powerful and secure web applications and web services. WebSmart s IDE is a versatile Windows-based design tool that seamlessly accesses your iseries database. It includes application templates, sophisticated wizards, an HTML editor, 100+ routines, SQL prototyping, a visual integrated debugger and more. You can use WebSmart to create both ILE-CGI and PHP applications. WebSmart is technology that you will easily understand. Its flexibility lets you build new applications or extend existing ones. You can create any application for any industry: Inquiries, Maintenance, Order/Entry, ecommerce, B2B, B2C, Wireless and more. It supports advanced web technologies such as SOA, Web Services, AJAX, Graphical Business Metrics and KPIs, and output to Excel. WebSmart is IBM ServerProven and listed on IBM s System i Developer Roadmap. WebSmart can be used by one or many developers. It includes sophisticated project and change management features such as version archiving, comparisons between versions, organize applications into projects, checkin/checkout, test versus production environments with flexible runtime library list management and more. WebSmart also integrates with commercial change management solutions from other vendors. Even if you have never written web applications before, WebSmart lets you quickly produce true Web applications that take full advantage of all the latest technologies and Web programming techniques. If, as an RPG programmer you are concerned about being able to make the transition, keep in mind that almost all WebSmart developers started out in the RPG world. The software together with our support team will help you to succeed too!

14 Productivity Benefits WebSmart has many features to boost your productivity as you write applications for deployment in browsers or as Web Services (SOA). Intelligent templates and wizards step you through the entire creation of applications with no coding or HTML knowledge required. Customizable templates let you skin an application with your corporate identity - including graphics, Flash components, etc. You can use WebSmart's standard HTML editor, or the WYSIWYG visual HTML editor. A file repository lets you optionally define business rules, presentation rules, custom HTML components and database relations at the database level, so you maximize productivity by avoiding repetitive coding. All these rules and design elements are automatically included in the application when you first design a program in WebSmart. Product Structure The product consists of three main components, one on the PC and two on the server. The core WebSmart component is a Windows application for designing web pages and integrating iseries data elements. The WebSmart Integrated Development Environment (IDE) includes wizards and templates for building off-the-shelf programs with little or no coding effort. And though the templates can produce full-featured programs with no coding on your part, you can also add custom logic to your programs using a simple, Java-like language called Program Macro Language (PML) or, if you are using WebSmart PHP, by writing your own PHP code. So the main function of the IDE is really to be a code editor that allows you to extend the logic of your programs to build powerful applications. The IDE also includes an interactive HTML editor to customize the look of the output pages. There are also two iseries components: The first iseries component is a code generator to produce the server-side programs that interact with the browser. The second iseries component is a Web Application Server that facilitates running the generated programs. The programs are generated in ILE RPG, and take full advantage of RPG IV and ILE features, such as bound modules, service programs, subprocedures and free-format RPG. You can also bind in modules written in other ILE languages. The three WebSmart components work seamlessly together to help you code and produce powerful and sophisticated web applications without having to first master all the complexities of coding CGI programs by hand. 14 Section I - Introduction and Installation Instructions

15 WebSmart ILE and WebSmart PHP WebSmart is really three tools in one: WebSmart ILE, WebSmart PHP and Clover. The section below outline the similarities and differences between the ILE and PHP versions of the software (Clover is discussed further below). WebSmart ILE Runtime Model Here is an image illustrating the WebSmart ILE runtime model: Figure 1-1. The WebSmart ILE runtime model. Web page content is delivered to the user by the following mechanisms: The user requests a URL on an iseries server from a browser (PC). The iseries HTTP Web Server (Powered by Apache, running in the QHTTPSVR) accepts the request and processes it. If the request includes a call to a CGI program, the program is invoked by the iseries Web Server. If the program is a WebSmart program, the WebSmart Web Application Server (WAS) is used to provide all the supporting functions for the programs to interact with a browser. For example, translation of data provided from the browser to the server program is done by functions in the WAS. The WAS resides on the iseries in a library called XL_WEBSPT. If the program is designed for file access or maintenance, the ILE program establishes a connection to the target database. Chapter 1 - An Introduction to WebSmart 15

16 The CGI program (WebSmart pgm) reads input parameters from the user request (via the Web Server). The CGI program constructs a web page, by merging static pieces of HTML with live data from the target database and writes the page to the Web Server. Finally, the Web Server sends the web page to the User, via the browser. WebSmart PHP Runtime Model Here is an image illustrating the WebSmart PHP runtime model, when using the iseries as your server: Figure 1-2. The WebSmart PHP runtime model on the iseries. Web page content is delivered to the user by the following mechanisms: The user requests a URL on an iseries server from a browser (PC). The iseries HTTP Web Server (Powered by Apache, running in the QHTTPSVR) accepts the request and processes it. If the request includes a call to a PHP program, the program is invoked by the iseries Web Server. The PHP program reads input parameters from the user request (via the Web Server). The Zend Core parses the requested PHP to construct a web page, merging static pieces of HTML with live data, and writes the web page to the Web Server. Finally, the Web Server sends the web page to the user, via the browser. 16 Section I - Introduction and Installation Instructions

17 Comparing WebSmart ILE and PHP If you are evaluating both WebSmart ILE and PHP, and considering the purchase of one or both products, here are some considerations to take into account. PHP and PML cannot be combined in a single program, but within an application there are no limits to combining PHP and ILE programs. You can transparently move from PHP to ILE programs via links, forms, menus or redirects, taking advantage of the strengths of both environments. Most WebSmart templates are available for both PHP and PML, and with a few small exceptions, also work exactly the same. You can work with both PHP and ILE definitions at the same time, in the same IDE session. All your definitions are shown as tabs across the top of the main window of the IDE. Databases WebSmart PHP currently includes templates for DB2/400 and MySQL. WebSmart ILE includes templates to create programs over DB2/400, as well as templates to create a JDBC connection program, and programs to work with MySQL and MsSQL tables (among others). Server Platforms WebSmart PHP can create programs to run on the iseries, Linux, Unix or Windows. WebSmart ILE programs are designed to run only on the iseries. Languages WebSmart ILE programs are coded entirely in PML and HTML, and generate ILE CGI code and compiled programs. WebSmart PHP programs are written entirely in PHP and HTML. PHP programs are interpreted, ILE programs are compiled. PHP includes functions, PML has 170+ functions. Both languages are growing, and while the number of PML functions may seem small, WebSmart ILE has been used for many years now to create hundreds of robust iseries applications across dozens of industries. PHP is open source, but BCD s PML is also extendable you can create your own functions, or we can add them to the tool for you. At present we have no plans to create a PML to PHP converter, though if you anticipate a need for this functionality, please let us know. Learning Curve WebSmart ILE generates RPG code, and the framework of the programs is very similar to how you would code things in RPG. In addition, a number of complex functions are encapsulated in custom functions that in the WebSmart WAS require hundreds or thousands of lines of support code. As a result, many RPG programmers find WebSmart ILE familiar, and not too difficult to pick up. WebSmart PHP may be more of a challenge for an RPG programmer, but experienced PHP programmer should be able to quickly grasp the logic of the templates and understand how to modify them, though learning the iseries-specific PHP functions may also take some time. Chapter 1 - An Introduction to WebSmart 17

18 Experienced WebSmart ILE programmers learning to use WebSmart PHP will be familiar with the IDE, templates, structure and objectives of the generated code, and supporting files. By using the generously commented WebSmart PHP templates as a starting point for your coding, you should be able to get up to speed relatively quickly. iseries Integration Zend and IBM have worked together to support PHP. PHP applications can run on the iseries, connecting to DB2/400. Many key iseries functions, such as calling external iseries programs or handling library lists, are supported. WebSmart ILE is even more tightly integrated into the iseries, often requiring far fewer lines of code to execute basic functions. Free Scripts and Example Programs One website alone has over 10,000 free PHP scripts you can use, and a quick Web search will turn up many other resources. However, most of these are not intended for the business environment in which iseries developers typically operate. For WebSmart ILE, BCD has over 145 sample programs and scripts that you can download, and our Technical Support team can assist you with the creation of your own applications. Hiring Pool There are literally millions of PHP developers who can quickly start creating applications for you with WebSmart PHP. The WebSmart ILE development environment can quickly be mastered by RPG programmers and others who are reasonably familiar with the iseries. Object Oriented PHP supports Object Oriented programming. This is not supported in ILE. Performance and Scalability While we haven t yet conducted extensive performance tests, because WebSmart ILE produces compiled ILE programs and PHP is an interpreted language we believe that ILE programs written with PML will run faster on the iseries. Runtime Object Requirements WebSmart ILE programs require that the WebSmart Web Application Server (WAS) be installed on the system where the application is running. For details on the advantages of the WebSmart WAS (which encapsulates functionality sometimes requiring thousands of lines of code), please refer to the WebSmart ILE Reference Guide. WebSmart PHP program require that Zend Core be installed on the iseries. The WebSmart WAS is not needed for WebSmart PHP programs. 18 Section I - Introduction and Installation Instructions

19 Other Miscellaneous Considerations And finally, here are a few other considerations to take into account when evaluating whether to use WebSmart ILE, WebSmart PHP, or both: PHP has excellent array support. In PHP the buffer is easily accessible. With PHP there is no easy facility for working with multiple parameters with the same names. In PHP variable names are case sensitive, and prefixed with a $ sign. In PHP field attributes (type, length) are not defined. This simplifies some tasks. PHP is relatively new on the iseries, and many of the advantages of using this programming language and model remain to be defined. WebSmart PHP vs. Other PHP Editors There are many PHP editors available, and some of them are very inexpensive or even free. However, when you choose to use WebSmart PHP to develop PHP applications, you are getting much more than a plain text editor with a few extra options. iseries Expertise BCD has been specializing in the System i family of computers for 30+ years. We understand how System i developers and IT shops think and work, and we understand where they are coming from in terms of experience. We know the System i platform inside out. BCD has a proven track record of stability and longevity as a System i market leader. Complete Integration in the WebSmart IDE If you already use WebSmart ILE you will find the transition to WebSmart PHP intuitive. They share the same design infrastructure and functionality; and you don t need to learn a completely new IDE. As a developer using WebSmart, you can move seamlessly between writing ILE CGI applications and PHP applications. Intelligent Templates and Wizards WebSmart PHP includes DB2 SQL, MySQL and Record Level Access templates that guide you through every step to create powerful dynamic Web applications. Most PHP editors don't include templates; you start with a blank palette, leaving you wondering what to do next; WebSmart PHP guides you through every step to create powerful dynamic web applications. Central Repository Like WebSmart ILE, WebSmart PHP has a central repository where you can define business, database and presentation rules at the database level, effectively providing powerful data modeling capabilities. Once extensions are defined in the Repository the intelligent templates can exploit them. Chapter 1 - An Introduction to WebSmart 19

20 Powerful Integrated Text-Based and Visual HTML Design Tools WebSmart PHP includes both text based and visual HTML design tools. Other editors may not include an HTML visual editor or HTML wizards. The visual design tool gives you a WYSIWYG view of your pages as you design them, and helps eliminate one of the initial barriers to creating web applications by minimizing the need for detailed HTML knowledge. Unique Separation of Content Presentation from Logic In most PHP editors, the logic (PHP) and the presentation (HTML) is interleaved. In WebSmart PHP the content presentation is separated from behavior (PHP programming logic) making it easier to both code your page design and application logic. This is sometimes known as the Model-View-Controller approach. The separated model used by WebSmart has the following advantages: The code is much easier to read. It is much simpler for people with different skillsets (developers and designers) to work on separate tasks without stepping on each other s toes. When PHP and HTML are completely interleaved, your developers need a much higher level of HTML knowledge, and it s difficult or impossible to effectively involve designers. It is easier to re-use PHP and HTML code snippets. And if you use the WebSmart PHP templates, these also make extensive use of external CSS and JavaScript files, further modularizing your application s functionality and design. SmartCharts WebSmart PHP includes license-free Flash graphs, charts, gauges and meters (often called KPIs or business metrics). SmartCharts easily integrate into your applications to visually improve the communication of your enterprise data. 5,000+ PHP Functions Cataloged and Integrated into the WebSmart IDE The available PHP functions can be a blessing or a curse. In WebSmart PHP, related functions are organized into tabs and integrated into the IDE development environment with real-time PHP syntax checking, prompting, color-coding and formatting. Most other PHP editors are simply generic programming language editors with limited color coding. As you add your PHP functions, WebSmart PHP shows you a prototype of the function along with tool tips to explain any parameters used by the function. The IDE also supports context-sensitive help for any function. All these features help reduce errors in your code, even before you start application testing. 20 Section I - Introduction and Installation Instructions

21 Strong Integration with DB2 in the Design Environment The WebSmart PHP IDE displays file attributes, field lists and file keys. This is a great help as you write your PHP or HTML code, and when you create joins. If you are creating applications to run on the iseries, WebSmart PHP has functions that help you use library lists at run-time, providing flexibility for how you reference database files or make calls to existing RPG or other ILE programs. This simplifies the task of managing test and production environments. Built-in FTP Client with Multiple Server Connection Capability WebSmart PHP comes with its own fully integrated FTP client, which you can use to easily connect to multiple servers, System i or otherwise, from the IDE. You upload or download files through the folder tree interface, making it easy to manage development efforts across multiple servers, platforms, and databases. Technical Support The BCD Technical Support is consistently rated as one of the best in the industry. Our support agreements provide you with unlimited phone, and web support for the life of the agreement. Clients evaluating BCD software also receive unlimited, free telephone and support. Support from most PHP editors is very limited. System i Web Consulting The BCD Professional Services group is available to help you create custom templates, add key modules, or build your entire application. Integrated Suite of Products WebSmart PHP is also part of a complete integrated suite of products that provide a full range of functionality, including RPG ILE/CGI Web development (WebSmart ILE), web application frameworks (Nexus Portal), dynamic Flash graphs (SmartCharts) and automated report distribution (Catapult). Chapter 1 - An Introduction to WebSmart 21

22 WebSmart and Clover WebSmart provides a platform to create sophisticated web applications such as file maintenance and order entry, shopping carts, web forums, document management, web services oriented applications, corporate portals, etc. just about any business application you can imagine. Using WebSmart s coding environment, you can also write business reports such as sales analysis, invoices, and so on. However, some of the features of typical reports, such as subtotals and break values, require additional coding within the tool to accomplish. Clover addresses these limitations with a new interface, tightly integrated with many of the existing features of the IDE, to enable you to write reports with little or no coding. Clover has its own set of templates that drive the report creation wizards, making it easy to create reports with breaks, subtotals, graphs, etc. Using the included SQL wizard, you can relate many files (for example, join a header to a detail file) and define how you want the data sorted, filtered and reported. Clover also includes a variety of SmartCharts templates, to create SmartCharts using the wizard, rather than having to code them by hand. 22 Section I - Introduction and Installation Instructions

23 How Should I Get Started? To get started, begin by installing the software. If you haven t done so already, you can find instructions in Chapter 2, or at our website (when you download the software). After you have installed WebSmart and verified your connection to the iseries, we recommend that you review the suggestions below to help you decide how to get started. I would like a live demo with a Technical Support team member. BCD provides free live demos of WebSmart to new users. If you would like to have someone give you a detailed walk-through of the product, pointing out all the key features and explaining how they work, just contact your sales rep or visit our web site to request a demo. You can also call our Technical Support line at any time for a short, adhoc walkthrough to get you going. For our demos we use GoToMeeting, which means that we can do the demo on our system or yours. We can either walk you through the steps on your system (intervening when you get stuck) or you can just watch us go through the demo on our own system. By using your system, you ensure that everything is set up and working right before you tackle things on your own. Or you may prefer to view the demo on our system, so you can try out the software without having to install it. I want to build a program immediately. Section II of this guide includes some simple exercises that walk you through creating a series of programs. These will help you familiarize yourself with key design steps and concepts. Or better yet, just try the templates over your own data files - you ll be amazed at how easy it is to get going. I want to see examples of specific features and how they are coded. Once you ve built a few programs using the templates the next logical step will be for you to start adding specific features to your programs. Before you start on this stage, we recommend you review our example programs at iseries400apps/exlist.pgm. This listing includes more than 130 programs highlighting features we are often asked about. These programs include illustrations of HTML, SQL, PML, PHP and JavaScript coding. You can browse the list or search for specific features. Then you can review the code, or download the definitions and generate them at your site (as they all use our example files in XL_WEBDEMO). We also have a gallery of WebSmart applications at And keep in mind that this list is populated from questions and ideas sent to us by people like yourself - so if there s something you need to do, and you don t see it in the list, give Tech Support a call. If it hasn t been done before, chances are we ll do it for you! I want to learn a little bit more about the software. If you haven t yet created web applications, WebSmart will introduce you to dozens of new concepts. We try to make our guides general educational resources for web development, as well as instruction manuals specific to WebSmart. Chapter 1 - An Introduction to WebSmart 23

24 Chapter 3 is a fairly simple overview of how the software works, and after reading that a good choice is to simply start creating programs, beginning in Section II - Getting Started. At the outset, you will likely find this more useful than just reading through the reference sections of this guide. Of course, if you like reading reference guides, don t let us stop you from doing that too! I want to make sure that my system will be secure. Balancing the needs of security and access is a tricky thing. Fortunately, the iseries has some great features that will satisfy even the most paranoid among us. For some basic information on ensuring that your iseries isn t open to the world, review the footnotes on the default configuration we install, in the section The WEBSMART IBM HTTP Server Instance on page 238 of Chapter 9. For a more in-depth discussion of the different methods of implementing security at all different tiers, please read Chapter 13 of the WebSmart ILE Reference Guide. I want to understand the specific challenges I ll face as an RPG programmer. Programming for the Web is a completely different environment from what you are accustomed to on the iseries. While the look and feel of your applications is an obvious difference that s immediately apparent, there are other, lower-level differences that you ll need to understand before you can effectively build applications with more than just a single page of data. One of the key concepts you may initially wrestle with is the notion of stateless programming. To help you understand this new programming environment, we recommend you start by quickly reading Chapter 3, in particular the section entitled Stateless Programming on page 52. I want to learn a bit more about PHP. If you are unfamiliar with PHP there are also many good PHP tutorials available online, such as Zend s PHP 101 tutorial at W3 Schools also has a PHP tutorial at Zend also has a useful guide entitled Zend Core for i5/os, which you can view online. I m a good programmer, but I don t know anything about HTML. Sooner or later you will have to learn at least some basic HTML. If you have ever worked with template-based application development tools, you know that the templates are nice, but it s not too long before you want to start tweaking your programs to better suit your needs and often you start with the UI. With web applications, this means making changes to the HTML. The WebSmart IDE allows you to edit your HTML manually or using the built-in visual HTML editor. In practice, like all visual HTML tools, WebSmart s has some inherent limitations, which means that eventually you ll want to get into the HTML code directly. While the Web itself is the best resource for learning HTML, the WebSmart ILE Reference guide includes a Web Page Design for Green-Screeners guide. If you read through that chapter and try out the examples, you should be able to learn enough to 24 Section I - Introduction and Installation Instructions

25 understand the structure of the HTML component of the programs WebSmart builds for you. You can then start to making changes to your own generated pages, and work on creating new pages from scratch (though in fact, with HTML almost everyone starts from a copy of something else as a starting point...). I know how to use WebSmart, and want to create some custom templates. If you already have online applications or a corporate website, you will probably want your WebSmart applications to match their look and feel. While you could work with each individual program to this end, it s a good idea to start thinking about creating a custom set of the templates for yourself. Chapter 10 of the WebSmart ILE Reference Guide describes how to work with the templates. The three main WebSmart template families, Idaho, Lincoln and MacLeod, have been designed to be easy to modify, so you can quickly add your own corporate logos or new structural elements. If you are wanting to do a more ambitious re-design of the templates, you may want to delegate the task to the most competent HTML programmer at your site (if your mostly concerned with the appearance), or even consider contracting the Professional Services division at BCD to take care of for you. I d like BCD to start building programs for me. BCD doesn t just sell WebSmart. WebSmart was created by BCD s sister company, ExcelSystems Software Development (ESDI). ESDI has created dozens of custom applications and hundreds of programs for our WebSmart customers, for both public and internal sites. If you have decided that WebSmart is your tool of choice for putting your applications online, but you don t have the resources in-house to get yourself started, there is no better choice of contractor than the BCD/ESDI Professional Services team to help you. We have very competitive rates, and our consulting staff work hand in hand with the developers to ensure that each program makes the most effective use of the software. And where necessary, we can even enhance the software to suit your needs! For details visit our Professional Services division s home page at I feel totally daunted. I have no clue where to start. I definitely need help. Making the transition to developing web applications can be difficult. But don t despair! WebSmart is in its sixth version, and to date hundreds of programmers like yourself (and some probably even more green-screen hardened!) have entered the exciting world of web application design. If after the suggestions above you still feel overwhelmed, or you don t think you ll ever have the time to get yourself sorted out, contact Technical Support to talk about how we can help you out. You can arrange a walk-through with a member of our Help Desk team or one of our trainers. We re confident that you ll find our support superb; we ll patiently walk you through the program design processes from start to finish, and give you lots of helpful pointers along the way. Chapter 1 - An Introduction to WebSmart 25

26 WebSmart Training Classes We offer frequent training seminars at our location in beautiful Sidney, BC, located on Vancouver Island (off the West coast of Canada, 5 minutes from the Victoria International Airport) as well as elsewhere in North America. If there are more than a couple of programmers at your site, it is more cost-efficient to have us pay you a visit and spend a few days with you doing training. And if you have a good training room, we can also invite other WebSmart customers in your area to attend the training and help offset your costs. Contact BCD for details, or visit our web site at for detailed information on the available training options. 26 Section I - Introduction and Installation Instructions

27 2 - Installation and Configuration C HAPTER 2 Installation and Configuration This chapter guides you through setting up WebSmart so you can design, create and execute programs in the default environment. As you start building production applications, you may want to adjust some of the settings, particularly the HTTP configuration directives relating to object locations, or create your own HTTP server instances (if you don t have them already). If you need help setting up your own working environment, or have any questions about the install, contact Technical Support. If you have a mybcdsoftware.com profile you don t need to fill out the software download form every time you get software. Contact Technical Support or visit our website (esdi.excelsystems.com/iseries400apps/acc_reques.pgm) to request a profile. The instructions describe how to install and configure all WebSmart 7.0 components. Some steps are only required for particular features or particular situations, so read the comments at the top of each step before proceeding. Follow the steps that apply to you. If you are using WebSmart on more than one system, or intend to do so, review the section Creating non-cgi Batch Programs, in the WebSmart ILE User Guide. Are you upgrading to V6R1 and already use a WebSmart version older than v 7.0? The upgrade to V6R1 is not like most regular System i OS upgrades. While there is always a risk of incompatibilities surfacing as a result of an OS upgrade, in this case it is a certainty ( If you have created WebSmart programs on any release prior to version 7 of WebSmart, you need to regenerate and recompile all those programs so they can be bound to the new WebSmart service program. Running the IBM command ANZOBJCVN over a WebSmart program can leave you with the mistaken impression that it will run correctly on V6R1. This is not necessarily the case. Service programs in XL_WEBSPT that are referenced by your program must also be able to be converted, and prior to WebSmart version 7.0, this was not the case.

28 Step 1: End the EXODUS Subsystem. Step 1 is required for: Upgrades, and if you have BCD s Catapult or Spool-Explorer installed. If this is a new install, and you know you don t have Catapult or Spool-Explorer installed and running, skip to the next step. The WebSmart IDE (the design tool) uses a communications middleware component called EXODUS to transfer data between the iseries and PCs at different times while you are creating your programs. For example, EXODUS is used to retrieve iseries file layouts, or upload code to be compiled. EXODUS is also used by BCD s Spool-Explorer/400 and Catapult. Before installing WebSmart you need to make sure that there are no EXODUS jobs running, to ensure there are no locks on objects that need to be updated or replaced. Here is how you can verify that you are ready to install WebSmart: Sign on to an iseries session as QSECOFR and run the WRKACTJOB command. Check whether there is an active subsystem called EXODUS. If the subsystem is not active, you can proceed directly to Step 2. If the EXODUS subsystem is active, then someone at your site may be working with an application that uses EXODUS for communications. To see a list of these jobs, run the command WRKOBJLCK XL_EXODUS *LIB. You can then you can contact the users associated with these jobs to request that they end their connections, or if you know what the jobs are, you can end them yourself. If one of the jobs using EXODUS is the Catapult Poller, end the Poller from the PC where it is running rather than by just ending the job on the iseries. After ending all EXODUS jobs, run the following command to end the EXODUS subsystem: ENDSBS SBS(EXODUS) OPTION(*IMMED). Ignore any message stating No subsystem Exodus active. When the EXODUS subsystem has stopped, you can continue with the next step. 28 Section I - Introduction and Installation Instructions

29 Step 2: Install Zend Core. Step 2 is required for: WebSmart PHP. If you have no plans to use or evaluate WebSmart PHP, skip to the next step. However, if you think you might at some time try out WebSmart PHP, install Zend Core first so the WebSmart install can automatically detect it and adjust the WEBSMART HTTP server instance accordingly. If you install Zend Core afterwards, you ll need to make these adjustments manually. Before you can create and run programs with WebSmart PHP you need to install Zend Core. To verify whether you have Zend Core installed, follow these steps: 1. At an iseries session, run the command GO LICPGM. 2. Select option Verify that licensed program 1ZCORE5 is installed. If Zend Core is not installed, you can download it for free from the Zend website, at (in the PDF version of this guide you can click this URL to go there now). The Zend website also lists the Zend Core system requirements. If you have installed any release of WebSmart before installing Zend Core, you will need to manually add some directives to your WEBSMART Apache HTTP server instance (or any server instance you regularly use). These changes are described in the WebSmart PHP Knowledge Base article 6910 at Or if you prefer, give Technical Support a call and we ll help you out. After installing Zend Core you can continue with the next step. Chapter 2 - Installation and Configuration 29

30 Step 3: Install the WebSmart iseries Components. Step 3 is required for: all WebSmart installs. Follow the instructions below to install and start the WebSmart iseries components. 1. Go to the Download Free Software link at (at the top right of the page). Once there, fill out the form to download WebSmart. 2. Download both the iseries and PC installation files. 3. When the download finishes, double-click the iseries install executable file WebSmart7.0.exe (the version number may vary) to unpack the files and transfer them to your iseries. 4. When prompted, enter your iseries IP address and the QSECOFR password: Figure 2-1. The upload utility presented when you execute the iseries install file. Click the Upload button. When the upload finishes the activity log displays the message File upload complete. You can then close the FTP utility. 5. Log on to an iseries session as QSECOFR and execute the command BCDINSTALL/BCDINSTALL. 6. Select option 1 next to the product WebSmart 7.0 (the version may vary) and press Enter to begin the installation. The iseries libraries installed are XL_WEBLIB, XL_WEBSPT, XL_WEBDEMO, XL_EXODUS and BCDSUPPT. 7. When prompted enter the license key provided to you by BCD. If you have not yet received a license key phone BCD at (630) , or sales@bcdsoftware.com. You can enter your license key after installing using the command XL_WEBLIB/UNLOCK. Finally, when the iseries install concludes, run the command WRKACTJOB to verify that the EXODUS subsystem is active and contains a job called EXSERVER. If the subsystem hasn t been started, run the command STRSBS XL_EXODUS/EXODUS. 30 Section I - Introduction and Installation Instructions

31 The WEBSMART HTTP Server Instance As part of your WebSmart iseries install we create, configure and start an Apache HTTP server instance named WEBSMART, running on port This allows you to start running your programs as soon as you install the software. You can use the WEBSMART HTTP server instance however you want, but we recommend that once you start creating production applications, you create your own server instances and use those. In our own internal development projects we have caused the HTTP server instances to go down due to malformed SQL and other programmatic issues, so we recommend that you create at least two separate server instances, for your development and production environments. If you need assistance with creating your own server instances, please call Technical Support and we can help you out. Testing your WebSmart ILE Install The installation includes a sample program you can run to verify whether all the components required to run ILE programs from your iseries were successfully installed. To try the sample program, type the following URL into your browser (or if you are viewing the PDF version of this guide, copy and paste this string). Replace the IP address shown with that of your own iseries. Leave the :8150 for the port number specified in our default configuration setup: If the test program runs fine, then you can continue with the sections below. Testing your WebSmart PHP Install The installation also includes a sample PHP program you can run to verify that the critical components required to run PHP programs were successfully installed. To run the sample program, type the following URL into your browser, replacing the IP address shown with that of your own iseries. Leave the :8150 for the port number specified in our default configuration setup: If the test program appears, continue with the sections below. If either of your test programs doesn t work, please contact our Technical Support team at (250) [7:30-5:00 PST], or by at excel@excelsystems.com. We have excellent support and we will be happy to help you out. Or if you are particularly ambitious you can attempt to identify the problem yourself using the troubleshooting suggestions at the end of this chapter. This could also be a useful preview of the types of things you will need to check once you start creating your own live applications! Chapter 2 - Installation and Configuration 31

32 Step 4: Install the WebSmart PC Component. Step 4 is required for: all WebSmart installs. Follow the steps below to install the WebSmart PC design tool: 1. If you haven t yet done so, go to the Download Free Software link. Fill out the form to download WebSmart and then download the WebSmart PC component. 2. When the download finishes double-click the downloaded file to unpack the install files and initiate the install. The PC install file is named websmart7.0client.exe [the version number may vary]. 3. Follow the instructions to install the WebSmart executables to your PC. 4. When the installation is complete, click Finish to exit InstallShield. You have now installed WebSmart. To launch the WebSmart Integrated Development Environment, double-click the icon in the open folder, or go to Start/Programs/ WebSmart 7.0/WebSmart (this version number may vary). Continue with the next step to configure the connection between the WebSmart PC and iseries design components, and create a new FTP connection. 32 Section I - Introduction and Installation Instructions

33 Step 5: Configure the WebSmart IDE to Connect to the iseries. Step 5 is required for: all WebSmart installs. The WebSmart IDE needs to be configured to connect to the iseries so it can retrieve file layouts and perform other functions related to your iseries database. Follow these steps: 1. Launch the WebSmart IDE (Start/Programs/WebSmart 7.0/WebSmart). 2. The software will automatically detect whether you have configured a connection to the server, and if not, prompts you to add a system: Figure 2-2. Creating a new iseries system description. 3. Enter your system name and IP (or DNS). Port 2015 usually works. At V6R1 IBM has taken over the use of Port If you are at V6R1 or higher, use port 7015 or any other available port. Then run the command XL_EXODUS/ZCFGTCP on your iseries to change the port used by the server component. 4. From the iseries System configuration you can also set default values for a few options that you need to specify every time you create a new WebSmart ILE program. These include your RPG source file and object libraries. The program object library XL_WEBAPPS will work in conjunction with the standard WEBSMART HTTP server instance configuration. If this is a new install and you choose to use a different library, you will also need to adjust the default configuration for the WEBSMART HTTP server instance or create your own HTTP server instance to use instead. Chapter 2 - Installation and Configuration 33

34 5. For the default web path to object, enter the following: where your_ip_address is the IP address of your iseries (make sure you don t forget the port number and final slash shown above). This assumes that you are using the default configuration and the WEBSMART HTTP server instance. The Program Attributes are described in the section ILE Program Defaults on page 226 of Chapter 9 of the Reference Guide. 6. To confirm your configuration click the Test Connection button. When you do this WebSmart prompts you to sign on to your iseries and then displays a confirmation message. If you don t get a successful connection, here are a couple of things to check: The most common connection error (10061) is caused by the EXODUS subsystem not being active. To address this run the WRKACTJOB command and check whether the EXODUS subsystem is running and contains a job called EXSERVER. If not, run the command STRSBS XL_EXODUS/EXODUS. If the subsystem is running but EXSERVER is not, end and restart the subsystem and confirm the job is added. Then try connecting again. If the subsystem is up, add XL_EXODUS to the library list of your iseries session and run the command ZDSPERRLOG to display a list of your connection attempts. Check for error messages (such as invalid User IDs, etc.). If you can t spot the problem immediately, call Technical Support at (250) Click OK to add the configuration entry. If you will be working with more than one system, you can add them all now. If you will be working in a relatively complex development environment, such as developing applications on multiple systems, or using multiple FTP sites or databases, review the section Working with WebSmart IDE Environments on page 232 of Chapter 9 of the Reference Guide. 34 Section I - Introduction and Installation Instructions

35 Step 6: Create an FTP Connection. Step 6 is required for: WebSmart PHP installs. If you do not plan to create PHP programs, skip to the next step. WebSmart PHP requires at least one FTP connection. Your FTP connections allow you retrieve and work with files related to your application, as well as set defaults for the PHP programs you create. In WebSmart IDE, open the Tools/Options window and click the FTP entry to present these options: Click here Then here Figure 2-3. The WebSmart default FTP options. Enter the following values for your new FTP site: Option Site Name URL Initial Directory Description Type an informational description of the site you are connecting to. Enter the IP address or domain name of your server. Enter the initial directory to be displayed. For WebSmart, use this value: /www/websmart/htdocs/wsphp/ (with no quotes). Chapter 2 - Installation and Configuration 35

36 Option Description Web Path Select a default path to pre-pend to your program name when you click the Launch button from within the IDE. The default WebSmart Apache HTTP server instance runs on port 8150, so this should normally be set to (no quotes). User/Password. Enter the user profile and password to use to connect to the iseries when saving the PHP files. FTP Port Select the FTP port on the remote system. The default value of 21 should usually work for you. Passive Mode Check this option if you need to establish your FTP connection in passive mode. After entering the required values, click the Test Connection button to verify that you have entered your configuration details correctly. If the confirmation window tells you that the connection is working, continue with the next section. If you didn t get a successful connection, double-check your values. If you have established links to the server in another application, compare your settings to those. For additional information on your FTP connections, please refer to the sections FTP Servers and Automatically Reconciling FTP Sites on page 223. You can also create and modify your FTP connections from the window pane at the lower left of the main IDE. Just right-click in the area below the FTP Sites tab to present the available options. If you will be working in a relatively complex development environment, such as developing applications on multiple systems, or using multiple FTP sites or databases, review the section Working with WebSmart IDE Environments on page 232 of Chapter 9 of the Reference Guide. 36 Section I - Introduction and Installation Instructions

37 Step 7: Create an ODBC Connection. Step 7 is required for: WebSmart ILE or PHP programs running over databases other than DB2. If you will not create programs over non-db2 tables, skip to the next step. If you intend to use WebSmart to create programs over other databases (such as MySQL in PHP, and MySQL, MsSQL or Oracle in ILE) you need to create an ODBC connection to your target database so WebSmart can load the file layouts. To create a new ODBC connection, launch the WebSmart IDE and go to the Tools/Options menu. Select the Servers/Databases section and click Add to present these options: Click here Then here Figure 2-4. Attributes of an ODBC connection (Tools/Options). Here is a description of the options you need to enter: Option Name/Description Server/Port Database User/Password Driver Description Type a name and description for this ODBC connection. Type a server IP and port number. Enter the database name. Type the User ID and password to be used to connect to this server. Select the driver. Test your connection, then press OK to create it. Chapter 2 - Installation and Configuration 37

38 Step 8: Set a Default User Profile for WebSmart PHP Programs. Step 8 is required for: WebSmart PHP installs, where you will be running PHP programs on your iseries and/or MySQL server. If you are only using WebSmart ILE, skip this step. After installing WebSmart PHP you need to set a number of connection defaults so your programs can access your iseries and database. While there are a few ways to handle this requirement, the WebSmart PHP program templates are set up to retrieve the connection values from a file on your IFS. When you execute WebSmart PHP programs, the first thing they attempt to do is load a preferences file, xl_functions001.php, by executing this statement at the top of the code: require('/esdi/websmart/v7.0/include/xl_functions001.php'); This file includes a section where you can specify default user profiles and system names (among other things). However, because this file is overwritten when you upgrade, it in turn attempts to load some defaults from another file, xl_user_preferences.php, which you need to create (see our online WebSmart PHP KB article 6998 for additional details). Create xl_user_preferences.php In your iseries IFS, open the file /esdi/websmart/v7.0/include/xl_functions001.php. Save the file as xl_user_preferences.php (or copy and rename xl_functions.php). In the new, copied file delete everything from (and including) this line up to the end of the Leave the?> at the end of the file. In the section that remains in xl_user_preferences.php enter default values for the connections you will be using, as described here: Value $pf_i5userid and $pf_i5password $pf_i5ipaddress $pf_db2systemname $pf_db2userid and $pf_db2password $pf_mysqlurl $pf_mysqluserid and $pf_mysqlpassword $pf_mysqldatabase Description iseries user profile and password to use for all i5 connections. If this value is left blank, Zend Core will use the special profile NOBODY. Unless you are by default connecting from your iseries to another one, use the loopback value here. Enter your iseries system name for all database file access. iseries user profile and password to use by default for all DB2 access. Default MySQL server to connect to. Default MySQL server user profile and password. Default MySQL database. When you create your own application you may want to load your User IDs another way (for example, by prompting the user to enter one), but this approach will get you started. 38 Section I - Introduction and Installation Instructions

39 Moving On After installing the software, we suggest you go back to the section How Should I Get Started? on page 23 of Chapter 1, which includes a list of initial objectives you may have when using WebSmart, and suggestions for the best way to accomplish those. If you have any difficulties or questions, please contact our Technical Support team at (250) [7:30-5:00 PST], or by at excel@excelsystems.com. We have excellent support and we will be happy to help you out. Installation and Configuration Troubleshooting Suggestions Here are some things you can check if your WebSmart ILE and/or PHP test programs (testcfg.pgm and testcfg.php, respectively) didn t run successfully in your browser. Confirm that the URL you entered is correct. Are you using the right IP address? Did you type the path after the IP address correctly? Did you include the default port number :8150 in the URL you typed? It s also possible that you have more than one IP address configured, one for Intranet access (often ) and one for Internet access. You can check this information by running the command CFGTCP then selecting option 10. Verify that the WEBSMART HTTP server instance is up and running. The install is designed to create and start an Apache server instance named WEBSMART. Run the WRKACTJOB to confirm that it is running. There should be several jobs running under the QHTTPSVR subsystem. If the WEBSMART server instance isn t running, you can attempt to start it with the command STRTCPSVR SERVER(*HTTP) HTTPSVR(WEBSMART). If you are testing WebSmart ILE, you can For WebSmart PHP, the test program should be in your IFS, at: \www\websmart\htdocs\wsphp\testcfg.php If either of these programs do not exist your iseries install may not have completed. Is your HTTP Server Configuration set up correctly? This should only be a problem if someone else installed the software and manually edited the configuration files after installing, But if you want to check this, Chapter 9 includes an overview of the default configuration, and instructions on how to make changes to it after it has been created. If you are checking your HTTP Server configuration, the first thing to check is whether the port number was changed by someone else after the install. If that s the case, then you need to change the port number in the URL. Chapter 2 - Installation and Configuration 39

40 WebSmart ILE: Is there just a problem running programs (but you can access IFS files)? To check if the problem is limited to running programs you can try accessing just a static file in your IFS. For example, try presenting this image: If this image is presented correctly, then your server instance is up and running, and there is just a problem with running your program. If you are having trouble running programs and are particularly ambitious, there are a couple of different ways you can run debugging using Apache: End the HTTP server instance and restart it using this command: STRTCPSVR SERVER(*HTTP) HTTPSRV(ApacheInstance '-vv') Replace ApacheInstance with the instance name (i.e. WEBSMART). This starts the Apache Instance in debug to generate a trace file. To view the trace file, stop the server and then look for a spool file under the user QTMHHTTP [on our system the spool file is called QZSRHTTPTR]. A spool file is created for each job that has ended, so check some of the most recent files. You can also try this command: TRCTCPAPP APP(HTTP) SET(*ON) HTTPSVR(ApacheInstance) TRCLVL(*VERBOSE) Use this command to run a trace on the server while it is running and without stopping it. To stop the tracing run this command: TRCTCPAPP APP(*HTTP) SET(*off) TITLE('My title'). You will need to log on with a profile that has authority to this command. WebSmart PHP: ZENDCORE issues. In order to run PHP programs on the iseries, you must have ZENDCORE installed correctly, and the ZENDCORE subsystem running. If you aren t sure whether ZENDCORE is correctly installed, contact your system administrator, or call BCD Technical Support. 40 Section I - Introduction and Installation Instructions

41 More About the WebSmart IBM HTTP Server (Powered by Apache) Instance The installation process is designed to automatically create and start an Apache web server instance called WEBSMART. To confirm that this server instance was successfully started run the WRKACTJOB command and look for the subsystem QHTTPSVR. This subsystem should contain several jobs named WEBSMART. If this server instance is not visible you can start it using the command STRTCPSVR SERVER(*HTTP) HTTPSVR(WEBSMART). If you have any difficulty with this process, contact Technical Support at (250) or by at The default configuration will normally be sufficient to get you up and running, though you may decide to make changes to it before promoting applications to production (see the note at the top of page 31 for further details). Working with the WEBSMART HTTP Server Instance The default configuration on install should work for you. If you need to make changes to the WEBSMART HTTP Server configuration you can do so via IBM's Web Administration for iseries pages. You can access this interface from your browser. To do this use the following URL: (insert your iseries IP address before the :2001). Log in using your iseries user profile. The page includes a list of your HTTP servers in a dropdown box. Find and select the WEBSMART entry (as shown below): Figure 2-5. Working with your iseries HTTP servers via the online interface. If the server isn t running (i.e. it shows with a status of Stopped, as above), you can click the green button to start the server instance. The status should change from Stopped to Running. Changing the WEBSMART Server Instance Default Port Number To avoid the possibility of conflicting with any existing HTTP server instances you may have running on your system, we ship the WEBSMART server instance configured to use port For this reason, your links to your programs look like this: If you don t already run a server instance on port 80 (the default), you can switch to using that. Then you won t have to include a port number in the URL. If you have any questions about how to change your HTTP server configuration, or whether you need to use a different port number, please contact BCD Technical Support. Chapter 2 - Installation and Configuration 41

42 42 Section I - Introduction and Installation Instructions

43 3 - WebSmart PHP Concepts C HAPTER 3 WebSmart PHP Concepts This chapter introduces some of the basic concepts behind WebSmart PHP and describes how WebSmart PHP works and what it can do for you. Following this chapter, Section II includes some tutorial exercises to introduce you to the key features of the tool. There are some concepts involved in using WebSmart that may be new to you. If you prefer to understand exactly what you are doing before building your first application, we recommend that you read this chapter prior to continuing on to Section II. If you learn best by example, then by all means skip straight to Section II and you can read this later. Here are some of the topics we discuss: What WebSmart is. Delivering dynamic web pages to a browser. CGI and stateless programming. WebSmart Program Definitions (PDWs). PHP programming. HTML Coding. Please note that as you read through the documentation, you will see sections dedicated to concepts such as cookies, style sheets, JavaScript, etc. If you start to feel overwhelmed, keep in mind that these features in WebSmart and web applications are helpful, but not essential. For example, you can easily create a wide variety of programs without using cookies. Because these functions are useful under some circumstances we have spent some time documenting them, but you certainly do not need to master every topic in our documentation in order to become a proficient developer of online applications.

44 What is WebSmart PHP? WebSmart PHP is an application development tool for producing iseries server-based, web-enabled PHP applications that interact with a browser. The generated programs interleave PHP and HTML code with data from a server. Web page content is delivered to the user by the following mechanism: 1. The User requests a URL (i.e. on an iseries server from a browser. 2. The iseries Web Server accepts the request and processes it. 3. If the request includes a call to a PHP program, the program is invoked by the iseries Web Server. 4. The PHP program reads input parameters from the user request (via the Web Server). 5. The program constructs a web page, by merging static pieces of HTML with live data, and writes the web page to the Web Server. 6. The Web Server sends the web page to the User, inside the browser. This type of server-based data delivery is commonplace at web sites. For example, if you have ever used a search engine such as Google then you have used an application that constructs pages on demand. The resulting pages presented to you are produced by a server-side program that runs your query request against a database, then constructs the HTML containing those results and presents it to you in the browser. Another example of applications that employ this technology is web-based sites, such as Hotmail.com. Whenever you access your account, a server-side program constructs a list of your Inbox by reading the stored data from a database and writing it as HTML to the browser. WebSmart helps you create web-enabled applications, hosted on the iseries or another server, that interact with real-time data quickly and easily. The product consists of two main components. The first is a Windows application - the Integrated Development Environment (IDE), for designing web pages and integrating iseries data elements. The IDE includes wizards and templates for building off-the-shelf applications with little or no coding. It also includes a code editor that allows you to extend the logic of programs to build powerful applications, and an interactive HTML editor to customize the look of the output pages. Although the tool can produce complete working applications with no coding on your part, if you need to you can write code using PHP. The other main component is the generator, which (in essence) combines your HTML and PHP code to produce the executable PHP program. 44 Section I - Introduction and Installation Instructions

45 With WebSmart you can produce almost any kind of application for a government institution, school or business. Here are some examples: Inventory of available products or product components for customers to view. List of knowledge-base articles for a software company to make available to users. Shopping cart applications, allowing ordering of products directly over the Internet. Sales reports for corporate executives, available over the company intranet. Online Order-entry applications for clients to access over the Internet. Web-based messaging or discussion forum. Data entry programs, for adding records to files. You can find examples of some of these types of applications at our web site. Advantages of Using WebSmart to Build Web-Based Applications WebSmart differs from many other tools used to build dynamic web-based applications in its use of templates and wizards. You need very little programming experience to use the tool because WebSmart leads you through a series of prompts to build a web page. In addition, it allows you to use a visual HTML design tool which simplifies coding HTML for the novice. As you get more experienced with writing HTML you can write it by hand, which still seems to be the preferred method for many web masters. Other benefits to using WebSmart include: You can use PHP, with its abundant supply of functions and rich body of online resources, to extend the logic of your application. There is extensive, context-sensitive help in the PHP and HTML editors. Full support for native record-level database access functions in PHP. WebSmart can utilize the iseries native database or a MySQL database running on another server. You do not have to re-engineer your existing files, or port them to another database such as Lotus Domino. WebSmart also utilizes the iseries native security functions. WebSmart applications also run using the iseries HTTP Server (Powered by Apache), included for free with OS/400. There is no need to purchase a proprietary web server, or to use products such as Net.Data. The WebSmart program templates are extensible, allowing you to create your own templates to your corporate standards. For example, you may wish to include a standard HTML header that references a corporate logo in the top of each web page. You can easily modify or create new templates to accomplish Chapter 3 - WebSmart PHP Concepts 45

46 this. You can also extend the program design wizards in conjunction with your template modifications. WebSmart includes powerful file repository functions that allow you to attach several different kinds of extension to your fields. These range from simple things, such as edit codes, to giving you the ability to include complete functions, or even automatically adding more files to your program whenever a particular field is used. WebSmart definitions are completely portable. They consist of simple text files that can be shared between different designers, or on different PCs. For example, you can design a program at work, then the definition to your home PC and work on it at home. WebSmart includes a powerful change management tool, to allow you to better control the stages of development of your PC definitions. The design tool is Windows-based, so it is both powerful and easy to learn to use. The code for each program is compact and efficient. You can use many functions that make it easy to address typical web-based CGI programming issues. For example, there are functions for creating and getting cookies and managing transaction processing. These functions help deal with the issue of persistence and maintaining conversation state between client (the user at the browser) and server. The generated applications are completely flexible in terms of look and feel: you are in no way constrained by green screen standards. The client component of generated applications consists of HTML. Unlike Java applications, questions of compatibility between browsers or browser configuration are not significant issues. Also, the user does not experience the often-lengthy wait that occurs while waiting for Java client applets or applications to load. The generated programs are much faster than Net.Data and most Java based CGI programs. You can use embedded SQL statements in your programs for reporting and block data access. You can use SmartCharts to create dynamic, high quality visual representations of your data. These and other features will quickly make you a convert to programming with WebSmart! WebSmart Definitions A WebSmart definition is a single PC text file with an extension of.phw. It contains all the elements needed to generate a working PHP program from within the WebSmart 46 Section I - Introduction and Installation Instructions

47 design tool. It includes information about the program and the files it uses, the PHP code and run-time HTML source. The PHW file can be opened in a text editor like Notepad where it is completely readable. Normally, however, you will work with these files in the WebSmart IDE (Integrated Development Environment), which parses the various components in a logical way. There are benefits and drawbacks to storing all the program definition information in a single PC file: The main benefit is that it is quite easy to organize your definitions, and move and share them at any time. You can a definition to a colleague, or copy it to a new name all using the same mechanisms as you would use for any PC file. It is also easy to debug the definition, or it to BCD Technical Support, for instance. Because the definition is stored on the PC, you can do substantial work on the definition without ever having to connect to the server. We have found that when we design programs, we tend to spend more time tinkering with HTML and the look of our programs than on writing the actual program logic. All of this type of work can be performed without requiring access to your server. The main drawback to using program definitions is that it requires a different approach to change management than what you may be used to when working on the iseries. However, WebSmart includes some powerful change management tools to help you with this task. WebSmart Change Management is described in Chapter 14 of the WebSmart ILE Reference Guide. PHP The main window of the WebSmart IDE lets you write free-hand code in PHP. The PHP controls the entire flow of your program, and gives you great flexibility and unlimited license to change the way your program works. Each program you create will contain some initial PHP that comes from a template. You can then modify the code using the PHP editor. Templates form the building blocks for programs in WebSmart. Each template has PHP embedded in it, with tokens, or placeholders, for information that is provided by the designer when they start to design a new program. As you go through the initial design process, the IDE uses intelligent wizards to prompt you for the relevant information to construct a complete program. The information that is asked for is based on the template's contents. The PHP, in conjunction with other components in the template, defines how the generated program will behave. When you select a particular template, it includes a set of predefined behaviors. However, once you have completed the initial steps provided by the Wizards, you can change the functionality of the program in any way shape or form, by changing the PHP code. You can also create new templates, which incorporate the Chapter 3 - WebSmart PHP Concepts 47

48 behaviors and the look and the feel of the pages and programs you wish to create for your company. The approach to development described above means that when you wish to change the functionality of a program, the bulk of the changes will be coded in PHP. You will need to learn at least the basic syntax of PHP to extend your program's functionality. Learning PHP WebSmart PHP is designed to be used by programmers who are familiar with PHP. If WebSmart PHP is your first experience with PHP, then we suggest you take advantage of the many online PHP tutorials, or take a PHP course (you ll find a few suggestions at the end of Chapter 1). If you are an RPG programmer, you may prefer to use the ILE version WebSmart instead. WebSmart also includes a number of built-in learning tools. The learning tools include: Color coding of various code elements. A window with a list of available functions. Pop-up info boxes with names of valid objects that can be specified for various parameters. Context-sensitive, online help for every function. A syntax-checker, with an error frame below the code. By clicking on an error, the code editor immediately positions you at the relevant line of code. An auto-format option that indents the code based on the structures present. The templates themselves. You can quickly become familiar with key PHP functions by simply going through the prompts used by the IDE Wizards as you create a new definition, then studying the generated code. The best source of help for learning PHP is the Web; there are myriad PHP learning resources available online for free. HTML To successfully design and work with web-based application, you will need to learn at least some rudimentary HTML. Each WebSmart template that we supply has sufficient HTML code embedded in it to produce a working page, so you can start enjoying success with the product immediately without having to worry about coding HTML. As you progress with the product, your expectations for the look and feel of the pages you create will undoubtedly change. While it is quite possible to create a complex application using only 3 or 4 HTML tags, you will probably find yourself wanting to improve the look and feel of your application. The WebSmart ILE Reference Guide includes our own Web Page Design for Green-Screeners. which explains the basics of HTML coding. If you work with the PDF version of this guide, you can click on the embedded hyperlinks to see the sample web pages in action. 48 Section I - Introduction and Installation Instructions

49 Remember that the best source of HTML help is the Web itself. When you see something you like on a web page, it is easy to view the source and examine how it was done, and what tags are required. (In Internet Explorer, go to menu View/Source; in Netscape, go to View/Page Source). In addition to all that help, the IDE includes a text editor for HTML, and you can also use our visual HTML editor to modify the HTML in a WYSIWYG interface. The IDE also includes a feature called HTML snippets. This allows you to create, change or delete fragments of commonly used HTML. You can then drag and drop them into the HTML for your program definition. Chapter 3 - WebSmart PHP Concepts 49

50 The WebSmart Programming Model As we noted in Chapter 1 of this guide, there are many other PHP editors available, some of them quite inexpensively, or even for free. But WebSmart PHP has been built for developers creating complex business applications, as opposed to wikis or other popular web-based tools. Separating Code from Content When a web program is started from scratch, the interface between PHP and HTML can often end up as a virtually indecipherable mess of spaghetti code, where HTML and PHP are interleaved in ways that to another programmer can seem almost random. By grouping your blocks of HTML code logically into segments your program becomes much more readable and maintainable. If you are curious as to how segments are handled in the generated PHP, open your generated PHP program from the FTP sites tab. After loading the program into the IDE, click on the Functions tab (next to the FTP site tab) and notice that your program has a wrtseg function at the bottom of it. Double-click this function to position to that spot in your code. In that function you ll see how segments are processed when your page is loaded. Each wrtseg statement in your mainline PHP has a corresponding, single, echo, corresponding to the IDE s HTML segment. This makes both your PHP and HTML very easy to read and maintain. Furthermore, using templates as the basis for the programs you create makes it easy to create and maintain an application skin - an overrall look and feel for your application. All new WebSmart programs are created from templates, and you can easily create your own templates to match the look and feel of your organization s current website or logos. Separating the Content from the Layout You may have already discovered this yourself in your first forays into Web development, but good programming skills do not necessarily imply good web page design skills. Even when a page is intended to be purely functional, displaying records in lists or individually, there is often a significant, visible quality difference between the work of a programmer and the work of an accomplished website designer. Enter the separation of content from layout by creating your programs from templates and using Cascading Style Sheets, you can easily create a consistent appearance for all your programs. And you can then enlist the help of a designer familiar with CSS to make all your programs look consistently good. If you haven t done so already, you should consider allocating funds to have a web page designer help you create some custom templates. It can make a big difference in the visible quality of your programs. Otherwise, your programmers may find themselves increasingly frustrated as they find that create programs that look good is much harder than you would think. 50 Section I - Introduction and Installation Instructions

51 The BCD Professional Services team can also help you create new templates with custom logic and HTML. Chapter 3 - WebSmart PHP Concepts 51

52 Stateless Programming iseries programmers are used to a programming model in which you always know where you are, how you got there, and where you re going next. This process of maintaining state stores all manner of useful information. Consider the following examples: When a program displays a screen to gather some user input, the program waits until the user press the Enter key before proceeding. When program A calls program B, program A waits until program B finishes executing before proceeding. The corollary of this is that when program B finishes executing, the operating system knows to return control to program A. We know that program C isn t called until program A has resumed execution after returning from program B. When program B returns control to program A, all the variable values, open files, record locks, etc. are remembered. In the world of programming applications for the Web, however, things are somewhat different. Consider how a request for a web program is processed: 1. You type in a URL into your browser s address bar and hit Enter; 2. The browser finds the machine on which the page you requested resides. This machine is the web server; 3. The web server receives the request, and starts a job to handle the request; 4. The program is called, some HTML output is produced; 5. The HTML output is returned to the browser, where it is displayed; 6. The program on the web server ends. So by the time you actually see the output in your browser, the program on the web server has ended. Since the program ends, there is no way of maintaining state. And since there is no way of maintaining state, there is no way of implicitly knowing what your path of execution has been. Some ways in which this translates into programming challenges are: When you view a list of records, and click the Next or Prev link, how does the program know where to start the list from? When you log into a secure site, how does each program know who you are? When enter search criteria into a form, how does the program remember these criteria when you click Next or Prev (the way Google does, for example)? These are issues that need to be dealt with in web programming. 52 Section I - Introduction and Installation Instructions

53 Section II - Getting Started SECTION II Getting Started In this Section: Chapter 4 - Building Your First Program with WebSmart PHP

54

55 4 - Building Your First Program with WebSmart PHP C HAPTER 4 Building Your First Program with WebSmart PHP Overview Now that you have successfully installed and configured WebSmart and your iseries is ready to serve web pages, let's build your first WebSmart PHP programs. This chapter is intended to introduce you to the WebSmart PHP development environment, and point out the key features of the design tool. Through the tutorial you will learn a number of general skills relating to using the WebSmart design tool, such as how to build, save, generate and run programs. We will also illustrate some fundamental WebSmart PHP programming skills, such as how to link programs together, limit record sets, and retrieve additional information from other files. In addition, the tutorial addresses critical HTML programming skills, such as how to create links, gather information using forms and then retrieve parameters, as well as some simple HTML formatting. Programs you build with WebSmart can be constructed to deliver one or more web pages, or link to other WebSmart programs using program calls. You design each program using the WebSmart IDE (Integrated Development Environment). Your design work on a program is stored in a single text file called a definition (more on this below). Definitions contain all the information required by the generator to produce a working WebSmart program, including HTML and PHP instructions. Definitions are completely portable, and you can copy them, save them to local or network drives, them to other WebSmart developers, etc. When you start constructing a definition for the first time, the IDE uses wizards to help you complete the basic steps. Once these are done, you can further customize the definition.

56 These are the basic steps you perform to construct a definition (this is just an overview, you don t need to do this now): 1. Start a new definition. This is no different from any Windows application; just use the File/New menu option, or click on the New icon in the IDE toolbar. 2. Select a template. Templates are pre-defined packages containing most of the information needed to construct a complete working definition, with placeholders used by the design wizard for filling in customizable components of the definition (such as the files and fields, file relations, etc.). There are a few different template families available, with similar functionality but different looks. Feel free to experiment to find the ones you like best. The New Program interface displays illustrations and overviews of all the different templates available. If you have a license to Clover or are working with an evaluation copy of WebSmart, you will also have access to numerous templates designed to create reports and SmartCharts. 3. Define the Program Attributes. This is information that is common to the entire definition. It includes items such as the program title, target source and object information, and library list object to use (library list objects are discussed in more detail below). You ll also choose some of the options that your program will include, such as support for adding, changing or deleting records. These options will vary depending on the template you have chosen. 4. Select any files. Then you need to choose which files you will use in your program. WebSmart stores your file layouts in a repository on your PC. If you have further added any WebSmart repository extensions to your files, then those are also built into your definition. The exercises in this tutorial use files with extensions. 5. Select any fields to place on the HTML pages or forms. Usually, these are fields that are associated with either a list of records or a single record on a page, depending on the template you selected. And these are all the basic steps. Once you have created the initial definition, you can generate the source code and compile your program to see how it works. Then you can modify the HTML and PHP to further customize your program. Some of these design steps vary depending on the template you choose. 56 Section II - Getting Started

57 What is a WebSmart Definition? A WebSmart PHP definition is a plain text file with an extension of.phw. You can view the definition using any text editor, but if you want to retain the changes to generate new source you can only work with the definition in the WebSmart IDE. The definition contains all the information necessary to generate a fully functioning program, including your program attributes, files, parameters, HTML previews, HTML segments and the complete PHP code that you have written for the program. WebSmart definitions are portable and self-contained. If necessary, you can send the.phw file to another person or store it on a network drive so that others can work on the program. For example, if your organization has an in-house web page designer, you can collaborate with them on a definition. And if you are having trouble getting a program to work like you need it to, you can easily send the entire definition to BCD Technical Support so we can help you troubleshoot it. The change management facilities built into WebSmart help you keep track of your definitions, and make sure that developers don t step on each other s toes when sharing them. This tutorial exercise assumes you will be using the iseries database. You can, however, use other WebSmart PHP templates for creating programs over a MySql database. If you do this, there are only a few minor differences in the design process. Chapter 4 - Building Your First Program with WebSmart PHP 57

58 Part 1 - Creating Your First Program To create your first WebSmart PHP program, begin by launching the WebSmart IDE (Integrated Development Environment) on your PC. To do this, click on the Start menu on your PC and select All Programs\WebSmart 7.0\WebSmart. Verifying your Configuration If you followed all the installation instructions, and verified each configuration setting as you made it, you should be ready to start building your first PHP program with WebSmart. But just in case it s been a while since you did the install, or someone else did it for you, let s quickly review your default environment settings. Checking your iseries Connection with Exodus WebSmart uses a middleware component called Exodus to connect to your iseries for retrieving information related to your database files. To check your Exodus connection, use the Help/Test Connection option from the IDE. When you do this, WebSmart prompts you to sign on to the iseries (if you haven t done so already), and then confirms the connection. If this process fails, review the section Configure the WebSmart IDE to Connect to the iseries. on page 33 of Chapter 2 for assistance. Checking your FTP Connection to the Server You also need an FTP connection to your server, to save the PHP program to the location from which it will be executed. Your current FTP connections are listed in the bottom left window of the IDE. To check your FTP connection, click the + next to the entry. If the list opens, your connection is fine. If you have problems with this step, check the section Create an FTP Connection. on page 35 of Chapter 2 for help. Checking your Apache HTTP Server Configuration and Launch Button Availability Finally, in order to run your programs you will need to have a the WEBSMART Apache HTTP Server instance up and running. You can check this at the Admin interface for managing your HTTP Connections, at If your HTTP configuration doesn t seem right, review the section Install the WebSmart PC Component. on page 32 of Chapter Section II - Getting Started

59 Selecting a Template For our first example we will create a Customer Maintenance program using the iseries SQL template named Page at a Time. Our first program will be used to work with a list of customers. Step 1: Start a new definition. Start by selecting the File/New option, or clicking on the leftmost icon in the tool bar (the blank page icon). If the New Program window doesn t default to showing the location below, you can find the WebSmart version 7.0 (PHP version 2.0) templates in the folder Program Files/ESDI/WebSmart/Templates v7.0/php Templates. The first choice you are required to make is which template to use for your definition. The window presented is illustrated below: Choose this template. Figure 4-1. The WebSmart New Program window (File/New from the WebSmart IDE). Notice that within the PHP Templates there are two sets for the iseries, an RLA (Record Level Access) set, and an SQL set. We created the RLA templates mainly for iseries programmers who are familiar with how the ILE/PML templates are structured. However, most programmers familiar with PHP and SQL find the SQL templates easier to work with and make changes to. Chapter 4 - Building Your First Program with WebSmart PHP 59

60 Step 2: Choose a template. In the PHP Templates entries, click the + sign next to the iseries SQL group and find the template called Page at a Time Maint.tpl (see Figure 4-1). Select this template. This template is designed to create a web page displaying a list of records. It also supports some additional features which we ll look at as we go. When you select the template, the wizard presents the Program Attributes dialog: Figure 4-2. The Program Attributes for a new PHP program. Step 3: Type a program name and description. Type the name custmaint for your program, and a program title (as illustrated above). The default library list is *FILES. Library Lists are described in more detail in the reference section, but this is the essence of what you need to know about them: On execution, most iseries programs need to open files in one or more libraries. However, the job that runs the PHP program will not automatically adopt the library list of any particular user profile or job description. This means that the program needs to set its own library list when it begins to execute. You can address this by specifying a library list which identifies all the libraries that you will need. The default value for this parameter is *FILES, so the program automatically determines which libraries to have in the library list based on the files used in the definition. 60 Section II - Getting Started

61 The Destination FTP Path is the folder where your PHP program will be created and executed from. The base value for this field is derived from the settings of the FTP site shown in the dropdown list. Your values may not match those shown above. The Web Path for Launching is the base URL used to launch your program from the IDE. This option doesn t affect the actual program object at all, it s just a shortcut. Technically it is a combination of your server s IP address (or domain name) and the HTTP server configuration mapping to the location specified in the Destination FTP Path. So in the above example, the HTTP server instance listening on port 8150 is set up to map requests in the path /wsphp/ to the IFS folder /www/zendcore/htdocs/wsphp/. When you click on the launch button, WebSmart appends your program name to the path specified to generate a complete path similar to this one: This URL will work once you finish creating and generating this program. Step 4: Choose any additional design options. After entering the values at the Program Attributes window, click Next or press Enter to continue with your design. Here are the additional design options for this template: Type your name. Change to 5. Check this option. Figure 4-3. Additional Design Options for the SQL Page at a Time template. At the window above, type your name (to be added to the program comments) and change the Number of Records per Page to 5. Also check the Provide Filter Fields option. Then click Next. Chapter 4 - Building Your First Program with WebSmart PHP 61

62 Step 5: Select your file maintenance options. The next step is to set the file maintenance options: Figure 4-4. File Maintenance Options for the SQL Page at a Time template. Though this program template is by default designed to support Add, Change, Delete and Display options, you can choose which features you want to include in each program you create. For this example, just accept the defaults. Click Next to continue. Step 6: Add the first file. The next step is to select the file (or files) used by your program. When you first get to the Files listing WebSmart assumes that you want to add a new file and prompts you to do that. The file we want to work with is MU_CUSTF in library XL_WEBDEMO, our Customer Master file. Add this file, as shown below: Figure 4-5. The Add File prompt. 62 Section II - Getting Started

63 When you click on the OK button or press Enter WebSmart first checks to see if the file already exists in your PC repository. If the file isn t found, WebSmart downloads the file layout from the iseries (you may be prompted to sign on to your server to do this). For this example program we are only going to use a single file. So after adding the file, click the OK button to confirm your choice, then click Next to continue with the field selection process. Step 7: Skip the Calculated Fields step. Before choosing the fields to include on your pages, the wizard gives you the opportunity to create any calculated fields you may need. For now, click Next to advance to the Field Selection for List window. Step 8: Choose the fields for the Record List page. This is the prompt to select fields for your list page: Figure 4-6. Selecting the fields to display in the record list. To select a field, you can double click on it from the list at left (labeled Available Fields), or click on the field, then on the first button (>) between the lists. For this example, we ll use the following fields: Customer Name Customer Number Address 1 City Chapter 4 - Building Your First Program with WebSmart PHP 63

64 State/Prov Country Contact Name Customer Since If you need to change the order of the fields you selected, you can click on the field (in the window at right, labelled Selected Fields), then on the up or down arrow buttons to move them. Note that you can Ctl+Click to pick more than one field at a time before moving them. Step 9: Choose the fields for the single record display page. After you pick the fields for the record list, click Next to choose the fields for the Single Record Display. The set of fields you choose below is displayed on a new page when the user clicks the Display, Change, Add or Delete options in this program: Figure 4-7. Selecting the fields for the Single Record Display page. Use the >> button to add all the fields from MU_CUSTF to the Single Record Display page and click Next>. 64 Section II - Getting Started

65 Step 10: Select the Fields to Filter by Remember that at the Additional Design Options prompt you checked the option to provide the user with filtering fields above the record list. Because you selected this option, the wizard presents a third field selection prompt: Figure 4-8. Selecting the fields to filter by. Choose the Customer Name, Customer Number and City fields. Step 11: Finish up. Finally, click the Finish button to conclude the pre-design steps and present the WebSmart Integrated Development Environment (IDE). Chapter 4 - Building Your First Program with WebSmart PHP 65

66 The WebSmart IDE The WebSmart IDE is where you work on your programs. Here is an illustration of the IDE as it appears after completing the steps outlined above: Figure 4-9. The WebSmart IDE upon completion of the wizard steps. WebSmart IDE Window Panes Your PHP and HTML code is displayed in tabs in the main window on the right. You can open multiple definitions (and other files) in the IDE, and your open files are shown in the top row of tabs above the window. We ll discuss the features of this window in more detail below. On the upper left are tabs listing the fields in each of the files you have chosen followed by a tab listing the variables used in this program. Following that are tabs for each set of PHP functions available. You can use the scroll right/left buttons to move between tabs, or right-click the tabs to display a list to select from. The window at the bottom left displays your FTP sites and a few other tabs with information that varies depending on what content you re working with in the main window. We ll also discuss this window in more detail later in this chapter. 66 Section II - Getting Started

67 WebSmart Design Modes You can work with your definition using the IDE in the following modes (use the toolbar icons or View menu options to switch between these): In the Default Mode (shown above) your PHP code is displayed in the first tab of the main window and the remaining tabs display your HTML code, split into segments. You can use F12 to switch between your PHP and HTML segments. In Vertical HTML Mode your HTML segments are grouped together vertically using the relationships defined in your preview definitions (more on this below). In this view you ll see a tab for each preview definition, and grey segment dividers within each of those sections. Finally, you can also work with your HTML in Visual HTML Mode, which lets you work with a more graphical view of your pages. Visual HTML editors make the HTML design process simpler because you only have to have minimal HTML knowledge. However, because all visual HTML editors make certain assumptions about the generated code, many programmers with some knowledge of HTML usually prefer to work with the HTML code directly. Step 12: Save your definition and generate your program. The program you are building should work without any further modifications, so go ahead and click the generate button: Figure The Generate toolbar icon. When you do this, WebSmart first prompts you to save the definition. The definition name defaults to the program name, with an extension of.phw. You can save the definition in any folder on your PC). At this point, if you haven t yet established a connection to the iseries, WebSmart prompts you to sign on prior to generating the source code for your program. Use your iseries User ID and Password. Step 13: Launch the definition. Once WebSmart has finished generating and compiling your program, it will attempt to launch it automatically. If it doesn t (this is a setting in your preferences) click the 'Launch' button (the rocket) in the toolbar to see the fruits of your labor so far. Chapter 4 - Building Your First Program with WebSmart PHP 67

68 Below is an illustration of what your program should look like at this point: Figure The generated PHP program Congratulations! You are now an accomplished PHP application designer! If your program didn t run when you launched it, here are a few things to check: Do you have the right IP address for your iseries? Is the port number there? If you entered the wrong value for the web path to object, you may need to manually correct the URL for your program. Is your HTTP server configured correctly? If you want to check this yourself, review the section Installation and Configuration Troubleshooting Suggestions on page 39 of Chapter 2. PHP is an interpreted language, so if there s a problem generating your page, you ll see it when you attempt to run it. You can configure the PHP engine to show errors by editing php.ini (usually found at \\usr\local\zend\core\etc\ on your IFS), and setting the following: display_errors = On. Read the note preceding this in the php.ini file, as there are security considerations to take into account when turning this setting on. If you can t spot the problem give our Technical Support team a call at (250) [7:30-5:00 PST], and we ll get you up and running! In the next sections you will continue by reviewing some of the key components of the definition we have created, and then we ll make a couple of changes to the program. 68 Section II - Getting Started

69 Part 2 - Understanding the HTML Technically speaking, HTML stands for Hyper-Text Markup Language, an encoding system to define the structure of a World Wide Web document. For our purposes, it s enough that you understand that the HTML simply controls how your web page looks. Working with HTML Segments WebSmart PHP definitions group your HTML code into one or more segments. A segment is a term we use to identify blocks of HTML that perform a distinct function, and logically belong together. For further discussion on the advantages of using HTML segments, please refer to the section Separating Code from Content on page 50 of Chapter 3. The definition you have just created has several HTML segments, including these: The list page header (named ListHeader), which appears only once on your list page, above the list of records. The list details that includes each record (named ListDetails) to be loaded to the page. This segment is repeated several times in the list page, and the number of iterations can vary depending on how many records per page you are displaying, and whether the user positions the list to within the last few records of the file. A segment named ListFooter, displayed after the last list record. This contains the HTML required to close the list that was started in the ListHeader segment. The page footer (PageFooter) segment is used at the bottom of all the pages in your program. By separating this from the ListFooter, it makes it easier for your pages to share a common look. The single record display (RcdDisplay) handles displaying a single record. In the program, PageFooter is appended to the bottom of this. These examples should give you an initial sense of how segments group together HTML code that has a unique function within the program, which you may want to individually control. In the next sections we will look at some of the most important characteristics of these segments. The segments you see in this program are typical of those you ll work with an any type of WebSmart PHP program, so it s worth taking a few minutes to familiarize yourself with them now, particularly if you haven t worked with HTML before. If you are already comfortable with HTML and understand the concept of segments, you can skip to Step 17 on page 77. For information about individual HTML tags, place your cursor on them and press F1. Chapter 4 - Building Your First Program with WebSmart PHP 69

70 The ListHeader Segment Step 14: Reviewing the content of ListHeader. To start, click on the tab for the ListHeader segment. HTML pages are divided into at least two sections; a head and a body. The HTML for the header portion of your program looks something like this: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " / <html> <head> <meta name="generator" content="websmart" /> <meta http-equiv="pragma" content="no-cache" /> <title>maintain Customer Master File</title> <link rel="stylesheet" type="text/css" href="v7.0/idaho/css/ screen.css" media="screen, tv, projection" /> <link rel="stylesheet" type="text/css" href="v7.0/idaho/css/ print.css" media="print" /> <script language="javascript" type="text/javascript" src="v7.0/javascript/esdiapi010.js"></script> <script type="text/javascript"> xl_attachevent(window, "load", WindowInit); function WindowInit() { xl_focusfirstelement(); } </script> </head> This page begins with a comment line that tells the browser the HTML standard to which this page was designed. You can go to the included URL for additional details. This is an optional statement we include by default in all our templates. The <html> Tag The actual content of your web page is delimited by <html> and </html> tags. The <head> Tags The header section of a web page is delimited by <head> and </head> tags, and its content includes some general attributes, as well as references to components that are not actually displayed in the page itself but affect how the page looks and functions. Meta Tags and Page Cacheing The <meta> element provides metadata such as the document s keywords, description and author. Historically, these have been used to provide guidance to search engine robots, directing them how to process the page. However, due to widespread mis-use, they no longer carry the weight they used to. In a <meta> tag you can also use the http-equiv property to set other attributes. In the example above where we are using one to instruct the browser to not cache the page. We 70 Section II - Getting Started

71 have included this tag in all WebSmart templates because your pages include dynamic content that is continually changing, though the URL may remain the same. When you re surfing the Web, most browsers attempt to save time by checking your page requests to see if they are URLs that have been previously loaded, and if so, may attempt to load a cached version of the page from memory. When you re revisiting pages with static content this usually isn t a problem; however, it s not something you want when loading pages containing dynamically updated data. Because the no-cache meta tag is not universally respected by browsers, in your WebSmart programs we also use a programmatic technique to ensure that pages are always reloaded. As you play around with your program, you ll often see something like this at the end of your URL string: &rnd= This parameter is a random number which changes every time the page is loaded, and we add it to further ensure that your browser doesn t attempt to reload old, cached data. Page Title Following the meta tab is the page title, between <title> and </title> tags. You should include a robust title in all the pages that you build. The title is displayed at the top of the browser window, and is also used by search engines when indexing your page. Cascading Style Sheet(s) This program also references two external style sheets, which govern the appearance of the page when displayed on the screen and when printed. The HTML style sheet is set of specifications that control the appearance of the text and formatting elements (i.e. tables) included in your page. By using a shared external style sheet, you can ensure that all the pages you design have a consistent look and feel. Another important advantage to using style sheets is that you can make changes to the appearance of your programs without having to change and regenerate programs individually. Chapter 4 - Building Your First Program with WebSmart PHP 71

72 HTML Notebook - Heading Tags and Style Sheets Let s use our heading tags as an illustration of how powerful style sheets can be. Using HTML heading tags (<h1> through <h6>) is a simple way to mark the different levels of text headings in your report. Text enclosed within <h1> and </h1> tags is normally displayed in a large, black font. The remaining tags present gradually smaller text. You can easily customize the appearance of these headings with style sheets. For example, this statement: h1,h2,h3,h4,h5 {font-family: Verdana, Arial, Helvetica, sans-serif;color: #A3A3BC;} ensures that headings 1-5 have a common color and use the same font family. You could also add individual lines to control each heading level individually: H1 {font-family:arial; font-size:20pt; color: red; margin-top: 20px;} H2 {font-family:arial; font-size:16pt; color: blue; margin-top: 10px;} H3 {font-family:arial; font-size:12pt} Notice that we also used named colors rather than hex values. Either option works, though of course the hex values support a more complete range of colors. Style sheets are described in the Web Page Design for Green-Screeners chapter of the WebSmart ILE Reference Guide. There are also a couple of different style sheets included in the standard set of HTML snippets shipped with WebSmart (your snippets are in the window at the lower left of the IDE). For further discussion on the advantages of using Cascading Style Sheets, refer to the section Separating the Content from the Layout on page 50 of Chapter 3. You can also read about this topic online. JavaScript Files This definition also includes a reference to one external JavaScript file, esdiapi009.js (the sequence number may be different in your own definition), which encapsulates a set of scripts with various features for your page. 72 Section II - Getting Started

73 The Body Components of the Segment ListHeader Following the </head> tag is the <body> tag marking the start of the page body. This section includes the actual text and images displayed by the browser. In our program, the body tag also includes an onload tag, that positions the cursor to the first relevant page element using JavaScript. Loading the Page Headings with the Style Sheets At the top of the body section of our page are these statements: <div id="headline"> <div id="logo" title="logo"></div> <div id="title">maintain Customer Master File</div> </div> <div id="divider"></div> <div id="contents"> These tags are handy ways to reference divisions in your document, and are usually tied to a style sheet definition of the named division. For example, if we go to this URL: Our browser loads screen.css, the style sheet we re using in our program. In screen.css we can find these statements: #logo { float: left; width: 86px; height: 60px; background-image: url(../images/pagelogo.gif); background-position: left; } #title { padding-top:26px; padding-bottom: 10px; font-size:26px; fontfamily: Georgia, "Times New Roman"; color:#097aba;} #divider { margin-bottom: 10px; } These and others like them govern the appearance of the contents area of our page. By using style sheets to control these elements, you can change all your pages instantly, just by adjusting the CSS file. Chapter 4 - Building Your First Program with WebSmart PHP 73

74 The Position-To Form Below the heading for the page is this simple HTML form: <!-- Table containing filter inputs --> <form action="$pf_scriptname" method="post"> <input type="hidden" name="task" value="filter"> <table class="keys"> <tr> <td>customer Name</td> <td><input type="text" name="cmname_filt" value="$cmname_filt"></td> </tr> <tr> <td>customer Number</td> <td><input type="text" name="cmcust_filt" value="$cmcust_filt"></td> </tr> <tr> <td>city</td> <td><input type="text" name="cmcity_filt" value="$cmcity_filt"></td> </tr> <tr> <td> </td><td><input type="submit" value="filter"></td> </tr> </table> </form> <!-- End table containing filter inputs --> This section of HTML produces this portion of your page: Figure The record list filter fields and form. This form is used to filter the list. In our template we place the form in a table to make it easier to control its location. After the text input box is a Submit button with the text Filter on it. Finally, below the two input tags the template closes the table and form. We ll look at the PHP code in more detail just below, but if you re curious about how the filters are handled in the code, you can press F12 to flip over to your PHP tab, and then search for filter1 through the PHP. 74 Section II - Getting Started

75 List Control Functions Following the position-to field, this program includes three links that are conditionally displayed above the list of records: <div id="listtopcontrol"> <a id="prevlinktop" class="nondisp">previous $ww_listsize</a> <a id="addlink" class="addlink nondisp" href="$pf_scriptname? task=beginmanage&mode=add&rnd=$ww_rnd">add Record</a> <a id="nextlinktop" class="nondisp">next $ww_listsize</a> </div> Depending on the features included in this program, and your position in the file, this area may display Next and Previous links, as well as an option to add new records. Data Headings The form is followed by the headings of the table displaying our data, starting with this HTML: <table class="mainlist"> <tr> <th>action</th> <th width="70"> <a href="$pf_scriptname?ordby=cmcust&rnd=$rnd">customer Number</a> </th> <th width="500"> <a href="$pf_scriptname?ordby=cmname&rnd=$rnd">customer Name</a></th> <th width="500"> <a href="$pf_scriptname?ordby=cmadr1&rnd=$rnd">address 1</a></th> <th width="200"> <a href="$pf_scriptname?ordby=cmcity&rnd=$rnd">city</a></th> <th width="20"> <a href="$pf_scriptname?ordby=cmstate&rnd=$rnd">state/prov</a></th> <th width="20"> <a href="$pf_scriptname?ordby=cmcount&rnd=$rnd">country</a></th> <th width="500"> <a href="$pf_scriptname?ordby=cmcont&rnd=$rnd">contact Name</a></th> <th width="100"> <a href="$pf_scriptname?ordby=cmdacr&rnd=$rnd">customer Since</a> </th> </tr> This HTML (and the sections for each field) generates these table headings: Figure Column headings for the sortable record list. Notice that the field headings are links: this program supports the ability to click on the column-headings to re-sort the list by the selected value. When you click each table heading, the program executes the JavaScript in the href attribute. Chapter 4 - Building Your First Program with WebSmart PHP 75

76 The ListHeader HTML segment is written to the page only once, so it includes only the table headings and not the list entries. Also notice there is no </table> tag in this segment, to end this table. That is included in a subsequent segment. A key component of the table headings is the column widths. When building the columns, the template defaults to allotting 10 pixels for each character. After you run your program once to verify its appearance, you can easily change these widths to better suit your data (and you can also easily adjust the defaults in the templates). The ListDetails Segment Step 15: Click on the ListDetails tab. This segment includes the main body of the table, shown below: <tr class="$pf_altrowclr"> <td><table class="actions"><tr> <td><a href="$pf_scriptname?task=disp&rrn=$ww_rrn&rnd=$ww_rnd"> <img src="/websmart/v7.0/idaho/images/view.gif" alt="display" title="display"> </a></td> <td><a href="$pf_scriptname?task=beginmanage&mode=change&rrn=$ww_rrn &rnd=$ww_rnd"><img src="/websmart/v7.0/idaho/images/edit.gif" alt="edit" title="edit"></a></td> <td><a href="$pf_scriptname?task=delconf&rrn=$ww_rrn"> <img src="/websmart/v7.0/idaho/images/delete.gif" alt="delete" title="delete"></a></td> </tr></table></td> <td class="text">$cmname</td> <td class="textright">$cmcust</td> <td class="text">$cmadr1</td> <td class="text">$cmcity</td> <td class="text">$cmstate</td> <td class="text">$cmcount</td> <td class="text">$cmcont</td> <td class="text">$cmdacr</td> </tr> In our running program, this section is repeated 5 times for each page (recall how we set this in the wizard dialog) and includes the actual fields we selected at the pre-design dialog. If you look at this section carefully, you can see that it is actually a single table row (as delimited by the <tr> and </tr> tags), with one cell for each field. Notice the first line above, which opens the table row. This row has been assigned a style sheet class corresponding to the variable $pf_altrowclr. This is the alternate row color, and its value is controlled programmatically at run time. The first column in the table also includes the icons for displaying or working with the selected records. Notice that these links all use the variable $pf_scriptname to set the first part of the URL for the Display, Change and Delete functions. 76 Section II - Getting Started

77 The ListFooter, PageFooter, ListPrev and ListNext Segments The ListFooter segment closes the record list table, and includes a div that controls whether the ListPrev and ListNext segments are displayed. The ListPrev and ListNext segments are only output when there are more records or a previous page to view. Recall that a segment is simply a collection of HTML that logically belongs together, so separating the ListPrev HTML and the ListNext HTML allows us to easily control whether they appear each time the page is loaded. Finally, the PageFooter segment ends the page. The RcdDisplay Segment Step 16: Click on the RcdDisplay segment tab. The main list portion of your program includes a Display icon down the left of the table. When you click on this link, the program loads the RcdList segment. If you show the details for a record and then peruse this section of HTML, you can see that it includes the standard page headers and footers, and a table including all the fields we have selected. The RcdDisplay segment also includes this interesting bit: <div id="navtop"> <?php if ($_REQUEST["task"] == "disp") wrtseg("rtntolist"); else if ($_REQUEST['task'] == "delconf") wrtseg('delchoice');?> </div> This particular bit is there so we can use this record display segment both as a straight display and also a delete confirmation page. Working with the Record List Fields If you flip back to the browser window where your program was loaded, you can see that some columns are wider than necessary for the data they contain. In the ListHeader segment, the <th> tags have a width attribute which is calculated based on the field size. By default, the field size is multiplied by 10 to arrive at a width in pixels. For example, because the Customer Name field (CMNAME) is 50 characters, the width attribute of the <th> tag is set to 500 pixels. If in fact the Customer Name contains 50 contiguous characters, 500 pixels is a reasonably accurate estimation of the screen real estate required to display this field. But with our data, that s not usually the case. Step 17: Adjusting Column Widths. In our example file most of the Customer Names are much shorter than 50 characters. So go to the ListHeader segment in the IDE and reduce the width of this column to 200. Do the same for the Address Line 1 and Contact Name fields. Chapter 4 - Building Your First Program with WebSmart PHP 77

78 Then regenerate the program to see how this has changed the appearance of your page. These column should now be narrower, allowing the rest of the data to be more evenly distributed across the page. Step 18: Adding a New Field Now let s try adding another field to the list. To start, we need to add a new column in the ListHeader segment. So go there now, and find the Country column (field CMCOUNT). Copy the line used to display that heading, and then paste those lines immediately below the Country headings. Then change the field name to CMPOST, and the text heading to Postal Code. When you finish these changes, that part of your HTML should look like this: <th width="20"><a href="$pf_scriptname?ordby=cmcount&rnd=$rnd"> Country</a></th> <th width="20"><a href="$pf_scriptname?ordby=cmpost&rnd=$rnd">postal Code</a></th> Then in the HTML segment named ListDetails, add a new table cell after the cell with the country field: <td>$cmcount</td> <td>$cmpost</td> <td>$cmcont</td> You can type the field name in directly, or place your cursor between the <td> tags and double-click the field entry in the list on the right. Step 19: Updating the PHP. Now you also need to make a couple of small changes to your PHP to get the field value. In the WebSmart IDE, toggle over to your PHP code tab and find this statement: wrtseg('listdetails'); To the section above it (prefaced with the comment Get the fields ), add this line: $CMPOST = $row['cmpost']; It should be the third to last entry. Then look in your list of functions in the bottom left of the IDE and find the function bldselstr. Double-click this entry to position the main window display to the start of that function. Find this line: $ww_selstring = 'SELECT RRN(MU_CUSTF), MU_CUSTF.CMCUST, MU_CUSTF.CMNAME, MU_CUSTF.CMADR1, MU_CUSTF.CMCITY, MU_CUSTF.CMSTATE, MU_CUSTF.CMCOUNT, MU_CUSTF.CMPOST, MU_CUSTF.CMCONT, MU_CUSTF.CMDACR FROM XL_WEBDEMO/MU_CUSTF'; 78 Section II - Getting Started

79 You need to add the Postal Code field to this line. Just after the "MU_CUSTF.CMCOUNT," add the following: "MU_CUSTF.CMPOST,". Step 20: Generate your program. Click the Generate icon to create and run this program. The list now looks like this: Figure The list of customers, with the new fields added only to the HTML. As you can see, we now have a column for the postal code, and you can click the column heading to try sorting the list by that value. Now you can continue with the next section. Chapter 4 - Building Your First Program with WebSmart PHP 79

80 Understanding the PHP Code While the HTML component of your definition determines the look of your pages, the PHP (PHP: Hypertext Preprocessor) is the code that actually makes what you are creating an actual program, and not merely a static page. The PHP controls when each section appears, and the presentation of the data on the page. To view and work with the PHP in your definition, click the PHP tab in the IDE or press F12 from any of your HTML segments. This is how the IDE looks when you re editing your PHP code: Figure The WebSmart IDE displaying the top of your PHP code. Below is an overview of the PHP code generated by this template. As with the HTML, the code generated by any template is representative of the style of coding you ll find in the other templates. So the general characteristics of the code that we ll point out in this program are also relevant (particularly) to other SQL PHP programs. Inserted Generation Time Code You ll notice that the first 4 lines of your code are protected. When you run a PHP program, any errors encountered are reported with line numbers. Because WebSmart inserts 4 lines of additional code at the top of the program when you generate your PHP from this definition, we protect these lines to ensure that the line numbers reported when you run the program match the line numbers in the IDE. 80 Section II - Getting Started

81 Those 4 lines of inserted code look like this (the last line below is wrapped): <?php internal_init(); // Make all global variables available locally foreach($globals as $arraykey=>$arrayvalue){if($arraykey[0]!='_' && $arraykey!="globals")global $$arraykey;} As you can see from the comment, the purpose of this little code snippet is to enable a technique for supporting global variables [which is not in the nature of PHP, where all variables are always local]. In your PHP, fairly near the top, look for this: global $db2conn; $db2conn = xl_db2_connect($options); This is an example of how a variable is set to be global, and a value assigned to it. And if you scan through the functions in this program, you ll notice they all begin like this: function display() { // Make all global variables available here foreach($globals as $arraykey=>$arrayvalue) { if($arraykey[0]!='_' && $arraykey!= "GLOBALS") global $$arraykey; } This is the part of the process that pulls in those global variables for each function. Program Comments Going back to the top of your code, the protected section is followed by some default comments generated by the template, along with some of your program attributes. We recommend that you also use this area to document any program modifications. Program Functions At the bottom left of the IDE is a list of the functions in this program. This is a reasonably full-featured program, so you ll see a dozen or so entries. You should be able to decipher their purpose without to much difficulty. Here are a few of them: Function beginmanage bldpage display Description This function initiates the process of adding or changing a record. This is the function that pulls together the pieces to create your record list page. Notice the wrtseg statements in this function, and the code around the wrtsegs. This function puts together the logic controlling which records will be displayed in the list. Chapter 4 - Building Your First Program with WebSmart PHP 81

82 Function disprcd endmanage filter Description The disprcd function is executed when you click the Display link next to a record in the list, to display details for an individual entry. This function is used to process a new or changed record. This function handles your filtering logic. Above these functions is your mainline code that sets up your global variables and determines which program function needs to be executed. If you like, spend a few minutes scanning through the PHP to try and get a sense of how this program works. For information on the individual PHP functions, place your cursor on them and press F1. If you are unfamiliar with PHP, the section How Should I Get Started? on page 23 of Chapter 1 includes some suggestions of good online resources, or you can search for your own. The wrtseg Function One difference between the way we structure the code in WebSmart PHP and how it s sometimes written by hand is the use of HTML segments. As we have noted earlier in this tutorial, your definition includes several HTML segments. These are written to the browser as blocks, using the wrtseg function, which is unique to WebSmart. Step 21: Search for wrtseg in your PHP. The first occurrence of wrtseg in this program is near the top of the display function: // Output the page and list header wrtseg('listheader'); If you re curious to know how this works, you can find the generated PHP for this program at your FTP site connection for this server. Your FTP sites are shown in a tab in the window pane at the lower left. Open your site and look for the file custmaint.php. Then double-click the file to open it. 82 Section II - Getting Started

83 When you open that file in the WebSmart IDE and click on the Functions tab (next to your FTP Sites) you ll see that your program includes a wrtseg function, where your HTML segments are collected together to be written to the page on demand: Conclusion Figure The wrtseg function in custlist.php (the program generated by WebSmart). The top arrow is indicating the IDE tab in which your generated PHP is shown. The arrow on the bottom left is showing where we have double-clicked the wrtseg function, to position to that spot in our code. Finally, the middle arrow is indicating the line of code that controls the printing of the ListHeader segment. If you like, you can spend some more time here familiarizing yourself with the generated code for this Customer Maintenance program. This concludes our overview of the process of using WebSmart PHP to create a program. To continue, we suggest that you experiment with the other templates, and try making other types of changes to your program. Chapter 4 - Building Your First Program with WebSmart PHP 83

84 84 Section II - Getting Started

85 Section III - WebSmart IDE Reference SECTION III WebSmart IDE Reference In this Section: Chapter 5 - IDE Wizards: Definition Creation Options Chapter 6 - IDE General Reference: Common Design Functions Chapter 7 - Using the HTML Design Tools Chapter 8 - Using the PML and PHP Coding Tools Chapter 9 - WebSmart Program and Configuration Defaults

86

87 5 - IDE Wizards: Definition Creation Options IDE Wizards: Definition Creation Options C HAPTER 5 In the tutorial section of this guide you learned how to use the WebSmart Integrated Development Environment (IDE) to create WebSmart applications. This section describes each of the main areas of the design tool, beginning in this chapter with the decision of which template you need to use to perform a particular function and the options presented by the pre-design Wizard as you first build a definition. Below is an illustration of the WebSmart IDE when you first launch the software: Figure 5-1. The WebSmart IDE. The WebSmart IDE has three main windows: The window on the right is the main area in which you ll work with your definition s HTML and PHP, as well as any other files you may open (JavaScript,

88 style sheets, templates, etc). When you open the file repository, files are also listed in this window. In the upper left you will generally see a list of files and fields and functions you can use in your code. Finally, the contents of the area on the bottom left includes your FTP connections, and some additional tabs which change depending on whether you re working with your HTML, PHP, JavaScript or another type of file. This area contains tools such as code snippets and a list of functions. The content of the status bar depends on your cursor location. When you re coding your PHP, the status bar displays function prototypes. If you are browsing the Most Recently Used (MRU) list, the status bar displays the full file paths for your recently used files. Most menu options are only available when you re working with a definition. But here is a quick overview of the functions you can perform when you first launch WebSmart: Create or Open Definitions To open a new definition, select the File/Open menu option, or click the toolbar icon. You can also select a definition from the MRU (Most Recently Used) list. Change your IDE View Options Under the View menu are options for hiding/displaying different parts of the window (such as the files and functions lists), as well as the toolbars and status bar. Set Your Program Defaults From the Tools/Options menu you can work with many of your configuration options and software defaults. From the Tools menu you can also work with the file repository. Note that the repository is populated as you create and work with programs; you don t need to preload it, unless you want to create repository extensions. Work with the Repository Before starting on a definition, you can pre-load your repository with any files to which you want to add repository extensions. Help Menu Options From the Help menu you can access PDF versions of the documentation, test your connection to the iseries, and link to the WebSmart home page. All these options are discussed in more detail in the following chapters. The next sections walk through the process of creating a new definition from scratch. 88 Section III - WebSmart IDE Reference

89 Creating New Definitions and Choosing your Template To create a new WebSmart definition select the New option from the File menu or click on the first icon at the left of the toolbar. When you do this, the WebSmart design wizard starts by prompting you to choose a template as the basis of your design. Here is an example of the window presented: Figure 5-2. The WebSmart New Program window (IDE File/New option). This is a list of the default templates stored in the "Templates v7.0" subdirectory of the WebSmart installation directory. A template serves as a starting point for your program design and includes a set of pre-built functions and HTML segments. There are also templates for creating simple HTML pages, Cascading Style Sheets, and programs to establish JDBC connections to other databases. You can also click the Browse button to use templates that you or other programmers at your site may have created and saved in another location. All WebSmart template files have an extension of tpl. Later in this guide you can also learn how to create your own templates, or customize the sets shipped with the product. Selecting a Template Use the preview information to find on a template that will create the type of program you need. Then double-click it to use it as the basis of your new design. You can also select the template by clicking on it and pressing Enter or clicking the Create button. Each of WebSmart ILE, WebSmart PHP and Clover require unique product licenses. Chapter 5 - IDE Wizards: Definition Creation Options 89

90 WebSmart Templates: An Overview The WebSmart development environment is premised on the value of using templates, style sheets, and HTML separated into segments, as a very effective way of helping you create web sites that are both consistent and of a high quality. If you haven t done any reading on this topic, try doing a web search on these themes before you start developing your site. For example, Wikipedia has an article on style sheets in Web development that discusses this, and there are many online articles that address the topics of separating content, layout and logic. There are a few different WebSmart template families. By family, we mean a set sharing a similar look and feel. Within each family, there are several styles of program available for you to choose from. All WebSmart templates include the following features: Streamlined HTML and PHP code so programs load and run efficiently. High quality designs that you can easily merge into existing applications. We have tried to avoid looks that are too distinctive, and therefore difficult to add to your own web site without first having to make wholesale changes to the structure and appearance of your pages. Broad usage of Cascading Style Sheets, making it easy to apply a total face-lift to your programs by changing just a single shared stylesheet. These templates also use a single consolidated JavaScript file which makes it easier to apply functionality changes across many programs. The three template families are available in Clover, WebSmart ILE and WebSmart PHP, making it easy for you to effectively combine various types of program in a single site. Most templates reference two separate style sheets, one for screen and another for print, which allows you to set separate fonts and page margins that are appropriate for the target media. The following sections describe the functionality of each WebSmart template. This information, as well as the prototypes shown from the New Program window, will help you to decide which template best suits your programming objectives. All the illustrations in this section use the Idaho template family so you can more easily distinguish the functional differences between styles. For additional discussion of some of the salient features in each style, also review the wizard options available for each program style, in the section entitled Additional Design Options on page Section III - WebSmart IDE Reference

91 Overview of the Main Template Categories Here is an overview of the distinctions between each of the main template groups you ll see in the New Program window. ILE, PHP and Clover Templates Use the ILE and PHP templates to create programs to display and work with data. As a general rule, the ILE and PHP templates that share a name and family are designed to create programs that also work the same way. Where this isn t possible, due to unique features of either the ILE or PHP environments, this is noted. Clover is used primarily to generate reports, charts and graphs. PHP iseries RLA, iseries SQL & MySQL Templates There are two sets of iseries PHP templates, one coded for Record Level Access and the other uses SQL. Most templates exist in both sets. The PHP Templates set also includes a set of templates that you can use with MySQL. WebSmart Template Families: Idaho, Lincoln & MacLeod Within the ILE, PHP and Clover templates available in WebSmart you ll see three template families named Idaho, Lincoln and MacLeod. These template families provide you with three different looks you can choose from when designing your application. The only functional difference in the programs created is that they reference different style sheets. So if you start an application with Idaho, and then decide that you prefer the appearance of the Lincoln family, you can switch over with a quick Find/Replace. The New Programs window includes illustrations of all the program types you can build with each of these three families. The ODBC Connection Required During the Design Process Accessing MS SQL Server Databases with the JDBC Templates WebSmart does not support MS SQL Server The following data types *are* supported: int, char, nchar, nvarchar, float, smalldatetime, datetime. Other data types may not be supported. While the JDBC templates allow you to create programs that at runtime use a JDBC connection to work with the MsSQL or MySQL database, during the design process the WebSmart wizard and IDE require an ODBC database connection in order to retrieve your file layouts. If you haven t yet created this connection, the wizard will prompt you to do so from the Program Attributes dialog. You can also set up your connection from the Tools/Options menu. This is described in the section Working with ODBC Connections (Other Databases) on page 224 of Chapter 9. Chapter 5 - IDE Wizards: Definition Creation Options 91

92 Descriptions of the WebSmart Program Templates The following pages include an illustrated overview of the template styles you can create with WebSmart. A Simple Page Template Use this template as a starting point for creating a simple program where you will add all the logic yourself, or when none of the other templates suit your needs and it s easier to code your program starting from scratch than adapt one of the other styles. This template requires no files, and by default generates a page similar to this one: Figure 5-3. A WebSmart program created using the A Simple Page template with no changes. This program consists of a single HTML segment into which you can insert any content you like. The default code in this program does nothing but write the HTML to the page. You can then add more pages and logic as necessary. The CSS, HTML Page and JavaScript Templates Among the templates available for creating programs are others you can use to help you get started with creating other Web objects to be part of the supporting cast for your WebSmart programs and applications. The CSS Template Use the CSS template to create a new Cascading Style Sheet. For more information about Cascading Style Sheets, visit 92 Section III - WebSmart IDE Reference

93 The HTML Page Template The HTML Page template creates an HTML page that is visually identical to the programs created with the A Simple Page template. This template is useful for situations where you need to create a stand-alone HTML page, rather than a program. The template allows you to build HTML pages within the WebSmart IDE, and then use those pages in your application. These pages can be used on their own, or as server-side includes accessed by other pages or programs. The JavaScript Template Use this template to help you start creating a new JavaScript function. The Input Capable Page at a Time Template This program features an input-capable list where you can modify many records at once. Other than this, the program supports the standard links as well as an optional Add Record link. Here is an illustration of this type of program: Figure 5-4. A program created with the Input Capable Page at a Time list template. In this style of program you can make changes to any number of fields in as many records as appear on the screen before clicking the Update button. The program also includes standard navigational links and forms. Chapter 5 - IDE Wizards: Definition Creation Options 93

94 The Add link is set to add as many records as you specified for your page size. This link is optional. Differences Between the PHP and ILE Versions of this Template In this style of program, the PHP version is built with SQL and the prompt fields at the top of the page filter the list; records that don t match the entered values are excluded from the list. Also, the values you enter aren t cleared when you press Enter or click the Filter button. In the ILE version of this program, the prompt fields position the list, meaning you don t have to enter exact values, and the values are cleared when you press Enter or click the Go to button. 94 Section III - WebSmart IDE Reference

95 The Page at a Time Maintenance Template This template allows you to display, modify and delete individual records in the first file that was chosen at design time. When you first run a program using this template, it presents a list of records. Icons providing display, change and delete functionality are located to the left of each record. Here is an illustration of a program created using this template: Figure 5-5. The record list in a program created with the Page at a Time Maintenance template. The number of records displayed on a single page when the program is run is defined in the wizard, and can be edited in the code of the program definition. By default, 20 records are displayed per page. The "next page" and "previous page" links allow you to page through the records in the primary file. Differences Between the PHP and ILE Versions of this Template In this style of program, the PHP version is built with SQL and the prompt fields at the top of the page filter the list; records that don t match the entered values are excluded from the list. Also, the values you enter aren t cleared when you press Enter or click the Filter button. Adding a filter to your PHP program is optional in the wizard step. In the ILE version of this program, the prompt fields position the list, meaning you don t have to enter exact values, and the values are cleared when you press Enter or click the Go to button. Chapter 5 - IDE Wizards: Definition Creation Options 95

96 The Page at a Time Maint SQL Server 2000 Templates This template employs a different programmatic technique, required to support scrolling lists in Microsoft s SQL Server Displaying Records When you click the button to display a record, the program presents a page similar to the one illustrated below, except that the fields are read-only. Deleting Records When you click the delete icon, the program presents a page similar to the Display page, prompting you to confirm the deletion of the record. When you delete the record, it is removed from the file. Changing and Adding Records When you add or edit a record the program presents a page similar to this one: Figure 5-6. The single record display, in a Page at a Time Maintenance program. This page is also created automatically by the template. In your template you can easily change the appearance of individual fields, and in the wizard you can choose which fields to include on both this page and the list. 96 Section III - WebSmart IDE Reference

97 The Record Listing Template The record listing template displays a list of all the records in a file. Here is an illustration of a program created using this template: Figure 5-7. An unrestricted record list. This template produces a read-only record list and does not provide the ability to display, modify or delete records. The Record Listing Template Lists ALL the Records! Unlike other list templates, this one is not set up for page at a time processing, so you should take some care when using it. If you are testing WebSmart and repeatedly running a record listing program over a file with a few million records, you may find yourself the focus of some unexpected attention. Chapter 5 - IDE Wizards: Definition Creation Options 97

98 The Single Record Maintenance Template This template includes the ability to add, display, change and delete records. In the initial wizard design process you can select which of these functions you want the program to be able to perform. This program supports two record retrieval methods: By Relative Record Number. Programmatically, this is the simplest option to use and works well if you are coming to this program from another where you have access to the RRN. This method is necessary if your file includes records with duplicate keys. By Key. This option can be a little more complicated programmatically, but is suitable for cases when the user is entering part or all of the key to retrieve the record. This method is necessary if you are accessing a non-iseries database, where the RRN is meaningless. Here is an illustration of this type of program, about to add a record: Figure 5-8. The page generated for making changes to a record. This page displays all the fields in the file as input boxes, enabling you to make and process changes. Note that this program will not run unless you provide a valid task parameter, and criteria (either key or rrn) to identify a record. For example, to change a record, your URL will look something like this: 98 Section III - WebSmart IDE Reference

99 Defining the Program Attributes After you select which template you want to use the design wizard presents the Program Attributes dialog. The program attributes for ILE and PHP definition have a few different options. Below is an illustration of both windows, with the program attributes for PHP templates superimposed on the attributes for ILE DB2 templates (ILE JDBC templates include a few more options not illustrated here): Figure 5-9. The Program Attributes prompts for ILE DB2 and PHP definitions. You can change any of the values you set here from the Attributes/Program menu in the IDE. You can also set default values for these options from the Tools/Options menu. Program Name Type the name of your generated program. For ILE CGI programs, this name defaults to upper case, and is limited to 10 characters. When you create a PHP program an extension of.php is automatically appended. The PHP program name can be up to 123 characters long. It s a good idea that when you save your definition file you include the program object name as at least part of the definition name. Though this isn t a requirement, it will help you down the road by simplifying the process of matching definitions (stored on the PC) to programs (stored on the iseries). Chapter 5 - IDE Wizards: Definition Creation Options 99

100 When you launch a program from the IDE, this program name (with an extension of.pgm or.php) is appended to the Web Path to Object, to execute your program. Program Library (ILE) Type the name of the iseries library where this object will be created. Title Type a text description of this program. This description is also used as the page title in the HTML portion of your definition. Source File & Library (ILE) Select the ILE RPG source file name and library for your program source. Library List Object When you execute your program, it will likely attempt to open files in various libraries. However, the job that runs the program will not likely have an initial library list which includes your data libraries. As a result, the program needs to set its own library list when it begins to execute. You can have it do this by specifying a library list object which contains all the libraries that you need. The default option is *FILES, to have the program automatically determine which libraries to have in the library list based on the location of the files used within the definition. Use the Refresh button if you have just created a new library list to use with this program and don t yet see it in the list. The option you select for your library list has implications for how you will handle the process of migrating your definitions from development to production environments. When you select *FILES WebSmart automatically builds a library list for your program at run time, based on the libraries of the files used in your definition. This is the simplest option to choose to quickly build your definition. However, if you are building your definition over files in a development environment, with test files in test libraries, specifying *FILES means that you will need to change the library references for all your files and regenerate and recompile your program before migrating to production. Named library lists are defined on the iseries, using the command EWRKLIBL, in library XL_WEBLIB. This command is described in the WebSmart ILE User Guide. Named library lists allow you to explicitly control which libraries are in the jobs library list at run time. This option initially takes a little more work, but simplifies the process of migrating your programs from development to production, as you then would only have to change either the library list object name in your definition (rather than all file library references), or the library list object itself on your iseries. One way to simplify the use of named library lists and change management is to use the program field 'pgmf_pgmlib' as the name of the library list in your setlibl call. [You could even make copies of the templates which did this automatically.] Then create a set of 100 Section III - WebSmart IDE Reference

101 library list objects (using EWRKLIBL as mentioned above) with the names of your test and production libraries. Thus, as the program object is moved from the test library to the production library (or QA or any other library you choose to set it up for), the program would automatically switch to using the new library list, without requiring any code changes, and without requiring you to change your file references. If you are using WebSmart Change Management (WCM), the library list object is set to *OBJLIB. This value means that the program is set to use the library list established for the set of definitions within your change management project, and will automatically use a new library list if it is moved to a new library (or set). WebSmart Change Management is described in the WebSmart ILE documentation. Web Path to Object/Web Path for Launching The web path is the URL which can be used to launch your program from the IDE. This is an optional value, only used as a shortcut for launching the program directly from the WebSmart design tool; it has no bearing on the ultimate location or URL of your program. This value should be a combination of your iseries's IP address (or domain name), the port # on which the appropriate Apache HTTP server instance is running, and the location of your program. If your program requires some initial parameters when called, you can also type a full URL here (including the parameters) and WebSmart is smart enough to use it instead of performing its default action of just appending the program name to the path. This is most easily done by completing your program, running it once with the required parameters, then copying that URL back here in this field. As an example of this feature, if you are creating an ILE program named MYPGM in the library MYLIB, your web path may look like this: This assumes that you have a statement similar to the following in the configuration for the HTTP server instance that is listening on port 8150: ScriptAliasMatch ^/mylib_map/(.*)\.pgm$ /QSYS.LIB/MYLIB.LIB/$1.pgm If you are working with a WebSmart PHP template, the file is saved at the location specified in the Destination FTP Path field, and your HTTP server instance must include mapping to access that file at that location. If your Destination FTP Path is set to: /www/zendcore/htdocs/xl_php/ then you will need to at least open that directory: <Directory /www/zendcore/htdocs> Order Allow,Deny Allow From all </Directory> Chapter 5 - IDE Wizards: Definition Creation Options 101

102 Your Web Path to Object will then look something like: Or if you want to include parameters, like this: Destination FTP Site (PHP) This refers to the server folder where the PHP program will be created. Select the server on which you will be running this program. From here you can also add new sites, or change the configuration for your existing site. The FTP site configuration options are described in the section Create an FTP Connection. on page 35 of Chapter 2, Installation and Configuration. Row Colors 1 & 2 (ILE) Many of the programs you build will display lists of records. When building these tables, most of the WebSmart templates are coded to alternate the background color of each row based on the two values you select here. We recommend you use the defaults for these values (the program fields altcol1 and altcol2 refer to the alternate color values defined in the template). If you change these values you run the risk of creating ugly pages! This feature populates the program field called pgmf_altrowclr with the alternating color codes at run time. To see where it is used, go to the ListDetails segment of an existing WebSmart definition, and look for a line of HTML similar to this one: <tr class=<field name=*pgmflds.pgmf_altrowclr>> The table row is assigned a style sheet class corresponding to the alternate row color value. The program field is loaded with the alternating values each time the segment is loaded. To disable the alternating row colors feature, just replace the field with a constant color value, or remove the class attribute entirely. You could also just specify the same value for the color of both rows. ODBC Connection (PHP MySQL & iseries JDBC Templates) If you are creating a PHP MySQL application, or an iseries application that will connect to another database using a JDBC connection, you need to create and select an ODBC connection to your database so WebSmart can retrieve your file layouts to build the program. For additional information, please refer to the section Working with ODBC Connections (Other Databases) on page 224 of Chapter 9. JDBC Connection Program The WebSmart JDBC templates are designed to reference a single, external program to establish connections. Type the program name and library here. The default value is JCONNPGM, but if you specify a different name, the wizard will remember that for the next programs you create. 102 Section III - WebSmart IDE Reference

103 Additional Design Options After you finish defining the Program Attributes WebSmart presents the Additional Design Options. This window includes a set of options that vary according to the template style you are working with and the functionality supported by the template. When you customize the existing templates or create your own, you can also control the values that this window prompts for. Please refer to the WebSmart ILE Reference Guide for further information. The sections below describe the additional design options available for each template. A Simple Page Template Here is an illustration of the first set of Additional Design Options presented for the Simple Page template: Figure Additional Design Options for the A Simple Page template. Programmer Name The programmer name is included in the default program documentation at the top of your PML. Here is an example of the details added by the wizard: // Program Name: MU_CUSTS // Program Title: Present Customer Snapshot // Created by: Larry Finklestein // Template family: Idaho // Template name: A Simple Page // Purpose: // Program Modifications: The first 5 values are populated by the wizard, the other two are for you to add. Chapter 5 - IDE Wizards: Definition Creation Options 103

104 Include Page Header All the main template families include a page header area where you can put your company logo, etc. The page header is normally included at the top of each page in your definition as follows: <div id="headline"> <div id="logo" title="logo"></div> <div id="title">program Title</div> </div> <div id="divider"></div> If you are using this program within a frames site that includes an area for standard site headings, you should uncheck this option. Input Capable List Page at a Time Template This template creates a program from which you can edit records directly in the initial list screen. The Additional Design Options include the standard options (described in the section A Simple Page Template on page 103) and a few others, shown here: Figure Additional Design Options for the Input Capable Page at a Time List Template. 104 Section III - WebSmart IDE Reference

105 Number of Records Per Page This option is available in all the styles that display lists of records on the main page. Select the number of records that you wish to display per page. This value is assigned to the listsize work field in the code, as shown here: // Set maximum list size to 20 for this program $ww_listsize = 20; The default value is 20. You can easily change this value in the code at any time (then regenerate your program) to adjust the list size. Include Add Link Check this option to include a link at the top of your list to add new records, as well as the additional PHP and HTML segments to support adding records. When you click the link to add new records the program presents a blank page for adding as many new records as set in your list size. Include Delete Option Check this option to include a Delete button next to each record in your list. Provide Filter Fields (PHP) This option is supported in the PHP version of this template, where the program processes the records using SQL. Check this option to include a set of fields to filter the list by, in the header area of your program. A later wizard step prompts you to choose the actual fields. The Page at a Time Maintenance Template When you create a program using the Page at a Time Maintenance template, the wizard prompts you for the standard additional design options (described in the section A Simple Page Template on page 103) and the number of records per page. Number of Records Per Page This option is available in all the styles that display lists of records on the main page. Select the number of records that you wish to display per page. This value is assigned to the listsize work field in the PML, in the Main function, as shown here: // Set maximum list size to 20 for this program $ww_listsize = 20; The default value is 20. You can easily change this value in the code at any time (then regenerate your program) to adjust the list size. Record Listing Template When you create a program using the Record Listing template, the wizard prompts you for the two standard additional design options, described in the section A Simple Page Template on page 103. Chapter 5 - IDE Wizards: Definition Creation Options 105

106 Single Record Maintenance Template When you build a new definition using the Single Record Maintenance template, the wizard prompts you for the standard additional design options (described in the section A Simple Page Template on page 103) and two others, shown below: Figure Additional Design Options for the Single Record Maintenance template. Record Retrieval Method You can choose between two record retrieval methods: Relative Record Number. This option is the simplest to use programmatically, and works well if you are coming to this program from another where you have access to the RRN. It may also be necessary if your file includes records with duplicate keys. Key. This option can be a little more complicated programmatically, but is suitable for cases when the user is entering part or all of the key to retrieve the record. This is also necessary if you are accessing a non-iseries database, where the RRN is meaningless. Choose the method most suited to your application. Target URL after Add/Change/Delete This is the value attached to the redirect function that is executed after the completion of an Add or Change operation. 106 Section III - WebSmart IDE Reference

107 SQL Page at a Time Maint Template If you anticipate using the SQL template to create programs that will be made available to an unrestricted audience, you should review some important security considerations in the section Security and SQL, in the WebSmart ILE Reference Guide. When you build a new definition using the SQL Page at a Time Maintenance template, the wizard prompts you for the standard additional design options (described in the section A Simple Page Template on page 103) and a few others, shown here: Figure Additional Design Options for the SQL Page at a Time Maintenance templates. Number of Records Per Page This option is available in all the styles that display lists of records on the main page. Select the number of records that you wish to display per page. This value is assigned to the listsize work field in the PML, in the Main function, as shown here: // Set maximum list size to 20 for this program $ww_listsize = 20;The default value is 20. You can easily change this value in the code at any time (then regenerate your program) to adjust the list size. Use Smurfs for Program State (ILE Only) Select this option if this program is part of an application using smurfs. This option enables you to choose whether the program state is handled with smurfs, stored as smurfs, or as session-only cookies. If you leave this option unchecked your program will use browser-life cookies instead of smurfs. Chapter 5 - IDE Wizards: Definition Creation Options 107

108 Generally, you should choose cookies to store the SQL program's state. The only situation in which you should choose smurfs is when you have many filtering fields in your SQL program. The reason for this is a technical limitation of many browsers: only 20 cookies can be stored for any given web site. Since each filtering field is stored as a separate entity, you'll rapidly run out of space if you try to use cookies, especially if you have more than one SQL program. Provide Filter Fields This options allows you to select a field or group of fields by which the user can filter the list. These fields are added above the record list. When you check this option, WebSmart prompts you (later in the design process) to select the fields by which you want to allow users to filter the records. Here is an illustration of the window presented to allow you to choose the fields: Figure Filter Field selection in SQL Page at a Time Maintenance templates. This is a version of the standard field selection window, described below in the section Selecting File Fields on page 124. When you are using the PHP SQL Page at a Time Maintenance template, at this step the wizard also displays your select string. 108 Section III - WebSmart IDE Reference

109 In the example above, we have chosen two fields which in the generated program are added above the list, like this: Figure Filter fields in a Page at a Time Maintenance program. Filtering and SQL Injection Attacks The SQL template includes built-in protection against SQL Injection attacks (see the section Security and SQL in the WebSmart ILE User guide for details). Numeric filter fields may contain numeric data only, and alpha filter fields will have the character replaced with the SQL wildcard character _. Include Sortable Columns Select this option if you want your list column headings to be links that reload the page, sorting the data by the column selected. Chapter 5 - IDE Wizards: Definition Creation Options 109

110 Creating Calculated Fields When you use the SQL templates the wizard allows you to create any number of calculated fields before choosing the fields to include in your definition. As the name implies, calculated fields can be simple calculations based on fields in your files (field1 + field2, field1 *.01, etc.). You can also create derived calculated fields using functions such as concat and substring. The list of calculated fields is initially empty. Click Add to create a new field. Defining the Field Attributes When you create a new calculated field, the first step is to define the field attributes: Figure Defining the field attributes for a new calculated field. For this example we are going to calculate the markup for each item in our file. Type the field name and description. You may already be familiar with this interface from Clover, where you need to also enter the field attributes. In that case, the field attributes are required because Clover is generated ILE/RPG code, not PHP programs. Then click Next to continue to step Section III - WebSmart IDE Reference

111 Defining the Field Logic After setting the field attributes, you create the field definition at this window: Figure Defining the formula for a new calculated field. Write your formula in the bottom window. To create it you can use any of your file fields, work and calculated fields, or program fields (in the left column). You can also use the operators shown in the middle column and the functions listed on the right. Files and Fields As building blocks for your calculations you can use database fields, work fields and program fields. These are available from tabs in the upper left of the window. Operators As with the functions (described below), the list of operators displayed above is limited to those most commonly used. If you are familiar with SQL you can use any valid operator or expression, whether it is displayed above or not. The list shown includes these: Operator Description Use single quotes around constants. () Use parenthesis to group ^ Use this symbol to raise values to a power of x. -, *, /,+ The operators shown include the basics for subtraction, multiplication, division and addition. You can use these to calculate values using database fields or constants. Chapter 5 - IDE Wizards: Definition Creation Options 111

112 Functions The functions are described in the next section, below. Formula Validation When you click OK Clover validates your formula on the iseries (you may be prompted to sign in if you haven t yet). If there is a syntax error the message is displayed in the area below the formula. If there are no errors Clover creates the field and returns to the list of calculated fields. Using Functions in Calculated Fields Clover supports numerous functions for creating calculated fields. In the dialog shown above (Figure 5-17) these are grouped in two folders: Advanced and Basic. The Basic folder is initially open, displaying a list of the most commonly used functions. The SQL functions available in the Basic and Advanced folders are not the complete set available. Some functions are quite obscure or difficult to use, so we didn t include them in the lists. However, your formula is validated on the server so you can use any valid SQL function in it. Below is a list of all the functions displayed; you can find additional information and examples of each of these functions in the Scalar Function documentation of the DB2 Universal Database for iseries SQL Reference: rbafzmstscale.htm Basic Functions Here is a list of the basic functions: Function concat date ltrim max min Description Concatenates two strings. Returns a date from a value. Removes blanks or hexadecimal zeros from the beginning of a string expression. Returns the maximum value in a set of values. Note that the scalar min function works differently than the summary min function. So in a normal (non-summary) report, the format of the min function is min(value1, value2, value3,...). Returns the minimum value in a set of values. Note that the scalar max function works differently than the summary max function. So in a normal (non-summary) report, the format of the max function is max(value1, value2, value3,...). 112 Section III - WebSmart IDE Reference

113 Function mod rrn rtrim sqrt substring time timestamp trim upper Description Divides the first argument by the second argument and returns the remainder. Returns the relative record number of a row. Removes blanks or hexadecimal zeroes from the end of a string expression. Returns the square root of a number. Returns a substring of a string. Returns a time from a value. Returns a timestamp from a value or a pair of values. Removes blanks or another specified character from the end or beginning of a string expression. Takes a string value and converts it to all uppercase values. Advanced Functions And here is a list of the advanced functions supported: Function Description absval Returns the absolute value of a number. case The case function is documented below. cast The cast function is documented below. char Returns a string representation of a value. character_length Returns the length of a string expression. coalese Returns the first argument that is not null. curdate Returns a date based on a reading of the time-of-day clock. curtime Returns a time based on a reading of the time-of-day clock. day Returns the day part of a value. dayofmonth Returns the day part of a value. dayofweek Returns an integer that represents the day of the week, where 1 is Sunday and 7 is Saturday. dayofyear Returns an integer that represents the day of the year. days Returns an integer representation of a date. decimal Returns a packed decimal representation of a number. digits Returns a character-string representation of the absolute value of a number. double_precision Return a floating-point representation of a number. float Returns a floating-point representation of a number. floor Returns the largest integer value less than or equal to a numericexpression. hex Returns a hexadecimal representation of a value. Chapter 5 - IDE Wizards: Definition Creation Options 113

114 Function hour ifnull integer left length locate microsecond minute month now nullif position posstr quarter real second smallint strip translate ucase value varchar vargraphic week year zoned Description Returns the hour part of a value. Returns the first argument that is not null. Returns an integer representation of a number. Returns the leftmost characters from the string. Returns the length of a value. Returns the starting position of one string within another string. Returns the microsecond part of a value. Returns the minute part of a value. Returns the month part of a value. Returns a timestamp based on a reading of the time-of-day clock. Returns a null value if the arguments are equal, otherwise it returns the value of the first argument. Return the starting position of one string within another string. Return the starting position of one string within another string. Returns an integer that represents the quarter of the year in which the date resides. Returns a single-precision floating-point representation of a number. Returns the seconds part of a value. Returns a small integer representation of a number. Removes blanks or another specified character from the end or beginning of a string expression. Translates one or more characters in a string. Returns a string in which all the characters have been converted to uppercase characters. Returns the first argument that is not null. Returns a character-string representative of a value. Returns a graphic string representation of a string expression. Returns an integer that represents the week of the year. The week starts with Sunday. Returns the year part of a value. Returns a zoned decimal representation of a number. 114 Section III - WebSmart IDE Reference

115 The CASE Field Function The CASE function is a special function used to return a single value based on a series of tests. The syntax is: CASE (search clause simple when) ELSE (NULL expression) END Search clause: WHEN search-condition THEN NULL expression Simple when: expression WHEN expression THEN NULL expression With a simple WHEN condition you specify an expression and each WHEN clause is compared against the expression. When a match is found, the value specified after the THEN clause is returned. With a search clause you specify the test conditions within the WHEN clause. When the result is true, the value specified in the THEN clause is returned. Below are a couple of examples using the CASE function. CASE DEPTFLAG WHEN '1' THEN 'Operations' WHEN '2' THEN 'Network Administration' WHEN '3' THEN 'Programming' ELSE 'Unknown' END CASE WHEN DEPTFLAG = '1' THEN 'Operations' WHEN DEPTFLAG = '2' THEN 'Network Administration' WHEN DEPTFLAG = '3' THEN 'Programming' WHEN '4' THEN 'Security' ELSE 'Unknown' END SELECT * FROM EMPLOYEE WHERE (CASE WHEN SALARY = 0 THEN NULL ELSE SALARY + COMM$ END) > The CAST Field Function The CAST function is used to change the attribute of a field during execution of the SQL statement. The syntax is: CAST expression AS data-type NUL You can change numeric to character, character to numeric, characters to dates, dates to characters, and so on. The CAST function does not change the original database field definition. The list of valid data types includes: INTEGER, INT, SMALLINT, FLOAT, REAL, DOUBLE PRECISION, DOUBLE, DECIMAL, DEC, NUMERIC, CHARACTER, CHAR, VARCHAR, CHARACTER VARYING, CHAR VARYING, LONG VARCHAR, GRAPHIC, VARGRAPHIC, GRAPHIC VARYING, LONG VARGRAPHIC, DATE, TIME, TIMESTAMP. Chapter 5 - IDE Wizards: Definition Creation Options 115

116 File Maintenance Options These template styles allow you to add, change and delete records: The Page at a Time Maintenance template The Single Record Maintenance template The SQL Page at a Time Maintenance template When you create a program using any of these templates, after selecting your additional design options the wizard prompts you to choose your File Maintenance Options. Here is an illustration of the window presented when you build a program using the templates listed above: Figure The File Maintenance Options wizard prompt (file maintenance program styles). Allow Record Addition Uncheck this option to not include a Create button in your program (for the list styles), nor the supporting PML code and HTML segments (in all styles). Protect Key Fields on Add Check this option if you are pre-setting the key fields for new records programmatically or passing them from another program, and you wish to block the key fields from being changed in this program when new records are added. 116 Section III - WebSmart IDE Reference

117 Allow Display of Full Record By default the templates include a display option. Uncheck this option to not include a Display button in your program (in the list style templates), nor the supporting PML code and HTML segments (in any of the styles, including the single record maintenance). The wizard design process is smart enough to skip steps rendered unnecessary by the options you select here. For example, if here you do not choose to allow display of the full records, the wizard will not prompt you later on for the fields to be included on the single-record display. Allow Record Change The template includes the ability to change existing records. Uncheck this option to not include a Change button nor the relevant PML code and HTML segments. Protect Key Fields on Change Check this option if you wish to block the key fields from being changed (by making them display-only) when a user changes a record. Allow Record Deletion Uncheck this option if you don t want this program to include a Delete button, nor the HTML and PML code to support this functionality. Chapter 5 - IDE Wizards: Definition Creation Options 117

118 Selecting the Files and Fields for your Program After setting your additional design and file maintenance options you need to select your files. When you first arrive at the Files window during the wizard steps, WebSmart immediately prompts you to add a new file to your definition (the Add/Change File window is described below). Most definitions require that you use at least one file in your program. You can add or delete other files from the IDE by selecting the Files... option from the Attributes menu. WebSmart templates do not support non-keyed files. Here is the Wizard Files window, after adding one file: Figure The wizard s list of files currently added to the definition. The next sections describe the options available here. 118 Section III - WebSmart IDE Reference

119 Adding New Files When you first arrive at the Files window WebSmart automatically prompts you to add a new file to your definition. To add more files to your definition, click on the Add... button to the right of the file list. When you do this, WebSmart presents this dialog: Figure Adding a new file to a definition. File Name/Library First you need to choose a the file name and library. This can be done a few different ways: By typing the file name and library. When you do this and click OK (or press Enter), WebSmart first checks to see if the file already exists in the repository on your PC. If not, the wizard may prompt you to sign on to your iseries (if you have not previously done so in your current design session) so it can download the file layout to your local repository. By selecting the file from a list on the iseries. Click on the Server button to load a list of files from a selected library on the iseries and choose one from the list. By selecting the file from the PC repository. Click on the Repository button to select a file from the list stored in the repository on your PC. The second and third options are described further on below. When you open an existing definition and one or more of the files it uses are no longer found, WebSmart allows you to search for the file in a different location, to replace the missing one(s). Record Format (ILE Only) Type the record format name. External Structure Use Only (ILE Only) This checkbox indicates that the file is being added to the definition solely for use in an external data structure definition (through the use of the crtextstruct function, described in the section crtextstruct on page 156 of Chapter 2 of the Reference Guide). By checking this box, the generator will ignore this file. If this checkbox is checked, and the Chapter 5 - IDE Wizards: Definition Creation Options 119

120 file is used for record level access, then the compile will likely fail. The tool will attempt to warn you when you define record level access functions which refer to files which have this option selected. The main reason for using this checkbox is to improve the performance of the generated program by avoiding an extra file open operation at runtime. Alias (PHP SQL Only) The file alias is a name by which you want to refer to your file instead of the file name. For example, if your Customer Master file name is something relatively meaningless such as CHK43DD, you could define an alias of Customer for use in your SQL. When you give a file an alias, it is referred to by this name everywhere in your SQL and the IDE. The file itself is not affected in anyway, this is simply a design feature. Browsing the iseries for Files In addition to keying in a file name and library manually, you can also browse your iseries for a file to use. When you click on the Server... button to browse the iseries, WebSmart presents a dialog similar to this one: Figure Selecting a file from a list on the server. Loading a List of Files The window above is initially empty. To load a list of files, type a library name in the Select Library option at the top of the window and click the Load button. Once you ve used a library it appears as an option in the list to be selected. Selecting a File To choose a file to include in your definition, wait until the list loads and then select the file from the list. Click OK or press Enter to return to the Files window. 120 Section III - WebSmart IDE Reference

121 Displaying File Fields After WebSmart has loaded a set of files, you can review file fields by selecting a file and then clicking the Fields button at the bottom of the window. When you do this, WebSmart presents a fields list in a separate window, illustrated below in Figure Viewing File Data At the bottom of the Server Files window is a View Data button, which presents an interface from which you can review file data. This is described below in the section Viewing File Data on page 123. Selecting a File from the Repository WebSmart also allows you to add a file to your definition from your local repository. To do this, click on the Browse Repository... button (Figure 5-20). When you click this button, a window similar to this one is presented: Figure Selecting a file from the local PC repository. If the file you need is already in your repository, you can double-click on it to select it. If it isn t there yet, you ll need to add the file manually at the Add Files window. Because file layouts are stored on your PC, you can work on your WebSmart programs without having to have an actual connection to the iseries - for example, on a laptop during a long flight. The only steps you would not be able to execute are the generation, compile and execution of the programs. However, the powerful Preview functions can Chapter 5 - IDE Wizards: Definition Creation Options 121

122 give you a good idea of how your program will look and work. For additional details on the WebSmart repository, please refer to the section Working with the File Repository on page 152 of Chapter 6. Reviewing File Fields To review the fields in file you have already selected, first double-click the file entry and then at the Add/Change window select the Review Fields option. When you select this option, WebSmart presents a window similar to this one: Figure Reviewing the fields in a selected file. Click OK or Cancel to exit. Changing Selected Files To change a file you are currently using in your definition, double click on the file from your list, or select it and click on the Edit button. From the dialog presented you can change the library and/or record format name or review the file fields. You can also switch to a different file. If you switch from one file to another (typically to change library references) at any time after the Wizard has completed the preliminary definition design, WebSmart will not automatically update all field references in your definition. You will need to go through your definition (particularly the HTML) and update any incorrect field references manually. 122 Section III - WebSmart IDE Reference

123 Deleting a File from the Definition To delete a file you have already selected for your definition, click on the file in the list, and then on the Delete button to the right (Figure 5-19). Synchronizing your Files Viewing File Data Your definition includes a view of your file layouts. If the layout of a file has changed on the iseries, you can select the file in your list, then click this button to update your definition with the current file layout. You can also review the data in a file using WebSmart s SQL utility (described in detail in the section SQL Prototyping on page 246 of Chapter 12 of the WebSmart ILE User Guide). To do this, select a file then click on the View Data (see Figure 5-21) or File Contents buttons (see Figure 5-19). Here is an illustration of this window: Figure Using the SQL utility to review file data. Chapter 5 - IDE Wizards: Definition Creation Options 123

124 Selecting File Fields If you are creating a new program using a template designed to list and/or edit records, the last Wizard steps are to select the fields to display in your pages. Some templates present more pages than others, so the number of field selection prompts will vary accordingly. WebSmart uses the fields you select here to build the initial set of PML and HTML code for your program. Here is an illustration of the Field Selection window for creating the list page in a Page at a Time Maintenance program: Figure Selecting file fields to include in the record list. In this example we have added three files to our definition, MU_CUSTF, MU_CNTRYPF and MU_DSCNT. These files are shown as tabs on the left of the window, and we can select fields from any of the three lists. On the right you can see that we have selected six fields from the Customer file, one from the Country file and another from the Discount Codes file. The list shows the field names, descriptions and attributes. When you select fields from multiple files, you may need to confirm that the necessary code exists to retrieve the extra records. This is not always handled automatically by the template. To include a field in your record listing, select it from the list at left, then click on the first button between the windows (the > symbol). You can also just double-click on a field to move it from one side to the other. Click on the >> button to include all the fields from 124 Section III - WebSmart IDE Reference

125 your file in a segment. To adjust the order of the fields you have selected, click on the field that you want to move, then use the up and down arrow buttons to change its position. The < and << buttons can be used to unselect a specific field, or all fields. Selecting Fields for Each Template Page Some templates include both pages that list many records and pages for working with individual records. Typically, the list would include a concise selection of fields for each record and on the maintenance or details pages you would include most fields in the file. Here is the field selection prompt for the Single Record Display page: Figure Selecting file fields for the single record display. From this window you can select the fields that you wish to include in the single record display. In the illustration above, we have pressed the >> button to include all the fields in the Customer file, and then added a few more fields from other files. Chapter 5 - IDE Wizards: Definition Creation Options 125

126 The WebSmart IDE Below is an illustration of the WebSmart IDE after the wizard steps have been completed: Figure The WebSmart IDE after completing the wizard steps. You now have a definition that will generate a complete working program, without having to write a single line of code HTML, PHP or even RPG. You can click on the compile button (the deconstructed yellow cube) to compile and launch your program. When you do this, WebSmart first prompts you to save your definition, then it begins the compile. Usually you will find that you want to modify the initial design produced by the Wizards. The next chapters of this guide describe how to customize the appearance and functions of your definition using the Integrated Development Environment. 126 Section III - WebSmart IDE Reference

127 6 - IDE General Reference: Common Design Functions C HAPTER 6 IDE General Reference: Common Design Functions The WebSmart IDE (Integrated Development Environment) is where you work on your definitions. This chapter describes the IDE functions, such as the toolbar and menus, that are consistent regardless of the components you are currently working on (PML, PHP, HTML, JavaScript, templates, etc.). The following chapters describe IDE features that change when you switch between PHP, PML or HTML modes. Chapter 9 explains how to change your WebSmart program defaults and set up more complex development environments for working with multiple systems, FTP sites and ODBC connections. Here is an illustration of the WebSmart IDE, where we currently have open both PHP and ILE definitions, as well as JavaScript and CSS files: Figure 6-1. The WebSmart IDE, with several files open.

128 The IDE Layout The large area on the right is your main design window. This is where you edit the HTML, PML or PHP for your definition, as well as any of the other text files that are part of your definition (JavaScript, templates or style sheets, for example). On left are the design assistant windows; the contents of these can vary depending on what you re working on in the main window. Using the Tabbed Interface The main window of the WebSmart IDE typically includes two rows of tabs. The top row corresponds to the files you have open, while the second row includes the code or HTML segments for the selected definition. For other file types (JavaScripts, CSS, templates, etc.) the second row of tabs is not displayed. Moving Between Open Files To select a different file, you must click on the tab in the top row. Closing and Saving Open Files When you right-click one of the tabs in the top row WebSmart presents three options, allowing you to close the file, save it, or save it with a new name. Moving Between Segments and Views You can use CTL+Tab to quickly cycle through the tabs of your selected definition. You can also press F12 to jump back and forth between the HTML and the PML or PHP. WebSmart will remember where your cursor was in both locations. You can also right-click any tab in this row to present a list of segments you can jump to. Changing the Default IDE Layout The WebSmart IDE supports various ways for you to re-organize the layout of your window. The illustration above (Figure 6-1) shows the default IDE layout, but you can move things around to better suit your needs. Adjusting the Size of the Window Panes Note that the borders between the three main areas shown above are movable: if you want to expand or contract any of the windows above, just click on the border between them, and drag it in the direction you want. Move the Toolbars, Fields and Functions Windows You can also tear away your toolbars as well as the fields, snippets and functions windows and move them around in the IDE. This is useful if you have lots of screen realestate and want to maximize your visible editing area, or simply want to change the locations of the different elements. 128 Section III - WebSmart IDE Reference

129 Working with the Main Window Many of the features available for working with your code in the main IDE window are discussed in the following chapters. The sections immediately below describe features that are common to working in the HTML, PML and PHP. Setting Bookmarks in Your Code A useful feature of the main window is the ability to put bookmarks in your code. This gives you a quick and easy way to jump between marked sections of your code. To add a bookmark in your code, go to the line that you want to bookmark and press Ctl + [any number from 0 to 9]. Then, to return to that spot, you can press Alt + [the selected number]. Here is an illustration of the IDE with a number bookmarks set in the PML: Bookmarks Figure 6-2. Two bookmarks in the PML code. You can set up to 10 bookmarks in your code. Setting Unnumbered Bookmarks Another (possibly easier) way to use bookmarks is to just a series of unnumbered bookmarks. To do this, just press Ctl+F2 to set your bookmark, and then press F2 to return to it later on. If you set multiple bookmarks, F2 cycles between them all. You can also use Ctl+F2 to clear each bookmark. Chapter 6 - IDE General Reference: Common Design Functions 129

130 Using the WebSmart IDE to Edit Other Files (JavaScript, Style Sheets, etc.) As your program design skills grow, you ll find yourself needing to work with a variety of files types that complement your base HTML and PML code. These can include JavaScript, Cascading Style Sheets, the WebSmart program templates, and others. Fortunately, you don t have to resort to opening each of these in separate windows, you can edit all these files directly in the IDE. The next sections describe how to do this. External File Tab Right-Click Options When you have opened other files in the IDE, these are accessible from tabs along the top of the main window. The tabs for the additional files have three right-click options: to close, save and save your file as a new name. Editing JavaScript Files in the IDE You d be hard pressed these days to find a sophisticated website that doesn t use JavaScript in one way or another. So we anticipate that as you use WebSmart to build programs for your internal and external web sites, you too will eventually be creating and editing JavaScript files. To edit a JavaScript file in the IDE just click the Open button in the IDE, and locate your JavaScript, CSS and HTML files. In the example below we are looking at the set of JavaScript files in the /websmart/ folder on the IFS: Figure 6-3. Browsing for a JavaScript file to edit in the IDE. 130 Section III - WebSmart IDE Reference

131 To view this list we just navigated our system to find the files we wanted. When you select a JavaScript, it opens in the IDE as shown here: Figure 6-4. Editing a JavaScript file in the WebSmart IDE. The file is displayed in a new tab. The script is fully color coded, making it easy to read. Also, in the window on the bottom left of the IDE is a list of the functions in this script, where the one we are currently working on is highlighted. This list of functions helps you to navigate the code, which can at times be lengthy. Editing WebSmart Templates in the IDE In addition to the other file types that you can work with in the WebSmart IDE, it also easy to edit your WebSmart templates. Chapter 6 - IDE General Reference: Common Design Functions 131

132 In this illustration we have opened the Record Listing template in the IDE: Figure 6-5. Editing a WebSmart template in the IDE. As you can see, the template is also color coded to make it easier to read and edit. At the top of the main window you can see that we have 5 tabs now: two program definitions, a javascript file, a style sheet and a template. You can open multiple files in a single instance of the IDE, enabling you to work on your template alongside the other key components of the definition. When you ve finished making your template changes, just click on the Save button to save. Chapter 10 of the WebSmart ILE Reference Guide, Working with Templates and SmartSnippets, describes the template structure and syntax and how to make changes to the templates shipped with the software. 132 Section III - WebSmart IDE Reference

133 The Fields and Functions Window The window that is by default located in upper left of your design screen displays the following information: The fields in each of your files. Any variables in your definition. A list of PML or PHP functions. The various lists of fields and functions are organized with tabs. The first tab on the left corresponds to the first database file you added to the definition. This is followed by the rest of your files, and your variables. Finally, there are tabs for your different sets of PML or PHP functions (depending on the type of definition you re working on). Below is an illustration of this window, widened to show more of the content: Figure 6-6. Fields window tabs when working with an ILE definition. In a PHP definition you will see a slightly different set of default tabs, and a much lengthier set of Function tabs. Use the scroll bar at the bottom of the window (not shown above, because the window has been made wide) to display additional information about the fields displayed. You can also click on the list headings for the field names and descriptions to re-sort the list by those values. Navigating Between Tabs Click on the tabs at the top of the window to bring a list of fields to the front. When the window is narrow, there are arrows at the upper right of the window to allow you to move between files and to the functions at the far right. You can also right-click anywhere over the tabs to select an entry to jump to. Chapter 6 - IDE General Reference: Common Design Functions 133

134 Placing Fields in PHP Definitions When you need to use a field in the PHP or HTML code of a PHP definition, you can also type the field name by hand or place it using the fields window. Placing Fields in the HTML Add fields to your HTML by placing your cursor where you want to insert a field then finding it in the window and double-clicking on it. Alternatively, you can left-click and drag & drop the field into your HTML directly. Here is an illustration of how a field gets added when you use either of these techniques: $CCNAME To place a field in your HTML as input capable, right-click/drag & drop it at the spot where you want to place it. Here is an example of the HTML inserted when you do this: <input type="text" name="ccname" size="75" maxlength="75" value="$ccname"> Notice that the input name attribute is the same as the field name. This is generally the best way to set up your inputs. Placing Fields in the PHP Code To insert a field name in your PHP, find the field in the list and double-click it. When you do this, the field is added at the spot where your cursor is currently positioned in the PHP. You can also drag and drop fields from the list to your PML. Additional features of the fields window that are specific to working in the PML are described in the section Using the Functions List Pane on page 205 of Chapter 8, Using the PML and PHP Coding Tools. 134 Section III - WebSmart IDE Reference

135 The Functions and Snippets Window The window in the bottom left of the IDE always displays your FTP connections in the first tab [see Create an FTP Connection. on page 35 of Chapter 2]. Then, depending on the type of file you are working with, it can also include one or more additional tabs: If you are working in your PML or PHP code, it shows the user functions that have been defined, your PML or PHP snippets, and the program notes. If you are working with the HTML, it shows the list of available HTML snippets and the program notes. If you are working on a JavaScript file, it will display the functions in the script, the PML snippets and your program notes. If the main window is showing a style sheet or template file, no additional tabs are shown. Each of these views is described below. Working with PML, PHP and JavaScript Functions When you are working with PML, PHP or JavaScript code in the main window, the window displays Functions, Snippets and Program Information: Figure 6-7. A list of the functions in the code displayed in the main window. The function you are currently working on is shown in bold in the list. Double-click on any of these functions to go to that spot in your main window. This window is more fully described in the section Using the Functions List Pane on page 205 of Chapter 8. The other two tabs shown above, Snippets and Info, are also described in Chapter 8. Working with HTML, PML and PHP Snippets This window also includes a tab displaying a list of what we call 'snippets'. Snippets are chunks of HTML, PML or PHP code (either shipped with the product or created by you) that you may want to use frequently, without having to retype them each time. They could also be JavaScript, XML, WML, HDML etc. fragments. Chapter 6 - IDE General Reference: Common Design Functions 135

136 Here is an illustration of the snippets window, showing HTML snippets: Figure 6-8. The HTML snippets window. Snippets are also useful as templates for building new sections of code where you may not be completely familiar with the syntax involved. For example, by dropping the snippet for a new HTML table onto your page, you can see the syntax for each of the tags, and experiment with different attributes, beginning from a basic table that works. To use a snippet, simply drag it from the snippets list window over to the desired location in your code, or place your cursor in the code and double-click the snippet. To change or delete an existing snippet, right-click on it and select the appropriate option. Create new snippets by right clicking anywhere in the snippets window and selecting the Add option. Editing Snippets When you add or change a snippet WebSmart presents a window like this one: Figure 6-9. Editing a PHP snippet from the WebSmart IDE. In this example we are editing the default WebSmart PHP Decrypt Data snippet. If you intend to create a new snippet using HTML, PML or PHP that currently exists in your definition, copy the section first (Ctl+C), then create the snippet. Once you are in the Add window, you can t get back to your code without cancelling out of the Add. 136 Section III - WebSmart IDE Reference

137 PHP and PML SmartSnippets WebSmart also ships with a number of PHP and PML SmartSnippets. These are effectively a next-generation approach to snippets where instead of constructing the snippet as a static chunk of code, the snippet prompts you for one or more required values before adding the code to your program. The snippet itself is created using the same structure as the templates, and you can both edit existing SmartSnippets and create your own. SmartSnippets are listed in the IDE along with the standard variety. The only difference is that when you attempt to add one to your page WebSmart begins by prompting you for a series of parameters, rather than just adding the static code to your PML or PHP. Example 1: PHP Program Call SmartSnippet It takes quite a few lines of code to construct a call to an RPG program from a PHP program, and WebSmart PHP includes a snippet with a framework of required code from the beginning. But there is also a smart program call, and when you add this one to your code WebSmart first prompts you for the program to call: Figure Entering the name of the called program (WebSmart PHP SmartSnippet). This SmartSnippet is designed to present two prompts: one where you can enter the program name and library, and a second optional prompt where you can enter the parameters for the program call. Chapter 6 - IDE General Reference: Common Design Functions 137

138 After we enter the values shown above and click Next, the SmartSnippet presents this second prompt: Figure A SmartSnippet program call parameters prompt. In the illustration above we have added three parameters. When we click the Finish button, WebSmart adds the code to our program. This SmartSnippet inserts some 70 lines of code, so we won t include it all here. But here are the first couple of sections: /********** Step 1: set up parameter list description ************/ /* Create an array that specifies the name of */ /* the input, the IO being performed, the variable */ /* type, and the variable name. */ $description = array( array( "Name"=>"company", "IO"=>I5_IN, "Type"=>I5_TYPE_PACKED, "Length"=>"6" ), array( "Name"=>"customer", "IO"=>I5_IN, "Type"=>I5_TYPE_PACKED, "Length"=>"6" ), array( "Name"=>"ordernbr", "IO"=>I5_IN, "Type"=>I5_TYPE_PACKED, "Length"=>"9" ), ); 138 Section III - WebSmart IDE Reference

139 /********** Step 2: prepare the program for calling **************/ $pgm = i5_program_prepare("xl_webapps/invdtls", $description); // Check if any errors occurred. if (!$pgm) die("i5_program_prepare"); In a standard snippet you d have to code all the parameters by hand, both here and two more times further down in the code. And if you were coding the entire call by hand you would probably have to do some research the first time, and a lot of hand-editing every other time you copied your original code for the call. Example 2: The Generate Smurf ID SmartSnippet Another of the SmartSnippets shipped with the software adds a gensmurfid function to your program. This function has a half-dozen parameters which aren t always easy to remember. The SmartSnippet displays a dialog with parameter descriptions and dropdowns listing the various options available. Here is an illustration of the window presented when you execute the Generate Smurf ID SmartSnippet: Figure The gensmurfid SmartSnippet prompt. When you click Finish here, WebSmart adds this line of code to your program: gensmurfid("*ifnone", "*WAS", 7, "*YES", "*BROWSER", "*YES"); As you can see, it s considerably easier than trying to guess the meaning of all the tooltips for each function parameter, were you to enter the function manually. Chapter 6 - IDE General Reference: Common Design Functions 139

140 Editing and Creating SmartSnippets As mentioned above, you can also edit the SmartSnippets we ship or create your own. Unlike standard snippets, where the snippet contains exactly what is added to your code, SmartSnippets are structure more like your program templates. Here is a section from the code for the SmartSnippet in Example 2: PDF='MAIN' { PANELS='*' { PANEL='1' { TYPE='FLAT'; TITLE='Enter gensmurfid parameters'; CONTROLS='*' { CONTROL='U_OPTLABEL' { TYPE='LABEL'; X='24'; Y='20'; WIDTH='170'; HEIGHT='40'; Text='Creation option: (*IFNONE = only gen smurf ID if pgmf_smurfid is blank)'; } CONTROL='U_OPT' { TYPE='DROPLIST'; X='228'; Y='16'; WIDTH='150'; HEIGHT='22'; VALUE='*IFNONE'; VALUE='*NEW'; SELECTED='0'; } The code above includes the header framework for the snippet and the first text label and field. You can see that the structure is relatively simple, and that by cloning existing snippets, you ll be able to easily create your own. The first CONTROL block creates the label, and specifies the dimensions and location. The second block creates a dropdown list with two values to choose from: *IFNONE and *NEW. 140 Section III - WebSmart IDE Reference

141 Following the text and field definitions is this last section: SHELL='*' { CODE='1' { TYPE='ONETIME'; SEG='1' { KEY='PDF=MAIN,BODY'; VALUE='gensmurfid("&U_OPT#", "&U_DUR#", &U_LIFE#, "&U_EXTEND#", "&U_PERSIST#", "&U_ENCRYPT#");'; } } } } This part creates the gensmurfid PML statement, replacing the variables in the string with the values selected from the controls. For further details on how to code these, review the other SmartSnippets shipped with the software. For details on the syntax of the tree structure illustrated above, please refer to Chapter 10, Working with Templates and SmartSnippets. Chapter 6 - IDE General Reference: Common Design Functions 141

142 WebSmart IDE Menu Options: Overview This chapter describes the features and functions accessible from most of the menu options in the IDE. Some options access powerful features that deserve separate sections of their own, so these are documented elsewhere in this guide: WebSmart Change Management (WCM) and the Manage menu options are described in Chapter 14 of the WebSmart ILE Reference Guide. The Tools menu includes options for setting program defaults and working with more advanced functions. Program defaults (the Options entry) are discussed in Chapter 9, WebSmart Program and Configuration Defaults. The remaining options are discussed in more detail in the sections below. The File Menu The options below are available from the File menu at any time during the design process. Because most of these are standard Windows functions, they are only described briefly. To select any of these options, click on 'File', then position your mouse to the option and click once. New. Select this option to create a new WebSmart program definition. The keyboard shortcut for this option is to press the Control key (Ctl) and then the letter 'N'. You can also click on the first icon in the toolbar (the blank page). Open. Use the Open option to select an existing definition, to review it or make changes. The keyboard shortcut for this option is Ctl + O. You can also click on the second icon in the toolbar (the folder). New Window [New/Open]. Select this option to open a new WebSmart window. You can also choose whether the new Window should prompt you to create a new definition or open an existing one. Close. Select the close option to end your design session with a specific definition or open file. If you have made any changes to the file since it was last saved, WebSmart will prompt you to save the changes. Save. The Save option saves any pending changes to the selected file. If the open file is an unsaved program definition, WebSmart prompts you for the name and 142 Section III - WebSmart IDE Reference

143 directory to which to save the file. The keyboard shortcut for this option is Ctl + S. You can also click on the diskette icon on the toolbar. Save as. The Save As option allows you to save an existing definition to a new name. Use this option when you have made changes to a definition and don't want to overwrite the original, or as a way to copy a definition. Close All. Use this option to close all the open files in the IDE. Generate. Select this option to generate the source code for your definition. If you have not yet saved your changes, it will first prompt you to do so. You can also click on the Generate button in the toolbar (next to the print icon) to execute this option, or press F6. Launch. The Launch option is used to test your definition without the need to manually open your browser and key in the URL. In order for this option to work, you need to have entered the correct path to the program on your iseries. You can edit the path from the Program Attributes dialog. You can find more information about this option in the section Web Path to Object/Web Path for Launching on page 101. You can also press F5 to launch your program. Print. You can use this to print the contents of a selected PML, PHP or HTML segment. You can also print using the Print icon in the toolbar. Exit. This will close the WebSmart application entirely. The MRU Files List If you are using WebSmart Change Management (WCM), you may have other options here. For details see the section Enable Menu Options for Mixed Change Management Environment (For Each Server) on page 221 of Chapter 9. At the bottom of the File menu, above the Exit option, is a Most Recently Used (MRU) list of the last 9 files you have worked with in the IDE. Use this list as a shortcut for continuing to work on files and definitions that you recently had open. If you are displaying the status bar below the main window, it shows the full path information for the MRU files as you browse the list. The MRU list also identifies definitions from the WCM environment with a [wcm] tag to the right. Chapter 6 - IDE General Reference: Common Design Functions 143

144 The Edit Menu As with the File menu, the available editing options are standard to most Windows applications, so we do not describe them here in detail. The exception is the Find option, which merits some additional comments. The Edit menu options include the following: Undo. Use this to 'undo' your changes. The keyboard shortcut for this option is Ctl + Z. The steps you can undo are retained until you close the definition. Cut. Cut allows you to move the highlighted contents of a field or section of your HTML or PML to the clipboard, removing it from its current location. You can then use the Paste option to place the information somewhere else. The keyboard shortcut for this operation is Ctl + X. Or you can also click on the scissors button in the toolbar. Copy. Use this option to copy the highlighted contents of a field or section of your HTML or PML to the clipboard, in preparation for pasting it somewhere else. The keyboard shortcut for this option is Ctl + C. You can also click on the button with the two pages in the toolbar. Paste. This 'pastes' the contents of your clipboard to the current cursor location. The keyboard shortcut for this option is Ctl + V. The toolbar button of a clipboard and page executes this option also. Find. Use the find option to locate (and optionally replace) a snippet of text in your HTML or PML source code. This will search from the current cursor position forward. The keyboard shortcut for the Find option is Ctl + F. Select All. This option selects the entire contents of the main (HTML or PML) window. The keyboard shortcut for this option is Ctl + A. Using the Find and Replace Options To find a text string in your HTML or PML, type CTL + F, or select the Find... option from the Edit menu. Below is an illustration of the window presented: Figure The Find & Replace window. Use this option to find (and optionally, replace) a section of text in one or more of your open files. The options available above are standard to most PC applications, so we won t explain them here in detail. 144 Section III - WebSmart IDE Reference

145 When you initiate a search in a definition, it begins by searching the segment you are currently in (PHP, PML or HTML) beginning from your cursor location. After it has completed searching the current segment, you can continue with the next: Figure Option to continue searching the next definition tab. If you are searching another open file (JavaScript, style sheet, WebSmart template, etc.) once it gets to the bottom of your code, it searches from your cursor to the end of the file, then goes back to the top of the file. You can adjust a number of defaults relating to how this works from the Tools/Options dialog, on the Confirmations tab: Figure Confirmation options related to the Find & Replace. These options are described in more detail in the section Find Options on page 215 of Chapter 9. Chapter 6 - IDE General Reference: Common Design Functions 145

146 The Attributes Menu The Attributes menu allows you to work with different settings for your definition, ranging from the program name to the HTML segments in your program. When you select any of these, they are presented in a common dialog with tabs for each of the other attribute types listed below. Program Attributes The program attributes include the name, title, web path for launching, and other general attributes. These vary slightly depending on whether you are working on an ILE or a PHP definition. These options are described in the section Defining the Program Attributes on page 99 of Chapter 5. Files Select this option to add new files, or work with those you have already defined to this definition. From this option you can also synchronize your local repository with the current file layouts on the iseries. The options available for working with your files have also been described in the section Selecting the Files and Fields for your Program on page 118 of Chapter 5. Segments Segments are sections of your HTML that are written to the web browser at a specific time by the PML or PHP source code. The creation and management of your segments is described in detail in Chapter 7, Using the HTML Design Tools. Previews Previews are a way for you to verify the result of your changes to your HTML without having to regenerated and recompile your program. They are discussed in the next section. 146 Section III - WebSmart IDE Reference

147 Previews HTML previews are used for grouping together sets of HTML segments that are displayed together on the page. These previews are used for two purposes: to determine how to display your HTML in vertical mode, and to speed up the process of proofing your HTML. The vertical HTML view is discussed on page 195 of Chapter 7. Using Previews to Proof your HTML When designing web programs, a high proportion of design time tends to be spent finetuning the appearance (i.e. the HTML) of the page. You will frequently find yourself making small changes to the page layout and wanting to immediately see the results of those changes in a browser. However, to actually run your programs in a browser, you not only have to be connected to the server, you also have to save, generate and (in an ILE environment)) compile your program. To make the design process more efficient WebSmart allows you to use HTML previews. This feature was added to WebSmart at its inception several years ago. Since then, most people s connection, generation and compile speeds have radically shifted upwards. So you may in fact prefer to just regenerate your definition and view the actual program in a browser (with real data). With PHP particularly, the generation process takes only a second or two longer than viewing a preview. To work with Previews, select the eponymous option from the Attributes menu, to display this window tab: Figure The list of HTML previews in a definition (Attributes/Previews). This window lists the previews currently defined in your definition. All WebSmart templates include one or more previews to display all the default HTML segments. Chapter 6 - IDE General Reference: Common Design Functions 147

148 Adding, Changing and Deleting Preview Definitions To add, change or delete a preview definition use the buttons on the right. Viewing a Preview From the List To view a Preview, first select it in the list and then click the View Preview button. When you do this WebSmart opens a window of your system s default browser and renders a preview of the page. Viewing Previews Directly from the IDE You can also select the preview directly from the drop-down list at the top right of the IDE window: Figure Selecting a preview from the IDE toolbar dropdown list. Here we are about to select the Display preview, and afterwards we will click the button to the left of the list to view it. There is also a shortcut available to intelligently preview your current HTML segment while working in the IDE: press Shift-F5. When you do this, the IDE attempts to find a preview which contains the current segment and, if it finds one, show it. If the IDE doesn t find a matching preview definition, it just previews the current segment on its own. Filling in the Blanks Because the preview does not actually access any iseries data to build the page, it displays 9s for numeric data, and a text string beginning with Lorem ipsum dolor sit amet... to represent alphameric data. Other place-holders are included for variables and include files that cannot be retrieved. When previewing segments, WebSmart attempts to display more accurate previews by adjusting the paths to images, stylesheets and JavaScript using the Web Path to Object value from the Program Attributes. If WebSmart can t resolve to your images, they are represented by the placeholder image used by whatever browser is rendering the page. For example, Internet Explorer shows a red X inside a square. 148 Section III - WebSmart IDE Reference

149 Working with Preview Definitions Below is an illustration of the panel presented when editing a Preview: Figure Working with the HTML segments in a preview definition. On the left is a list of the HTML segments that exist in this definition. To include a segment in your preview, click on it to select it, then on the > button to move it to the list of selected segments at right (or double-click it). The example above shows the default Main List preview, which includes 7 separate segments. Repeat Count The repeat count value allows you to more accurately represent list-style pages, by selecting one or more segments to be repeated a specified number of times in the preview. In the example above the ListDetails segment has a repeat value of 10, so the preview resembles a page displaying 10 records. Debugging Options The debugging options are discussed in the User Guide, in the sections The WebSmart Interactive Debugger on page 340 and Using EWRKDBG with WebSmart Programs on page 346 of Chapter 18. Chapter 6 - IDE General Reference: Common Design Functions 149

150 The View Menu The View menu allows you to select which of the WebSmart design tools and window components you want to see in the IDE. From the View menu, you can also select the option to work with your file repository and add repository extensions. The repository view is described in the next section below, and repository extensions are described in Chapter 11 of the WebSmart ILE Reference Guide, File Repository Extensions. The default view settings will generally work best for you, however you can use the available options to show or hide the following IDE features: Toolbar. This is the toolbar normally shown at the top of your design window, and including the icons for saving, cutting and pasting, generating and launching, switching between HTML and PML views, etc. Systems Toolbar. This toolbar includes a list of systems and environments you can connect to and work in. HTML Toolbar. The toolbar used to invoke the HTML wizards. These are described in the section HTML Wizards on page 173 of Chapter 7. Debug Toolbar. The debug toolbar options are discussed in the section The WebSmart Interactive Debugger on page 340 of Chapter 18 of the WebSmart ILE User Guide. Files and Functions. Use this option to display/hide the files and functions window. Utility Tabs. These are the tabs normally visible in the bottom left of your IDE window, including your FTP sites, PML or PHP functions and snippets, HTML snippets and program information. Status Bar. The status bar shows the parameters for the PML functions you are working with. PML/PHP. Check this option to display the PML or PHP in the main IDE window. This can be accomplished more easily by clicking the appropriate tab for your definition, using the button in your tool bar, or pressing F12 to toggle from a current HTML segment. HTML Tab View. Choose this option to display the HTML tab view. Again, this is more easily accomplished by pressing F12 or clicking on the HTML button in the toolbar. HTML Vertical View. Choose this option to display the vertical HTML view. You can also switch to the vertical HTML view using the toolbar button. HTML Visual View. Selects the Visual HTML design tool view for your HTML. This is more easily done using the toolbar buttons. 150 Section III - WebSmart IDE Reference

151 Repository. Work with the files in your repository. The repository is discussed in the next section below. Preview. Present the currently selected preview. While you can do this from the View menu, the main tool bar shows a drop down list of the available previews and you will generally find it easier to select and execute your previews from there. You can also press Shift+F5 to present a smart-preview, where WebSmart automatically displays the best preview incorporating the segment you are currently working with. Previews are described above on page 147. Chapter 6 - IDE General Reference: Common Design Functions 151

152 Working with the File Repository Each PC on which WebSmart is installed has a unique file repository, usually consisting of entries for each database file in each definition that the PC s user has worked with. To display your repository, select the View/Repository option or click on the repository icon in the WebSmart tool bar. You can also use the repository when you re adding files to your definition. In that case, the interface is slightly different. This is described in the section Selecting a File from the Repository on page 121 of Chapter 5. The repository is also discussed in detail in Chapter 11 of the ILE Reference Guide, File Repository Extensions. Below is an illustration of the WebSmart IDE displaying the repository: Figure The WebSmart file repository (on your PC). The main window displays a list of all the files in your local repository, grouped by library. You can use the scroll bar scan through the list, or use the Page Up and Page Down buttons on your keyboard (after clicking in the window). There are two drop down lists above the window, where you can select the database to work with and your development platform. For example, you can have a view of your PHP DB2 repository, or an ILE view of the same database. 152 Section III - WebSmart IDE Reference

153 Repository Options The iseries DB2 Repository In this repository the folders represent iseries libraries. To view/hide the files in a specific library, click on the + or - symbol to the left of the folder. The entries within the folders are your files. To view/hide the fields in a file, click on the + or - symbol to the left of the file name. The MySQL Repository In this view, the folders represent your MySql databases, and the tables you have defined. The options for working with your files, fields and libraries are available from the rightclick menu. These options are described below. Insert File Select the Insert File option to download file information from the selected database to the repository on your PC, and add an entry to your list. When working in with a DB2 database, WebSmart prompts you for the file and library in this window: Figure Importing a file to the DB2 repository When click OK here, if you are not currently connected to your server, WebSmart will prompt you to log on. Files are also added to the repository automatically as you use them. So unless you plan ahead of time to work on a new project offline, you shouldn t often have to use the import option. This option is useful if you are going to be working on an application later on without having access to your database; for example, on a laptop while you re on the road. By loading your repository beforehand, and with the assistance of the preview options, it is possible to work on your application without having to generate your source code and compile your program. Synch All The repository stores the layout of the database files on your PC. Over time it is possible that the layouts of your files will change. Use this option to update the layout of each file in your PC repository with the current layout on the server. If you do not periodically synchronize your files, you may inadvertently start designing a program using an outdated file layout. Even if you have not synchronized a file, WebSmart advises you at generation time that file layouts may not match, and you can synchronize the file at that time. So in general, you don't have to worry about executing this option on a regular basis. You will normally Chapter 6 - IDE General Reference: Common Design Functions 153

154 only use this option if you know that many of your file layouts have changed and you want to pre-empt the generation message, or specifically include new fields in your programs. If you have many files in your repository and/or a slow connection, this option may take some time to run. Synch This menu option is available when you have selected an individual file in the repository. Use this option to synchronize the layout of an individual file against the layout on the iseries. See the 'Synch All' section above for a description of what synchronization accomplishes. Add Extension To use this option first click on the + sign next to a file to display the fields, then rightclick a field and select the Add Extension option. When you do this, WebSmart presents the Edit Extension dialog. Local and global file extensions are described in detail in of the WebSmart ILE Reference Guide File Repository Extensions. Global extensions are supported only in ILE. Change Extension To use the Change Extension option, you must first display the fields for a file, then click on the + sign next to a field that already has a repository extension associated with it. The list will then display all the extensions currently attached to the field. Right-click on the one you wish to change. When you do this, the Edit Extension dialog is presented, and you can make changes to the current field definition. The Edit Extension dialog, and field extensions in general, are also described in Chapter 11 of the WebSmart ILE Reference Guide, File Repository Extensions. Copy & Paste Use these options to copy a repository extension or set of extensions from one field to another. To copy all the extensions from a field, select the field and then right click to select the copy option. To copy a single extension, expand the list of field extensions and right-click only the one you need to copy. Expand All Click on a file and select this option to view all field extensions. Remove To remove either a file from your local repository or an extension from a file, select the object and choose this option. 154 Section III - WebSmart IDE Reference

155 An example of when you might want to remove files from your PC repository is if they reference temporary libraries where the files no longer exist on the iseries. Properties This option displays field properties, including the file and field names, the field length and text description, and the key properties (where appropriate). Repository Import Features A useful feature of the repository is that it converts O-type fields to A types when the files are loaded to the repository. This means that if you have DBCS fields you can use them transparently within the IDE. This feature is not active in the PHP MySQL repository. Chapter 6 - IDE General Reference: Common Design Functions 155

156 Validating the HTML, PML and PHP Included in WebSmart are powerful HTML, PML and PHP syntax checkers to help you isolate and identify most potential problems with the syntax of your code. The validation option will affect whichever component of your definition is currently displayed in the main window. Executing the Validate Option You can execute the syntax checker by choosing the Tools/Validate menu option, by clicking on the toolbar button, or by pressing F7. Also, every time you generate your source WebSmart automatically runs the syntax checker and issues a warning if any errors are found. If an error is encountered you can choose to continue with the generation attempt, or cancel it. Working with the Errors Window When you run the syntax checker the results are displayed in a new window that opens below the main coding window. You can re-size the errors list pane by dragging the top border. You can also click on the x in the upper right to minimize it. Note that this doesn t close it entirely - you can still pull it back up by dragging it up from the bottom border of your main IDE window, or by pressing F7. When an error is reported, you can double-click on the error message to position to that line of code. When you do this the line in error is also highlighted in green. To reset the highlighting, press F7 to rerun the syntax check. Examples An example of PML syntax error is: PML - Source Code Line 34: Expression is outside a function Syntax check completed: 1 error and 0 warnings encountered. In this example, the error was generated by a missing bracket above the line indicated. When you are coding PHP, your errors may look like this: PHP - Source Code Line 122: Open curly bracket { missing. PHP - Source Code Line 123: Orphaned curly bracket! PHP - Source Code Line 155: Invalid variable name or keyword Syntax check completed: 3 errors and 0 warnings encountered. The HTML validation produces output such as the following: ListHeader Line 10: Hint - The <IMG> tag should have an alt attribute to improve accessibility. ListFooter Line 4: Spelling -pgm. ListFooter Line 6: Error - Expected </FONT> but found </CENTER>. The <FONT> start tag was on line 43. As you can see, the HTML validator identifies several types of error. 156 Section III - WebSmart IDE Reference

157 Customizing the HTML Validation Tools Depending on your tolerance for feedback, you can configure the HTML validator to give you different levels of information: Figure HTML validation defaults (from the Tools/Options menu). These options are described in the section HTML Default Options on page 216 of Chapter 9. You can also toggle on/off the automatic HTML validation upon generation, from the Generation Options tab of the Program Attributes. The HTML editor is based on a file called tags.txt, in the WebSmart directory. If you need to edit this file, you can open it in the WebSmart IDE. Customizing the PML and PHP Validation Tools In Figure 6-21 you can see that there are also PML and PHP defaults. These share a single additional option for customizing the validator: the option to check for unused items. This is also described in Chapter 9. Formatting your Code Another option available from the Tools menu is to Format Code. The principal function of this is to make the indention and appearance of your PML or PHP code more consistent. You can also press F9 (while working with your code) to execute this option. Chapter 6 - IDE General Reference: Common Design Functions 157

158 SQL Prototyping The last Tools menu option presents the SQL prototyping utility. This SQL interface allows you to execute SQL queries via the WebSmart IDE. You can use this interface to develop and test SQL statements for use in your WebSmart programs, or you can use it as an SQL utility to perform ad-hoc queries. There are also several other convenient features: Access WebSmart s repository for file information. Save commonly used queries for later use, and re-execute queries from the history list. Insert a saved query into your code. Select a WebSmart library list to be used when running a query. Save the results of a query to a CSV file. This utility is described in the section SQL Prototyping on page 246 of Chapter 12 of the WebSmart ILE User Guide. 158 Section III - WebSmart IDE Reference

159 The Help Menu The Help menu includes links to a number of resources you can use to assist you in working with WebSmart and the IDE. Tip of the Day The WebSmart tip of the day displays programming and design tips that you can browse through. Select this option to view today s tip. The window also has a checkbox you can use to control whether the tip window is presented every time you start up WebSmart. User Guides & Language Reference Links There are several guides available from here: The WebSmart ILE User Guide. This guide includes everything from details on how to get started on building your first programs to other types of how-to tasks. Generally, if you need help with doing something, you would start by looking at the User Guide and searching for your topic in the index or table of contents. The WebSmart ILE Reference Guide. The Reference Guide includes detailed information about all the screens, options and functions available in WebSmart. Consult the Reference Guide for details on function parameters, or if you need to know how a particular option, window or feature works. The Clover User Guide. This guide describes the Clover web report generation tool, that is shipped as part of WebSmart. The WebSmart PHP User Guide. This guide includes information about WebSmart PHP, including installation instructions and a tutorial, as well as reference information for the PHP functions that are unique to WebSmart. PHP Language Reference. This is a link to You can find the most current versions of all these guides at our website. BCD Web Site From the BCD website you can download current versions of the software and documentation. At our site you will also find many other tools, such as example programs, downloadable code samples, a searchable knowledge base, and demo apps. Test Connection When you select this option WebSmart prompts you for your user ID and password, then attempts to connect to the iseries. If a successful connection is made, a window pops up displaying a status message, the version of the currently installed release of WebSmart and the latest update you have applied. Check for Updates... Use this option to check the BCD server for WebSmart updates. About WebSmart Select this option to display your current release level and IDE build number. Chapter 6 - IDE General Reference: Common Design Functions 159

160 160 Section III - WebSmart IDE Reference

161 7 - Using the HTML Design Tools C HAPTER 7 Using the HTML Design Tools This chapter describes the IDE functions that are specific to working with your HTML. The HTML code in your definition largely controls the appearance of the web pages you create, and the HTML forms you build to gather information from the users will in turn control much of the functionality of these pages. The other main component of your definitions is the PML or PHP code. The PML or PHP is the code that processes your web pages, directing the actions that are executed as the users click on links, selects options from forms or enters new data into files. The PML and PHP design tools are described in the next chapter. This chapter is not intended as a guide to the HTML language. Refer to Chapter 6 of the WebSmart ILE Reference Guide, Web Page Design for Green-Screeners, for a quick guide to writing HTML. For the most current information on HTML, you should check the Web itself. HTML Editing Modes You can choose between three different modes to edit your HTML: HTML Tab View. This is the default, used in illustrations throughout this guide. In this mode, you edit the HTML manually, and your HTML segments are displayed as tabs across the top of the main IDE window. HTML Vertical View. In this mode you also edit the HTML manually, but the segments are grouped together vertically, based on the relationships defined in your previews. For example, the page header is above the record details, followed by the page footer. The previews are shown as tabs across the top of the main IDE window. This view is discussed in more detail on page 195. Visual HTML View. You can also work in the visual HTML view. This view is also discussed later in this chapter. The advantage of using the visual HTML mode is that you can effectively create simple or complex web pages with only a minimal knowledge of HTML. The design interface is typically much the same as any generic word processor, and about as easy to use. So if

162 HTML Color Coding you have little or no HTML knowledge, and want to get started quickly with WebSmart, you can use the built-in visual HTML tool, or link to another tool that you are familiar with (such as Dreamweaver). However, if you are an experienced HTML programmer you probably prefer to work with the HTML code directly to ensure that you have total control over your code. Visual HTML editors must make certain assumptions about page layout and how to generate the code. This isn t normally a significant problem if you are using the visual HTML tool consistently, but may cause unexpected changes to your code if you toggle back and forth between the two design modes. The WebSmart IDE color codes your HTML to improve its legibility. You can also use the color coding as a quick way to tell whether your HTML is correctly formatted: malformed HTML tags or invalid keyword won t be consistently color coded in the way that correctly formatted tags are. For example, if you add the following image tag: <img src="music/<field NAME=MU_ITMF.IMURL>" witdh=94 height=140> The src and height keywords are purple, but width is misspelled, and in the IDE appears in black [as you can see in the PDF version of this guide]. 162 Section III - WebSmart IDE Reference

163 PHP in HTML Segments You should be aware of a powerful feature supported by the IDE: you can code PHP directly into your HTML by simply enclosing the code between <?php and?> tags. <% and %> are industry-standard tags indicating the insertion of some extra code. If you are editing your pages in an external visual HTML editor, the code contained within these tags should be handled just like a comment. Here is a sample of some inline PHP: <?php IMCAT = $_REQUEST["IMCAT"]; IMGROUP = $_REQUEST["IMGROUP"]; IMITEM = $_REQUEST["IMITEM"];?> Notice that the code is appropriately color coded. It is also automatically validated when you validate the PHP. Inline Function Calls You can also add inline functions calls in your HTML, like this: <?php myfunc();?> The added code is processed at the appropriate time as the HTML is loaded to the page. This programming technique is very useful, and you should take a few minutes to understand and master it. There are few things you wouldn t want to do: A wrtseg statement that writes the segment you re in generates an infinite loop. You also want to avoid calling a function that writes the segment you re in. Chapter 7 - Using the HTML Design Tools 163

164 Working with the HTML Here is an illustration of the WebSmart IDE, showing the HTML design window: Figure 7-1. An HTML tab in the main IDE window. The windows on the left side of the IDE are described in Chapter 6, IDE General Reference: Common Design Functions. Chapter 6 addresses all the IDE design functions that are common to both working in the HTML and the code, including the placement of database fields and work fields, the creation of work fields, and working with snippets. In this illustration we are working with the HTML in tab view, where segments are displayed in separate windows and accessed via the tabs along the top. You can also work with your HTML in the vertical view, with the HTML segments displayed top to bottom in tabs for each preview definition. 164 Section III - WebSmart IDE Reference

165 HTML Segments When you design a website, the HTML portions of your web pages are generally divided up into pieces which we call 'segments'. The presentation of these segments is controlled by a wrtseg function in your code. By dividing your HTML up into segments, you have more control over how and when you present the different sections of your page. It also means that you can reuse different sections of your HTML, and improve consistency between pages. For example: many of the web pages you build will likely include lists of records. The length of this list may vary depending on how many records you choose to present and the number of records in the file. However, the information displayed above and below the list will probably be more static, irrespective of the list size. The footer information may also be shared by other pages within the program. By dividing your page into multiple segments it is easy to control the presentation of each section at the right time: the top and bottoms of the pages are written once, and the record list portion is written multiple times, within a loop in your code that executes as many times as you have records. You don t however have to always use multiple segments. If you are presenting a web page that just displays information for a single record, you can just use one segment. Navigating Between Segments In the HTML Tab View the tabs above your HTML window allow you to move between the different segments of your definition. Just click on the tab for the section you want to work on and WebSmart will bring it to the front. To quickly move between your HTML segments in the Tab view use the CTL+Tab shortcut. You can also right click anywhere above the tabs to quickly select a segment to jump to. In the Vertical HTML view, segments are presented as divisions within the main page, divided into logical groupings based on the previews you define. To go to another segment select the appropriate preview tab, and then scroll down through the sections. Chapter 7 - Using the HTML Design Tools 165

166 Working with HTML Segments To add or delete segments in your program select the Segments option under the Attributes menu. Below is an example of the list presented: Figure 7-2. Working with your definition s segments (the Attributes/Segments menu option). To create a new segment, click on the Add button and enter a new segment name and description. To change the name or description of an existing segment double-click it, or click on the segment name then the Change button. When you change the name of an HTML segment, you need to make sure that you manually change all locations in the code that refer to it. When you select a segment and click the Edit HTML button, WebSmart returns you to the HTML editor with the selected section at the front [this feature is supported in the default, tabbed segment mode]. Deleting Segments To delete a segment, select it from the list above and then click the Delete button. When you delete a segment, WebSmart also removes it from any previews which reference it. 166 Section III - WebSmart IDE Reference

167 Resequencing Segments As you work on a definition you may end up with various related segments that are separated from each other in the list shown above, and consequently, in the tabs presented in the IDE. You can resequence your segments (and tabs) by clicking the Resequence button to present a window similar to this one: Figure 7-3. Resequencing your program s HTML segments. On the left is a complete list of all the segments in your program. You can move the entire list over to the right window and then sort the entries, or if you just want to move a set of segments to the beginning, just move those to the right window and hit OK. WebSmart will prompt you to append the rest of the segments to the bottom of the list. To move a segment to the right window to change its placement, double-click it or select it from the list at left then click on the first button between the windows (the > symbol). Click on the >> button to include all the fields from your file. Then, to adjust the order of the fields you have selected click on the entry that you want to move and use the up and down arrow buttons to change its position. The < and << buttons can be used to unselect a specific segment (or all of them), if you want them out of the way and just want to append them to the bottom of the list when you re done with the rest. Chapter 7 - Using the HTML Design Tools 167

168 HTML Right Click Options Inserting Colors As you work with your HTML there are several different things you can do by rightclicking different elements within your code. In addition to the standard options to Cut, Copy, Paste and Select All, you can also edit field properties (ILE only) and insert various items. These options are described next. You can also right-click anywhere in the HTML to insert a color (for example: #0033FF). When you select this menu option, the Color Selection window is presented. You can then select one of the standard colors, or build your own. 168 Section III - WebSmart IDE Reference

169 Inserting Calendars Another right-click option allows you to insert a calendar lookup in your HTML. You ll normally place this lookup adjacent to an input-capable date field in your application. When you select this option WebSmart presents this prompt: Figure 7-4. The Insert Calendar prompt. You need to enter or select the required values. Date Field This corresponds to a field in one of your files. Click on the button to the right of the prompt to select a field from the set available in your program. Date Format Use this drop down to select the format in which the user will enter the date. The Added Code When you click OK, WebSmart inserts code similar to the following: <a href="#" onclick="var elementobj; var elementname = 'CMDACR'; for(formindex = 0; formindex < document.forms.length; formindex++){ for(elementindex = 0; elementindex <document.forms[formindex].elements.length; elementindex++){ if(document.forms[formindex].elements[elementindex].name == elementname){ elementobj = document.forms[formindex].elements[elementindex]; }}} var cal = new CalendarPopup(); cal.select(elementobj, 'anchor_cmdacr', 'MM/dd/ yyyy'); return false;" name="cmdacr_calpos" ID="anchor_CMDACR"> <img src="/websmart/calbtn.gif" border="0" height="21" width="34" align="absmiddle"></a> Chapter 7 - Using the HTML Design Tools 169

170 Using the Calendar Lookup Here is an illustration of how the calendar lookup appears at runtime: Inserting HTML Figure 7-5. Using the calendar lookup. We have added calendar lookups to both the order and ship date fields. In the illustration above, we clicked on the button to the right of the order date field, and have selected June 21, 2006 as our order date. Calendar Features To select a date, click on it on the calendar. You can use the arrows above the calendar to advance to the next month, or go back a month. The special link at the bottom of the calendar (Today) inserts today s date into the field. You can also use the right-click Insert options to invoke the HTML wizards described below in the section HTML Wizards on page 173. These facilitate the addition of HTML elements to your page. 170 Section III - WebSmart IDE Reference

171 Validating Your HTML Locating mismatched tags in HTML can be one of the most frustrating web development tasks. To assist you with this type of problem, WebSmart includes a powerful HTML syntax checker. In addition to validating for invalid tags and syntax, the syntax checker can also be customized to also offer a variety of other general quality warning messages. This feature has been discussed in the section Validating the HTML, PML and PHP on page 156 of Chapter 6, and you can find a description of the validation options in the section HTML Default Options on page 216 of Chapter 9. A simple technique for checking your HTML visually is using the color-coding. An example of this is included in the section HTML Color Coding on page 162, at the beginning of this chapter. To validate your HTML, select the HTML view in your main WebSmart design window and press F7. You can also click on the icon of the white page with the red check mark in it, just to the left of the preview drop-down box and icon. Below is an illustration of the messages presented: Figure 7-6. The Errors window, after running a typical HTML syntax check. You can drag the top border of the error message window to resize it. You can also minimize it using the X in the upper right corner, or by dragging the top border to the bottom of your window. The list of errors above includes a wide variety of warnings, hints and errors. Double-click on a specific error to go to its location. Chapter 7 - Using the HTML Design Tools 171

172 When you set your design options to automatically validate the HTML on generation, the syntax checker will validate ALL your HTML. If you press F7 to run a syntax check while on a specific segment, it will validate that segment and any others that associated with it in your preview definitions. It needs to include the extra segments because of the way pages are constructed in WebSmart, where, for example, a <table> might start in one segment, include cells in a second, and end in a third. So keep in mind that if you have three interdependent segments for which you haven t defined a preview binding them together, the syntax checker may incorrectly report mismatched/orphaned tag errors. 172 Section III - WebSmart IDE Reference

173 HTML Wizards While HTML is in theory a simple markup language, in our experience it causes programmers a level of difficulty in the process of building web applications that is disproportionate to its complexity as a language. To facilitate adding correctly formatted HTML elements to your pages, WebSmart includes a set of HTML tools. These are available from either the HTML/Insert menus, or the toolbar buttons shown here in the second row (beginning with B): Figure 7-7. The HTML toolbar. When you choose a tag, WebSmart presents the appropriate wizard interface (described in the sections below). The actual HTML inserted will vary depending on the options you pick. Below is a table of the options available from the toolbar: Bold. Italicize. Underline. Set alignment. Insert a comment. Insert a line break. Create a paragraph. Mark a division. Mark a text span. Create a heading. Create a table. Create a form. Insert an image. Insert a link. Insert a special character. Insert a list. Insert a PML function. Figure 7-8. The options in the HTML toolbar. Chapter 7 - Using the HTML Design Tools 173

174 Inserting Simple HTML Elements Bold To bold a portion of text, first highlight the selected text string, then click the Bold button. The result is as shown here: <strong>this text is bold.</strong> Alternatively, you can click on the Bold button to insert the HTML <strong> tags, then type the text between the tags. Italicize To italicize a text string, use the I button from the toolbar. The result in the IDE is as shown here: <i>this text is in italics.</i> As with bolding, you can also first add the tag, then type the text within the tags. Underline To underline text, first highlight the string, then click on the third button in the HTML toolbar. The results are as shown here: <u>this text is underlined.</u> Text Alignment The fourth button in the toolbar (note the drop down indicator to the right of it) allows you to set the alignment for a text string. By default, clicking on the button will center the selected text. To select a different alignment option, click on the drop down, as shown here: Figure 7-9. The text alignment option in the HTML toolbar. From here you can click on any of the three options. The results in your HTML are as shown here: <center>this text is centered.</center> <div align="right">this text is aligned to the right.</div> <div align="left">this text is aligned to the left.</div> 174 Section III - WebSmart IDE Reference

175 Inserting Comments To format a text string as a comment, use the Comment button in the HTML toolbar. The result in your HTML is as shown here: <!--The set of HTML below is designed to present the toolbars from which the user will choose the next page to present.--> This text is not output to your page. Inserting a Line Break In HTML, line breaks have to be explicitly added in order to be shown in your web page. The line break button produces the following results: This is on one line.<br>and this is on the next. It doesn t matter whether there is an actual line break included in the IDE or not; this doesn t affect the output. Inserting a Paragraph To mark a block of text as a paragraph, highlight the block and click on the paragraph button. When you use this option, WebSmart first presents this dialog: Figure The Insert Paragraph prompt, presented from the HTML menu or toolbar. From here you can set the following attributes: Class. This corresponds to a set of a style sheet attributes identified by a key word. This results in the HTML class="classname" being added to your tag, referencing a class in the style sheet associated with the page. Style. The Style is an in-line style attribute selector. This results in the HTML style="style:attribute" being added to your tag. Using the style attribute in-line allows you to add attributes to your paragraph without having to define them in a <style></style> section in the head of your HTML, or to override page-level values. An example of specifying a style value is: color:red; fontstyle:italic; font-weight:bold; font-family:arial (no quotes). Title. The Title is what appears in the tooltip when you mouseover the element. You would normally use this in buttons, links and images, but it is supported for all HTML elements. Chapter 7 - Using the HTML Design Tools 175

176 Here is an example of how to use this tag: <p class="keypoint" title="lemur Key Idea">Lemurs are a special group of primates found only on Madagascar and the Comoro Islands. There are 50 species of lemurs and 17 are on the endangered species list. </p> <p class="keypoint" title="lemur Key Idea">Lemurs are prosimians, or primitive primates. They are social animals with long limbs, flexible toes and fingers, and long noses. </p> As with line breaks, it is generally a good practice to insert a blank line in your HTML to reflect paragraph breaks on your page. Here is an illustration of the effect of the tags we have used so far, using the page preview to show them: Figure Examples of how some common HTML tags affect your text formatting. 176 Section III - WebSmart IDE Reference

177 Creating Text Divisions The <div> tag is frequently used in HTML in conjunction with style sheets, to create blocks of text sharing particularly characteristics. Here is the window presented to prompt you for the division attributes: Figure The Insert Division prompt, presented from the HTML menu or toolbar. The key difference between using <p> and <div> is that the paragraph tag includes a line break, and the <div> tag does not. The options available above are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Here is an example of how you might use the <div> tag: <div class="keypoint" title="lemur Key Idea">Lemurs are a special group of primates found only on Madagascar and the Comoro Islands. There are 50 species of lemurs and 17 are on the endangered species list. </div> <div class="keypoint" title="lemur Key Idea">Lemurs are prosimians, or primitive primates. They are social animals with long limbs, flexible toes and fingers, and long noses. </div> Creating Text Spans The <span> tag is used to associate a particular set of characteristics with a text string (usually shorter than a paragraph, or division). When you click this button, WebSmart presents this dialog: Figure The Insert Span prompt, presented from the HTML menu or toolbar. Chapter 7 - Using the HTML Design Tools 177

178 The options available above are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Here is an illustration of how you could use this tag: Lemurs are a special group of primates found only on <span>madagascar</span> and the <span>comoro Islands</span>. There are 50 species of lemurs and 17 are on the endangered species list. As with the <div> tag, the <span> tag is most often used in conjunction with style sheets. Inserting Text Headings HTML supports a standard set of 6 heading tags, H1 through H6. To format a text string as a heading, highlight the text and select the appropriate level of heading from the list, as shown here: Figure The HTML toolbar dropdown, for inserting one of the standard heading styles. Selecting the heading shown above would result in the following in your HTML: <h3>all About Lemurs</h3> We recommend that you use headings in conjunction with style sheet entries which further describe the attributes of each heading level. Here is an example of a simple style sheet you could include in the <head> area of your page to control the appearance of your headings: <style type="text/css"> H3 {font: 12pt Arial; color: blue; text-align: center; font-weight: bold} </style> 178 Section III - WebSmart IDE Reference

179 Inserting Tables and Table Components HTML tables are the structural backbone of most web pages, so the table tool is one of the most useful. Click on the drop down arrow next to the button to choose between adding a table, row or cell, as shown here: Figure The HTML toolbar option for inserting tables, table rows and table cells. When you insert tables, rows and cells, you can also set the class, style and title from the Style/Accessibility tab. These options are described in the section Creating Text Divisions on page 177, above. When you insert a table (which is also the default option when you click on the button), this window is presented: Figure The Insert Table prompt, presented from the HTML menu or toolbar. Specify the table attributes as required. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Rows/Columns Select a number of rows and columns to add to your table. Table Width This can be a static value in pixels, or a percentage of the available width (within the page, or within another table cell). Click on the check box to indicate that the entered value is a percentage. Table Height This can be a static value in pixels, or a percentage of the available height (within the page, or within another table cell). Click on the check box to indicate that the entered value is a percentage. Chapter 7 - Using the HTML Design Tools 179

180 Border Select a value for the border width. Background Color Enter a hex value for the background color, or click on the button to select a color using the color chooser. ID The ID tag is an option usually used in conjunction with javascripting. If you don t know what it means, then you don t need to use it. Column Headings? Check this box if you would like to have a row included at the top of your table, for displaying column headings. The cells in heading rows are delimited by <th></th> tags, rather than the standard <td></td>. Here is an illustration of the HTML inserted by this option: Inserting Table Rows <table border="1" height="50" width="90" bgcolor="ede3c5"> <tr> <td></td> <td></td> </tr> <tr> <td></td> <td></td> </tr> <tr> <td></td> <td></td> </tr> </table> When you select the option to insert a table row (see Figure 7-15), this window is presented: Figure The Insert Table Row prompt, presented from the HTML menu or toolbar. 180 Section III - WebSmart IDE Reference

181 Rows to Insert Select the number of rows to insert. Align Select the horizontal alignment of the row content. Valid value are left, right and center. Vertical Align Select the vertical alignment of the row content. Valid values are baseline, top, middle and bottom. Inserting Table Cells When you select the option to insert a table cell/column (see Figure 7-15), WebSmart prompts you for the following details: Figure The Insert Table Cell prompt, presented from the HTML menu or toolbar. All the values shown above are defaults. If you do not change any of these values, WebSmart will insert a simple <td></td> pair. To add additional cell attributes, make changes to any of the values shown above. Columns to Insert Select the number of table columns to insert. Type This option allows you to choose whether the cell will include Table Data (and be enclosed in <td> tags), or be a Table Header (and use <th> tags). Width Enter the column width, either in pixels or as a percentage of the total table width. Check the % checkbox to indicate that the value entered should be interpreted as a percentage. Align Select either center, left or right as the horizontal alignment options. Chapter 7 - Using the HTML Design Tools 181

182 Inserting Forms Vertical Align Select the vertical alignment for the contents of the cell. Row Span Table cells can be set to span multiple rows. Select the number of rows to span. Column Span A table cell can also span multiple columns. Enter a value greater than 1 to include the colspan attribute in your tag. Another HTML task that is often fraught with difficulty is the addition of forms to your pages. WebSmart includes HTML wizards to facilitate inserting plain forms, as well as buttons, text inputs, radio buttons, check boxes, password fields, selects, hidden fields and text areas. When you insert a plain form (by simply clicking on the icon), you are prompted for these options: Figure The Insert Form prompt, presented from the HTML menu or toolbar. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Action Enter the form action. This is generally a target URL to be executed by a form. To the right of the Action is a browse button from which you can select a file field. This is useful if the URL you are going to execute includes variables stored in database, work or program fields. Method Select a form method of GET or POST. The advantages of each of these are discussed elsewhere in the documentation. 182 Section III - WebSmart IDE Reference

183 Submit Button Text Type the word or words to be displayed on the form submit button. Form Name Use this option to define a unique name for your form. Target The TARGET attribute is used to specify in which frame of a frameset the form response should be rendered. If no frame with such a name exists, the response is rendered in a new window unless overridden by the user. Special frame names begin with an underscore: Target Value _blank _self _parent _top Description Renders the response in a new, unnamed window. Renders the response in the current frame (useful for overriding a BASE TARGET). Renders the response in the immediate FRAMESET parent. Renders the response in the full, unframed window. Inserting Buttons To insert a button, click on the right side of the Insert Form button, and select this option. This window is presented: Figure The Insert Submit Button prompt, presented from the HTML menu or toolbar. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Button Type There are three button types: Submit. To submit a form. Button. A push button, with other attributes identifying the action to be taken. Reset. A button to submit a form. Chapter 7 - Using the HTML Design Tools 183

184 Name Specify a unique name for this input. Button Text Type the text to be displayed on the button face. Inserting a Text Input The text input is one of the simplest forms to add. When you add a text input, you can enter the following attributes: Figure The Insert Text Input prompt, presented from the HTML menu or toolbar. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Name Enter a unique name for this text input. Value Specify the initial value for this text field. Size Specify the size of the field to be added to the page. Max Length Specify the maximum length, in characters, that the text field will allow. 184 Section III - WebSmart IDE Reference

185 Inserting a Radio Button Select the Radio Button option from the form drop down to add a radio button to your page. The options available when adding this HTML element are as follows: Figure The Insert Radio Button prompt, presented from the HTML menu or toolbar. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Name Enter a unique name for the radio button. Value This is the value assigned to the radio button when it is checked. The name/value attributes indicate the name/value pair sent to the server when the radio button is selected. Button Label This attribute explicitly associates the label being defined with another control. When present, the value of this attribute must be the same as the value of the id attribute of some other control in the same document. When absent, the label being defined is associated with the element's contents. Checked by Default Select this option to have this radio button selected by default. Disabled Disabling a radio button means that the radio button is greyed out and is unable to be edited by the user. Read Only This attributes, new in HTML 4.0 and poorly supported by current browsers, prevents the user from editing the content of the text or password input types. In the case of a radio button, you could use this to indicate that the value is not changeable. Chapter 7 - Using the HTML Design Tools 185

186 Inserting a Checkbox When you insert a checkbox, the WebSmart HTML wizard prompts you for the following values: Figure The Insert Checkbox prompt, presented from the HTML menu or toolbar. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Checkbox Label This attribute explicitly associates the label being defined with another control. When present, the value of this attribute must be the same as the value of the id attribute of some other control in the same document. When absent, the label being defined is associated with the element's contents. Name Enter a unique name for the checkbox. Value This is the value assigned to the checkbox when it is checked. The name/value attributes indicate the name/value pair sent to the server when the checkbox is selected. Checked by Default Select this option to have this checkbox selected by default. Disabled Disabling a checkbox means that it is greyed out and is unable to be edited by the user. Read Only This attributes, new in HTML 4.0 and poorly supported by current browsers, prevents the user from editing the content of the text or password input types. In the case of a checkbox, you could use this to indicate that the value is not changeable. 186 Section III - WebSmart IDE Reference

187 Inserting Password Fields When you insert a password field, you have the following options available: Figure The Insert Password Input prompt, presented from the HTML menu or toolbar. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Name This is a required attribute that associates a symbolic name to the field for submission to the form processing script. Value This indicates a default value for the password field. The real value is obscured of course (usually each character is represented as asterisks), but the value will be passed to the form processing script paired with the NAME attribute upon submission. Size This attribute controls the amount of display space allocated to the password field. Max Length This optional attribute constrains the number of characters that can be entered into the password field by the user. If the MAXLENGTH attribute is larger than the optional SIZE attribute, the password field should scroll as necessary. Chapter 7 - Using the HTML Design Tools 187

188 Inserting an HTML Select Form When you click on the option to insert a Select, WebSmart presents this window: Figure The Insert Select List prompt, presented from the HTML menu or toolbar. To use this window, enter values for the first three options, then add, one by one the value/list text pairs. To add the value/list text pairs, enter values for each, then click on the Add button. To remove an entry that you have added, select it in the list and click the Remove button. To select a default value, click on the box that appears in the leftmost column as you add each entry. When you have finished adding all the values click on the OK button to add the HTML. Here is an illustration of the HTML added by Select wizard: <select name="selectname" multiple size="3"> <option value="option_1">option 1</option> <option value="option_2">option 2</option> <option value="option_3">option 3</option> <option value="option_4">option 4</option> </select> The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Name This is a required value that associates a name with the field for submission to the form processing script. 188 Section III - WebSmart IDE Reference

189 Lines Visible A Select form shows a list of options for the user to select from. Choose how many visible lines will be displayed on the page. In the example above, the list size has been set to 3, meaning that the first three values will be visible on the page, and a scroll bar will be added to allow you to view the last entry. Multiple Select Click this option to allow users to select more than one value (by shift-clicking). Default Selection If there is a entry in your list that you would like selected by default, check this box (in the list at the bottom of the dialog) after adding a Value/Text pair. Value This is the value returned when the user selects one of the entries in the list. List Text This is the text displayed in the list for each value that can be submitted by the form. Inserting Hidden Fields Hidden fields are a useful way of submitting values to the form processing scripts which do not have to be displayed on the page. These can either be key defaults, values passed from previous pages, or default form processing options. To insert a hidden field, select the Hidden option from the form wizard drop down. WebSmart presents this dialog: Figure The Insert Hidden Field prompt, presented from the HTML menu or toolbar. Name This required value associates a symbolic name to the field, to be submitted to the form processing script. Value This is the value associated with the hidden field. Chapter 7 - Using the HTML Design Tools 189

190 Inserting Text Areas The last HTML element you can insert with the wizard is a text area. Text areas are useful for eliciting text strings from the user. When you choose the option to insert a text area, WebSmart prompts you for the following options: Figure The Insert Text Area prompt, presented from the HTML menu or toolbar. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Here is an illustration of the HTML inserted: <textarea name="specialinstructions" rows="3" cols="40"> Type special instructions here. </textarea> Name This required value associates a symbolic name to the text area, to be submitted to the form processing script. Rows Choose a visible number of rows to be displayed on the page. Columns Choose how many columns should be displayed on the page. Value This is the text value submitted by the form. You can also enter some text here to be initially displayed in the box when the web page is first presented. 190 Section III - WebSmart IDE Reference

191 Inserting Images To insert an image into your web page, click on the Image icon in the HTML wizard toolbar. When you do this, WebSmart prompts you for these options: Figure The Insert Image prompt, presented from the HTML menu or toolbar. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page 175. Source Enter the URL where the image will be found. Height/Width The image height and width (in pixels) is an optional value, allowing the browser to allocate space in the web page to the image before it has loaded. It avoids the irritation of seeing the web page being restructured on the fly as the images load. Border If the image is also a link, most browsers will by default draw a border around the image, unless you specify a value of zero for the border. Alt Text Enter the text string to be displayed when the user mouses over the image, or as the image is loading. This value is also used by some search engines. ID The ID tag is an option usually used in conjunction with javascripting. If you don t know what it means, then you don t need to use it. Chapter 7 - Using the HTML Design Tools 191

192 Adding HTML Links to your Web Page When you click on the Link button to use the HTML wizard to add a link, WebSmart displays this window: Figure The Insert HTML Link prompt, presented from the HTML menu or toolbar. When you are adding a link, the best way to do is it is to first highlight the text string (or image tag), then click on the button. This loads the value on the page to the Link Text shown above, and places the text (or image tag) within the link. Href This attribute indicates the URL to be loaded when the hyperlinked text or image is activated. This value is required. Link Text This is the text string or image that will function as a link. Target This attribute is generally used with frames, to specify in which frame the form response should be rendered. If you specify a non-existent frame name, the response is rendered in a new window unless overrides it. Special frame names begin with an underscore: Target Value _blank _self _parent _top Description Renders the response in a new, unnamed window. Renders the response in the current frame (useful for overriding a BASE TARGET). Renders the response in the immediate FRAMESET parent. Renders the response in the full, unframed window. ID The ID tag is an option usually used in conjunction with javascripting. If you don t know what it means, then you don t need to use it. The options available on the Style/Accessibility tab are the same as those available for the Paragraph tag, and are described above in the section Inserting a Paragraph on page Section III - WebSmart IDE Reference

193 Adding Special Characters There is also an HTML wizard that you can use to add special characters to your page. For example, if you need to add a greater than (>) symbol to your page, which has a special meaning in the HTML, it s best to add it as &gt. Another common example is the &nbsp tag (non-breaking space), which allows you to add blank spaces to a text string. When you click the & button, & is automatically inserted. Otherwise click on the drop down to the right of the button to select from several other special characters. Adding Lists to your Web Page The second-last button in the HTML toolbar allows you to add lists to your page. These are the options available: Figure The Insert HTML List prompt, presented from the HTML menu or toolbar. List Style Lists can be ordered or unordered. Ordered lists are numbered, unordered lists are bulleted. Bullet Type When creating lists of either type, there are a number of formatting options you can choose from for either the enumeration or the bulleting: For a default ordered list (1, 2, 3...) leave the Bullet Type set to Disc. Ordered lists can also be enumerated by capital letters, small letters, large roman numerals, small roman numerals. Unordered bulleted lists can be formatted to have solid or hollow discs, or squares. The option you choose is included using the type attribute in your list tags. Number of Items Select the number of items you plan to have in your list. Chapter 7 - Using the HTML Design Tools 193

194 Adding Functions Use the last HTML toolbar option on the right to insert a PHP function call in your HTML. When you click this button, this prompt is presented: Figure The Insert Function prompt, presented from the HTML menu or toolbar. Existing Function Name The default option for this value is *NEW, to create a call to a new function that you will subsequently create in your program. If you click the drop down option, WebSmart allows you to select from the list of functions currently defined in this program. Function Name If you selected *NEW for the first option, you must also type the function name. If you select a function from the list, you can ignore this option. The function name is used in both the line added to your HTML: <?php listdetails();?> and your PHP function: func listdetails() { // List Details } Function Description If you select the *NEW option for your function, you can also add a description. This optional value is included as a comment in your new PHP function (as shown above). 194 Section III - WebSmart IDE Reference

195 Vertical HTML View The Vertical HTML feature is another way to view your HTML. Normally when you are working with the HTML, sections are separated into segments, with tabs for each segment displayed along the top of the main window. The Vertical HTML view allows you to work with your HTML segments as they are organized into previews. Page previews are sets of related HTML segments grouped into an order in which they would normally be displayed on a page. The Vertical HTML view allows you to work with a preview group of segments together in a continuous vertical display. You can select the Vertical HTML view from the View menu or by clicking on the toolbar icon. If when you switch to vertical HTML you have a preview with no valid segments, WebSmart will ask you if you want to remove it. Here is an illustration of the Vertical HTML view: Segments within a preview definition. Figure Characteristics of the WebSmart IDE s Vertical HTML view. The Vertical HTML feature still presents a tabbed view of the HTML, except that the tabs represent each of your previews. In the above example the definition has three previews: Main List, Display and Manage. Each of these previews contains only the set of HTML required to display the selected page. Chapter 7 - Using the HTML Design Tools 195

196 This means that some segments may appear in multiple previews, while there may be others that aren t used in any preview. The individual HTML segments are easily identifiable in the vertical view; they are separated by a grey header bar with minimize/ maximize options, and a properties icon. This header is read-only and cannot be altered or deleted. In the left margin, level with each segment header is a + or a - icon you can use to expand or collapse the segment. When you collapse a segment everything except the header disappears from the view, like this: Figure An illustration of three HTML segments in Vertical HTML mode. The third is visible. In this illustration we have collapsed the ListPrev and ListNext segments. You can click on the + icons to expand the segments. Editing the HTML in the Vertical View All the usual editing options are available in the vertical view of HTML, with some exceptions relating to the header lines. You can copy and paste between segments, but WebSmart won t allow you to delete a block of text that includes the header. You can copy a block of text which includes the header and when you paste it the header will appear as a comment. The right click menu works in the vertical view of HTML but will not include the option to insert HTML if the cursor is on a header. 196 Section III - WebSmart IDE Reference

197 The Visual HTML View The WebSmart HTML views described in the previous sections (Tabbed and Vertical) allow you to enter or modify HTML source code. You do this either by typing the code as text, or by dragging and dropping code snippets and field tags onto the editor window. If you prefer the additional features of a visual HTML design environment you can use the Visual HTML view. The intent of visual HTML tools is to allow you to create and edit HTML content in an environment similar to most word processors, shielding you from the intricacies of the actual HTML. Unfortunately, the perfect visual HTML tool has not yet been invented, so most programmers find themselves having to tweak the HTML manually at some point. We ll look at how you can do this too. But until you learn a little more about HTML, you can use the visual editor to create basic web pages almost as easily as you would create a document in a word processor. Here is an illustration of a record management segment in the visual HTML editor: Figure An illustration of the WebSmart IDE s Visual HTML editor. If you are at all familiar with visual HTML editors, or even with a word processor such as Microsoft Word, many of the options above should be self-explanatory. For example, to edit a block of text you highlight it and select a font, font size or background color. There are also buttons you can use to set your alignment and indention, and so on. Chapter 7 - Using the HTML Design Tools 197

198 There are also a number of buttons beginning about half way along the top row that allow you to add various HTML components. If you are entirely unfamiliar with HTML and HTML tags, then we recommend you take a few minutes to review the Web Page Design for Green-Screeners on page 413 of the WebSmart Reference Guide. We won t describe each of the HTML options here, but there are a few functions that deserve special mention. We ll discuss these next. Previewing the Page Title HTML The second button of the visual HTML utility allows you to preview the appearance of the page. When you click this button, a drop down menu appears prompting you to select a screen resolution (or the page size you are designing for). These values include 640x480, 800x600 and 1024x768. When you click one of the values, WebSmart pops up a preview of your page. This is helpful so you can see how your images or text will look in wide or narrow layouts. Text and Background Colors Following the Preview button is a set of options standard to most application (Find, Cut, Copy, etc), and then there are two options for working with the color of your text and backgrounds. Changing Text Colors To change the color of a text string, highlight the text and then click the underlined A to change the foreground color, as shown here: Figure Changing the text color in the Visual HTML editor. 198 Section III - WebSmart IDE Reference

199 The drop down list includes a standard set of 40 colors, and you can click the More Colors option at the bottom to present this color picker: Figure The Visual HTML editor s expanded color picker. In this window you can access three different color views, and add custom colors to be used for your text or backgrounds. Changing Background Colors The steps to change background colors are the same as those outlined above. The only difference is that you need to first highlight the area of the page, or click on the page element (table row, for example) shown in the bottom border of the visual tool. Manually Editing your Page Title HTML As we mentioned above, almost all web page designers eventually end up having to tweak some of their HTML by hand. If you find that the visual interface to the editor isn t able to give you the precision you want with some design element, you can click the last button on the top right of the visual editor - - to work with your HTML manually. Chapter 7 - Using the HTML Design Tools 199

200 When you click the View/Edit Source button, WebSmart pops up this window: Figure Editing the HTML manually using tools in the Visual HTML editor. This window includes a wealth of useful information. In addition to showing you the actual title page HTML so you can fine-tune any changes made via the visual interface, you can also see the paths for the title page itself (in the status bar), and the paths to the images you are using. All this information is useful when you start to add your own components to the title page. Edit the HTML manually, and then click the apply button to format the HTML including the parts you added. Click OK to save your changes and return to the IDE. Advanced Formatting Options The visual HTML editor also provides a set of tools you can use to apply advanced formatting options to page element. Click the first icon on the left of the bottom row of your visual HTML editor toolbar to choose from the following options: Text Formatting. Paragraph Formatting. List Formatting. Box Formatting. Custom CSS To use these options, first highlight the section of the page you want to edit. For example, to edit a text string, first highlight it, then select the Text Formatting option. To edit a table cell, select that cell and then choose the Box Formatting option. 200 Section III - WebSmart IDE Reference

201 Example Formatting Options: Boxes (or Tables) It is beyond the scope of this guide to discuss all the HTML options available, but as an example, here is an illustration of the box formatting options: Figure Formatting a box (table) in the Visual HTML editor. If you are at all familiar with HTML, you can see that the formatting options are a reflection of the table and table cell attributes supported in HTML. So these interfaces for working with the attributes serve to help you take advantage of the features supported by HTML without having to worry about the details of the tag syntax. And if you do want to familiarize yourself with the actual tags, you can toggle to the View/Edit HTML window. Custom CSS The most powerful and flexible formatting option is to create a custom set of CSS tags for your page elements. For example, if we needed to apply some custom formatting to our table, would click on the <TABLE> tag in the bottom border of the editor and then select this option. This window is presented: Figure Inserting a custom CSS tag using the Visual HTML editor s tool. This presents a free-format window in which you can enter your CSS for the selected element, and a small preview window in which to view your results. Chapter 7 - Using the HTML Design Tools 201

202 202 Section III - WebSmart IDE Reference

203 8 - Using the PML and PHP Coding Tools C HAPTER 8 Using the PML and PHP Coding Tools This chapter describes the IDE functions that are specific to working with your PML and PHP code. For information on the PML language, please refer to the WebSmart ILE Reference Guide, or use the context sensitive help in the PML editor. For information on the PHP language, you can search online, or use the context sensitive help in the PHP editor. PHP is a programming language originally designed for producing dynamic web pages. 1 For more information about PHP, a good place to start is the PHP 101 course at Zend s Developer Zone ( Though the actual physical appearance of your web pages is mainly determined by the HTML component of your programs, remember that creating web pages is just part of what you are doing with WebSmart. Each section of HTML presented in a page in your browser is merely the result of a wrtseg statement within the PML or PHP code, and a small part of everything that your program is doing. WebSmart is a tool for creating programs, not mere static web pages. Every WebSmart definition you create is driven by either PML or PHP. The basic code to run a program is included in the template you select to use as the initial framework for your applications. This means that in some cases you may not need to write new code, or change the default code,to create a program. However, if you do need to make changes to your programs, there is no limit to what you can add or change in a definition - the WebSmart templates are starting points, not unchangeable program skeletons. To work with the code in any program definition click on the icon showing an unrolled scroll located on the WebSmart IDE toolbar, or click the leftmost tab on the second row: Figure 8-1. The tab with your definition s code (in this case, PML). 1. Wikipedia:

204 The IDE Code View Here is an illustration of the PHP Editor: Figure 8-2. The WebSmart IDE, showing a PHP editing tab. Figure 8-2 shows 3 panes. For an overview of the general features of the IDE and the three windows, please review the sections beginning with Changing the Default IDE Layout on page 128 of Chapter 6. Chapter 6 also discusses the following topics: The Fields and Functions Window Placing Fields in PHP Definitions This chapter discusses the IDE features that are unique to working in PML/PHP mode. Working with Multiple Files in the IDE The WebSmart IDE supports the ability to open and work with multiple files in the IDE, including JavaScript, style sheets and other external files. The IDE shows these open files in tabs above the main coding window. Use these tabs to navigate between the files. You can right-click the external file tabs to close or save them. 204 Section III - WebSmart IDE Reference

205 The Functions List Window The first columns of the window in the upper left include your file fieldsvariables. The last columns in the window (towards the right) are tabs for your various sets of functions. As with the field entries, you can use this list to place your functions in the code, either by double-clicking a function, or dragging and dropping it into your code window. When you place a function WebSmart adds the function name and structure of the parameters required. The cursor is positioned to the first parameter entry. Here are some examples of how your functions are added: i5_command(,,, ); DateTime::format( ); opendir(, ); In each of these cases, the cursor is placed immediately inside the open parenthesis. Using the Functions List Pane The functions pane displays an alphabetical list of all the functions you have defined in your program. Here is an illustration of this pane: Figure 8-3. An illustration of the functions list displayed in the WebSmart IDE. From here you can double-click on a function to position to that spot in your code. To delete a task, you need to remove the associated function code; you can t delete the entry in this list. The Snippets and Information Tabs The Snippets tab is described earlier in this guide, in the section Working with HTML, PML and PHP Snippets on page 135 of Chapter 6, IDE General Reference: Common Design Functions. The Info tab displays some summary details about your definition. Chapter 8 - Using the PML and PHP Coding Tools 205

206 Here is an illustration of the tab: Figure 8-4. The program definition information tab. This includes a number of details relating to your program and definition. 206 Section III - WebSmart IDE Reference

207 The Main Coding Window The largest window in the IDE is used to display your PML, PHP or HTML code. The options available from this window when you are in HTML mode are described in Chapter 7. The following sections describe the appearance of the PML or PHP coding window, the code it contains, and its behavior as you add new code. The main coding window supports all the standard windows editing features, such as: Copying, cutting and pasting highlighted text. Dragging and dropping highlighted text. Deleting highlighted text. Also, as you add to your code, if the number of lines of code exceeds the length of the window, a scroll bar is automatically added to the right margin of the window. The next sections below describe various tools that assist you in coding your PHP, but you should never forget the Help key: while you are working in the PHP editor, you can press F1 at any time to present function-specific help. PHP Color Coding and Auto-Formatting Your PHP code is automatically color coded as you add it, and periodically refreshed when you toggle back and forth between different views. PHP embedded in your HTML inline is also color-coded. Below is a list of the colors associated with the different components of you PHP code: Color Components Red Punctuation marks, such as (),;{}. Also operands such as +/-=. Maroon Numbers Blue Function names, structures and conditionals. For example: func, if, while, and. Olive Constant values, marked by being within double quotes. For example Order Number and 57CHEVY. Green Comments. Comment lines must start with //, and can be on their own, or appended to other statements. Black Everything else. This includes function and field names, and other function parameters. In addition to the automatic color coding, when you press Enter after adding a new line of PHP the editor also indents new lines of PHP code to the right level, based on your current nesting level within structures. You can refresh the formatting of your PHP at any time by pressing F9, or selecting the Tools/Format Code menu option. Chapter 8 - Using the PML and PHP Coding Tools 207

208 Intelliprompting A very useful coding tool is the WebSmart IDE s intelliprompting. As you type new PML or PHP function names, the IDE displays a subsetted lists of potential matches for the function you are starting to code. For example, as we begin to add this PML getparm statement below on line 81, by the time we reach the p the IDE has limited our list of potential functions to these seven: PHP Prototyping Figure 8-5. WebSmart s intelliprompting displaying a list of potential function matches. Use your up and down arrow keys to go to a function from the list and the Enter key to select it. You can turn this option on/off from the Environment section of your Tools/Options. As you type your PHP code, the IDE presents prototypes of the functions on the left-hand side of the bottom border of the window. As you are adding new functions you can press F1 to present a help window containing further details on that function. The prototypes presented are extracted from several files, including the generator file parser.txt (at Tools/Options/Generator Files), as well as the files prototypes.pml (for the fixed-format generator) and uprototypes.pml, which exist in your ESDI/WebSmart 208 Section III - WebSmart IDE Reference

209 folder. These files are used for several other things as well, so if you take a look at them, make sure you don t make any accidental changes! Here are some sample prototypes for three ILE functions: VOID wrtseg(segment &segment, ALPHA &getaux=false { FALSE TRUE } ) VOID crtfld(field &field, NUM &fldlen, ALPHA &fldtyp="a" { "A" "N" "B" "S" "V" }, NUM &flddec=0, ALPHA &desc="") ALPHA substr(alpha &str, NUM &start, NUM &len) The first two begin with VOID to indicate that they don t return any particular value, so the syntax as you type them would be wrtseg(... and crtfld(... The substr function, on the other hand, returns an alpha value, so the syntax would be substrfield = substr(... PHP Parameter Tooltips As you are keying in your PHP functions the editor displays tooltips for parameters. These are associated with the values shown in the function prototype, and are displayed below your function statement as you key it in. For example, as you key in a wrtseg function, after you type the opening (, the tooltip displays the text string segment, to indicate that what you need to key in is a string, and it refers to a segment. If the function requires several parameters, the IDE displays the next tip after your type the comma following the first parameter. As you are begin working with WebSmart, you will likely find these tips useful. If, as you become more proficient with the software, you start to find them redundant, you can turn them off from the Tools/Options dialog, in the PHP/PHP section. You can also clear an individual tip using the Esc key. You can turn this option on/off from the Tools/Options window, in the Environment options. Syntax Checking the PHP After making changes to your code it is a good practice to run the syntax checker. The syntax checker runs through your PHP code (and any PHP embedded in your HTML segments) and bring to your attention any possible problems it encounters. WebSmart also runs the syntax checker automatically every time you attempt to generate. If any syntax errors are found you are given the option to abort the generation, or continue anyway. You can run the syntax checker by clicking the toolbar button - - or by pressing F7. When you execute the syntax checker the IDE presented an additional window pane below your main code listing displaying all the errors encountered. Chapter 8 - Using the PML and PHP Coding Tools 209

210 At the bottom of the image below is an illustration of the errors window presented by the syntax checker. In this example, we have also double-clicked on an error to position the cursor to that line of code in the main window: Figure 8-6. Positioning to an error indicated by the syntax checker. You can resize the syntax checker window by dragging the top border. You can also close the window by dragging the border to the bottom of the main design window, or clicking on the X in the upper right corner of the message window (When you do this it just minimizes the errors window to the bottom of the main window. You can get it back by dragging it up from the bottom border.) To position the code window to an error, double-click on the error in the window. This works even if the error is in code embedded in an HTML segment. The message should give you a good idea about the nature of the error, and sometimes even some suggestions on how to fix it. 210 Section III - WebSmart IDE Reference

211 PHP in HTML Segments You should be aware of a powerful feature supported by the IDE: you can code PHP directly into your HTML by simply enclosing the code between <?php and?> tags. <% and %> are industry-standard tags indicating the insertion of some extra code. If you are editing your pages in an external visual HTML editor, the code contained within these tags should be handled just like a comment. Here is a sample of some inline PHP: <?php IMCAT = $_REQUEST["IMCAT"]; IMGROUP = $_REQUEST["IMGROUP"]; IMITEM = $_REQUEST["IMITEM"];?> Notice that the code is appropriately color coded. It is also automatically validated when you validate the PHP. Inline Function Calls You can also add inline functions calls in your HTML, like this: <?php myfunc();?> The added code is processed at the appropriate time as the HTML is loaded to the page. This programming technique is very useful, and you should take a few minutes to understand and master it. There are few things you wouldn t want to do: A wrtseg statement that writes the segment you re in generates an infinite loop. You also want to avoid calling a function that writes the segment you re in. Chapter 8 - Using the PML and PHP Coding Tools 211

212 212 Section III - WebSmart IDE Reference

213 9 - WebSmart Program and Configuration Defaults C HAPTER 9 WebSmart Program and Configuration Defaults There are a number of environment and design interface settings you can adjust from the WebSmart IDE. These range from default program locations to HTML confirmation preferences and communications settings. Most of these options are available from the Tools/Options menu. Below are explanations of each set of options. General Program Options When you first go to Tools/Options, these options are presented: Figure 9-1. The Tools/Options window.

214 IDE Options Show Tooltip for All Function Parameters WebSmart can present tooltips for your function parameters as you type your code. If you want to see these tooltips (described in the section ) check this option. Show Intelliprompting The WebSmart coding window can also display an intelliprompting window as you add new functions. The intelliprompting window shows a dynamic subset of functions matching the characters you have typed. This feature is described in the section Intelliprompting on page 208 of Chapter 8. Uncheck this option to turn off the intelliprompting feature. Automatic Backup Check the Perform Automatic Backup option if you wish to periodically back up changes to your definition as you work on it. If you select this option, you also need to add a backup interval (for example, 10 minutes). Backup definitions have the same name as your definition, but an extension of.bkp, and are deleted when the pdw is saved or closed. Note that definitions are also automatically saved as the first step in the generation process. Check for Product Updates Check this option to have WebSmart check the website at the chosen intervals, and if a new version is detected, redirect you to the product updates page. Uncheck the box to disable the option. Launch after Generation Check this option to automatically launch your program every time you generate. Source Code Default Font Use this option to specify the default font used to display your code. The initial value is Courier New 10pt. Only monospaced fonts are supported. Show Line Numbers Check this option to display line numbers in the main code window. 214 Section III - WebSmart IDE Reference

215 Confirmations Click on the Confirmations category to present the following options: Figure 9-2. Setting your default confirmation options (Tools/Options). Confirm before loading a file into repository? When you use a new file for the first time, WebSmart normally also adds the file to your local PC repository. Check this option to have the IDE prompt you for whether you want to do that. Confirm successful generation? Select this option if you want WebSmart to alert you when the generation process has been completed. When you first install WebSmart, all of these options are checked. As you become more familiar with the software, you will likely want to uncheck a few of these. When these messages are displayed you have the option of indicating whether you ever want to see them again. Find Options The confirmations tab also includes a number of options to control how your text finding tool works: Confirm before continuing a search from the top of a document. If you want the find to automatically search your entire PHP every time, starting from your cursor, Chapter 9 - WebSmart Program and Configuration Defaults 215

216 uncheck this option. Otherwise, the search will start from the cursor insertion point and continue to the bottom of the page, and prompt you for whether you want to continue from the top. Allow searches across multiple HTML segments. Check this option if you want to allow searching more than one HTML segment when you use the find option in the HTML. Confirm before searching the next HTML segment. If you have toggled on the option above, you can also set whether WebSmart should prompt you as it moves from one HTML segment to the next, when searching multiple segments. You can toggle any of these options on or off. HTML Default Options The HTML default options include the following: Figure 9-3. HTML default options (Tools/Options). The first set of options are related to the level of validation that you want to execute on your HTML when you run a syntax check. Select the types of validation you want to execute. 216 Section III - WebSmart IDE Reference

217 Show Warning Messages These include warnings such as when you use tag attributes that aren t supported by the latest HTML specification. For example, The WIDTH attribute in the <INPUT> tag is not part of the HTML 4.0 specification and may not work. Show Accessibility Suggestions The suggestions presented when this option is turned on generally relate to the usage of tags or other HTML features that are not handled gracefully in older or text-based browsers (such as not specifying width and height values on images, etc.). Show Hints Unselect this option if you don t want the HTML editor to show hints. Hints are general design suggestions affecting the overall structure of your page, including things like having a lack of Meta tags, page titles that are too short, or not using websafe colors. If you aren t certain what the impact is of toggling the above options, open any WebSmart definition and press F7 in a longish HTML segment. The set of hints presented will likely include examples of all the above. Spell Check Unselect this option if you don t want to spell check your HTML when you validate. The spell checker uses a file called dictionary.txt in the root of the ESDI/WebSmart folder, You can add more words to this file if you wish (for example, your company name). If you are using WebSmart in a non-english language environment, and have a good word list for your own language, you may wish to replace this list entirely with one of your own choosing. Otherwise you should just turn this option off. Validate on Generation Check this option if you want to validate your HTML every time you submit the definition to be generated. By default, WebSmart only validates the HTML when you explicitly select the Tools/Validate option or press F7. To turn this option on or off for a particular definition, go to the Generation Options tab of the Program Attributes. Convert Special Characters to &abc; equivalent Select this option if you use the &abc; special character notation. This feature is targeted mainly at non-english language clients who use many non-english language characters in their HTML text. WebSmart uses the table stored in the file rpltable.txt (in the WebSmart directory) to identify special characters and replacement values. Here is a sample of the contents of this file: ç,ç è,è ê,ê This file is fairly robust, but you can add more values if you need them. This functionality is described in more detail in the section Replacing Special Characters with the &abc; Chapter 9 - WebSmart Program and Configuration Defaults 217

218 Equivalents on page 362 of Appendix B of the WebSmart ILE User Guide. You can turn this option on or off for individual definitions at the Generation Options tab of the Program Attributes. Use Alternate Visual HTML Tool One of the challenges posed when attempting to produce online content is that of learning HTML. While WebSmart includes its own visual HTML editor, if you have already mastered designing web pages with another visual HTML tool, WebSmart allows you to use this tool to create and modify your pages. To do this select the Use Alternate Visual HTML tool option shown above (Figure 9-3). After selecting the option you can browse your PC to select the desired executable. Note that the degree of successful integration between the two tools will depend on two main factors: How the visual tool reacts to WebSmart <field> tags, which are not part of the standard set of HTML tags. As long as the tool ignores them, you re fine. The quality of the tool you use. Some tools clutters the HTML with useless junk (in extreme cases, some tools can make the HTML almost unworkable by hand). Once you have selected your alternate tool, just click on the 'Visual HTML' tool bar button to launch it and edit your HTML segments. 218 Section III - WebSmart IDE Reference

219 Server Options iseries Systems There are a number of different connection types that you can create with WebSmart, and which ones you need and use will depend on your development environment. All WebSmart installs require at least one iseries connection, though you can add as many as you need. Set up your iseries system connections from here: Figure 9-4. iseries defaults (Tools/Options). The systems listed above are available for you to select from the dropdown list in the main IDE window. User the Add, Change and Delete buttons to work with your system descriptions (and associated programming defaults). Chapter 9 - WebSmart Program and Configuration Defaults 219

220 Adding & Configuring your Systems The System Name/IP Address list is initially empty. To add a system to it, click the Add button. The window below appears (showing an existing system): Figure 9-5. Creating a new iseries system description. If you have multiple iseries you want to connect to, add them to the list one at a time. When you add a new system you will see the environment name in the window title, indicating that it will be added to your current environment. System Name The System Name should, by convention, be the same as the name of the iseries as determined by running the DSPNETA command on your iseries. In fact though, it really doesn't matter what name you type in here, because WebSmart uses the IP address to resolve to the host system. The name is simply for your reference in the list of systems shown in the WebSmart IDE. IP Address Type your iseries IP address. If you don t know what value to enter here, go to an iseries command line and type the command CFGTCP and press Enter. When the menu appears, type option 1= Work With TCP/IP Interfaces. This will present a list of IP addresses for the system. Port The Port field is used to define a port number on the host to attach to. This must correspond to the port number specified when configuring TCP/IP on the iseries (which you most likely did during the install, or afterwards using the ZCFGTCP command). The default value of 2015 is usually acceptable. We provide the option to configure this value in case you already have a TCP/IP service (such as FTP, Telnet, Ping etc.) that uses the default port number. 220 Section III - WebSmart IDE Reference

221 Default Program Library Type the name of the default program object library for your new programs. Default Program Library List Object Type the name of the default program library list object for new programs. Leave this value blank to use the special value *FILES. The implications of each option are discussed in the section Defining the Program Attributes on page 99 of Chapter 5. Default Program Source File and Library Type the values for the default program source file and library for new definitions. Default Web Path This is value is used when you test your applications by clicking the launch button from the IDE. When WebSmart attempts to execute your program, the program name is appended to the value set here. An example of the value you might enter here is: This option is discussed in more detail in the section Web Path to Object/Web Path for Launching on page 101 of Chapter 5. After you have entered these values, click OK to save your changes. Other iseries Settings Below the list of systems are a few other iseries-related options. Remember Session Password If the 'Remember session password' value is checked, you will only need to type in your name and password once, no matter how many connections you establish to the iseries. The only time this value shouldn't be checked is if you are signing on to the iseries under several different user profiles, or if you are working on a PC shared by multiple users. Conversation Timeout This is the default amount of time that Exodus (the WebSmart communications middleware component) will wait when contacting the host iseries and during normal conversations, before issuing a timeout message. The default value of 30 is usually enough, but if your iseries is subject to heavy workloads, you may consider increasing it. Use WebSmart Change Management by Default (For Each Server) This option determines whether the Default File/Open and File/New (along with the toolbar items) will invoke WCM (WebSmart Change Management) 'Open' and 'New' operations. Enable Menu Options for Mixed Change Management Environment (For Each Server) This option causes a set of additional menu options to be added to the 'File' menu, allowing you to open and create both managed and local definitions. Chapter 9 - WebSmart Program and Configuration Defaults 221

222 If you have checked both this option and the previous one (Use WCM by default), the File menu includes these four options: New... New Local... Open... Open Local... If you check this option, but have NOT selected the option to Use WCM by Default, then the File menu includes these four options: New... New Managed... Open... Open Managed... FTP Servers If you are working with WebSmart PHP, you must define at least one FTP connection. Your FTP connections allow you retrieve and work with files related to your application, as well as set defaults for the PHP programs you create. These are the FTP connection options: Figure 9-6. Adding a new FTP connection. 222 Section III - WebSmart IDE Reference

223 FTP connections require these values: Option Description Site Name Type an informational description of the site you are connecting to. URL Enter the IP address or domain name of your server. Initial Directory Enter the initial directory to be displayed. For WebSmart, use this value: /www/websmart/htdocs/wsphp/ (with no quotes). Web Path Select a default path to pre-pend to your program name when you click the Launch button from within the IDE. The default WebSmart Apache HTTP server instance runs on port 8150, so this should normally be set to (no quotes). User/Password. Enter the user profile and password to use to connect to the iseries when saving the PHP files. FTP Port Select the FTP port on the remote system. The default value of 21 should usually work for you. Passive Mode Check this option if you need to establish your FTP connection in passive mode. After entering the required values, click the Test Connection button to verify that you have entered your configuration details correctly. If the confirmation window tells you that the connection is working, continue with the next section. If you didn t get a successful connection, double-check your values. If you already have established links to the server in another application, compare your settings to those. Automatically Reconciling FTP Sites When you create a new definition, some of the options associated with it are derived from your FTP connection settings. Because this information is stored on your PC, it s possible that it may not exactly match the attributes used by other programmers at your site to describe the same connection. For example, suppose you and another developer are working on the same application but have given your FTP connections different names and description. When you attempt to open a definition created by your co-worker, WebSmart will by default present a message similar to this one: Figure 9-7. Reconciling FTP connection settings in a definition. Chapter 9 - WebSmart Program and Configuration Defaults 223

224 This window is telling you that this program was created for an FTP site name V5R4, which is undefined on your PC. However, WebSmart has identified a site defined on your PC, named iseries box, where the critical attributes match the site V5R4. You have the following options: Always Use a Matched Site. When you click this button, the IDE default option (found in Tools/Options/Server/FTP) of this name is set on. Use Local Site Name. When you select this option, this single definition is adjusted. Select Different. Use this option to browse your FTP sites and select one different than the first match found by WebSmart. When you adjust a definition, all references to the site are updated. Working with ODBC Connections (Other Databases) If you are intending to create applications that work with non-db2 files, then you need to create an ODBC connection for every database you will work with. To add an alternate database to your WebSmart configuration, click on the Databases category in your default options. Here is an illustration of those options: Figure 9-8. Attributes of an ODBC connection (Tools/Options). 224 Section III - WebSmart IDE Reference

225 Click the Add button to create a new database connection. Name/Description. Type a name and description for this ODBC connection. Server/Port Type a server IP and port number. Database Enter the database name. User/Password Enter the User ID and password to be used to connect to this server. Driver Type the driver here. Default Connection Check this box to make this your default connection. Automatically Reconciling Database Connections When you create a new definition, some of the options associated with that definition are derived from your ODBC connection settings. However, because this information is stored on your PC, it s possible that it may not exactly match the values used by other programmers at your site, even though they are working over the same database. For example, suppose you and another developer are working on the same application, but have given your ODBC connections different names and descriptions. When you attempt to open a definition created by your co-worker, WebSmart will present a window asking you how want to reconcile that difference. You have the following options: Always Use a Matched Database. When you click this button, WebSmart always uses the suggested match. This is the equivalent of checking the Automatically Reconcile Database Connections option. Use Local Site Name. When you select this option, this single definition is adjusted. Select Different. Use this option to browse your ODBC connection sites and create or select one different than the first match found by WebSmart. When you adjust a definition, all references to the site are updated. Chapter 9 - WebSmart Program and Configuration Defaults 225

226 ILE Program Defaults PML Defaults From these groups of attributes you can set options relating to developing applications for the ILE/PML environment. From here you can set a couple of options relating to ILE programming with WebSmart: Figure 9-9. ILE program attribute defaults (Tools/Options). Check for Unused Items when Syntax Checking Use this option to have the syntax checker review your PML for unused objects. This is a useful option for cleaning up old, unused fields, segments, arrays, etc. Target Platform/Language This options allows you to select your default generator. There are three options: iseries ILE RPG Fixed Column Generator iseries ILE RPG Free Format Generator Java Servlets Generator. The default is the iseries ILE/RPG Free Format Generator. This generator resides on your PC. The ILE RPG Fixed Column generator resides on the iseries, and should generally only be used to regenerate older definitions that may use functions that have changed in the Free Format generator. If you need to generate Java Servlets, the code generation will happen on your PC, but the compile still occurs on iseries. Please note that if you plan to generate Java servlets you need to purchase a separate software license for WebSmart JSE. 226 Section III - WebSmart IDE Reference

227 Paths and Repository Options Click on the Paths and Repository entry to work with these options: Figure The ILE generator path and repository defaults (Tools/Options). Snippet Directory When more than one programmer at your site is using WebSmart you may want to share snippets. You can do this by specifying a network directory for the snippets file and copying the initial set shipped with the software (in the folder shown above) to that directory. Any new snippets then created would be available to all programmers. Servlet Directory Specify the default servlet location for new definitions. Make New Extensions Global WebSmart supports the ability to add file extensions to your database files through the PC-side file repository. This allows you to automatically include simple and complex functionality in your programs simply by virtue of selecting a specific file and field. When you define file extensions, you have the ability to define them as global. To define an extension as global means that you would like to share it with all other programmers using WebSmart on that iseries. Each time you generate a definition, WebSmart checks to see if you have added, changed or deleted any global extensions and then makes the appropriate changes on the iseries. WebSmart then checks to see if there are any global extensions already on the iseries which have been added, changed or deleted by others. Chapter 9 - WebSmart Program and Configuration Defaults 227

228 If you are one of the main WebSmart developers at your site, you may want to make all the extensions you create global by default. When this option is selected, the Global option is automatically checked when you add an extension. Verify File Level ID s with the Server When Definitions are Opened Choose this option to connect to the iseries to check if the extensions file is current. You may not want to check this because it requires constant iseries connection availability, and slows down the opening of every definition. Synchronize Extensions Automatically Whenever Repository is Loaded Check this option if you want to synchronize your repository extensions each time the repository is loaded. The repository is loaded the first time you open a definition or when you click on the 'repository' icon in the tool-bar (whichever is first). This is simply a way of making repository extension synchronization occur more frequently. Other times that extension synchronization occurs is when a definition is generated, when an individual file is synchronized, or when the 'Synchronize' button on this tab is pressed. Repository Selection The remaining three options can be executed separately for each file repository you have defined. WebSmart creates a separate PC-side repository for each server and database you create a connection to. Use this dropdown list to select the repository your want to synchronize, or download/ upload global extensions for. Synchronize Use this button to trigger an immediate repository extensions synchronization. This will upload any global extensions changed since the last synchronization and download any global extensions changed by others since the last synchronization. This synchronization is done automatically at various times during development, such as during generation or when an individual file is loaded to a definition. The date and time at which your extensions were last synchronized are displayed. Download of All Repository Global Extensions Now Use this button if you want to replace all the global extensions on your PC with the version of the extensions stored on your iseries. Generally this option is only used if you feel that for some reason your PC has gotten out of synch with the global extensions on the iseries. Upload of All Repository Global Extensions Now Use this option to upload all global extensions to the iseries and flag them as changed (which will cause other users to download them when they next synchronize). As with the above option, this is generally only done when you suspect that somehow your extensions are not being propagated correctly. 228 Section III - WebSmart IDE Reference

229 Generator Files The last set of defaults available to work with are the generator files. When you click on this entry, the list of files presented is similar to this one: Figure The list of WebSmart ILE generator files available from Tools/Options. The default list of generator files you can work with includes the following: parser.txt frags.txt tokens.txt pgm001.txt pgmrpt.txt uparser.txt To work with any of these entries, click the file name and then on the Edit File button (you can also double-click the file). The file then appears in the main IDE window from where you can make and save your changes. The uses of these files are discussed in the WebSmart ILE documentation. If you aren t certain how these files are used, you shouldn t make changes to them. Chapter 9 - WebSmart Program and Configuration Defaults 229

230 PHP Program Defaults Click on the PHP entry in the Options window to work with these default settings: Figure PML defaults for programming in the ILE generator (Tools/Options). Customizing your Function Groups This window lists the function groups displayed in the top left-hand window of the IDE. Use this area to customize the tabs shown, and if necessary, create new tabs with your own functions or subsets of the functions you frequently use (from other tabs). By default, all functions groups are shown in the IDE. Click the Customize Function Groups option to create your own groups as well as to select which of the default groups is included. You need to restart WebSmart for your changes to take effect. When you add a new group, WebSmart prompts you for the name and description. Then you can edit the prototype file for that group. 230 Section III - WebSmart IDE Reference

231 PHP Generator Files The last set of defaults you can work with are the generator files. When you click on this entry, the list of files presented is similar to this one: Figure PHP generator files (Tools/Options). The default list of generator files you can work with includes the following: frags.txt shell.php tokens.txt To work with any of these entries, click the file name and then on the Edit File button (you can also double-click the file). The file then appears in the main IDE window from where you can make and save your changes. You should only change these files with the assistance of Technical Support. Chapter 9 - WebSmart Program and Configuration Defaults 231

232 Working with WebSmart IDE Environments The WebSmart IDE allows you to create development environments to encapsulate a set of iseries, FTP and database connections along with their related defaults. These defaults (for ILE) include your source file and object libraries. This simplifies the process of using the WebSmart IDE to work on different applications and multiple systems. When Should I Create an Environment? Environments are primarily tools for developers working in more complicated environments. Factors that could contribute to the decision to use environments include: Working on multiple PHP applications, where you have defined more than one target FTP site. Working with applications that involve multiple, different databases. If you are just developing ILE applications on one or more systems, then you probably don t need to set up environments. Below are a couple of example situations where environments would help you keep your systems, FTP connections and databases organized, and avoid accidentally compiling programs to the wrong location. Example 1: Multiple PHP Applications Suppose you work on two applications, Payroll and Manufacturing. They both run off the same box, so you have only one system. But you're programming PHP, so you want different FTP Sites for each application. This is a good time to define environments: Create two FTP Sites, one for each application. Define only one system, since you have only one box. Then set up two environments, each referencing the same system, but different FTP sites. Example 2: Working on Several Systems Suppose you're a consultant who has several clients: Client A has 1 box and runs WebSmart ILE programs. Client B has 2 boxes and runs WebSmart ILE programs. Client C has 2 boxes and runs WebSmart ILE and PHP programs, and accesses a MySQL database on a Linux server. In this situation you would define the following: 5 systems, 1 for each box 2 FTP sites, for client C's PHP programs 1 additional database, for client C's MySQL database 232 Section III - WebSmart IDE Reference

233 Then you would set up 3 environments: Environment 'Client A', which consists of 1 system. Environment 'Client B', which consists of 2 systems. Environment 'Client C', which consists of 2 systems, 2 FTP sites, and 1 database. As you switch between the different environments, the available Systems, FTP Sites, and databases will change to those declared for each environment. By using environments you won t accidentally compile something to the wrong place. As you attempt to create and compile programs and work with your repositories, WebSmart will automatically connect to the systems and databases that you need. Configuring Environments Here is an illustration of an IDE configured to work in two environments: Figure Selecting the iseries library to use with your version of the WebSmart IDE. Use the Add, Change and Delete buttons to create and work with your environments. Chapter 9 - WebSmart Program and Configuration Defaults 233

234 Creating New Environments When you click the Add button to create a new environment, WebSmart first prompts you for the name and description: Figure Creating a new WebSmart development environment. Environment Name & Description Type a name for your environment. This is displayed in the IDE toolbar dropdown, from which you can select the environment to work in. The description is displayed in your default options. Click Next to continue. 234 Section III - WebSmart IDE Reference

235 iseries Systems After you enter the environment name and description, the next step is to select the iseries Systems that should be part of the environment: Figure Selecting the iseries systems to be included in your development environment. Check the systems you ll need to access in your development project. When you select multiple systems for an environment, those systems will appear in the Systems dropdown list for that environment. However, you can only connect to one system at a time, and generation will occur to one system only. Once you've logged into a system, the IDE remembers that you've logged into that system, so even if you switch to a different system and then switch back, you'll still be logged in. Click Next to continue. Chapter 9 - WebSmart Program and Configuration Defaults 235

236 Selecting the Environment FTP Sites The next step is to select the FTP sites you will need to access in your application (if any): Figure Selecting the FTP sites you ll need to access in your development project. Check the site(s) that you ll need to access. Then click Next to continue to the final step. Selecting the Environment Databases The final step in setting up your environment is to choose any additional databases (other than those implicit in the iseries systems you included) that you may need to access: Figure Selecting the database which you will need to access when working in this environment. Check the required database(s) and click Finish to create the environment. 236 Section III - WebSmart IDE Reference

237 Running Multiple Versions of WebSmart Concurrently WebSmart includes a somewhat hidden option that allows you to specify a different server-side library, so you can run different versions of the tool concurrently. This option is intended for situations where you want to install a newer version of WebSmart, perhaps to take advantage of a new feature, while still retaining a 'production' version of the software until you have put the new version through some tests. We recommend that you discuss your objectives with Technical Support before attempting this, but these are the general steps to follow: 1. Save XL_WEBLIB to a save file. Use the SAVLIB command to perform this step, NOT the CPYLIB command. Using the CPYLIB command can result in changes to object authorities which may adversely impact your ability to access data in some files. 2. Install the latest version of the software. 3. Rename XL_WEBLIB to XL_ENV1 (or the environment library of your choice). 4. Restore XL_WEBLIB from the save file used in step Install the new client (the IDE) to a different directory than the default. 6. In the new client, press F11 and enter the new environment library name. After performing these steps, when you run the new client it will run with the new server version, while the old client will still run the old version. This is not a complete separation of environments, as XL_WEBSPT is still be shared, but the old programs will still use the old WAS (Web Application Server) and the new programs will use the new WAS. Chapter 9 - WebSmart Program and Configuration Defaults 237

238 The WEBSMART IBM HTTP Server Instance Overview The IBM HTTP Server Instance (Powered by Apache) that you ll need in order to run your WebSmart programs is automatically created and started during the WebSmart install. This instance is called WEBSMART.After installing the software you can verify that it has been started via the WRKACTJOB command. This section includes an overview of the default configuration, as well as some background information on what a server instance is and how to make changes to it after it has been created. The HTTP server has to be configured to control, among other things, what operations can be performed by users, what security is imposed on users, and to map directories and iseries libraries. Without performing at least some minimal configuration changes, your system will not be able to run any CGI programs. For more in-depth information we recommend you read the following: HTTP Server (Powered by Apache): An Integrated Solution for iseries Servers, available at: The iseries HTTP Server (Powered by Apache) supports multiple "Server Instances". A "Server Instance" is a description of a set of jobs whose execution parameters are governed by the associated configuration description for this instance. For example, you might eventually have two server instances, one for access to your site by company employees, and another for access by the general public. The instance used by the general public could be accessible through a different IP address, domain name or port number, and would presumably have much tighter restrictions on what files or programs could be accessed. Another example of using multiple instances of your HTTP Server is to have one for testing your applications, and another for production. 238 Section III - WebSmart IDE Reference

239 Confirming that the WebSmart IBM HTTP Server (Powered by Apache) Instance was Successfully Created The installation process automatically creates a web server instance WEBSMART. To confirm that this configuration was correctly created, perform the following steps: 1. At an iseries session, run the WRKACTJOB command and find the QHTTPSVR subsystem. Check whether this includes a number of jobs named ADMIN. If not, start the *ADMIN instance of the HTTP server, using the following command: STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN) 2. When the jobs have been started, Open a browser and go to the admin interface for your iseries, at the address where your_server_ip is the IP address of your iseries. 3. [This step may vary depending on your OS/400 release.] Click the IBM Web Administration for iseries link to navigate to the Manage HTTP Servers page (how you do this will depend on your operating system level), and display the configuration for web server instance WEBSMART. The page presented is similar to this one: 4. Select the option to Edit Configuration File. If the WEBSMART instance is not listed in the drop down list (in the top circle, above), please contact Technical Support. Chapter 9 - WebSmart Program and Configuration Defaults 239

240 Your configuration should be similar to this: LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 1 LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM Listen *: DocumentRoot /www/websmart/htdocs Options -ExecCGI -FollowSymLinks -SymLinksIfOwnerMatch -Includes - IncludesNoExec -Indexes -MultiViews LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined LogFormat "%{Cookie}n \"%r\" %t" cookie LogFormat "%{User-agent}i" agent LogFormat "%{Referer}i -> %U" referer LogFormat "%h %l %u %t \"%r\" %>s %b" common CustomLog logs/access_log combined LogMaint logs/access_log 7 0 LogMaint logs/error_log 7 0 SetEnvIf "User-Agent" "Mozilla/2" nokeepalive SetEnvIf "User-Agent" "JDK/1\.0" force-response-1.0 SetEnvIf "User-Agent" "Java/1\.0" force-response-1.0 SetEnvIf "User-Agent" "RealPlayer 4\.0" force-response-1.0 SetEnvIf "User-Agent" "MSIE 4\.0b2;" nokeepalive SetEnvIf "User-Agent" "MSIE 4\.0b2;" force-response-1.0 CGIConvMode %%MIXED/MIXED%% ProxyPass /wsphp/ 3 ProxyPassReverse /wsphp/ <Directory /> 4 Order Deny,Allow Deny From all </Directory> <DirectoryMatch /esdi/websmart/v*/include/> 5 Order Deny,Allow Deny From all </DirectoryMatch> 1. These service programs are required by Zend Core, to run PHP programs. 2. This value is the port number that you select for your iseries to listen on for HTTP requests. Because we are automatically installing the configuration above, we haven t specified port 80, the normal default, to avoid the possibility of conflicting with existing applications listening on that port. If you aren t using port 80 for anything else, you can optionally specify port 80 here, to avoid having to append :8150 to your IP address. 3. These directives (also used by WebSmart PHP) are responsible for directing requests for PHP resources to the Zend PASE Apache instance. 4. This <directory> container disables, by default, access to all directories. This means that by default, all access to the system is blocked, and only the avenues we explicitly create will provide access. 5. This set of directives is used to block access to the include files used by PHP programs. 240 Section III - WebSmart IDE Reference

241 # # Directives for WebSmart # <Directory /www/websmart/htdocs> Order Allow,Deny Allow From all </Directory> # deny access to the WCM directories 1 <Directory /esdi/websmart/wcm/> Order Deny,Allow Deny From all </Directory> 1. These directives exist so that external users can t access definitions and other objects stored in the Web- Smart Change Management directory on the IFS. Chapter 9 - WebSmart Program and Configuration Defaults 241

242 # The WAS configuration programs should be protected. 1 It currently requires a valid iseries user profile. <LocationMatch /wascfg.*> Require valid-user AuthType Basic AuthName SecureArea PasswdFile %%SYSTEM%% UserID %%CLIENT%% </LocationMatch> 1. Authentication. This LocationMatch set of authentication directives acts like a green-screen signon, requiring a valid iseries User profile and matching password to be entered by the user of the browser before they can access an area of your website (or any part of it at all). It is important to realize that this protection takes place at the Server level, not at the client (browser). When the web server receives a request to access a page that is covered by protection, the web server causes the browser to prompt for User ID and password info. If you use protection at the server level you won't have to worry about prompting the user for a valid User ID and password in the web page you design. For more information on security see Chapter 13 of the WebSmart ILE Reference Guide. The mechanism used for implementing authentication directives at run-time is as follows: 1. The Web server receives a request for a page and tests to see if a authentication directive covers it. 2. If it is, the Web server causes the browser to pop up a window prompt for a User ID and Password: In the protection above, the Password file is set to %%SYSTEM%%, while the User ID is set to %%CLI- ENT%%. This means that the validation occurs using your iseries user profiles, and the server job will adopt the submitted profile to service the request. The above directives are applied to this Location or URL pattern and mean the following: The user will see the realm name of SecureArea (this name can be anything) when prompted by the browser for User ID and Password. The password entered by the user is checked against valid User profiles. The server job will adopt the submitted profile to service the request. Apache directives are not positional, so you can add these lines anywhere in your configuration file. However, we do recommend that you place them after any <Directory> containers in your file to maintain some logical separation and to make future maintenance easier. For further suggestions relating to securing the WAS configuration programs, and setting up authentication directives in general, please read the section Access to the WAS Configuration and Authentication Directives on page 244, below. 242 Section III - WebSmart IDE Reference