Getting Started with Logi Info/Logi Report and Java
Getting Started with Logi Info/Logi Report and Java Installing and Understanding Logi Analytics Managed Reporting Products For Linux, UNIX, or Windows with the Java Runtime Environment November 2014 This document has been formatted for double-sided printing, hole-punching, and placement in a ring-binder. Author: Lee Hausman Logi Analytics is a trademark of Logi Analytics, Inc. Microsoft, Microsoft Word, Microsoft Excel, Windows, Windows XP, Windows Server, Windows Vista, and Visual Basic are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Other products and company names mentioned in this book may be trademarks of their respective owners. Logi Analytics, Inc. 7900 Westpark Drive, Suite A200 McLean, Virginia 22101 703-752-9700 Copyright © 2009-2014, Logi Analytics, Inc. All rights reserved. Table of Contents Introduction ............................................................................................................................................................ 1 System Requirements ............................................................................................................................................. 3 General Requirements ........................................................................................................................................ 3 How Many Servers Do You Need? ...................................................................................................................... 4 Server Virtualization ........................................................................................................................................... 5 About Logi Reporting with Java .............................................................................................................................. 6 Development Options ......................................................................................................................................... 6 Deployment Options ........................................................................................................................................... 6 Database Connectivity and Tools ........................................................................................................................ 6 Basic Platform Knowledge Required ................................................................................................................... 7 Product Licenses ................................................................................................................................................. 7 Differences from Logi Applications for .NET ....................................................................................................... 8 Sharing Session Variables with Other Apps ........................................................................................................ 8 Installing Logi Studio on Windows ........................................................................................................................ 10 Preparing to Install ............................................................................................................................................ 10 Installing the Software ...................................................................................................................................... 15 Configuring IIS ................................................................................................................................................... 22 Modifying or Repairing the Installation ............................................................................................................ 24 Product Licensing .................................................................................................................................................. 25 Built-in Trial License .......................................................................................................................................... 25 License Keys and License Files .......................................................................................................................... 25 License Management ........................................................................................................................................ 26 When a License Expires..................................................................................................................................... 29 Licenses and Server Virtualization .................................................................................................................... 30 Upgrading Logi Products and Apps ....................................................................................................................... 31 General Requirements ...................................................................................................................................... 31 Upgrade Impacts ............................................................................................................................................... 31 Upgrading the Products .................................................................................................................................... 32 Changing the Version of Your Logi Applications ............................................................................................... 33 Creating Application Pools ................................................................................................................................ 35 Logi Application Overview .................................................................................................................................... 37 Understanding Logi Applications ...................................................................................................................... 37 Introducing Elemental Development ................................................................................................................ 38 i Using Support Files with a Logi Application ...................................................................................................... 40 Application Deployment.................................................................................................................................... 41 Additional Helpful Information ......................................................................................................................... 41 Java Server Configurations .................................................................................................................................... 42 General Information .......................................................................................................................................... 42 Apache Tomcat 5.5 / 6.0 / 7.0 ........................................................................................................................... 44 JBoss 4 ............................................................................................................................................................... 45 JBoss 5.1 ............................................................................................................................................................ 45 JBoss 7.1 ............................................................................................................................................................ 46 Sun Glassfish (SJSAS) 2.1 ................................................................................................................................... 47 Sun Glassfish (SJSAS) 3.0, 3.1 ............................................................................................................................ 47 BEA WebLogic 10 ............................................................................................................................................... 47 Oracle WebLogic 12c ......................................................................................................................................... 48 IBM Websphere 7, 8.5 ....................................................................................................................................... 48 Introducing Logi Studio ......................................................................................................................................... 49 Logi Studio Geography ...................................................................................................................................... 49 Panel Arrangement ........................................................................................................................................... 53 General Features ............................................................................................................................................... 54 Using Logi Studio ................................................................................................................................................... 56 Getting Started .................................................................................................................................................. 56 The Welcome Panel ........................................................................................................................................... 57 Application Files ................................................................................................................................................ 58 Working with Elements ..................................................................................................................................... 64 Setting Element Attributes ................................................................................................................................ 67 Intelligent Token Completion ............................................................................................................................ 73 Studio Wizards................................................................................................................................................... 75 Assigning Themes and Style Sheet Classes ........................................................................................................ 79 Testing and Debugging Applications ................................................................................................................. 83 Deploying Logi Applications .............................................................................................................................. 88 Ribbon Menu, Shortcuts and Search ................................................................................................................. 94 The Database Browser ...................................................................................................................................... 99 The SQL Query Builder .................................................................................................................................... 101 The MDX Query Builder ................................................................................................................................... 102 Working with Studio Panels ............................................................................................................................ 104 Changing Logi Application Versions ................................................................................................................ 106 Team Development Features .......................................................................................................................... 107 Deleting a Logi Application .............................................................................................................................. 111 Granting File Access Permissions ........................................................................................................................ 113 Using .NET? Let the New App Wizard Do It ..................................................................................................... 113 ii Using Java? It’s Usually Done for You ............................................................................................................. 113 Which Accounts? ............................................................................................................................................ 113 Which Application Sub-Folders? ..................................................................................................................... 114 Granting File Access Permissions .................................................................................................................... 114 No Security Tab Visible?.................................................................................................................................. 119 Managing Support Files ...................................................................................................................................... 120 Using Themes and Style Sheets .......................................................................................................................... 123 About Themes ................................................................................................................................................. 123 Selecting a Theme in Studio’s Wizard ............................................................................................................. 124 Adding Themes Manually ............................................................................................................................... 124 Creating Your Own Themes ............................................................................................................................ 126 About Cascading Style Sheets ......................................................................................................................... 127 Create an Example Style Sheet ....................................................................................................................... 128 Including a Style Sheet in Your Application .................................................................................................... 129 Editing a Style Sheet in the Workspace .......................................................................................................... 130 Editing in the Style Sheet Selector .................................................................................................................. 131 Editing a Style Sheet Using the External Style Sheet Editor............................................................................ 132 Applying a Style Sheet to Your Definition ....................................................................................................... 132 Assigning Style Classes to Elements ................................................................................................................ 134 Development Best Practices ............................................................................................................................... 138 Debugging Reports.............................................................................................................................................. 140 Previewing and. Browsing ............................................................................................................................... 140 Using Comments, Remarks, and Application Notes ....................................................................................... 143 Using the Test Parameters Panel .................................................................................................................... 145 Using the Application Debugger ..................................................................................................................... 146 Logging Errors ................................................................................................................................................. 150 Hello World! Tutorial .......................................................................................................................................... 152 Glossary ............................................................................................................................................................... 160 Resources and Support ....................................................................................................................................... 164 iii Introduction This publication introduces developers to Logi Info and Logi Report, known as Logi Analytics’ “managed reporting” products. It refers to the latest release of these products, v11.3.049. Logi Info is our licensed product that allows developers to create comprehensive reporting solutions and web applications, using the full range of features and components. Logi Report is a reduced version of Logi Info that, while still capable of producing excellent reports, does not include all of Info’s power and features. Developers working with the .NET Framework on Windows platforms are directed to our companion Getting Started publication for .NET on those platforms. The general purpose of this publication is to assist the reader in installing their Logi Analytics product, in making it functional, and in getting a basic understanding of how Logi reports and web applications work. Other publications and online documents are available that focus on specific aspects of Logi applications, such as displaying data in tables or in charts. Documentation for Logi Analytics products, available on the Logi Developer Network web site, will always present the most up-to-date information. Specifically, you can look there for the newest features; publications like this one are by their nature more difficult to keep current. Unlike products based on client-server technology, Logi Analytics’ products were conceived to be web-based from the start. They output only HTML and script to the end-user’s browser and as a result achieve simplicity, cross-browser compatibility, and an ease-of-use that eludes other products. At the same time, this means that some of the flashier functionality of desktop applications or downloaded custom components is not available. However, the resulting minimal configuration management requirements and tighter security of Logi products provides ample proof of the correctness of its approach, especially in an enterprise setting. The technique of “elemental development”, the creation of report pages by combining pre-defined objects (or elements) from a toolbox into a hierarchical tree that mirrors the top-to-bottom layout of an HTML page, makes for speedy report development. New Logi developers are often surprised at how quickly they can produce meaningful reports. In addition, because report designs can be made dynamic at runtime, developers also often find the number of report definitions they must manage reduced, often by as much as 50%. The DevNet web site includes numerous free sample applications that can be quickly downloaded and that provide a great learning opportunity for new developers. Frequently the sample apps mirror the examples in the documents on DevNet. Logi developers are urged to take advantage of these sample apps. What should the Logi developer already know? A prospective Logi developer should already have a good understanding of general web technologies, such as HTML and style sheets, and be familiar with their data sources and the techniques, such as SQL, needed to access that data. Experience with JavaScript is useful but not required. What information is not presented here? General web server, database server, and network management techniques touch on the successful deployment of Logi applications but are beyond the scope of this publication. The assumption is made that develop1 Getting Started with Logi Info and Logi Report for Java ers have these skills themselves or have access to others within their organizations with them and the specifics of these topics are not included here. We hope you enjoy working with these products and quickly become productive and successful with them. Comments about this publication are welcomed and can be addressed to [email protected]. 2 Getting Started with Logi Info and Logi Report for Java System Requirements The following general hardware and software components are required for Logi Info and Logi Report: General Requirements Browsers: - Internet Explorer: : 7, 8, 9, 10, 11 (Certified) - see Note below about earlier versions - Firefox, Chrome: all current public versions (Supported) - Opera, Safari: all current public versions (Supported) Hardware: 1 GHz or higher processor recommended; 400 MHz minimum required. 1 GB or higher recommended; 512 MB of RAM minimum required. 300 megabytes (MB) of available hard disk space. Operating Systems: - Suse, Red Hat, Ubuntu, CentOS and just about any other flavor of Linux - Solaris, HP-UX (Limited support) - Windows Server 2012 R2, 2008, 2003 - Windows 7 (all editions) - Windows Vista (Business, Enterprise, and Ultimate editions only) - Windows XP Professional - 32- and 64-bit Windows OS and Linux OS support Web Servers: - Apache-Tomcat 5.5, 6.0, 7.0 (without Tomcat FHS) - JBoss 4, 5, 7 - Sun GlassFish (SJSAS) 2.1, 3.0, 3.1 - BEA WebLogic 10 - Oracle WebLogic 12c - IBM Websphere 7, 8.5 Software: The following components must be installed: (Development machine) - For products prior to v11.0.127, Microsoft .NET Framework 2.0 or 3.x - For v11.0.127 products and later, Microsoft .NET Framework 4.x (Web server) - Java Development Kit (JDK)t 1.6, 1.7, or 1.8 or complete JVM such as JRockit. OpenJDK is not supported. Data Sources: Logi Info and Logi Report can use any of the following data sources/services: - Amazon SimpleDB - DB2 database server - Files: Excel, CSV, XML - Google Maps, Google Docs 3 - MySQL database server - ODBC-compliant database servers - OLEDB-compliant database servers - Oracle database server Getting Started with Logi Info and Logi Report for Java - HP Vertica - JDBC-compliant database servers - Microsoft Access - Microsoft SQL Server - Microsoft SQL Server Analysis Services - MongoDB - PostgreSQL database server - Salesforce.com - SMTP email servers - Sybase database server - Twitter.com - Web Services (REST and SOAP) Notes: Microsoft Internet Information Server (IIS) must be installed before installing Logi products. Prior to v11.0.127, .NET v2.0 or 3.x was required; for v11.0.127 and later, .NET 4.x is required. If not already in place, with your consent, appropriate versions of the .NET Framework are installed when Logi products are installed. They are also available for free from the Microsoft Download Center Internet Explorer 5 and 6 are no longer considered "modern" browsers, meaning that they have limited support for the current standard browser technologies, including CSS2, JavaScript, and AJAX. Without this support, in Logi applications certain style and visual elements will render incorrectly, transparent backgrounds for charts and other image-related content will be impaired, and problems using features such as our Dashboards and interactive pagination controls will occur. Microsoft has declared the lifecycle of these browsers ended. Internet Explorer 10 is supported in v11.0.519 (14 June 2013), and later. Browser updates are being released so rapidly that it's impossible for us to guarantee that all browser versions will work on a day-to-day basis, or that a new browser release won't be incompatible with an older version of Logi products. How Many Servers Do You Need? You should think of your "reporting server" as a computer that has a web server and the Logi server engine software installed on it. Ideally, this computer should be dedicated to this task alone. However, other configurations are possible and quite feasible, including those in which the web server also serves other functions (i.e. is not dedicated to reporting alone) and/or the database server is also on the reporting server computer. Which configuration should you use? We do not have guidelines based on specific numbers of users or reports to share with you; each deployment situation is different. Whether you choose to combine functions (web, Logi report, and database servers) on one computer is, ultimately, your decision. Numerous factors can affect this decision, including the amount of web server traffic, the number of concurrent database users, the size of the databases, the complexity of the database queries, the frequency of report access, and, not least, cost. You may care to begin with a combined configuration and, as your report usage grows, change to a dedicated configuration. The nature of Logi products allows you to do this easily and without additional cost (if per-server CPU counts remain constant). 4 Getting Started with Logi Info and Logi Report for Java Recent studies concerning server virtualization suggest that database servers are frequently under-utilized. On the other hand, many database vendors recommend that their products be run on a dedicated server. You may wish to check with your database vendor for their recommendations concerning database servers. Server Virtualization Many organizations are using server virtualization to maximize hardware usage and reduce costs. Server virtualization products allow the assignment of CPU resources to processes. This may take the form of a maximum percentage of combined CPU utilization, or as specific allocation of logical CPUs, to a virtual machine (VM). The server administrator is responsible for making these configuration decisions. Logi v10 and later product licenses treat a VM just like a regular, non-virtualized server and run just fine in this environment. In order to ensure good performance in any virtualized server environment, administrators must be careful to allocate appropriate resources to VMs. It's not uncommon to relocate a VM from one hardware platform to another, for example, for hardware maintenance. The Logi license will "move" with the VM, as long as the machine name remains unchanged. 5 Getting Started with Logi Info and Logi Report for Java About Logi Reporting with Java Our Java products consist of two parts: Logi Studio and the Logi Server Engine. When a Java application type is selected during development, Studio generates applications that use the JDK (or other JVM) rather than .NET. The Server Engine includes special components that allow Logi applications to be deployed as Java applications on Windows or Linux platforms. Development Options The process of creating Logi applications is identical regardless of output library choice. Some specialized elements that are included to support the Java environment are available, such as Connection.JDBC, when developing Java applications. The formats of definition, support, and other files that make up a Logi application and are created by developers remain the same for all versions of Logi managed reporting products, regardless of the OS they run under. Logi Studio, though Java-aware, is a Windows application. Developers creating Logi apps use Studio on a Windows PC to develop their Logi applications, regardless of the final deployment environment. Developers have the option of developing and testing their application entirely on a Windows platform before moving it to a production Linux/UNIX server. Deployment Options Logi applications can be deployed on servers running Windows or Linux/UNIX. A Logi application can be moved to one of these servers and enabled to use the JDK (or other JVM) by adding special folders to the application folder (changes in the _Settings definition, such as the application path and connection attributes, may also be necessary). Database Connectivity and Tools Connectivity to databases such as Oracle, MySQL, and MS SQL Server is supported via JDBC. Connections to a variety of other non-database datasources are also supported, including XML, CSV, Excel data files, and web services. Specific MySQL and MS SQL Server database drivers are provided with the Logi Server Engine, so developers do not need to separately download and install them. However, these may not be the correct version for all circumstances and developers may need to update or replace them. In v11.0.416, our SQL Server JDBC driver was upgraded to work with JDK 1.7 and MS SQL Server 2005+. The previous version of the driver's sqljdbc4.jar file, however, is still provided, as sqljdbc4.old, for users who work with MS SQL Server 2000. 6 Getting Started with Logi Info and Logi Report for Java Developers working with Oracle, who wish to use the Database Browser and Query Builder tools within Studio, need to install and configure the Oracle Client (OLEDB) on the Windows platform where Studio for Java is installed. Basic Platform Knowledge Required Developers planning to use Logi for Java applications with Linux/UNIX servers should ensure that they have a good working understanding of the OS, JDK (or other JVM), web server, and management tools on their server. The detailed knowledge required to successfully administer these servers can be extensive and complex and is well beyond the scope of Logi documentation. Product Licenses Current Logi Info and Logi Report versions come with a built-in 15-day trial license. You don't need to do anything but install the product and you can begin using it immediately. A clearly-visible display in the Studio main menu, shown below, counts down the days remaining in the trial period. Clicking the counter display will take you to a web page that offers information about purchasing a Logi Info license. After the trial period expires, Studio won't be usable and any Logi reports you may have developed will no longer run without a real license. Logi Analytics licenses are server-based rather than individual-user or concurrent-access licenses, so an unlimited number of end-users can access Logi reports through a single web server. Our licensing scheme allows you to deploy our product on one development machine and on one production server. As mentioned earlier, additional separate licenses for Studio, for additional developers, are also available. Licenses are keyed to you or your organization; they take the physical form of license files, which are assigned to a specific computer. DevNet includes a License Management page where you can manage your licenses, including reviewing them, assigning and un-assigning them to machines, and generating license files, at any time, without any interaction with our staff. For more detailed information about licenses, see our document Product Licensing. You may not use our products for redistribution with, or embed them in, other products without an OEM license; contact our Sales group for more information if you need OEM licenses. 7 Getting Started with Logi Info and Logi Report for Java Differences from Logi Applications for .NET Generally, Logi Java applications provide all of the features and functionality found in Logi .NET applications. Occasionally new features will first be released for .NET applications and then for Java in subsequent releases. Naturally, Logi apps created for Java do not support Windows-specific technologies such as OLEDB. Analogous Java technologies, such as JDBC, are supported instead. However, for the best results, developers should try to use native connections, such as Connection.MySQL, before using generic connections like Connection.JDBC. JavaScript is the only scripting language available when building Java applications. However, a built-in "VBScript emulator" essentially allows our intrinsic functions, such as IIF(), which are modeled on VBScript, to be available for use in a Java application. Currently, Logi applications for Java do not have support for the following elements: All OLAP elements (note that XOLAP elements, however, are supported) The Salesforce.com Connector (prior to v11.0.416) DataLayer.Web Scraper Prior to v10.0.428, when exporting reports to PDF from a Java application, data table column headers would not be repeated after page breaks. Sharing Session Variables with Other Apps On a web server, Logi applications for Java and regular (non-Logi) Java applications maintain their session variables in different ways. And, typically, Logi application session variables are accessed using @Session tokens, while Java application session variables are accessed via JSP or by using the javax.servlet.http.HttpSession object. If a Logi application for Java is to be integrated with a Java application, then how can their session variables be shared? Prior to v11.0.127, almost all session variables were automatically copied between two integrated applications. However, this behavior did not always produce the best performance and has been discontinued. The Java Session Copying element, introduced in v11.0.127 and available in the _Settings definition, provides a more selective method for session variable copying between the two applications. In order to use this feature, you must not use session variable names that contain spaces in your Logi application, and there's a small performance penalty for this process, so it's best to minimize the number of variables copied. It may be necessary to restart your web server if you edit the lists in the attributes described below. The element has four attributes, consisting of Regular Expressions, which control which session variables are copied. As it can be difficult to write Regular Expressions which both include and exclude strings, we've provided two attributes ("include") which are processed first, followed by two other attributes ("exclude") which are processed second, making it easier to accomplish both types of operations. 8 Getting Started with Logi Info and Logi Report for Java Attribute Copy From Java Exclude Copy From Java Include Copy To Java Exclude Copy To Java Include Description Specifies, as a comma-separated list of Regular Expressions, the Java application session variables that will not be copied to the Logi application session variable space. This attribute is processed after Copy From Java Include, removing variables from that list. Specifies, as a comma-separated list of Regular Expressions, the Java application session variables that will be copied to the Logi application session variable space. Specifies, as a comma-separated list of Regular Expressions, the Logi application session variables that will not be copied to the Java application session variable space. This attribute is processed after Copy To Java Include, removing variables from that list. Specifies, as a comma-separated list of Regular Expressions, the Logi application session variables that will be copied to the Java application session variable space. Once copied, session variables are identified, in the Java app, using its session object's attribute ID and, in the Logi app, as the name used with a @ Session token. For example: Java JSP: session.getAttribute("userEmail") Logi app: @Session.userEmail~ It is possible to return to the pre-v11.0.127 "copy all" behavior by manually adding the following XML to your _Settings definition source code, as a child of the <Setting> tag: <JavaSessionCopying CopyToJavaInclude="^" CopyToJavaExclude="DebugFile,bUsesSort$,-tra$,-xmlDef$, -Xsl$,-rdDef$" CopyFromJavaInclude="^" CopyFromJavaExclude="^rd,^dt" /> 9 Getting Started with Logi Info and Logi Report for Java Installing Logi Studio on Windows There are two major parts to the Logi product in the installation file you downloaded: Logi Studio, our development environment, is a Windows application that's typically installed on a Windows development machine and interacts with the local IIS web server for Logi application development and testing. The Logi Server Engine is a set of files that's part of each Logi application and which provides an extension to the IIS web server at runtime. When you build a Logi application, Studio adds the Engine files to the application. The engine also includes a Windows utility application, Logi Server Manager, which allows you to perform basic configuration of Logi applications without using Studio. A very typical installation scenario is to install Studio and the Server Engine on a Windows development machine, and then install only the Server Engine (including Server Manager) on the production web server. This "development and production" dual installation is allowed by our licensing scheme. Additional copies of Studio may be licensed and installed on additional development machines. There are a number of ways to deploy your Logi applications to production, including Studio's built-in Application Deployment tool. Other installation scenarios, involving shared network drives and team development, are feasible and can be used. This document covers installation of Studio and the Server Engine on a development machine, but you'll also see what's needed to install the Server Engine on a production server. 32- or 64-bit? Logi Info and Logi Report are both available for 32-bit and 64-bit systems. There are different Logi product distribution files for 32-bit and 64-bit versions, so be sure you downloaded the right one for your system. Preparing to Install Logi products work with all editions of Windows 7 and the examples that follow use that OS. Installation for other Windows OS versions is similar with differences noted below Use the Administrator Account Windows 7 includes a number of security enhancements that impact software installation and it is critical that installation and configuration occur while using the software with the built-in "Administrator" account. 10 Getting Started with Logi Info and Logi Report for Java Even if your personal account has been added to the local Administrators Group, it may not have sufficient privileges, so don't rely on it. As shown at left, the correct practice when running the Logi installation program or using the Command Line to make configuration adjustments is to start the tool by right-clicking its icon and selecting "Run as administrator" from the menu to start the program. This ensures that appropriate permissions are provided for the installed components. Don't see a "Run as administrator" option? If the system is in a network domain, your network admin may have created security policies that don't allow you to see this option, in which case you need to consult your IT staff for assistance. If you’re working the Windows Server or Windows XP operating systems, ensure that you have logged into the machine using an account that’s included in the machine’s local Administrator group. .NET Framework Logi Studio requires the .NET Framework components. When Windows 7 and Vista are installed, multiple versions of the framework are typically included. Before doing anything else, ensure that you have .NET installed by using File Explorer to browse to: C:\Windows\Microsoft.NET\Framework where you should see several folders, such as v2.0.50727, one for each version of .NET installed. Prior to v11.0.127, .NET v2.0 or 3.x was required; for v11.0.127 and later, .NET 4.x is required. If not already in place, with your consent, appropriate versions of the .NET framework are installed when Logi products are installed. They are also available for free from the Microsoft Download Center. Installing/Enabling the IIS Web Server When Windows 7 is installed, the components for the IIS web server are also installed, but they’re usually not enabled. You must do this manually, before you install your Logi product. 11 Getting Started with Logi Info and Logi Report for Java 12 Getting Started with Logi Info and Logi Report for Java This is accomplished in Control Panel, under Programs → Turn Windows features on or off, as shown above. It is very important that you select all of the options shown for now. Under "World Wide Web Services" you will need to expand and check all sub-items - ensure that you have check-marks in all the boxes shown above! For other Windows operating systems, you will need to use the Control Panel utility to actually install IIS: The example above shows how to navigate within Control Panel to install IIS. Finally, you need to configure IIS. First, ensure that the ASP.NET web service extension can run: 13 Getting Started with Logi Info and Logi Report for Java In Windows 7, this is done in the IIS Manager tool, as shown above, by selecting the Home item at the left, then double-clicking the ISAPI and CGI Restrictions items. If the ASP.NET entry (or entries) is marked Not Allowed, edit its settings and check the Allow extension... checkbox. For other Windows operating systems, this is done in the IIS Manager tool, by selecting the Web Service Extensions item in the left hand tree list, as shown above. 14 Getting Started with Logi Info and Logi Report for Java Then ensure that the Web Service Extension for the latest ASP.NET version you have installed (or a different version, if you prefer) has been set to Allowed. Select the item and click the Allow button if necessary to assign this status (if using the Standard view, right-click the entry and select Allow from the popup menu). The IIS "Default Web Site" When it's enabled, IIS creates a "Default Web Site" and the New Application wizard in Logi Studio expects to create all new Logi applications as virtual directories of that web site. If you have renamed, replaced, or disabled the "Default Web Site", or have installed another web server that handles HTTP requests on Port 80, the wizard will fail during its application registration phase. Under these circumstances, you can continue to use Logi Studio to develop Logi applications but you will need to manually register them. This process is described in our document Windows IIS Configuration. Installing the Software As usual, you can click Back at any time before the physical installation begins to go back to the previous screen. 1. 15 For Windows 7, start the installation by right-clicking the Logi product installation program icon and selecting "Run as administrator" to launch the installer. For other Windows operating systems, just double-click the Logi product file icon. Allow it to complete the installation preparation. Getting Started with Logi Info and Logi Report for Java 2. When the Welcome Screen appears, click Next. 3. License Agreement: Select the "I accept the terms..." radiobutton after reading the license agreement and click Next to continue. 16 Getting Started with Logi Info and Logi Report for Java 4. Destination Folder: Optional - click Change to specify an alternative installation location if you don't like the default location. Multiple versions may be installed on the same machine and will co-exist smoothly using the default values here. Click Next to accept the installation location and continue. 5. 17 Setup Type: Select the Typical or Custom radiobutton (see Custom information below) and click Next to continue: Getting Started with Logi Info and Logi Report for Java If you selected a "Typical" setup, skip ahead to Step 6. If you selected a "Custom" setup, the dialog box shown above appears. The following components are available during a Custom setup: Studio - The integrated development environment used by developers to create applications and report definitions. Server - The Logi Server Engine that processes XML data in report definitions and outputs HTML. LogiXML Scheduler Service for .NET- The Logi Windows Service that manages scheduled events; required if you want to have scheduled report generation and distribution. Not available in Logi Report. LogiXML Scheduler Service for Java- The Logi Java daemon that manages scheduled events; not applicable when using the .NET version of Logi Info. Not available in Logi Report. Left-click any of the components shown and make a selection from the popup menu to include them in the installation. If desired, click Space to review the disk space requirements for the Custom setup you've selected. Click Next to proceed without the review. 18 Getting Started with Logi Info and Logi Report for Java The Disk Space Requirements display gives you information about available storage space and warns you if there isn’t enough space for the installation. You can repeatedly adjust the components in the Custom setup and see the effect on storage here, if necessary. Click OK to return to the previous dialog box. 19 Getting Started with Logi Info and Logi Report for Java 6. Ready to Install: Review the installation summary and click Install. 7. The physical installation will begin and you'll see several progress indicators for different tasks. 20 Getting Started with Logi Info and Logi Report for Java 8. Installation Complete: If you’re using Windows 7 and have User Account Control (UAC) turned off, or if you’re using another Windows OS, you can click Finish to exit the installer and launch Studio, and skip the next two steps. If UAC is not turned off, uncheck the "Launch Logi Studio" checkbox, then click Finish and proceed to the next two steps. 9. Use the Computer browser to navigate to C:\Program Files. Right-click the LogiXML IES Dev folder and select Properties. In the Security tab, add NETWORK SERVICE to the list of user names and grant it Full Control. Repeat the process, granting Full Control to your own account (and to any other Logi developers who will work on this computer). 21 Getting Started with Logi Info and Logi Report for Java 10. You may now launch your Logi product and you should see a splash screen like the one shown above. Installation is complete. However, go on to the next section to complete the IIS configuration. Configuring IIS First, using the IIS Manager tool provided with the OS, ensure that the ASP.NET extension is allowed to execute: This is done, as shown above, by selecting the Home item at the left, then double-clicking the ISAPI and CGI Restrictions item. If the ASP.NET entry (or entries) is marked Not Allowed, edit its settings and check the Allow extension... checkbox. Next, you must ensure that either your Default Web Site, or your individual Logi application virtual directories (when you create them), have the correct .NET Trust Levels assigned: 22 Getting Started with Logi Info and Logi Report for Java In order to be able to cache data, interact with handlers, and perform other required operations, the .NET Trust Levels must be set to Full (Internal), as shown above. Finally, here's a "best practices" tip for configuring IIS for use with Logi applications: We recommend that you create a new Application Pool specifically for your Logi applications, as shown above, left. Then you will need to assign your Logi app virtual directories to it by editing their Basic Settings and selecting the new pool, as shown above, right. This allows you to manage and restart the pool independently of any other non-Logi applications that are also using IIS. Beginning in v10.0.385, Logi apps can use the default Integrated pipeline mode in application pools, resulting in better performance; Logi apps built using earlier versions must use Classic mode. 23 Getting Started with Logi Info and Logi Report for Java Modifying or Repairing the Installation Suppose you installed Logi Info but didn't initially install the Scheduler, and now you find you want to schedule reports. Or you suspect a Logi Studio .DLL file is missing or is corrupted and you want to fix it. These kinds of situations can be addressed by either modifying or repairing the installation, which you should do by re-running the installation program file (don't forget to right-click it and use "Run as administrator" to start it). Do not use Control Panel → Programs to do this; it will request an .msi file, which is not retained after the original installation. 24 Getting Started with Logi Info and Logi Report for Java Product Licensing Logi Analytics licenses are server-based, rather than individual-user or concurrent-access, licenses, so an unlimited number of end-users can access Logi reports through a single web server. Our Logi Info and Logi Report licensing scheme allows you to install our product on one development machine and one production server. A license is required for both our development tool, Studio, and for our Server Engine. Your development system will likely require both but production web servers generally do not need Studio installed on them. So, we offer both a "Studio and Development Server" combination license and a standalone Server license, and this two-license approach allows flexibility in different situations. If you upgrade an existing installation of our products from one major version to another major version, for example version 10 to version 11, you will need a new license. A version 10 license will not work with version 11. Contact Customer Service if you want to upgrade and need a new license. Built-in Trial License All Logi v11 and v10 products come with a built-in 15-day trial license. You need do nothing but install the product and you can begin using it. A clearly-visible display in the Studio toolbar, shown below, counts down the days remaining in the trial period. In addition, the number of days remaining is displayed in the Debugging Trace Page, available when debugging is turned on. Clicking the Studio counter display will take you to a web page that offers information about purchasing a product license. After the trial period expires, Studio and any Logi reports you may have developed will no longer run without a real license License Keys and License Files When you purchase a Logi product, here's what happens in the licensing process: 1. A license key, specific to you or your organization, is created for you by our staff and stored in our licensing database. 2. You visit DevNet's License Manager page to create a license file. You do this by assigning your license key to a specific computer, by Computer Name. DevNet then generates a license file. 25 Getting Started with Logi Info and Logi Report for Java 3. You then download this file and use it to license each Logi Info/Report application you develop. A typical license file name is lgx100201.lic and licenses are product-specific. This licensing scheme is the same for both .NET and Java deployments. When you download your license file, you save it in C:\Program Files\LogiXML IES DEV\LogiStudio to license any new apps, and in the application folder of any existing Logi application that you've created with a trial license or that you'll be updating to v11 or v10. If you need to move an application to another machine, or re-install your Logi product on a different machine, you can "un-assign" the license from one machine, assign it to another, and generate a new license file. OEM licenses operate in a similar fashion, but can be assigned to multiple machines. Centralized License File If you have a large number of Logi apps on the same web server, you may care to use a single, centralized license file rather than manage multiple copies of it. In versions 11 and 10, the General element in the _Settings definition includes a License File Location attribute where the location of the license file is specified. This value is a fully-qualified web server file system path to the folder where the file is stored. For example, C:\myProjects\License. You must ensure that all web applications that will use this license run under an account that has security permissions to access files in the folder you specify in License File Location. With this centralized license approach, if you use the exact same file path to your license file on both your development machine and your production server, you can deploy Logi applications by copying them, without having to replace the license file or adjust your _Settings definition attributes each time. OEM License File Customers with OEM licenses can embed the entire license inside their Logi application. In the _Settings definition, the General element has an OEM Distribution License attribute which allows Logi applications to run on a server that does not otherwise have a license key installed. This is especially useful for XCOPY-type deployments: the Logi installation program does not have to be run on the web server. To use this attribute, double-click the attribute name to open its Zoom window and then copy the entire XML contents of your OEM license file into it. This attribute only works with OEM licenses; other types of licenses copied into here will be ignored. License Management Our DevNet web site includes a License Management page where you can manage your licenses. In order to manage your licenses, you must be a DevNet member and login first. 26 Getting Started with Logi Info and Logi Report for Java The details of the License Management page are shown above and here's an explanation: 1. Product - This select list displays the names all products licensed to you; select a product to display its licenses. Filtering and search capabilities are available to refine the list, too. 2. License Key - The license "key" created for you when you purchased the product appears here. 3. Version, Type & Expires - The license version and type and any expiration date appear here. 4. License - Click the "Create" link in this column to assign your license to a specific machine. Once done, the machine name will appear in the next column and the link will change to "Download". Click the link again to download and save your license file. You may download the file as many times as necessary but it's only valid on the assigned machine. 5. Assigned To - This column displays the name of the machine a license has been assigned to. The "X" link allows you to "un-assign" the license - when this is done, the License link will revert back to "Create", and you may assign the license to another machine. 6. Note - This column displays optional text you enter to help you more easily identify the computer. Click the edit icon to add or edit this text. 7. History - This link allows you to track the history of assignments for this license. Here are the details of the process of creating and downloading a license file: 27 Getting Started with Logi Info and Logi Report for Java If the link in the Licenses column of the table shown earlier says "Create", clicking it will display the Create License File pop-up panel, shown above. You use it to assign the license to a specific machine, by entering the computer name. The Optional Note input is for your use if you want to further identify the machine and its text appears in the table of licenses shown earlier. If the computer on which this license is to be used runs a Windows OS, then the computer name value is what's known in Windows parlance as the "machine name". You can open a Command Prompt window on the machine and enter "hostname", then press Enter to have the name displayed. If a multi-part name is displayed, such as "myPC.myCompany.local", use just the first part, "myPC". If the computer on which this license is to be used runs a Linux or other UNIX-derivative OS, then the "computer name" value is the computer's "hostname". You can go to a command line and enter "#hostname", then press Enter to have the name displayed. Use the full hostname value, exactly as it's displayed, for your computer name value entry. Click OK to generate the license file for the designated computer. 28 Getting Started with Logi Info and Logi Report for Java Once the license file has been generated, the link in the Licenses column will change to "Download". Click this link to display the Download License File pop-up panel, shown above. Click the Download button to download and save the license file. If the computer on which this license is to be used runs a Windows OS, then save the license file to C:\Program Files\LogiXML IES Dev\LogiStudio This will provide licensing for development work using Logi Studio, as well as for new Logi applications that are developed on the machine and run there using any web server. If you're upgrading any older Logi applications, you'll also need to copy the license file into their application folder. When a License Expires After the 15-day trial license period expires, Studio won’t start up and any Logi reports you've developed will no longer run unless you have a real license. Instead a banner, similar to the one shown above, will be displayed at the top of each report. If you've purchased a regular license and for some reason it expires, a 7-day grace period will start. At the end of the grace period, reports will no longer run and the banner will be displayed. 29 Getting Started with Logi Info and Logi Report for Java The banner will also appear if the license file can't be found. For example, failing to place a copy of the license file in the application folder after a major version upgrade or a deployment will cause the banner to be displayed. In all cases, providing a valid license in the correct location will remove the banner and let the application run. Licenses and Server Virtualization Many organizations are using server virtualization to maximize hardware usage and reduce costs. Server virtualization products allow the assignment of CPU resources to processes. This may take the form of a maximum percentage of combined CPU utilization, or as specific allocation of logical CPUs, to a virtual machine (VM). The server administrator is responsible for making these configuration decisions. Logi v11 and v10 product licenses treat a VM just like a regular, non-virtualized server and run just fine in this environment. In order to ensure good performance in any virtualized server environment, administrators must be careful to allocate appropriate resources to VMs. It's not uncommon to relocate a VM from one hardware platform to another, for example, for hardware maintenance. The Logi license will "move" with the VM, as long as its machine name doesn't change. 30 Getting Started with Logi Info and Logi Report for Java Upgrading Logi Products and Apps Each new release of Logi Analytics managed reporting products provides feature enhancements and improvements. Customers are encouraged to take advantage of these improvements by upgrading to the latest releases when they become available. These instructions provide guidance for the process of upgrading, uninstalling, or modifying your Logi product installations and managing the related versions of your Logi applications. The installation tool, InstallShield, does not remove any files or folders created or modified after the initial installation, including Sample Applications that you may have modified, so your report definitions are safe during an upgrade. General Requirements Logi products for the Windows environment and Logi Studio require the .NET Framework. Prior to v11.0.127, .NET v2.0 or 3.x was required; for v11.0.127 and later, .NET 4.x is required. If not already in place, with your consent, appropriate versions of the .NET framework are installed when Logi products are installed. They are also available for free from the Microsoft Download Center. Separate installations of different versions of Logi products can co-exist as long as they are installed in different directories. IIS 6 users may need to implement Application Pools to isolate Logi applications using different .NET framework versions. This is an IIS configuration task and is explained later in this document. Application Pools are a standard feature of IIS 7+. Upgrade Impacts Logi v11 and v10 products include several changes you should know about before upgrading: 31 Logi v11 products include stylistic and appearance improvements in charts, super elements, themes, etc. which are noticeably different. You may care to do a test upgrade before committing to a comprehensive upgrade. Starting with v11.0.518, when using IIS 7+, you must use Application Pools that use .NET 4.0. If such an application pool doesn't exist, Studio will create one, named "Logi Info .Net v4.0" when you upgrade an existing Logi application or create a new one, and will assign the application to it. Logi Info v10 and 11 includes a free, 15-day trial license but, when it expires, you will need a paid, regular license. If you're a customer in good standing, Logi Customer Service will assign that license to you in advance, but you will need to go to DevNet and download the license file. Getting Started with Logi Info and Logi Report for Java A new version of the Logi scripting engine was included with v10. In any application being upgraded to v10 or 11 from earlier versions you will need to engage it manually by adding the following casesensitive constant, using the Constants element, to the application's _Settings definition: rdScriptingEngine = Version10 Major browsers continually tweak their features, especially their JavaScript handling. Once you upgrade your Logi application, you may find that you need to make small adjustments to any JavaScript code you‘ve written. Logi Report has been discontinued as a free product. Existing Logi Report installations, and applications developed with it, will continue to work as before. Logi Report v10 or 11 users who registered on DevNet and secured a free, standard (non-trial) license are still able to manage their license files on DevNet. Those with OEM, maintenance plans, or other contracts involving Logi Report will experience no change in their use of the product. You are urged to visit the DevNet Release Notes page for your product to understand the technical changes in new versions, before upgrading. Upgrading the Products Upgrading to a new version involves two steps: installing the new release of your Logi product, and upgrading the version of any existing Logi applications. You can do the former without doing the latter; applications are not automatically upgraded. Original and upgraded applications can co-exist, so upgrading can be phased in as desired. How do you get an upgrade? Customers who have purchased a maintenance plan for Logi Report or Logi Info, or are using them under an OEM agreement, should contact Logi Customer Service via email or telephone (703-752-9700 x148) for instructions for downloading upgrades. Customer Service can also answer questions you may have about purchasing or renewing a maintenance plan. To upgrade your Logi product, run the downloaded installation program and install the new version into the same location as the previous version, or to a different location if you wish to have both versions installed. No un-installation of the original version is required, and existing definitions or data will not be overwritten. The upgrade installation will take 2-3 minutes to complete. If you wish to install an upgrade for evaluation purposes, we recommend that you install it into a different folder than any previous version, such as C:\Program Files\LogiXML IES Dev Test. This will preserve the previous version of Studio. If you install an update into the same folder as a previous version, Studio will be updated and you will not be able to roll it back without uninstalling and re-installing the previous version entirely. If you have previously installed and used the Logi Scheduler service, we recommend that you make a safety copy of your existing schedule data, before upgrading: (Win .NET) C:\Program Files\LogiXML IES Dev\LogiXML Scheduler Service Java\Schedules.vdb3 (Win Java) C:\Program Files\LogiXML IES Dev\LogiXML Scheduler Service Java\Schedules\*.* (Lin/UNIX) <installFolder>/Schedules/*.* and then proceed with the upgrade installation. Your existing data file should be upgraded in place without any difficulty. 32 Getting Started with Logi Info and Logi Report for Java Changing the Version of Your Logi Applications Logi applications are individually tagged with a version identifier for, and contain files specific to, the product version used to create them. When a new version of a Logi product is installed, your applications are not automatically upgraded. This allows you continue to use both versions of the product and upgrade your applications on your timetable. In order to use all of the features in the latest Logi release, you will need to change application versions on any machines, development or production, where you upgrade your Logi product. When you open an application, Studio displays a warning in its Application tab, as shown above, if the application's version does not match the version of Logi Info and Studio being used. Clicking the Change Version... link will cause the application's version-specific binary files to be replaced with the files for a version you select from a list of installed versions. This will not affect any definitions or support files. A progress indicator, like the one shown above, will be displayed. 33 Getting Started with Logi Info and Logi Report for Java Changing an application version to v11.0.127 or later will also trigger some web server diagnostics to run after the upgrade and you'll see some information about that process. Once the tests end, you'll the results, as shown above. The failure of any test indicates that something is wrong with your web server environment's ability to run the upgraded application. This could be caused by a number of things, such as failing to install the new Logi version as an Administrator, or having incorrect file permissions on the application folder, or failing to have the correct version of .NET installed. Contact Logi Support for assistance. Changing Versions with Server Manager Another method of changing an application's version is by using Server Manager, shown below, which is installed with Studio and is available via Studio's Tools menu or the Start Menu. 34 Getting Started with Logi Info and Logi Report for Java It's a tool that allows you to examine all of the Logi applications on the web server and manage them individually or as a batch. Server Manager is intended for use only with .NET applications, using the IIS or Cassini web servers; if neither of these servers is installed, Server Manager will prompt you to install them. The Server Manager dialog box displays a table showing each application installed on the local web server and a list of all the Logi product versions installed on the machine. To change an application's version, check one or more applications, select the version desired, and click Change Version. The process usually takes less than a minute for each application selected. Versions can be upgraded or downgraded. Creating Application Pools The Application Pool is a method of isolating different .NET applications within the web server, in order to provide improved reliability. In IIS 7, the default application pool, "DefaultAppPool" is created at installation and all virtual directory applications, when created, are assigned to this default pool. However, applications using different .NET versions can't be run at the same time in the same pool. If they are, error messages will appear for whichever application is started last. The recommended practice is to create a new application pool and assign all applications that use the same .NET version to it. 35 Getting Started with Logi Info and Logi Report for Java To create a new application pool: 1. Open the IIS Manager (see All Programs → Administrative Tools ) 2. Select and right-click the Applications Pools item in the list on the left. Select Add Application Pool... from the pop-up menu. 3. Enter the new name of your choice as the Application Pool ID and leave the default pool settings selected. Click OK 4. Right-click the Application Pools item in the list on the left and click Refresh to see your new pool. To assign an application to the new Application Pool: 1. 2. 3. 4. Expand the Sites item in the list on the left, and then expand the Default Web Site item below it. Find and select your application in the list. In the right-hand Actions Panel, click Basic Settings... A dialog box like the one shown above will appear. Click Select... and choose your new Application Pool from the list. 5. Click OK. Your application is now assigned to your new Application Pool. 36 Getting Started with Logi Info and Logi Report for Java Logi Application Overview This chapter introduces Logi Analytics' application architecture. A key concept, Elemental Development, is introduced, along with report definition files, elements and attributes. Elemental Development is the foundation of Logi applications. In this overview, you'll learn how Logi applications deliver content to the web and how to include external files such as images, scripts, and XML data files. Understanding Logi Applications A Logi application generally consists of one or more reports. A report is really a web page so, while Logi products are most frequently used as reporting tools, they can also be used to create rich, web-based applications. The Logi Analytics DevNet web site, for example, is built entirely with Logi Info. Logi reports deliver data in a presentable and accessible manner as web pages. They use Internet technologies and browser software to distribute rich, interactive reports and applications. Logi reporting tools bring leadingedge Internet technologies together, allowing developers to quickly deliver results efficiently. The framework underlying this consists of: An integrated development environment (Logi Studio) An XML-based language, coded in text-based definition files A runtime server (the Logi Server Engine) Logi reporting tools separate the report development, data access, and presentation processes: 1. Report definitions are text files that contain the information describing report layout and contents, stored as XML data. While it is possible to write definitions with any text editor, Logi Studio provides an integrated development environment with lots of tools and helpful wizards that do much of the coding for you and reduce development time. 37 Getting Started with Logi Info and Logi Report for Java 2. When a report is requested, the Logi Server Engine on the web server parses the report definitions and accesses data sources as required. 3. The retrieved data and presentation details are formatted based on the definition and accompanying style sheets; HTML and script is generated and returned to the user's browser for viewing. This arrangement allows the Logi Server Engine to operate as a stand-alone entity that's completely independent of systems that call upon it for reports. Separate applications, regardless of their host OS, environment, or development language, that wish to embed or access Logi reports, for example, need only include a standard hyperlink to do so. The Windows version of the Logi Server Engine is an ASP.NET application, so Logi report applications can also be integrated directly into other ASP.NET applications. The Java versions of our products, for use in Linux/UNIX environments, have been created using the MainSoft toolset, which ports .NET applications to the Java world. Introducing Elemental Development Elemental Development is the process of creating flexible reporting applications using predefined, XML-based objects or "elements". The advantages of Elemental Development are: XML elements are reusable and encapsulate specific functionality common to most web applications A hierarchical layout of elements makes it easy to manage the presentation and functionality of large web-based reports Studio's drag-and-drop user interface shields developers from repetitive coding and shortens development time Elements and their properties (or "attributes") can be easily added, deleted, moved, and modified to create almost any type of report Rules governing the parent-child associations that can be made between elements are embedded in our Studio development tool. Developing reports using elements makes the process quick and intuitive, and saves the developer the work of creating lower-level functionality. For more about Elemental Development, see this White Paper: http://devnet.logianalytics.com/downloads/ED_WhitePaper.pdf Definition Files Developers using Logi reporting tools create one or more definitions to build web-based applications. One report definition is equivalent to one dynamic web page. Every Logi application contains at least one report definition and can include multiple definitions as the application grows. 38 Getting Started with Logi Info and Logi Report for Java Other types of definitions can also be part of a Logi application. The example above shows Logi Studio's Application Panel and the six major types of definition files found in Logi applications, which are described below: Definitions _Settings Reports Mobile Reports Widgets Templates Processes Description (Required) The one _Settings definition in every Logi application contains global configuration values for the entire application. It contains elements that define the application's virtual path, debugging capabilities, database connections, security information, and more. This folder may contain report definitions built with elements that define a dynamic web pages. A report definition typically contains report header and footer elements and a body element. The main body of the report can include any combination of text, charts, dashboards, data tables, user input controls, etc. Introduced in v10.0.259, this folder may contain report definitions that are used exclusively to deliver content to mobile devices, built with a combination of common and special-purpose elements. Not available in Logi Report. This folder contain may contain definitions for a special class of Logi reports that can be independently embedded into external HTML pages. Not available in Logi Report. This folder contains definitions that allow Logi Info developers to use forms-based reporting, using Word, Excel, and PDF forms. Template definitions model the "fill-able" form fields contained within the source template file. Available in Logi Report v10.1.59+. This folder may contain definitions that provide a level of automation and contain the logic needed to perform specific tasks within an application. Process tasks can be used to perform scheduled operations, such as exporting a report to PDF format or then emailing it to a group of recipients. Not available in Logi Report. From XML to HTML... Every definition file created with Logi Studio is an XML document, which describes multiple objects we call elements and their attributes. Elements encapsulate different types of functionality and presentation; attributes enable developers to customize element properties and behavior. For example, a DataLayer element retrieves data from a data source and a Chart.Pie element creates a pie chart from the data. The Chart.Pie element has attributes to specify the chart’s height, width, radius, color, and more. 39 Getting Started with Logi Info and Logi Report for Java The image above left is an example report definition, "Test3", which contains Style Sheet and Body elements. The Body element has a "child" element: a Label element, which has a Caption attribute. The Source code for this report (middle image) shows the underlying XML source code generated in Studio. The Logi Server Engine processes the XML source code, generating the HTML needed to present the page in a web browser (right image). Using Support Files with a Logi Application Studio's Application Panel also includes a folder for Support Files. These are files that are part of the application but are not definitions built using elements: Logi applications may include the following types of Support fAiles: 40 Style Sheet - Cascading Style Sheet (CSS) files for presentation control Script - JavaScript or VBScript files Image - GIF, JPG, PNG and other types of image files Template - Word, Excel and PDF form template files Getting Started with Logi Info and Logi Report for Java XML - XML data files as a data source for report definitions HTML - Custom HTML web content to be included within the application Application Deployment All of the files that typically make up a Logi application reside under one folder, the application folder. This folder is registered with the web server as a "virtual directory" and though most often located on the web server, can be located on any network-connected server. Distributing Logi applications, such as deploying them from a developer server to a production server, is a simple matter of copying the application folder to the production server. Studio includes a convenient Application Deployment Tool that deploys applications using a variety of techniques techniques and is discussed in a later section of this document. Additional Helpful Information If you're a developer who's just getting started with Logi Info or Logi Report, you may not be aware of all of the features available in the products. If you'd like a visual introduction to the elements, see our Element Gallery. DevNet also includes a number of free sample applications that you can download and run in Studio to see the techniques used to produce a variety of reporting applications. 41 Getting Started with Logi Info and Logi Report for Java Java Server Configurations Logi products work with a variety of Java-based web servers, which often require specific configurations to work correctly and for optimum performance. This chapter provides the details of these configurations for each server, including: Apache Tomcat 5.5 / 6.0 / 7.0 JBoss 4 JBoss 5.1 JBoss 7.1 Sun Glassfish (SJSAS) 2.1 Sun Glassfish (SJSAS) 3.0, 3.1 BEA WebLogic 10 Oracle WebLogic 12c IBM Websphere 7, 8.5 General Information Some general configuration rules: The official Sun JDK 1.6 or 1.7 is required for non-Apple platforms. JDK 1.6 is required for Apple platforms. The JRE is not sufficient and "OpenJDK" is not supported, but Oracle JRockit can be used. It's possible to use Logi products on systems that use symbolic links or the Filesystem Hierarchy Standard (FHS), but it makes configuration much more complicated and we don't recommend it. When Logi Studio creates a new application, it's deployed in exploded format within a single "Logi application folder", not as a WAR file. WAR deployments are not supported at this time. Setting Java Options The following JVM flags should be added to the Java options settings that used to tune/monitor the JVM. The Performance Settings are strongly recommended for the Sun JDK, whereas the JConsole and Tracing Settings are optional but recommended, at least during initial implementation: Typical Performance Settings (required) JConsole Settings (optional, for monitoring) 42 "-server (JDK) -Xmx1280m (JDK and JRockit) -XX:MaxPermSize=256m (JDK) -XX:-DisableExplicitGC (JDK) -XX:CompileThreshold=8000 (JDK) -Djava.awt.headless=true (JDK and JRockit) -Dcom.sun.management.jmxremote -Djava.rmi.server.hostname=<your host ip addr> -Dcom.sun.management.jmxremote.port=1099 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false Getting Started with Logi Info and Logi Report for Java Tracing Settings (optional, for testing) -verbose:gc -Xprof -XX:-CITime -XX:-PrintCompilation -Xloggc:$CATALINA_HOME/logs/gc.log -XX:+PrintGCDetails -XX:+PrintGCTimeStamps" For 64-bit JVMs you need to add a -d64 flag in the Performance Settings to force the JVM to use 64-bit addressing, if the flag is supported. It is supported in the JDK, but not in JRockit, for example. The $CATALINA_HOME environment variable in the example refers to the folder into which Apache Tomcat has been installed; for other web servers substitute the appropriate variable. The JDK includes the Java Monitoring and Management Console (JConsole) tool. It uses the extensive instrumentation of the Java virtual machine to provide information on the performance and resource consumption of applications running on the Java platform using Java Management Extension (JMX) technology. For more information about JConsole, see this article. About the Performance Settings What do the performance settings recommended above actually do? Here's an explanation: Setting Descripton -server This option instructs the launcher to run the Java JVM in Server Mode. The JVM can optimize a number of things for server environments, improving performance. -Xmx This option sets the maximum amount of memory that can be allocated to the JVM heap, improving performance. -XX:MaxPermSize This option sets the maximum amount of memory that can be used for the permanent generation, or "PermGen", Java's fixed block of memory for loading class files. Failure to set this to at least 128m will cause errors to occur and a setting of 256m is recommended. -XX:-DisableExplicitGC This option disables calls to the function System.gc(), which is often run explicitly by many classes. When it runs, it triggers a full garbage collection process, which consumes a lot of execution time and results in inefficient heap usage. When it's disabled, the JVM still performs garbage collection nonetheless, whenever necessary. -XX:CompileThreshold This option sets the number of method invocations/branches before compiling. The JVM usually waits for a method to be executed a certain number of times before it's compiled. Not compiling every method helps startup time and reduces RAM footprint. This option allows you to control that threshold. -Djava.awt.headless This option, when set to true, prevents graphics rendering code from assuming that a graphics console exists, avoiding any chance of encountering an obscure Java bug related to X-servers and graphics rendering. 43 Getting Started with Logi Info and Logi Report for Java Apache Tomcat 5.5 / 6.0 / 7.0 1. Logi application folders must be stored beneath the webapps folder. 2. Use the environment variable $CATALINA_OPTS to pass in the JVM flags described above to the Tomcat start-up script. The $CATALINA_HOME environment variable in the example refers to the folder into which Apache Tomcat has been installed. Special Connection Pooling for Oracle in Connection-Intensive Environments Logi applications may quickly open and close dozens of database connections and, in some connectionintensive environments, this may cause server resource problems. The following configuration changes for Tomcat implement connection pooling and have been tested with our Connection.JDBC and Connection.Oracle elements: For server-wide connection pooling, change these files: 1. Add this to the file $CATALINA_HOME/conf/web.xml: <resource-ref> <description> DB Connection Pooling</description> <res-ref-name> jdbc/Oraclecp</res-ref-name> <res-type> javax.sql.DataSource</res-type> <res-auth> Container</res-auth> </resource-ref> 2. Create a new file $CATALINA_HOME/conf/context.xml, containing the following: <?xml version="1.0" encoding="UTF-8"?> <Context> <Resource name="jdbc/Oraclecp" auth="Container" type="javax.sql.DataSource" removeAbandoned="true" logAbandoned="false" maxActive="20" maxIdle="3" maxWait="10000" removeAbandonedTimeout="30" username= "<yourUsername>" password="<yourPassword>" factory="org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory" driverClassName="oracle.jdbc.OracleDriver" url="jdbc:oracle:thin:@<yourServerName>:1521:BMBTDEV"/> </Context> 3. Copy the "ojdbc6.jar" file from <LogiAppFolder>/WEB-INF/lib to <TomcatInstallFolder>/common/lib 4. Manually edit your Connection element attributes in _Settings.lgx (using the Source tab in Studio's Workspace) to be: Connection String = jndi-datasource-name=jdbc/Oraclecp These links provide additional information about connection pooling: 44 Getting Started with Logi Info and Logi Report for Java http://www.onjava.com/pub/a/onjava/2006/04/19/database-connection-pooling-with-tomcat.html http://java.sun.com/j2se/1.4.2/docs/guide/jdbc/getstart/datasource.html http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html JBoss 4 The following configuration details apply for JBoss 4: 1. Delete the files <LogiAppFolder>/WEB-INF/lib/log4j-1.2.8.jar and <LogiAppFolder>/WEBINF/classes/log4j.properties 2. Auto-deploy is used with this server so either manually or through Logi Studio's New Application wizard, give the root folder for your Logi application a .war file extension. Ensure that this folder is placed beneath whatever folder you've configured as your auto-deploy folder, for example: jboss/server/default/deploy/myLogiApp.war See the Hello World! Tutorial for some examples of working with the New Application wizard. 3. The startup batch file "run.bat" may include the following line: set JAVA_OPTS=%JAVA_OPTS% -Xms128m Xmx512m. This must be prevented from overriding our required Java Options environment settings (see the General section, above). Users can either modify the batch file or the environment variable. 4. Logi v10.0.114+ users: JBoss ships with a xerces library that conflicts with Logi's implementation of it, so remove the following .jar files from the <LogiAppFolder>/WEB-INF/lib folder prior to deploying: xml-apis-1.3.04.jar xml-apis-ext-1.304.jar xercesImpl-2.7.1.jar JBoss 5.1 The following configuration details apply for JBoss 5.1: 1. Auto-deploy is used with this server so either manually or through Logi Studio's New Application wizard, give the root folder for your Logi application a .war file extension. Ensure that this folder is placed beneath whatever folder you've configured as your auto-deploy folder, for example: jboss/server/default/deploy/myLogiApp.war See the Hello World! Tutorial for some examples of working with the New Application wizard. 2. Set the Java options by editing $JBOSS_HOME/bin/run.conf so that it includes: -Xmx1280m -XX:CompileThreshold=8000 -Djava.awt.headless=true 3. Edit <LogiAppFolder>/WEB-INF/web.xml and add the following: <context-param> <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name> 45 Getting Started with Logi Info and Logi Report for Java <param-value>true</param-value> </context-param> 4. Logi v9.5.x users: Right-click this link mscorlib.jar and save our customized version of the file in <LogiAppFolder>\WEB-INF\lib, replacing the standard file of the same name. 5. Logi v10.0.114+ users: JBoss ships with a xerces library that conflicts with Logi's implementation of it, so remove the following .jar files from the <LogiAppFolder>/WEB-INF/lib folder prior to deploying: xml-apis-1.3.04.jar xml-apis-ext-1.304.jar xercesImpl-2.7.1.jar JBoss 7.1 The following configuration details apply for JBoss 7.1. We do not recommend using JBoss 6. 1. Auto-deploy is used with this server so either manually or through Logi Studio's New Application wizard, give the root folder for your Logi application a .war file extension. Ensure that this folder is placed beneath whatever folder you've configured as your auto-deploy folder, for example: jboss/server/default/deploy/myLogiApp.war See the Hello World! Tutorial for some examples of working with the New Application wizard 2. Set the Java options by editing $JBOSS_HOME/bin/run.conf so that it includes: -Xmx1280m -XX:CompileThreshold=8000 -Djava.awt.headless=true 3. Edit <LogiAppFolder>/WEB-INF/web.xml and add the following: <context-param> <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name> <param-value>true</param-value> </context-param> 4. If your JBoss server isn't capable of dynamic deployment, or you're not sure about the server settings, restart your JBoss server, using bin/standalone.sh. 5. Use a specific port and parameter when browsing the Logi applications. For example: http://localhost:port#/yourLogiApp/rdpage.aspx?rdReport=Default and be sure to use the correct case-sensitive spelling of the Logi report definition file name, e.g. Default vs default. 46 Getting Started with Logi Info and Logi Report for Java Sun Glassfish (SJSAS) 2.1 1. The root folder for any Logi application must be manually given a .war file extension and should be manually deployed using the Glassfish Admin Console. 2. Right-click this link sun-web.xml and save our customized version of the file in <LogiAppFolder>\WEB-INF, replacing the standard file of the same name. Sun Glassfish (SJSAS) 3.0, 3.1 1. Manually add a .war file extension to the Logi application folder. Deploy your application using the Glassfish Admin Console. 2. In addition to the recommended Java Options listed in the General Information section above, your Java Options -XX:MaxPermSize setting should be set to a minimum of 300m. 3. Right-click this link sun-web.xml and save our customized version of the file in <LogiAppFolder>/WEB-INF. Keep the included <LogiAppFolder>/WEB-INF/web.xml file, but replace the existing <LogiAppFolder>/WEBINF/sun-web.xml file, if you have one. 4. Right-click this link faces-config.xml and save our customized version of the file in <LogiAppFolder>/WEBINF, replacing the standard file of the same name. 5. Logi v9.5.x users: Right-click this link Mainsoft.Web.jar and save our customized version of the file in <LogiAppFolder>/WEB-INF, replacing the standard file of the same name. BEA WebLogic 10 1. Auto-deploy is used with this server. Logi application folders must be manually given a .war file extension. 2. The JVM settings described above can be changed by editing them in: (Linux/UNIX) $WL_HOME/user_projects/domains/<Logi_Domain>/bin/setDomainEnv.sh (Windows) $WL_HOME/user_projects/domains/<Logi_Domain>/bin/setDomainEnv.cmd 3. Right-click this link weblogic.xml and save the file in <LogiAppFolder>/WEB-INF. 4. If using requests that return a large amount of data, performance can be improved by configuring the "TCP Chunk" parameters. You must pass -D weblogic.Chunksize=65535 for Logi to work properly under Weblogic. See the following information: Tune the Chunk Parameters 47 Getting Started with Logi Info and Logi Report for Java Oracle WebLogic 12c 1. Auto-deploy is used with this server. Logi application folders must be manually given a .war file extension. 2. The JVM settings described above can be changed by editing them in: (Linux/UNIX) $WL_HOME/user_projects/domains/<Logi_Domain>/bin/setDomainEnv.sh (Windows) $WL_HOME/user_projects/domains/<Logi_Domain>/bin/setDomainEnv.cmd 3. Right-click this link weblogic.xml and save the file in <LogiAppFolder>/WEB-INF. 4. If using requests that return a large amount of data, performance can be improved by configuring the "TCP Chunk" parameters. You must pass -D weblogic.Chunksize=65535 for Logi to work properly under Weblogic. See the following information: Tune the Chunk Parameters IBM Websphere 7, 8.5 Please see the following document, Deploying a Logi Info Application on WAS for specific information 48 Getting Started with Logi Info and Logi Report for Java Introducing Logi Studio Logi Info and Logi Report include our primary development tool, Logi Studio. This integrated development environment is the recommended tool for use by developers in creating their Logi applications. This chapter provides introduces the features of Logi Studio. Logi Studio is a tool designed to let developers create Logi applications as efficiently and easily as possible. The definition files that form the "source code" of a Logi application are simple text files and can be edited with any text editor; however, Logi Studio makes the development and testing process typical of programming much easier. Logi Studio is not a web application; it’s a Windows client application. A licensed copy must be installed on the desktop computer of each developer. Studio is a .NET application and must be installed on a Windows platform, and is available in 32- and 64-bit versions. Studio allows you to create either .NET or Java-based web applications and reports. All of the files that make up an application, including definitions, images, style sheets, scripts, XML data, and HTML pages, can be managed within Studio. All, with the exception of images, can be created and edited within Studio. Files can also be managed directly in the Windows file system. Studio includes a number of wizards and other tools that automate many standard development tasks, incorporates a set of "rules" that prevent you from combining incompatible objects, and Intellisense-like features that provide code completion options to speed development. Its element-based technique of adding and arranging objects in a hierarchical tree eliminates most tedious coding. Welcome to Logi Studio. We hope you will enjoy working with it. Logi Studio Geography Logi Studio has a simple layout that makes it easy to develop applications and provides an array of features and tools. Learning "what's where" is the first thing you should do when beginning to work with Studio. The Getting Started Dialog Box The first time you launch Studio, you'll see the Getting Started dialog box. 49 Getting Started with Logi Info and Logi Report for Java The dialog box, shown above, contains everything you need to quickly become familiar and productive with Studio. You should definitely explore all of its contents if you're a Logi Info newbie. You can hide it when you no longer need it. The Welcome Panel With the Getting Started dialog box hidden, you'll see the Welcome panel when you start Studio and whenever there's no application open. 50 Getting Started with Logi Info and Logi Report for Java The Welcome panel provides quick links to recently-opened applications, links that open applications using a variety of methods, and a link to DevNet, our online community. In addition, you'll see some useful content, from DevNet, displayed in a scrolling area. Working on an Application When you open an application in Studio and begin editing a report definition, it looks like this: Logi Studio uses six standard panels, which can be resized to suit your needs: 51 Getting Started with Logi Info and Logi Report for Java 1. The Application panel groups all of the files that make up a Logi application together into one file management tree. 2. The Workspace panel is where files are edited. Tabs at the top are displayed for each file that's opened, as well as the Welcome and Application pages. Different editors are displayed within the tab pages depending on the file type being edited (report definition, style sheet, XML data, etc.). Report definitions (shown) display the elements that make up a report, in a hierarchical Element Tree. When editing report definitions, tabs at the bottom are displayed for switching between views of the Element Tree (the Definition), the underlying XML source code (Source), and a mini-browser preview of your work (Preview). When the Preview or Source tab is selected, the Element Toolbox, Attributes, and Test Parameters panels are automatically hidden, allowing the full width of the Workspace panel to be used. 3. The Attributes panel is where developers enter element attribute values. Attributes can be sorted alphabetically or by Category and the Attribute Spy feature can be invoked. Attribute names can be double-clicked to open a "zoom" window for easier data entry. For some attributes, valid choices, in a selection list, can be summoned by clicking a down-arrow or mini-browse button in their value field. 52 Getting Started with Logi Info and Logi Report for Java 4. The Test Parameters panel allows you to insert values as for parameters that are normally passed to the page. This panel is only visible if the report expects parameters and is not displayed until a report has been run or previewed once. 5. When an element is selected in the Element Tree in the Workspace panel, the Element Toolbox panel provides a list of context-appropriate child elements that can be added to the Element Tree. Tabs at the bottom filter the element selection between child and sibling elements. 6. The Information panel includes quick help text; the element or topic name is a link to more information on DevNet. Panel Arrangement The Attribute and Element Toolbox panels can be re-arranged to suit individual developer tastes: 53 Getting Started with Logi Info and Logi Report for Java The Attribute and Element Toolbox panels can be re-arranged to suit individual developer tastes, using the Tools View menu options: Panels can also be arranged side-by-side, as shown above. General Features Logi Studio provides convenience and efficiency for developers. It includes many features added in direct response to requests from our developer community. General features include: 54 Multiple-Document Editor - The Workspace Panel allows multiple files of different file types to be opened simultaneously, including report and process definitions, style sheets, script files, and XML data files. Elements and attribute values can be easily copied between definitions. Support File Editing - Studio's internal support file editor provides improved editing and intelligent formatting of the source material based on file type. Features include line numbering, collapsible code regions, and syntax-specific highlighting. Global Search and Replace - The editor's Find and Replace feature supports current document and cross-document searching using a variety of criteria. Attribute Spy - This feature displays in the element tree, next to all relevant elements, their values for a selected attribute. For example, this feature allows you to quickly see which style class has been assigned to each element. Tree-based Element Selection - Child elements can be selected and added to the element tree either from the Element Toolbox Panel or by right-clicking a parent element and selecting from the popup menu that appears. Getting Started with Logi Info and Logi Report for Java 55 Intelligent Code and Token Completion - The task of entering tokens in attribute values is simplified by this feature, which dynamically presents selection lists for token types and appropriate identifiers in a drop-down list. Attribute Value Selection Lists - Values can be selected from drop-down lists for attributes with discrete sets of value options, such as True/False, Percent/Pixels, etc. Color Picker Tool - Attribute color values can be selected from a "color picker" tool, which can be opened from the attribute value. Test Parameters Panel - Parameters used in previews and tests remain accessible for easy use in the Test Parameters panel. Element Copy/Paste and Drag/Drop - Multiple elements can be selected at once in the element tree and copied, moved, or deleted. Query Tools - The Query Builder is a separate dialog box that allows queries to be created from graphic table representations, using drag-and-drop techniques. SQL statements can be extended across multiple lines, allowing more complex statements. In addition, statements can be tested by selecting them and pressing F5; the operation will be limited to just the selected portions of the query statement. Attribute Display Order - Element attributes can be viewed listed either in functional groups or sorted alphabetically. Database Browser - This handy utility launches from the toolbar and allows browsing of the structure and data in connected databases. It's also a non-modal window, so it can be kept open and referred to it while working with elements and attributes. Style Class Selector - This utility, shown as the first option in a the drop-down list of available classes for any Class attribute, appears as a dialog box and displays available classes and previews their effects as each is selected. Classes can also be edited right in place in the dialog box. Getting Started with Logi Info and Logi Report for Java Using Logi Studio Logi Studio is a standalone Windows application that provides a comprehensive development environment for creating Logi Info and Logi Report web applications. It's capable of producing applications that run in .NET and Java environments. A typical scenario for Java developers is to use Studio on a Windows system to develop and test their applications, and then deploy them to their Linux or Windows servers to be run under the Java libraries. Studio provides a number of features that make development easy and fast. The panels that make up Studio can be arranged, docked, or hidden, so that developers can tailor the environment as they desire. Studio manages your project files and includes editors for every type of file that might be included in a web application except images. Intelligent-completion features reduce the number of keystrokes necessary (and, hence, typos made). You can develop and test your application right inside Studio. Getting Started When Logi Studio starts, it presents a Getting Started dialog box: 56 Getting Started with Logi Info and Logi Report for Java A number of features are available to introduce you to Logi Info, including: Sample Apps Sample applications built with Logi Info can be launched using the View button. They'll open in your default browser and provide some interesting examples of the possibilities available. Welcome Video This short video gives you an introduction to the technology behind a Logi Info application, and shows you how they're constructed. Key concepts and features are explained. Studio Tour An interactive image of Studio helps you discover its geography, terminology, and features. Hover your cursor over the numbers in the images for descriptive text. Create Your Own This step-by-step tutorial, in conjunction with an included tutorial application, guides you through creating your first reports, including a Data Table, a Bar Chart, an Analysis Grid, and a Dashboard. Discover DevNet Links are provided into useful documents and features in our Developer Network website. You can disable the dialog box, so that it no longer appears when Studio starts, by unchecking the checkbox at the bottom. You can always redisplay it by clicking the Getting Started button, shown above, at the top-right of the Studio's main menu. Its state can also be set directly in Tools → Options. The Welcome Panel When the Getting Started dialog box is hidden or moved aside, you'll see the Welcome panel when you start Studio and whenever there's no application open. 57 Getting Started with Logi Info and Logi Report for Java The Welcome panel provides quick links to recently-opened applications, links that open applications using a variety of methods, and a link to DevNet, our online community. In addition, you'll see some useful content, from DevNet, displayed in a scrolling area. Application Files A Logi application is made up of a number of files that reside in an application folder group with a specific hierarchy. 58 Getting Started with Logi Info and Logi Report for Java The physical folder structure that contains source files is represented within Logi Studio in the Application panel, as shown above left. Files can be right-clicked and managed in the file system, as shown above right. Files that are deleted in Studio are placed in the Recycle Bin and can be restored, if desired. Report definitions can also be selected as the default report for an application (it's often useful to temporarily make a report the default during development, to avoid having to navigate to it through other reports during testing). Files can be added to the application via the New File toolbar icon or, as shown above, by selecting and rightclicking the folder in the Application panel where you wish to add the file. Right-clicking the folder presents you with the option add a new file or an existing file to the application. If you select Existing Definition… a copy of the file will be placed in your application; the original file is left untouched. 59 Getting Started with Logi Info and Logi Report for Java You can also copy files into, or out of, Studio by dragging and dropping them from, or to, the operating system (from Windows Explorer or the Desktop, for example) or another Studio instance. In Studio, files are dragged from or dropped onto the file/folder tree in the Application Panel. When dropping files, if you don't explicitly drop them onto a folder in the tree, Studio will attempt to place them in the correct folders based on their file extensions. Files can be dragged and dropped within other folders in the file tree. Studio also supports a hierarchy of "pseudo folders" for additional file organization purposes. Folders are created by right-clicking any folder, as shown above, and selecting Add → New Folder. 60 Getting Started with Logi Info and Logi Report for Java Creating folders in this manner and then creating or dragging files into them produces the kind of file names shown in the example above. No actual folders are created in the file system. In Studio, entire folders can be dragged into other folders to reorganize them. The following types of files are found in a Logi application: _Settings - This XML-formatted definition file provides configuration information with application-wide scope. Paths, constants, datasource connections, diagnostic settings, etc. are all configured here. Reports - Report definitions are the basic source code files of a Logi application, with each report definition usually equating to one web page. Individual files, with an .LGX extension, are enumerated here; double-clicking a definition will open it in the definition editor in the Workspace panel. Mobile Reports - Introduced in v10.0.259, these are report definitions specifically designed for creating reports for mobile devices. Not available in Logi Report. Processes - Process definitions are a special category of non-presentation source files. They can contain code for conditional and unattended processing and provide flexibility and coding depth not available in Report definitions. Process definitions are not available in Logi Report. Support Files - These are the files that support the report and process definition files and include style sheets, images, XML data files, and external HTML files. Widgets, Templates - These folders contain files that are for special purposes. Templates are not available in Logi Report. To edit most files, double-click them and they’ll open in an editor in the Workspace panel. Do not attempt to edit complex data files in proprietary formats, such Excel spreadsheets, in the Workspace panel - these should be opened and edited externally. 61 Getting Started with Logi Info and Logi Report for Java In the file system, a basic Logi application looks like the example shown above. All of the files for a single application are contained in one folder, the "Application folder", which makes deploying the app easy. Folders beginning with "rd" are system folders and must be present. The two folders highlighted above are created automatically when the app runs, so don't be concerned if you create a brand new app and don't see them at first. Other folders may also be created, based on features in your application. Editing Files Logi Studio includes file type-aware editors for viewing and editing application files: As shown above, when files are opened (multiple files can be opened simultaneously) they're added to the Workspace panel in tabbed panels. The editor for each tab panel is appropriate for the file's type. Features include: 62 The tabs themselves can be reordered by dragging. Editors may include line numbering, color coding, and collapsible regions. Elements and text can easily be copied and pasted between files in different tab panels. Copying an element also copies all of its child elements. Intelligent completion of element names and HTML tags is provided when typing Undo-Redo (Ctrl-Z, Ctrl-Y) is available for all changes made since the last Save. The Preview panel for definitions includes Forward, Back, Refresh and Stop buttons. Getting Started with Logi Info and Logi Report for Java Multiple elements (hierarchical peers) in the element tree can be selected at once, then moved or copied as a group. Elements have their valid child elements available for selection directly from their (right-click) context menus as well as from the Element Toolbox panel. Files are closed, and their tabbed panel removed, by clicking the X icon in the tab by the file name. You are prompted to save any changes that have been made. Tab context menus, available by right-clicking, were added to the tabs, as shown above. The menu options vary based on the type of file being edited in the tab panel. At the bottom of the Definition Editor Panel are several tabs. The Source tab provides a view of the definition's XML source code. If an element is selected in the definition when the Source tab is clicked, its corresponding XML tag will be highlighted in the source code, as shown above. Skilled developers can edit the source directly here, if desired. Copying the XML source is an easy way to send the definition to someone else; for example, another developer or to Logi Support in an email. In fact, just copying the element right in the element tree itself and then pasting it into an email or another application will result in the XML source being pasted. 63 Getting Started with Logi Info and Logi Report for Java Working with Elements The primary source code files for Logi applications are report definitions. These files contain XML-formatted text and Studio allows you to create and edit this text in a graphical manner by manipulating objects, called "elements". In Studio, elements are arranged in a tree structure that mirrors the top-to-bottom structure of a web page and some elements have names that are similar to HTML tags. The example above shows elements in the "Element Tree" in a report definition. An element can be the "owner" of another element, creating a parent-child relationship between them. In the example above, the Image, New Line, and Label elements are children of the Body element. These relationships are governed by rules which are enforced within Studio by restricting the availability of child elements for assignment to a parent element. 64 Getting Started with Logi Info and Logi Report for Java Elements can be added to the element tree by first selecting the parent element and then double-clicking the child element in the Element Toolbox panel, or by dragging-and-dropping the element. The Element Toolbox, shown above, includes: 1. 2. 3. 4. Elements that can be double-clicked and added to the definition. Other elements, grouped in folders by function. Links to start wizards that may be available. Tabs to specify the relationship of the displayed elements to the element selected in the definition: Child or Sibling. Only elements which apply to the specified relationship type will be displayed. A child and sibling element can also be added to the definition by right-clicking an element in the tree and selecting it from the context menu that appears. An element's context menu, shown above, includes several useful options for working with elements, such as moving, copying, cutting, or deleting them. 65 Getting Started with Logi Info and Logi Report for Java You can also select multiple parent elements (hold down the "Ctrl" key while selecting them) and then add a child element beneath all of them at once. In the example above on the left, multiple Data Table Column elements have been selected, then the Sort element was chosen from the Element Toolbox. The result, on the right, shows a Sort element added beneath each selected Data Table Column element. Once in the tree, elements can be moved up or down by dragging them or by using the Up and Down tool bar arrows or similar items in their context menus. The example above shows a New Line element being dragged upward in the tree; note the circled green positioning dot that helps you determine where to drop it. When an element is moved in this way, all of its child elements move with it. Even groups of elements (peers, on the same level in the tree) can be selected and moved at the same time. Elements can also be copied and pasted, individually or in groups, back into the same definition, into another definition, or even into another Logi application in order to reuse them. All of their child elements will be copied with them. Even XML source code, copied from the Workspace panel's Source tab, can be pasted right into the element tree and will instantly appear there as the correct elements. This is a great way to share code via email or discussion forums. Two special elements, Shared Element and Include Shared Element, can be used to make one instance of a group of elements re-useable throughout your application. Elements placed under a Shared Element element in one definition can be referenced using the Include Shared Element element in other definitions. This is par- 66 Getting Started with Logi Info and Logi Report for Java ticularly useful, for example, for managing headers and footers that appear on many reports within an application. Element Positioning By default, Logi definitions use Flow Positioning to arrange the elements on a report page. This is a very common scheme in web applications in which each element's location is dependent on the location of the elements preceding it. This is the most flexible scheme and works best across multiple browsers and devices. However, some developers may require absolute positioning, where elements are located on the page based on pixel coordinates. This is known as Layout Positioning and Logi Studio supports it. Layout Positioning is enabled on a report-by-report basis using a special attribute. Note that switching between positioning modes has some potentially irreversible effects! For more information about positioning, see our DevNet document Positioning Elements. Setting Element Attributes Elements can have a number of attributes, or "properties", that govern how they behave. The attributes for a selected element appear in the Attributes Panel and the number of attributes varies depending on the nature of the element. As shown above, attribute names appear in the left column and attribute values are entered in the right column. Some attributes are required while others are optional. Attributes can be sorted in two ways: by Category or Alphabetically, by clicking the highlighted icons. When sorted by category, the required attributes appear at the top. Depending on the attribute, values can be entered in several different ways. Generally, values can always be typed-in directly. 67 Getting Started with Logi Info and Logi Report for Java Double-click the attribute name to open the Attribute Zoom window, shown above, which contains a larger, multi-line text entry area and allows you to see longer values without scrolling. Hovering your cursor over the value column will cause the complete value to appear in a tooltip, even multiline SQL statements. The values for some attributes consist of a specific set of valid choices and, as shown above, these are chosen by first clicking the circled down-arrow and then selecting a value from the drop-down list of choices. The length of the list can be expanded by dragging the indicated corner of the list. 68 Getting Started with Logi Info and Logi Report for Java Where attributes require column names from a datasource, as shown above, a drop-down list is provided that will, first, retrieve the column names, and then, display them in a drop-down list for easy selection. This feature only works with datasources that respond to schema requests, such as databases, and so does not work with flat files. In addition, the parent data table or chart must have a valid ID for column names to be retrieved. For some attributes, clicking the browse button in the value column will launch a wizard or tool. For example, when the browse button is clicked in the image above, it will open the Query Builder tool, or… 69 Getting Started with Logi Info and Logi Report for Java …in the case of Color attributes, clicking the browse button cause the Color Selector dialog box, shown above, to be displayed. Colors can be selected from Basic, Web, and Professional palettes and can also be entered as hex, HSL, and RGB values. Attributes can be assigned for several elements at the same time, by selecting multiple elements (hold down the Shift or Ctrl keys while clicking elements). The Attributes panel will show all of the attributes the selected elements have in common; attributes that already have different values assigned will be indicated by the "(Differing values)" message. As shown above, assigning an attribute like Class in this state will set the individual Class attributes for each of the selected elements. 70 Getting Started with Logi Info and Logi Report for Java Element ID Attributes Some elements require a unique ID attribute value, which has to be entered by the developer. Developers are encouraged to use a "naming scheme" that conveys both element type and purpose. However, most ID attributes are optional. In addition, if an optional ID value is left blank, Studio will identify the element in the Element Tree by using text from another attribute value, as shown above. The attribute that Studio selects for this purpose varies, depending on the element type. The purpose of this change is to eliminate most "duplicate ID" errors (often caused when copying and pasting elements) and to relieve developers, in most cases, of the need to provide IDs at all. Variable and Parameter Lists Certain elements consist of lists of "variable attributes". In this case, the Attributes Panel displays an interface that allows you to enter as many attribute names and values as needed. 71 Getting Started with Logi Info and Logi Report for Java In the example above, a Link Parameters element has been selected and three attributes have been created. Attributes are created by entering a name in the text box at the top of the Attribute Panel and clicking the "+" icon. The new attribute then appears in the list and its value can be set by typing a value directly into the righthand column. Values can consist of numbers, text, tokens, or formulae. Attributes can be removed by selecting their name and clicking the "-" icon. Attribute names can be edited by selecting them and clicking the "Pencil" icon. This will place the name into the top text box, where it can be edited. The icon will change to a "Diskette" icon and clicking it again will save the edited attribute name. Attribute values can be edited directly, as usual, by placing the cursor on them. Express Attribute Navigation Some developers may prefer keyboard navigation to set attributes, avoiding constant switching between their keyboard and their mouse. Here are some keyboard shortcuts that allow this kind of mouseless navigation: Keys Action Once you've entered an Attribute value, the Tab key can also be used to commit the value and move to the next value down. Tabs can also be used to move from Element to Attributes – Select an element and press the Tab key three times. Focus is placed on the last value attribute visited, or the first empty attribute, and you can begin typing a value immediately. No cursor bar appears in the attribute value. Commit Value and Move - After typing an Attribute value, press Enter to commit it, and then the Up/Down arrow keys can be used to move to another attribute. Abandon Value and Move - After typing an Attribute value, press Esc to abandon it, and then the Up/Down arrow keys can be used to move to another attribute. The Attribute Spy The Attribute Spy feature allows you to see all of the values assigned to a particular attribute for all elements at once. This is a very powerful tool that makes it easy to compare values, such as style sheet class assignments, or get an overall view of values without excessive navigation and mouse-clicking. 72 Getting Started with Logi Info and Logi Report for Java As shown above, simply select an attribute (1) and then click the Attribute Spy button (2) at the top of the Attributes panel. Text will appear in the Workspace panel (3) indicating the values for that attribute for every element in the tree (excluding elements that do not have a value assigned for that attribute). Click the button again to hide the text. Intelligent Token Completion One of the most useful features in Logi Studio is the token completion feature. It can be difficult to remember all of the token types and identifiers that are available and this feature presents them and also prevents typing errors. 73 Getting Started with Logi Info and Logi Report for Java Here's how this feature works: 1. Type an @ sign and the first letter or two of a token type in an attribute value and a list of token types will appear, as shown above left. Use the Up and Down arrow keys to further navigate to the desired type, if necessary, and press the Space Bar to select it. The token type will be added in the attribute value. You can instead type @ + first letter, for example, @f, to navigate to the desired token. 2. Type a period (.) after the token type, as shown above right, and a list of token identifiers will appear. Type a letter or two and/or use the arrow keys again to navigate and the Space Bar again to select the desired identifier. It will be appended to the token type in the value column, including the trailing tilde. Similarly, you can use the intelligent completion feature to provide column names, for example, for @Data tokens: 1. Type an @ sign and the letter "d" in an attribute value and a list of token types will appear, as shown above left. If it's not positioned there already, use the Up and Down arrow keys to navigate to the Data token item. Press the Space Bar to select it. The token type will be added in the attribute value. 2. Type a period (.) after the token type, as shown above right, and a list of columns, based on the datalayer in use, will appear. Use the arrow keys and Space Bar again to selection the desired column and it will be appended to the @Data token in the value column, including the trailing tilde. Under certain circumstances, you may instead see an item named "Retrieve columns..." which will get the column names and then display them. This feature only works with datasources that respond to schema requests. The token completion feature also appears in other places, too: 74 Getting Started with Logi Info and Logi Report for Java For example, when you use the Attribute Zoom window and enter tokens, as shown above. Also, in the SQL Query Builder, if you edit your query manually and use tokens, it will pop up. The Space Bar and Period keystrokes work in these instances in the same way as described earlier. Token Validation Studio includes a token validation feature which examines tokens as you enter them and will flag those that are incorrectly spelled. In the example shown above, the tilde ("~") has been left off of the end of the Data token. Studio responds by displaying an Invalid Token button in the current definition tab. Clicking the button will take you to the offending token. The validation routine looks for missing tildes and misspelled token types ("@Requet" instead of "@Request", for example). Studio Wizards Studio includes "wizards", or automated procedures, which walk you, step-by-step, through a number of complex tasks, from creating new applications to building charts. They save a lot of key strokes and mouse clicks and provide a repeatable, consistent productivity enhancement. Wizards can be invoked in several ways: 75 Getting Started with Logi Info and Logi Report for Java When you select an element that has wizard support in the Element Tree, a special tab will appear on the main menu, containing items for the appropriate wizards, a shown above. Element wizards are also available in the context menus that pop-up when you right-click an element, as shown above. As in the main menu, their availability depends on which element is selected in the definition. The wizards shown above are specific to the Body element. 76 Getting Started with Logi Info and Logi Report for Java By default, if you double-click an element in the Element Toolbox that has a wizard associated with it, a dialog box like the one shown above will be displayed. It offers you the choice of inserting the element into the Element Tree or running the wizard. This behavior can be changed by unchecking the checkbox, in which case elements will just be inserted in the future. You can also control this behavior in the Tools → Options menu option. Wizards are also capable of validating your definition and will let you know, for example, if you're missing an element which needs to be provided before the wizard can proceed. Wizards in Action Studio's wizards are too numerous to document individually (there are more than 50!), but let's look at a representative example of a wizard in action: 77 Getting Started with Logi Info and Logi Report for Java In the definition shown above, Data Table and DataLayer.SQL elements have been added beneath the Body element, and the datalayer has been configured with a valid SQL query. Right-clicking the data table displays its context menu; let's let the Element Wizard add data columns to the table by selecting the Add Data Columns wizard. If the query is invalid or contains a typo, or you try this with a datasource that can't return a schema, the wizard will fail. In such a case, the wizard will display an error message that should assist you in correcting the problem. 78 Getting Started with Logi Info and Logi Report for Java As shown above, the wizard presents a dialog box displaying all of the columns that the SQL query returned. First, we'll click the Uncheck All link and then individually check the boxes for the first four columns, so that the selections look like the example shown above. Then we'll click Next. The wizard will insert, and configure, all of the elements necessary for the data table columns we selected, as shown above. Studio's wizards are a great resource for configuring elements, such as charts, that have a large number of configuration choices. For example, you could use the Add a Chart wizard to get the basic chart set up for you and then you could customize it from there. Assigning Themes and Style Sheet Classes The presentation qualities of elements are set in two ways. In some cases presentation values, such as Color, may appear as element attributes that can be assigned directly. However, in most cases, this is achieved by using a Theme or by manually assigning style classes to an element's Class attribute. Using Themes Themes allow developers to instantly apply a consistent "look" to their applications. A theme is a collection of graphic images, a style sheet, and a template modifier file, that impart a specific appearance to a Logi application. Several standard themes are provided for your use and others are also available on DevNet in the Sample Themes library. Themes do the work for you, assigning style classes and setting other appearance attributes, making it easier to produce great looking reports without an in-depth knowledge of style classes and style sheets. You can easily switch between themes in order to experiment with them. 79 Getting Started with Logi Info and Logi Report for Java When you use the New Application wizard in Studio, one of the steps is the selection of a theme for the new application, as shown above. As shown above, one way to apply a theme is to add a Style element to your report definition, then set its Theme attribute to the name of one of the available themes. The report will have the theme applied to it. More information about themes is available in a later chapter, Using Themes and Style Sheets. 80 Getting Started with Logi Info and Logi Report for Java Using Style Classes The first step in using style is to assign a style sheet. This .css file is typically placed in your application's _SupportFiles folder and assigned using the same Style element used in the previous example to assign a theme. Once the style sheet has been assigned to the report definition, its style classes are available for use. As shown in the example above left, classes from the currently assigned style sheet are available for selection from a drop-down list in the Class attribute value of an element. The classes in the list are drawn from the style sheet assigned to the report definition or the application. This is a quick way to select classes, although class names can also be typed in directly. Multiple classes can also be assigned, separated by commas. A preview of the effect of the assignment is shown in Studio's Information panel. The list of class choices includes a (Class Selector...) item, shown above right, which opens the Class Selector tool. 81 Getting Started with Logi Info and Logi Report for Java The Class Selector tool, shown above, allows a class to be assigned by selecting it in the class list (1) and clicking OK. The attributes of the class are shown in the upper right panel (2) and they can be edited there. Controls (3) allow you to save, add, and delete classes and the effect of the selected class is shown in the lower preview panel (4). This tool provides pretty comprehensive class management right within Studio. A more convenient editing option is to open the style sheet, by double-clicking it in Studio's Application panel, and it will open in a special editor in the Workspace panel. The intelligent editor will provide style selector choices and completion suggestions as you type. Finally, you can use an external style sheet editor, if you've installed one: You can open and edit style sheets in the external style sheet editor by selecting the file in the Application panel, as shown above left, and right-clicking it, then selecting Open Externally from the pop-up menu. 82 Getting Started with Logi Info and Logi Report for Java Another method is to select the Style Sheet element in the element tree, select its Style Sheet attribute, and click the Open File... link that appears at the top of the Attributes panel, as shown above right. These actions will launch the application associated in the file system with the .css file extension and open the style sheet in it. More information about themes is available in a later chapter, Using Themes and Style Sheets. Testing and Debugging Applications A Logi application may have one or more report definition files and, while actually browsing a report shows you the big picture, doing so can be cumbersome if you have multiple report definitions. Using the Preview Tab Studio's Preview button, at the bottom of the Workspace panel, provides the developer with a fast way to view the report definition currently being edited. To preview a report definition that's open in the Workspace panel: 1. In the Application Panel, select and open the report definition to preview. 2. Click the Preview button at the bottom of the Workspace Panel, as shown above. 3. Browse and interact with the report definition using the toolbar at the top of the Preview panel. Note that clicking Preview will save all open definitions before displaying the report. 83 Getting Started with Logi Info and Logi Report for Java Using the "Live Preview" Feature The Live Preview feature allows you preview your work in a separate desktop window. The Main Menu's Live Preview item is shown above. The live preview will be displayed in a separate window and any changes made to the definition will immediately be reflected in that window. You can resize and relocate the new preview window as desired; you can even drag it onto a separate display, if you have one You can also switch to Live Preview from regular Preview mode: To start Live Preview, first preview the report definition, using the Preview tab, and then click the Live Preview icon, circled above. The preview will be displayed in a separate window, and Studio will switch back to its Definition tab. You can resize and relocate the new preview window as desired; you can even drag it onto a separate display, if you have one. Any subsequent changes you make to the definition code will immediately be reflected in the Live Preview window. 84 Getting Started with Logi Info and Logi Report for Java If you don't want definition changes to be updated immediately in the Live Preview window, you can pause and restart them, using the Pause and Play icons, circled above. To exit Live Preview, just click the Live Preview window's Close (X) icon. Browsing the Default Report Definition In a Logi application, one of the report definitions is designated as the "default" report - the page that will be shown if no definition is specified in the URL. If you don't change it, this is usually the Default report definition. You can browse the default report by clicking the Browse icon, shown above, in Studio's toolbar. Your computer's default browser (the one associated with .htm/html file extensions) will be used for this. You can change the "default" report designation in the Application Panel: As shown above, left, select the desired report definition, right-click it, and select Set As Default from the popup menu. This sets the Application element's Default Report attribute, shown above, right, in the _Settings definition. You can also change this attribute value directly in the _Settings definition. Using the Run Application menu item will save all open, unsaved definitions before displaying the report. 85 Getting Started with Logi Info and Logi Report for Java Browsing Any Report Definition You can also browse any report definition without opening it in the Workspace Panel or setting it as the default report. As shown above, select the desired report definition, right-click it, and select Run in Browser from the popup menu. Using this menu item will save all open definitions before displaying the report definition. Using the Test Parameters Panel One of Studio's least well-known panels is the Test Parameters panel. Studio makes this panel visible when the current definition expects to receive parameters. It provides a way for developers to supply request variable values for their definitions when previewing them in Studio, and it makes experimenting with different values very easy. 86 Getting Started with Logi Info and Logi Report for Java The example above shows this panel in action. Studio will automatically populate the left column with the tokens for any request variables expected by the current definition in the Workspace. You can enter values for those tokens, and they'll be fed to the definition when you Preview it in the Workspace panel, or right-click it in the Application panel and select "Run in Browser". Token values are not fed to the application when you click the Run Application menu item or press F5. Using the Debugging Features Logi Studio also provides debugging features for an application, but they have to be enabled to work. They are not enabled by default. You can turn on comprehensive debugging for all your report pages by clicking the Debug menu item, shown above, and selecting Debugger Link from the selection list. Selecting a debugger style in the menu sets an attribute value in the _Settings definition, as shown above. This value can also be set manually. When the Debugger Style has been set to Debugger Link, the Debugger Trace Report can be accessed in two ways: using the Debug this page link which will now appear at the bottom of your report pages, or from a link that appears on a runtime error page. The trace report appears either in the Preview panel or in your browser, depending on which method you were using to view your report. 87 Getting Started with Logi Info and Logi Report for Java As shown in the example above, the debug icon for the report "floats" in the lower right-hand corner of the browser window, so you don't have to scroll down to use it. Any charts, which are processed separately by the Logi Engine, will have their own debug icon and trace report. For more information about debugging, see our document Debugging Reports. Deploying Logi Applications After you've developed your Logi application on your development machine, it's time to deploy it to your production server. There are several ways to this, and they're all discussed in our Deploying a Logi Application document. The easiest of these methods is to use Studio's Application Deployment tool. Before you use it, however, ensure that: 88 Logi Server is installed on your production server. On a development machine you generally install both Logi Studio and Logi Server. You may also install both of them on a production server but it's not required. However, we suggest you install Logi Server so that our Server Manager tool will be available on the production server. The appropriate .NET framework or JDK 1.6+ or JRockit has been installed on the production server. Getting Started with Logi Info and Logi Report for Java You have an appropriate Logi license for the production server. You have the appropriate security credentials for writing to the production server. The production server has connectivity to the database server or other datasources needed by your application, and you know the security credentials they require. You know any storage conventions for folder locations on the production server that you need to observe (such as, "all applications must be installed on the D: drive, not the C: drive")? The Application Deployment tool is capable of copying all or part of your application to the production server using either file system copy commands to local or shared network drives, or one of three flavors of FTP (standard, SSL, and SSH). In Studio, the details of each operation are called a "deployment target" and they can be saved for later reuse. The Application Deployment tool is started in Studio by selecting it from the Main Menu Tools tab, as shown above. If no deployments have been defined, the dialog box shown above appears. Click the link or New... to define your first deployment target. 89 Getting Started with Logi Info and Logi Report for Java The Add/Edit Deployment Target dialog box contains the following: 1. An arbitrary name you give the deployment, for future reference. 2. The transfer method: Copy to Local or Network drive, FTP, FTP (SSL), or FTP (SSH). 3. If Local/Network selected: the UNC file path to destination app folder on production server. Example: \\myWebServer\myLogiApp If FTP variant selected: the FTP protocol URL to destination app folder and arguments. Examples: FTP & FTP SSL: ftp://myWebServer/myLogiApp,ftp://myWebServer.com:8082/projs/myLogiApp FTP SSH: sftp://[email protected]/myLogiApp If necessary, you will be prompted to supply a user ID and a password; do not include them in the URL. Both active and passive FTP is supported. 4. 5. 6. 7. 90 The Test button can be used to ensure connectivity to destination. Select the files that are to be transferred. Files are overwritten at destination without warning! If Server Engine has been selected above, the server type options for the deployment are shown. If Server Engine has been selected, the available versions installed on the development machine are listed. Getting Started with Logi Info and Logi Report for Java If the destination requires a user ID and password in order to access it, when you click the Test button, you'll be prompted for login credentials. If the credentials are successfully authenticated, the user ID will automatically be saved with the deployment target details and, optionally, the password as well. Once a deployment target has been defined, it appears in a list… …as shown above, where they can be managed and edited. To run a deployment, check its checkbox and click the Deploy button. If multiple deployments are selected, they'll run consecutively. The connection with the destination server will be established and then the files will be deployed to it. The Deployment dialog box will expand to display the results of the process, as shown above. The running log indicates which files are added, replaced, or skipped. Deployment process logs are created in the 91 Getting Started with Logi Info and Logi Report for Java rdDeployment folder beneath your app root folder as text files and are accessible through the View Logs link. Finally, the deployment will complete and the link to its log file will be displayed. It's very important that you understand that copying the files, using the Deployment tool, does not register the application with a web server on the target machine. So, after the first deployment, this has to be done by the developer using Studio, Server Manager, or the web server's tools. Controlling Which Files Are Deployed The Add/Edit Target dialog box allows you to select the files to be deployed by category: Category Description Application Definition and Support Copies all files in all folders with names beginning with an underscore, such as _Definition, _Script, _Support Files, etc. This includes folders like _Images and _Stylesheets, which are from the old app folder scheme. Identical files will be skipped. Application Settings Copies _Settings.lgx only. Identical files will be skipped. Server Engine (.NET app) Copies the rdTemplate and bin folders - files are overwritten without warning. Also copies any .aspx, .asax, and .config files if they do not already exist; does not overwrite them if they do exist. Server Engine (Java app) Copies rdTemplate, Assemblies, and WEB-INF folders - files are overwritten without warning. Also copies any .aspx, .asax, and .config files if they do not already exist; does not overwrite them if they do exist. 92 Getting Started with Logi Info and Logi Report for Java Why not just deploy all of the categories all of the time? You'll want to do so for your first deployment but, generally, you won't want to for subsequent deployments in order to avoid overwriting files that may have been customized for the production server, such as _Settings.lgx. And, unless you're changing engine versions, deploying the engine files with every deployment is unnecessary and a waste of time. So the tool offers you the opportunity to tailor your deployments as needed. However, developers may want to exclude specific application definition and support files from a deployment, and Studio provides an easy way to do that: By default, all files in Studio's Application Panel are included in deployments. However, if you wish to exclude a file, select it in the Application Panel, right-click it, and uncheck the Include in Deployments item in the popup menu, as shown above. 93 Getting Started with Logi Info and Logi Report for Java If files have been excluded, the View Excluded Files link, shown above, will be displayed to alert you to this situation when you add or edit a deployment target in the Deployment tool. Clicking the link will display a list of the excluded files. License Files License files are never included in deployments, so you will have to manually deploy your license file the first time you deploy your application, or configure it to use a centralized license file. For more information about license files, see our document Product Licensing. After a First-Time Deployment After the first time an application is deployed, you must: Provide a license file for the application, unless you're using a centralized license file. Register the application with the web server. Ensure that the datasource connection strings or parameters, constants, and other server-specific settings are correct in the _Settings definition. For a Java app, complete any special configurations required for your web server. Subsequent deployments for the purpose of updating report definitions, images, XML data, etc. should not require you to do any of the steps discussed above, unless you're changing folder locations or _Settings attributes. This means Logi Server Engine files and _Settings.lgx can be left out of future deployments undertaken for simple update purposes. For more information, see our Deploying a Logi Application document. Ribbon Menu, Shortcuts and Search Studio operations can be controlled using the Ribbon Menu at the top of the screen. Here are its tabs and major items: New Application Create a new application with the assistance of the New Application wizard. Open Application Open an existing application from the File Explorer, the recent apps list, or a list of apps registered with the local web server. New File Save, Save All, Close Create a new file by selecting a file category. Save the file in the current Workspace editor tab, save all edited files, and close the current application, with a prompt to save any unsaved files. Edit Actions, Remark, Standard editing actions including Cut, Copy, Paste and more. Comment and unMove Up/Down comment elements and rearrange their order. 94 Getting Started with Logi Info and Logi Report for Java Search/Replace Search current, or all, definitions and supporting text files, and replace text, if desired. Element Navigation, Navigate to previous or next element in the Element Tree navigation history. ExExpand/Collapse pand or collapse all child elements beneath the selected element. Test Actions Control debugging, and preview a definition in a browser or in a separate "live" window. Themes Application Deployment Application Obfuscation Server Manager Team Development Database Browser Elements/Attributes Panel Options Apply the selected Theme to the current report, or to the entire application. Deploy the application to other servers using the Application Deployment Tool. Render definitions unreadable by humans to prevent tampering and theft using the Application Obfuscation Tool. View registered applications and change their Logi Engine versions individually or in bulk. Manage built-in Logi source code control with file check-in/out and change history. View schema and basic data samples from databases with connections in _Settings file. Specify the arrangement and order of the Element Toolbox and Attributes panels in Studio. Specify Studio options including file encoding and definition editor colors. The Wizards tab appears when an element that has supporting wizards is selected. The number of wizards available varies depending on the selected element. Some menu items have self-explanatory drop-down lists of choices, while others open a dialog box: 95 Getting Started with Logi Info and Logi Report for Java In the example shown above, the Tools → Options item displays the Studio Options dialog box, containing these items: 96 Show "Getting Started" dialog box - Select this option to display the dialog box for new users when Studio starts. Ask to run wizards... - Controls whether or not a dialog box prompts you to insert an element or run its wizard when you double-click an element in the Element Toolbox. Automatically open... - Select this option to have Studio, at startup, reopen that last application open when Studio was closed. Limit SQL Requests... - Uncheck this option to allow very large result sets to be returned, but be prepared for possible delays. GIT Friendly – (v11.4.046+) When checked, prevents writing of the standard SavedAt, SavedBy, and EngineVersion attributes in definition file source code, which can interfere with some code repositories like GIT. Also adds a .gitignore file in the application folder. Enable ribbon access... – (v11.4.046+) Uncheck this option to prevent shifting focus to the Ribbon Menu when the Alt key is pressed. This is useful with some European keyboards that use key combinations that include the Alt key to produce characters like @ and ~. Definition File Encoding - Specifies that character encoding scheme to be used in Logi definition files. Remarks Color - Colored block indicates the color to be used for remarked (commented out) elements in the element tree. Click the block to open the Color Selector dialog box and choose a new color. Notes Color - Colored block indicates the color to be used for Note element text in the element tree. Click the block to open the Color Selector dialog box and choose a new color. Getting Started with Logi Info and Logi Report for Java The other items on the Tools tab, Application Deployment, Application Obfuscation, Server Manager, Team Development, and the Database Browser, are discussed in separate sections in this document. The Ribbon Menu items can be collapsed vertically to get more screen real estate, using the arrow highlighted above. The menu can be expanded again by clicking the arrow again, or by selecting a different menu tab. The menu's Getting Started button, shown above, will redisplay the Getting Started dialog box whenever needed. The menu's Help button, shown above, displays a drop-down list of resources for getting assistance and reporting problems. Keyboard Shortcuts The following keyboard shortcuts are available for those who may prefer to save mouse clicks: Applications and Files Editing Ctrl n = New application Ctrl f = Find Ctrl o = Open application Ctrl h = Replace Ctrl l = Open application from local web server Ctrl z = Undo Ctrl s = Save selected file Ctrl y = Redo Ctrl, Shift s = Save all open files Ctrl r = Toggle remark/unremark F1 = Studio Help Ctrl x = Cut 97 Getting Started with Logi Info and Logi Report for Java F2 = Rename selected file Ctrl c = Copy F5 = Run current definition in browser Ctrl v = Paste F7 = Move element up (includes children) Ctrl + = Next navigation history item (v10.2.424) F8 = Move element down (includes children) Ctrl - = Previous navigation history item (v10.2.424) Ctrl ↑↓ = With focus in Attribute panel and value committed, move to Prev/Next element in Element Tree. You can download and print our handy Studio Keyboard Shortcuts quick-reference card, if desired. Search & Replace Logi Studio includes a Search feature, including a Search control right on the main menu: As shown above, the ribbon menu includes a text input control for entering new search terms and it keeps a historical list of terms sought during the current program session. Clicking the magnifying glass icon starts a new search using the displayed terms. Searches are not case-sensitive initially and can also be initiated using the Ctrl + F keys. Clicking the A-B icon, or using the Ctrl + H keys, will open the Search and Replace feature. 98 Getting Started with Logi Info and Logi Report for Java Search results are displayed in the Find and Replace dialog box, shown above. Additional searches can be launched from here with more selective scope and criteria, if desired. Results returned are listed by definition and are active links: clicking a result row will open and highlight the specific occurrence in the definition in the Workspace panel. Clicking the Replace tab in the dialog box reveals controls in which you can enter a replacement term and selectively make replacements. The Database Browser The Database Browser tool allows developers to view the objects and data in connected databases. The objects available include Tables, Columns, Views, and Stored Procedures. The database browser does not work with datasources that do not return a schema when queried, such as XML data files. 99 Getting Started with Logi Info and Logi Report for Java The Database Browser is launched from the main menu’s Tools tab, as shown above. Select a database from the list of connections that have been configured in the _Settings definition for this application. The Database Browser, shown above, provides the following features: 1. 2. 3. 4. 5. A tree view of the Tables available in the database is presented, as shown above. Each table folder can be expanded to display its columns. The database's Views and Stored Procedures, if any, are also available. The Query Builder utility can be launched from here with this button. The Details tab provides table or column properties, the Source tab allows Stored Procedure code to be viewed (but not edited), and the Data tab displays the table's actual data. 6. Rows of data displayed in the Data tab can be right-clicked and edited or deleted. The Database Browser will work with the databases for which we provide "native" Connection elements, such as Oracle, MS SQL Server, and MySQL. It may work with other databases that use a connection that mimics that of a database for which we provide a native connection, such as Netezza PostgreSQL. It is not guaranteed to work with every possible database and, in that case, we recommend that you use tools provided with the database to examine and manipulate it outside of Studio. The Database Browser may not support all of the functions and views available in Microsoft Access databases. 100 Getting Started with Logi Info and Logi Report for Java By default, the Database Browser will only return 10,000 rows of data. You can turn this limit off in Studio in Tools Options. The Database Browser is a non-modal dialog box and can remain open, for reference, while you work elsewhere in Studio. The SQL Query Builder The SQL Query Builder tool allows developers to examine data and construct and test their queries from within Studio. It's launched either from the Database Browser or … …by clicking the browse button at the end of a datalayer element's Source attribute, as shown above. 101 Getting Started with Logi Info and Logi Report for Java The SQL Query Builder presents database objects in a (1) tree, from which tables and views can be dragged into the (2) center work area. Manipulating the visual objects results in a SQL query being generated in the (3) bottom command area. The query can use multiple lines in the command area and can, therefore, include DECLARE statements and other more complex SQL statement constructions. Clicking the (4) Data tab at the top of the SQL Query Builder executes the SQL statements and displays the results in that tab panel. The F5 key can also be used to execute statements; portions of statements can be highlighted and selectively executed using F5 as well. SQL statements such as INSERT and UPDATE can be used to modify the data but there is no graphical way to directly make modifications in the Data tab. By default, the SQL Query Builder will only return 10,000 rows of data. You can turn this limit off in Studio in Tools → Options. Clicking (5) OK will cause the query constructed in the command area to be copied into the datalayer’s Source attribute, if the SQL Query Builder was called by clicking the attribute's browse button. Otherwise, the query text can be selected, copied, and pasted as needed. The SQL Query Builder will work with the databases for which we provide "native" Connection elements, such as Oracle, MS SQL Server, and MySQL. It may work with other databases that use a connection that mimics that of a database for which we provide a native connection, such as Netezza PostgreSQL. The SQL Query Builder will not support all of the functions and views available in Microsoft Access databases, or other non-standard SQL languages, such as Salesforce Object Query Language. It is not guaranteed to work with every possible database and, in that case, we recommend that you use tools provided with the database to create and test queries, and then copy and paste them into Studio. When Query Has Been Entered Manually Note that if you have already entered a query manually in the Source attribute and you then open SQL Query Builder, the tool will try to "reverse-engineer" the query into its graphical representation. It succeeds at this most of the time but, if the query includes tokens, the SQL Query Builder may fail and display an error message, especially when Logi tokens have been used outside of a SELECT statement. Use with Oracle and Multiple Schemas Due to Oracle's potential for use of multiple schemas, each potentially with many objects, prior to v10.1.59 it was possible for SQL Query Builder to crash when trying to retrieve thousands of schemas and objects. A new, updated version of the SQL Query Builder was included in Studio beginning in v10.1.59 to address this issue. When connecting to an Oracle DB, the updated SQL Query Builder will retrieve a list of schemas, prompt you to select one, and then retrieve the related objects. The MDX Query Builder The MDX Query Builder provides an easy way to construct MDX queries, which are essentially twodimensional queries against three-dimensional (cube) data. The notation used to select cube data has strict formatting requirements and the MDX Query Builder helps developers build valid queries. 102 Getting Started with Logi Info and Logi Report for Java It's launched, as shown above, by clicking the browse button at the end of the DataLayer.MDX element's MDX Source attribute. Based on the selected (1) Cube, the MDX Query Builder presents lists of (2) Dimensions and Members, and (3) Measures. These can be moved to an axis or added and removed by selecting and right-clicking them, as shown above. The (4) results of these actions can be seen in the Results panel, in tabular or (5) source code form. Clicking (6) OK will cause the query constructed in the Results panel to be copied into the datalayer's MDX Source attribute, if the MDX Query Builder was called by clicking the attribute's browse button. Otherwise, the query text can be selected, copied, and pasted elsewhere as needed. When a Query Has Been Entered Manually Note that if you have already entered a query manually in the MDX Source attribute and you then open it in the MDX Query Builder, the tool will try to "reverse-engineer" the query. It succeeds at this most of the time but, if the query includes tokens or is created using a non-standard SQL language, the MDX Query Builder may fail and display an error message. This is especially likely when Logi tokens have been used outside of a SELECT statement. 103 Getting Started with Logi Info and Logi Report for Java Working with Studio Panels Studio provides an intelligent and dynamic development environment for the creation of Logi applications. Though almost all of the source files used in a Logi application are text files and can therefore be edited with something as simple as Notepad, the wizards, editors, and other tools within Studio make the development process faster and easier. The primary visual feature of Studio is its set of panels. These are used to manage, organize, and edit the files that make up a Logi application. The panels are flexible and can be sized to suit personal tastes. To resize a panel, simply position your cursor over the panel border (where it will change to the resizing cursor, as shown above) and drag the border in the desired direction. This applies to both vertical and horizontal separators. If you prefer to add elements to the Element Tree using the "right-click and pop-up menu" method, you may not want to see the Element Toolbox panel at all; similarly, you may not use the Test Parameters panel. You can effectively hide these two by reducing their heights, as shown above. Just drag their separator bars downward completely. The Test Parameters panel is displayed only if the application accepts parameters. 104 Getting Started with Logi Info and Logi Report for Java If desired, the vertical positions of the Element Toolbox and Attributes/Test Parameters panels combination, can be swapped, as shown above, using the Tools → Elements & Attributes Panels main menu item. The two panels can also be arranged side-by-side was added, as shown above. 105 Getting Started with Logi Info and Logi Report for Java Changing Logi Application Versions A Logi application includes files and settings installed on the web server and version-specific binary files included in each Logi application project folder. This allows each Logi application to maintain its own version identity and allows backward compatibility from new versions of Logi products. Applications can be upgraded and downgraded to different versions and, when a new version of Logi Info or Logi Report is installed, applications must be upgraded before they'll have the benefits of the new version. When you open an application, Studio displays a warning in its Application tab, as shown above, if the application's version does not match the version of Logi Info or Logi Report being used. For existing Logi .NET and Java applications, v10 and later, Studio provides a quick and easy way to change versions: To change versions, click the Change Version... link, shown above. This will display a wizard with a list of the installed versions and, after you select one, will replace the application's version-specific binary files with the files of the selected version. The replacement may take several minutes. This will not affect any definitions or support files you have created and you can revert the change. 106 Getting Started with Logi Info and Logi Report for Java For .NET applications, the Server Manager, which can be launched from Studio's Tools menu, can also be used to change application versions. This is a tool that allows you to examine all of the .NET Logi applications on the local web server and manage them. The Server Manager dialog box, shown above, displays a list of the applications installed on the local web server. Select one or more applications (1) and the desired product versions (2), and click Change Version... (3). The process usually takes less than a minute for each application selected. Server Manager is intended for use only with .NET applications, using the IIS or Cassini web servers; if neither one of these servers is installed, Server Manager will prompt you to install them. For additional important information about changing application versions, see our document Upgrading Logi Products. Team Development Features Logi Studio includes two features for use in a team development environment, where multiple developers are working on the same Logi application. File Locking prevents multiple developers from inadvertently working on the same file at the same time and blocking or overwriting each other's modifications. File History retains a copy of each file revision and current versions can be "rolled back" to earlier versions. 107 Getting Started with Logi Info and Logi Report for Java As shown above, these features are enabled by adding a Team Development element to the application's _Settings definition. The two features, File History and File Locking, are enabled by setting their respective attributes. When you Save the _Settings definition, the Team Development features will become enabled. Definitions in the Application panel, including the _Settings definition, will be shown with a "padlocked" icon, indicating that the files have been locked. Hovering your mouse over the definitions will cause a "File Locked" tooltip to appear. Attributes and their values for elements in those definitions will be shown with gray text, indicating that they cannot be edited. Individual files can be unlocked, opened, closed, or locked using the pop-up menu options, shown above, that are now available when a file is right-clicked. The file icons will change to reflect a file's locked or unlocked state. Locking applies to text-based support files as well as definition files. 108 Getting Started with Logi Info and Logi Report for Java Team Development uses a source control system approach, where to unlock a file is to "check it out" and to lock it is to "check it in". This means: When no one is working on any file, they are all locked (checked-in) and available to be unlocked (checked-out) by anyone. When you unlock (check-out) and open a file, you can edit it, but everyone else is prevented from working with it. When you save and/or re-lock (check-in) the file, then it's available to be unlocked by anyone again. When a file has been unlocked by a user, other users attempting to unlock it will see an "in-use" icon next to the entry in Studio and a tooltip that indicates who's working with this file, when they hover their mouse over it. Note that the initial locked state is also applied to the _Settings definition, and you must now unlock it if you want to modify it. If they've been enabled in the _Settings definition, File Locking and File History information can be viewed by clicking the Team Development menu item, shown above, in the Tools tab. When the menu item is clicked, the Team Development dialog box opens, as shown above. File Locking details are displayed in the first tab, allowing development team members to determine which files are locked, who locked them, and when. 109 Getting Started with Logi Info and Logi Report for Java File History details are displayed in the second tab. Revision information and the actual revised data are presented. If a particular file is double-clicked, an individual file history dialog box is displayed and it includes a Rollback... button, which can be used to replace the current file contents with the selected version's contents. The Team Development features use a local database file located under the folder "TeamDevelopment", shown above, in the application folder. The folder and database file are automatically created when the Team Development features are enabled. The Pack Team Development Database feature was added in v10.2.002 to maintain performance. Clicking the appropriate button in the Application History tab will present a prompt for confirmation. Clicking Yes will start a process that makes a backup of the Team Development database and then packs and shrinks it. All developers should close the application in Studio before a packing operation is started. You should pack the database whenever you feel that File History retrieval is taking a long time. These features allow team developers to work together on an application, without getting in each other's way, and provide a useful audit trail of modifications. 110 Getting Started with Logi Info and Logi Report for Java System Configuration A commonly-used approach for team development is to set up a centralized "development server" where the Logi application files can be accessed, using a shared network folder, by all members of the development team. Logi Info Server is installed on that server, along with a web server and all necessary supporting files. A Logi Info license is required for that server. Developers who can "map" a local drive to the shared folder on the development server must be given Read, Write, Modify, and Delete file access permissions. Developers must also have Logi Info or, at the very least, Logi Studio installed and licensed on their own machines. They then "open" the Logi application on the development server and apply the Team Development settings as outlined above. In the _Settings definition, the Path element's Application Path attribute should be set to the URL of the Logi app on the development server, rather than to the usual http://localhost/yourApp. Do not set the Alternative Definition Folder attribute, which is not relevant for this situation. Third-Party Source Control Products The choice of a source control system is highly dependent on the complexity of the source control functionality required. For smaller, simple applications, the use of the Team Development functionality within Logi Studio is often enough. Logi Team Development allows you to maintain version control, based on file saves, and provides file-locking/sharing capabilities for multiple developers. If you require more sophisticated source control, then a third-party product will be necessary. Examples of popular products include Microsoft TFS, GIT, and SVN. The files that make up a Logi Info application are used directly from the file system; they're not stored in, or controlled by, a database or other constraining mechanisms, so third-party source control products can be used directly on them without concern. To benefit from a third-party product, however, you should keep your Logi application's source code folders (_Definitions, _SupportFiles, _Templates, _Scripts, _Plugins), and all the root folder .aspx files under source control. Keeping the bin, rdTemplate, and other "rd*" system folders outside of source control will allow you to easily move between different versions of the Logi engine without interfering with your source control functionality. Given the large number of, and different types of, source control products available, there are no plans to provide tighter integration between them and Logi products. Deleting a Logi Application If you want to delete an entire Logi application, you can do so by using your file system tools, such as Windows Explorer, to delete the entire application folder. On a typical Windows server platform, for example, you would delete: C:\inetpub\wwwroot\yourAppFolder and all of its subfolders and files. Note that your web server may hold some application files open to improve performance and you might receive an "access denied" type error when you try the deletion. If this happens, try stopping and restarting the 111 Getting Started with Logi Info and Logi Report for Java web server. For IIS, this can be done very easily by running iisreset.exe from the Start Menu Run option or from a command line window. Once the web server is restarted, try deleting the application folder again. Afterwards, in Studio, your application will still appear in the Recent Applications panel of the Welcome tab. Click its entry, as if to open it, and Studio will display a warning that it no longer exists and remove it from its list of recent applications. 112 Getting Started with Logi Info and Logi Report for Java Granting File Access Permissions A Logi application, on your web server, consists of an application folder with a set of sub-folders and files. Depending on the nature of the application, there may be a need to write data into some of those sub-folders. For example, data caching, temporary file creation, and exports are but a few of the operations that will write data to these folders. However, the default security settings for these folders prohibit file writing by accounts normally used to run web applications (which is what your Logi application is), so you may need to explicitly grant file access permissions to these folders (which are identified below). Using .NET? Let the New App Wizard Do It If you use the New Application Wizard in Studio (File → New Application...) to create a .NET Logi app, it will set the appropriate file permissions for your application for you. It actually provides a pretty wide-open security setting, granting all rights to everyone, and you may care to set more restrictive rights manually. You may, nonetheless, need to manually grant rights when you deploy you app to a production server. Generally, if your application does anything more than put simple text on a page, granting file permissions will be required and you'll need to do this for each Logi application you develop and deploy. Using Java? It’s Usually Done for You The New App Wizard doesn't set file permissions for Logi apps because, for the majority of Java web servers and configurations, it's already done for you. Your Java web server may already grant blanket permissions to apps deployed within certain folders, or that are auto-deployed, for the accounts that web apps run under. However, it’s up to you to have a working knowledge of your Java web server, and its security requirements and features. Which Accounts? For an IIS server and a .NET app, which accounts do you grant these file permissions to? If your Logi application runs on a web server with either Windows Server 2003+, Windows Vista, or Windows 7 as its operating system, you'll need to assign file permissions to the NETWORK SERVICE account. If your Logi application runs on a web server with either Windows XP or Windows 2000 as its operating system, you'll need to assign file permissions to the local ASPNET machine account. Note: that's "ASPNET", without a period, not "ASP.NET". This presumes a default OS installation in which no special renaming or removal of default accounts has been undertaken. 113 Getting Started with Logi Info and Logi Report for Java For a Java-based server, the account that is used to run web applications is the one that will need to be granted file permissions. Which Application Sub-Folders? Your web server account will, of course, have to be able to read all of the files in your application folder. The two sub-folders in your Logi application folder that will routinely need to have write permissions granted to them are rdDataCache and rdDownload. The latter is often used as a convenient place to hold temporary files and does not necessarily have anything to with actual downloads. If, in the course of your development work, you add your own new sub-folders to hold data files or "save files" used with elements like a Dashboard, or decide to write data to another folder you will need to grant Write and possibly even Full Control permissions to them as well. One approach that guarantees access is to give full control permissions to the Logi application folder (which is what the Studio New App wizard does). All files and folders within the app folder then inherit the permissions. However, this is not necessary and, as mentioned earlier, may cause security concerns. Granting File Access Permissions Depending on your OS, you'll use File Explorer or My Computer to set file permission. The examples images used below come from Windows XP Pro. 114 Getting Started with Logi Info and Logi Report for Java 1. On the web server, navigate into your Logi application's folder and select the rdDataCache folder. 2. Right-click the folder and select Properties from the pop-up menu, as shown above, left. 3. In the Properties dialog box, click the Security tab, as shown above, right. Click Add... No Security tab visible? See special section below. 4. The account used must be a local account, on the computer, rather than a network account. In the Select Users dialog box, shown above, left, click Locations... 5. In the Locations dialog box, select the computer's name, which will be at the top of the list. If the computer is not part of a network domain or even on a network, this step may be unnecessary. 6. Enter the desired account name (ASPNET or NETWORK SERVICE) into the Select Users dialog box, as shown above. If desired, you can click Check Names to verify spelling and account existence; if valid, the name should change to <computer name>\<account name>. Then click OK. 115 Getting Started with Logi Info and Logi Report for Java 7. Back in the rdDataCache Properties dialog box, you'll see that ASP.NET Machine Account has been added to the list of user names, as shown above. 8. Select the ASP.NET account in the list and check the Write permissions checkbox. Ensure that the other checkboxes shown are also checked. Click OK. Repeat this process for the rdDownload folder and for any other folders that you'll be writing data to. Granting Permissions to Windows 7 App Pools In addition to setting the permissions shown above, you may also need to give permissions to the "application pool". Logi applications are generally run by IIS within an application pool, which provides isolation and performance improvements for web apps that may use different versions of .NET. To assign file access permissions to an application pool: 116 Getting Started with Logi Info and Logi Report for Java 1. Open the IIS Manager utility, locate your Logi application and determine, by examining its properties, which application pool it's assigned to. Note the name of the pool ("DefaultAppPool" in the example). 2. In the example above, we're setting permissions for the sub-folder "SavedFiles". Use File Explorer to navigate to your Logi app folder, then select and right-click the sub-folder in question, and select Properties. 117 Getting Started with Logi Info and Logi Report for Java 3. In the Properties dialog box, click the Security tab, and then the Edit button. 4. In the Permissions dialog box, click Add. 5. In the Select Users or Groups dialog box, enter "IIS APPPOOL\<the app pool name>" as shown above. 6. Click OK, to close the dialog box and return to the Permissions dialog box. 118 Getting Started with Logi Info and Logi Report for Java Finally, select the application pool in the names list, and set its permissions, as shown above. Then click OK. No Security Tab Visible? In order to make the Security tab visible in the Properties dialog box, you must turn off Simple File Sharing. This is usually an issue only on stand-alone computers. 1. Open Control Panel and locate the Folder Options link. In Windows XP, this is through the Appearance and Themes link. Or, instead, you can access Folder Options through the Tools menu item in My Computer. 2. In the Folder Options dialog box, select the View tab. 3. At the very bottom of the Advanced settings, un-check the "Use simple file sharing" option. Click OK. The security tab should now appear when you select a file or folder's properties. 119 Getting Started with Logi Info and Logi Report for Java Managing Support Files In Logi applications, "Support Files" are defined as files that are part of an application that are not Report, Process, or other definition files. This chapter discusses support files and their management within an application and provides important information about how files are handled in Studio. These files generally include: Images (.gif, .jpg, .jpeg, .png, .bmp, .wmf, .xbm, .art) Style Sheets (.css) Scripts (.js) Data files (.csv, .mdb, .xls, .xlsx, .xml) HTML files (.htm, .html) Other files, for example CSV data files, required for an application can be included in this category but definitions for Templates and Widgets cannot. Logi Studio and the support files concept are designed to make managing these files as easy as possible. In Logi Studio, support files are managed in the Application Panel. The panel display standard organizational folders for each category of file in an application, including the support files. The default manner in which support files are displayed is shown above left, with all support files shown together. Right-clicking the Support Files folder produces a popup menu, as shown above right. Note that the adding an existing file copies the existing file to your project folder; the original file is left untouched. The Application panel displays the files that are included in the application; there are no Registry entries, tables, or other data concerning the files maintained by Studio as part of an application. This allows you to move, rename, or delete files outside of Studio without causing havoc. Adding a large number of support files from within Studio could be time-consuming. To save time in this situation, files can be copied outside of Studio, using file system tools, directly into the appropriate folder. The files will automatically appear in Studio the next time the Application panel is refreshed, or the application is closed and re-opened. 120 Getting Started with Logi Info and Logi Report for Java The image above shows a typical collection of files and folders for a basic Logi application, as they exist in the file system. The top two folders, highlighted in yellow, correspond to the Reports and Support Files folders shown in Studio's Application panel. Other empty folders shown in Studio, such as Templates, will be physically created in the file system automatically when they're given some contents in Studio. Studio is equipped with editors in the Workspace panel for all support files except images. Double-clicking these files will open them in the Workspace panel for editing. Developers can also manage the files (copy, delete, rename, etc.) from within Studio by right-clicking them, as shown above. 121 Getting Started with Logi Info and Logi Report for Java If you wish to further organize your support files, you can do so by creating a new "folder", as shown above. This is a logical folder and does not appear in the file system as a separate folder. Here's how this works: when you create a new logical folder, you can give it a name, such as "dataXMLs". Files that you add to that folder from within Studio will appear in the file system with the folder name prepended to their name, with a dot separator. Or, if you're working directly in the file system, to get files to appear in that folder, you rename them to begin with the folder name and a period. So, for example, renaming sampleTopics.xml to dataXMLs.sampleTopics.xml in the file system will cause it to appear in Studio "inside" the new folder you created. You're not required to manage support files from within Studio, but by doing so you ensure that all necessary files are included in the project folder, simplifying deployment. In addition, specifying the location of files within your report definitions is simplified as the standard support file folders are "known" to Logi applications. 122 Getting Started with Logi Info and Logi Report for Java Using Themes and Style Sheets This chapter introduces developers to features that can be used to control the presentation of Logi applications. You'll learn how to use Themes, how to include a style sheet within a Logi application, and how to assign individual style classes to elements. About Themes Themes were introduced in Logi v10. In the context of Logi products, a "theme" is a collection of graphic images, a style sheet, and a template modifier file, that impart a specific appearance to a Logi application. Several standard themes are included with Logi Info and Logi Report for your use and are also available on DevNet in the Sample Themes library. These themes include a collection of graphic images, a style sheet, and a template modifier file, which impart a specific appearance to a Logi application. Themes do the work for you, setting appearance attributes for complex elements such as charts and superelements such as the Analysis Grid, and making it easier to produce great looking reports without an in-depth knowledge of Cascading Style Sheets. You can easily switch between themes in order to experiment with them. As of this writing, the standard themes shipped with the products include: Theme Black Pearl Clarity Professional Blue Professional Green Signal Silver Simple Blue Transit Description A black background and dramatic colors make this an unusual theme. Offers a clean look that's "easy on the eyes". Gradients and a polished look, with colors grouped in the blue spectrum. Gradients and a polished look, with colors grouped in the blue spectrum. A modern, professional, and attractive look that works well with both desktop and mobile displays. A simple, understated look. A stronger appearance with flat blue color scheme. A bold theme designed to look good on mobile devices. Introduced in 10.0.31 10.2.424 10.0.31 10.0.31 11.3.049 10.0.31 10.0.31 10.2.424 Note that standard themes may be updated when a new product version is released and this may produce small changes in the appearance of applications that are upgraded to the new version. Similarly, applying an updated theme to an application using an older product version or vice versa, by copying them, may result in an unexpected appearance. Use Beyond Appearance Themes, however, are not "just a pretty face". Because themes are capable of altering your report definitions, they can be used for purposes unrelated to application appearance. For example, they can be used to set default attribute values. This can be very useful if you consistently use the same set of attribute values for, say, 123 Getting Started with Logi Info and Logi Report for Java data tables, and you want to apply them as defaults every time you start a new definition or application. See the final section in this document for more information. Selecting a Theme in Studio’s Wizard When you use the New Application wizard in Studio, one of the steps is the selection of a theme for the new application: Just select a theme from the list and it will be applied automatically to your new application. Adding Themes Manually You can also apply a theme manually. A theme can be applied at the application level (which is what the wizard does): 124 Getting Started with Logi Info and Logi Report for Java As shown above, to apply a theme to the application as a whole, add a Global Style element to the _Settings definition. Then set its Theme attribute to the name of one of the available themes. All reports in the application will have the theme applied to them. To apply a theme to an individual report definition: As shown above, add a Style element to the report definition. Then set its Theme attribute to the name of one of the available themes. The report will have the theme applied to it. Themes and Style Sheets When a Theme is selected for a definition or application, it automatically applies a specific appearance to super-elements, like the Analysis Grid. In addition, the Theme makes available a standard set of style classes that developers can apply to regular elements. This can save a lot of time and helps to create a consistent appearance. 125 Getting Started with Logi Info and Logi Report for Java In the example shown above, we see a definition that has had a Theme applied to it. A Division element has been selected and one of the Theme-supplied style classes is being assigned to it. As you can see, all of the Theme-supplied classes begin with the letters "Theme" and they address alignment, font sizes, borders, and other useful styles. Themes do not set the style class for every element; for example, Label and Rows, Row, and Column Cells (HTML tables) are not affected. You can set the Class attribute for these elements independently of the Theme. You can specify both a style sheet and a Theme in a Global Style or Style element. If you have a style sheet and a Theme assigned, the available classes from both will appear in the drop-down class list. Interaction with Other Style Sheets You may already have a style sheet that you like to work with when developing reports. How will that interact with a theme when it's applied to your report? If you have assigned a style class to an element and the theme also applies a style class to that same element, the theme's style will be applied first, then yours. This means both styles will be applied but your style will "win" when there's a direct conflict. When there's no conflict, the effect will be additive. Themes and Exports Theme effects will also be applied to exports, which may or may not be desirable, and there is no way to block or undo the effects of a theme that has been assigned using the Global Style element. So if you plan to export reports to a format where appearance is important, such as PDF, you may want to assign themes using individual Style elements in each report, instead of the Global Style element. Creating Your Own Themes More advanced developers are encouraged to examine the stock themes and use them as a "jumping off" point for the creation of their own custom themes. At a minimum, themes consist of a Theme Modifier file, which does the work. Themes that impart an appearance generally also include a collection of images and a Theme style sheet. While themes are generally used to give an application a specific appearance, the Attribute Defaults sample theme (Advanced category) here on DevNet is an example of a theme that sets attributes to default values, but does not deal with appearance. Standard themes distributed with v10 and v11 Logi products are stored, when you create an application, in <yourApp>\rdTemplate\rdTheme folder and these should never be edited. 126 Getting Started with Logi Info and Logi Report for Java However, you can copy them and then customize the copies. Any themes you create should be stored in a folder named _Themes beneath your application folder, i.e. <yourApp>\_Themes. They will then be available for your application, along with the stock themes, in the Style element's Theme attribute selection list, and will also be available for deployment with Studio's Deployment Tool. One of the key mechanisms in a theme is the "template modifier file" or TMF. A TMF is an XML file that includes instructions for modifying the elements and attributes in a report definition. The TMFs in the stock themes are quite complex, as they attempt to cover all of the elements one might use in a report. Your custom themes do not necessarily have to be so all-encompassing; they could, for example, only address the charts or other elements that are specifically in your reports. If you examine the TMF and style sheet in one of the stock themes, you'll see that the class and ID names are all carefully constructed to be unique, which is very important and which you are also encouraged to do. Our document Using Template Modifier Files provides detailed information about creating and using TMFs. DevNet's Element Reference page has information about all of the elements and their attributes and may be useful when creating your own themes. If you want your custom themes to be available in Studio's New Application wizard, copy them to (.NET) C:\Program Files\LogiXML IES Dev\LogiStudio\BaseApp\RepDev\rdTemplate\rdTheme (Java) C:\Program Files\LogiXML IES Dev\LogiStudio\BaseApp\RepDevJava\rdTemplate\rdTheme The New Application wizard displays a thumbnail image of each theme. If you want to include images for your custom themes, place them, as a 225 x 160 px .JPGs with the same names as your themes, in this folder: C:\Program Files\LogiXML IES Dev\LogiStudio\bin Finally, if you create an appearance-specific, custom theme that you think looks cool, it would be great if you shared it on DevNet. About Cascading Style Sheets Cascading Style Sheets (CSS) is a technology that allows the presentation aspects of web pages to be separated from the other page content. It can be used to add "style" (e.g. fonts, colors, alignment, spacing, and more) to web pages. It's a mature standard, fully supported by the W3C. If you're a developer with web design experience you should already be familiar with style sheets. 127 Getting Started with Logi Info and Logi Report for Java Internet Explorer has lagged behind Firefox and Chrome in supporting new CSS standards. Not only does this introduce compatibility issues you may have to deal with but, because Logi Studio uses the Windows operating system's IE components, Studio's Preview function may be affected. Issues of this nature tend to arise especially if you integrate 3rd party libraries that make heavy use of HTML5 and CSS3 into your Logi application. If you're a developer with web design experience, you should already be familiar with style sheets. If not, as used with Logi applications, style sheets are independent text files that define style "classes" with property settings. For example, the definition for the class "font8ptBold", shown below, contains selectors that cause text to appear in an 8-point, bold font: .font8ptBold { font-size: 8pt; font-weight: bold; } Classes are assigned to elements within a Logi application in order to control their appearance. For example, we might assign the font8ptBold class to a Label element so that its caption will appear on the web page in an 8-point, bold font. CSS includes a wide variety of selectors that can affect everything from font weight, size, and color to the positioning of images on the page. Use of style sheets creates slightly more complexity for the developer than having appearance properties directly associated (as attributes) with elements in Logi Studio. The trade-off, however, is that they offer far more flexibility and browser-version compatibility. Logi reporting tools are CSS standards-compliant and to help you work with style classes, Logi Studio includes a style sheet editor. Logi products allow you to set a "doctype declaration" for your application, which gives the browser some guidance about how to render the page. This is discussed in our document Using Doctype Declarations and can help sort out some the behavioral differences between browsers. The "cascading" part of the style sheet name refers to the way in which the effect of a class permeates downward through hierarchical structures of elements in web pages. The effect starts at the top and, unless superseded by other classes, continues downward within the container, structure, or child elements. You can develop your own "standard" style sheet file (or files) and then re-use it or parts of it with different Logi applications. This saves development time and promotes a consistent look for your applications, if desired. You may care to develop and share a "company style sheet" so that all of your Logi application developers produce reports with the same appearance. Style classes can be applied in a number of ways, including "inline" or embedded directly into HTML. However, it's beyond the scope of this chapter to provide a complete explanation of Cascading Style Sheets; excellent resources can be found online at http://www.w3schools.com/css/css_intro.asp . Create an Example Style Sheet Select and copy the following text, paste it into Notepad or a similar text editor, and save it to your desktop (or any other location you prefer) as CSSExample.css: 128 Getting Started with Logi Info and Logi Report for Java /* CSSExample.css: our example style sheet */ .myTable { padding: 5px; border-width: 2px; border-style: solid; border-color: Silver; border-collapse: collapse; background-color: White; font-family: Verdana, Arial; /* if Verdana font not found, will use Arial */ font-size: 9pt; font-weight: normal; color: Black; /* this is the font color */ } .myTable TH { padding: 5px; border-style: solid; border-color: Silver; background-color: #F0F0F0; font-size: 10pt; color: Maroon; } .myTable TD { border: 2px solid Silver; padding-left: 5px; padding-right: 5px; text-align: center; } /* TH: automatically applied to table header */ /* colors can also be specified using hex */ /* TD: automatically applied to table cells */ /* combines three border selectors into one */ .fontBold { font-weight: bold; } /* end of style sheet */ If you're wondering what those "TH" and "TD" designations are, they relate to the tags that make up an HTML table: TH = Table Header, and TD = Table Data. By including them as shown above, their classes will be automatically applied to any data table that uses the myTable class. This is a bit of CSS shorthand that saves you time and effort. The next two sections discuss how to include this style sheet in your application, and how to edit it within Studio. Including a Style Sheet in Your Application For the remainder of this document, we'll show screen shot images based on a fictional Logi application that pulls data from the Northwind Foods database (creating a similar, real application is discussed in our Basic Report Tutorial). If you already have a basic Logi database table report created, you can use it as we proceed. From the Logi application perspective, a style sheet is a support file that's included with a report application. In Logi Studio, the Support Files folder in the Application Panel provides an interface for managing style sheets. Multiple style sheets can be included within a Logi application and they appear in Studio's Application Panel. 129 Getting Started with Logi Info and Logi Report for Java A style sheet is considered a Support File which is included with the application. In Logi Studio, the Support Files are organized in the Application panel (upper left corner) beneath their own folder, as shown above. Now let's add your example style sheet one to your application: 1. 2. 3. 4. In Logi Studio, right-click the Support Files folder in the Application panel. Select Add Existing File... from the popup menus. Browse to the location where you saved the example style sheet, select it, and click OK. The CSSExample.css style sheet will be added to your list of application support files and the file itself will be copied to your application project file, in the _SupportFiles folder. As you see, multiple style sheets can be included within a Logi application. When you right-clicked the Support Files folder to add the style sheet you created earlier, you may also have noticed an option to Add → New File... which lets you create a style sheet file from scratch. Editing a Style Sheet in the Workspace There are several ways to edit style sheets from Logi Studio and the most direct way is to do it right in the Studio Workspace editor: 1. 2. 3. 4. 130 In the Application panel's Support Files folder, double-click the style sheet file to be edited. The style sheet contents will appear in the Workspace panel, as shown above, and can be edited. As you type, the editor will provide assistance via pop-up lists of selector names and values. Make the necessary changes or additions and click Save on the toolbar. Getting Started with Logi Info and Logi Report for Java Note that use of the Workspace Preview tab automatically saves definition files but does not save style sheet changes. You must click Save to save your changes before previewing. You can also select and right-click a style sheet file in the Application panel, and click Open Externally to edit it in any external CSS editing tool, such as Top, that you have installed. The file will be opened in whatever application is associated with the .css file extension Editing in the Style Sheet Selector Turn your attention to the Attributes panel now. Many elements have a Class attribute and its value field includes a drop-down list icon. Clicking this icon causes a list of classes from the style sheet(s) assigned to your application (described in the next section) to be displayed. The top item in this list is a link to the Class Selector tool, which offers a second method of previewing and editing your style classes. The Class Selector tool can be opened by selecting it from the list of Class attribute value choices for any element, as shown above. 131 Getting Started with Logi Info and Logi Report for Java The Class Selector tool, shown above, allows a class to be assigned by selecting it in the class list (1) and clicking OK. The attributes of the selected class are shown in the upper right panel (2) and they can be edited there. Controls (3) allow you to save, add, and delete classes and the effect of the selected class is shown in the lower preview panel (4). Editing a Style Sheet Using the External Style Sheet Editor The external editing option works only if you have installed a 3rd-party style sheet editor program, which has been associated in the file system with the .css file extension. This external editor can then be launched from within Studio in two different ways: A style sheet file can be selected in the list of files in the Application panel, right-clicked, and opened externally, as shown above left. Or, in a report definition, when the Style element's Style Sheet attribute has been selected in the Attributes panel, as shown above right, the Open Referenced File... icon will appear and can be used to open the file in the external editor. Note that, if you've edited a style sheet in an external editor, you may need to "refresh" the file in Studio before any changes are recognized. This is done by right-clicking the file in the Application panel and selecting Refresh Application. Applying a Style Sheet to Your Definition Once a style sheet file has been added to an application's _SupportFiles folder, it's available for use with any of the definitions within that application. 132 Getting Started with Logi Info and Logi Report for Java 1. Open your report definition in the Workspace panel and select the Style element, as shown above. 2. In the Attributes panel, click the Style Sheet attribute and pull-down the list of available style sheets. 3. Select the CSSExample.css style sheet entry in the list, which will assign it to the Style Sheet attribute. Now the classes in that style sheet are available for use in your definition. Assignment Using a URL If a style sheet resides on a web server, it can instead be assigned using an absolute URL, such as: http://www.myFirm.com/CSS/myStyleSheet.css Just enter the URL into the Style Sheet attribute, instead of a file name. Global vs. Local Style Sheets The presence of the Style Sheet element in a report definition indicates a local style sheet, one that applies only to that definition. A Logi application may contain several report definitions, and each definition may use a separate style sheet. Alternatively, a global style sheet can be used instead, one that affects all report definitions in an application. The global style sheet is configured in the _Settings definition. Or, if they will all use the same style sheet, a global style sheet can be used for all report definitions in the application. The global style sheet is configured in the _Settings definition: 133 Getting Started with Logi Info and Logi Report for Java 1. Select the _Settings definition in the Application panel and then select the root element (_settings) in the Workspace panel. 2. Double-click a Global Style element in the Element Toolbox to add it to the definition. 3. Select the newly added Global Style element in the Workspace panel. 4. In the Attributes panel, enter a value for the Style Sheet attribute or select one from the pull-down list. Now all of the applications definitions will be able to use classes from the global style sheet and you need not assign a style sheet to each definition individually. However, what happens if you assign both a local and a global style sheet, and each has a class with the same name but with a different class definition? As you might guess, the local style sheet's classes will override those of the same name in the global style sheet. Assigning Style Classes to Elements Now you're ready to assign style classes from the style sheet to elements in your application. The images below assume this query: SELECT CategoryID, CategoryName, Description FROM Categories has been used to produce a report from the Northwind Foods database. Follow along in your application, making adjustments as necessary. These examples assume you've already assigned the CSSExample.css style sheet to your application. The report output above shows the data returned by the query. It's raw, unformatted, and ugly. Let's assign some style sheet classes to improve the appearance of our output. Elements that can be affected by classes have a Class attribute. Some may have several class-related attributes depending on the complexity of the element. 134 Getting Started with Logi Info and Logi Report for Java In your report definition, select the Data Table element and, in the Attributes panel, find its Class attribute and, using the drop-down list, select the myTable class, as shown above. Note that the list includes all of the classes in your style sheet. It's also possible to manually assign multiple classes, separated by commas or spaces, as a Class attribute value. Now let's preview the report: As shown above, here's our table with the style sheet classes applied. Quite a difference from the raw table! The style sheet has affected font sizes and colors, text alignment, background color, spacing and padding, and borders. The classes affect everything about the table and its contents, flowing down through the Data Table element and all its child elements. This is the "cascading" effect of Cascading Style Sheets. However, the effects can be overridden by assigning other classes to child elements lower down in the hierarchy. Let's see how that works. With the myTable class assigned to the table, all the data in all the columns appears in a normal, black font. Let's change the data in the first column, the CategoryID, to be bold-faced as well. 135 Getting Started with Logi Info and Logi Report for Java As shown above, select the Data Table Column element for the Category ID and, in its Class attribute, select the fontBold class from the drop-down list. As you can see above, the class applied to the data column has produced an additive effect, in that column only. We could just as well have assigned the class to the Label element that actually displays the data. By assigning it to the Data Table Column, we applied the affect to all its child elements, which covers situations where you have multiple Labels or other elements in the column. Create an Alternate Row Class If you're using a standard Logi theme, it comes with a ThemeAlternatingRow class that you can assign to your Data Table element's Alternating Row Class attribute. If you're not using a theme, or want to create your own class for alternating data table rows, the following exercise shows you how to do it. Add a new class to the style sheet and then assign it to the Data Table. The goal is to have every other row in our table look slightly different, which makes it easier to read across many columns. 1. In the Application panel, double-click and open the CSSExample.css style sheet file. 2. In the Workspace editor, add the following CSS class: .alternateRows { background-color: LightYellow; } 3. Click the Save icon in the toolbar, to save the style sheet changes. 4. Click the tab at the top of the Workspace panel to return to your report definition. 136 Getting Started with Logi Info and Logi Report for Java 5. Select the Data Table element and assign your new alternateRows class to the Alternating Row Class attribute. 6. Preview the results: Create Dynamic Row Highlighting If you're using a standard Logi theme, it automatically applies dynamic row highlighting. However, if you're not using a theme, or want to create your own class for dynamic row highlighting, the following exercise shows you how to do it. Note that this effect may not work with all browsers (especially older browsers): 1. Once again, open your CSSExample.css style sheet file. 2. In the Workspace editor, add the following CSS class: .myTable TR:hover TD { background-color: LightYellow; } 3. 4. 5. 6. Click the Save icon in the toolbar, to save the style sheet changes. Click the tab at the top of the Workspace panel to return to your report definition. Select the Data Table element and delete the Alternating Row Class attribute value, leaving it blank. Preview the results, and pass your mouse cursor over the rows: As you’ve just seen, style sheets are powerful tools that assist you in creating visually-interesting report presentations. More information about style sheets can be found in our documents Managing Style Sheets and Using Style Sheets. 137 Getting Started with Logi Info and Logi Report for Java Development Best Practices Logi Analytics offers training for our managed reporting products and this chapter enumerates the "best practices" that are taught in our classroom sessions covering report development with Logi Studio. The items included here are based on the experiences of hundreds of Logi developers and offer the new developer a head start in learning correct and valuable Logi development techniques. 1. KISS: Begin with the end in mind Keep it simple! Start to design your report definition by mentally visualizing the finished report or web page. If necessary, sketch it out on paper to understand the broad page geography and to identify separate regions. 2. DevNet is your BFF DevNet is your best source for documentation, reference, and samples. 3. Always turn on Debugger Links During the development process, turn on and leave on the Debugger Links debugging option. 4. Speeling matters, cAse matters Pay close attention to spelling accuracy and the correct use of case. Always assume that case is significant, even when dealing with SQL syntax (case-sensitivity may have been enabled for the database server). 5. Think "Waltzing @~" When working with tokens, think of the famous Australian bush ballad, Waltzing Matilda, and let it remind you to start every token with an @ sign and, most importantly, to end it with a ~ (tilde). 6. Always edit your definitions in Studio Studio provides the best environment for development and will catch or prevent many errors. 7. Save early, save often Save your work in Studio frequently to avoid a loss due to power outages or equipment failure. Back-up your work at the end of a productive day. 8. Always specify the data type Always set the Data Type attribute value for sorting and group elements and others that use it. 9. Use regular file names Don't use spaces or special characters in file names. 10. Provide a unique ID for every element Provide a unique ID for every element, even when it's optional, and don't use any special characters in the ID. Use a logical and consistent naming scheme for element IDs. 11. For best performance, do it in SQL If possible, do as much grouping, sorting, and qualifying as possible in SQL (i.e. on the database server), instead of with datalayer child elements. 138 Getting Started with Logi Info and Logi Report for Java 12. Filters and Conditions always "Filter Through" In general, data filtering is hierarchical and cumulative: later filtering begins with the results of any earlier filtering. Security Filters are an exception to this rule. 13. Use Divisions liberally Use Division elements often to provide structure to your report definition, making it easier to maintain, copy, or rearrange grouped elements. Divisions also make it easy to apply Style, Security, Conditions, and Show Modes to groups of elements. 14. When exporting, always "Go Native" When building exports into your report definition, always select those elements with "Native" in their names, such as Export Native Excel and Export Native Word. 15. Always specify the Connection ID Always set the Connection ID attribute value for datalayers and other elements that use it. 16. Quote Text comparisons, not Numeric comparisons When making comparisons in Condition attributes, in SQL queries, and in script functions, always quote (or double-quote) text, but not numbers. For example, place double-quotes around a request variable and a literal when comparing text: "@Request.Name~" = "Fairfax" but not around those comparing numbers: @Request.InvoicePrice~ < 100 17. "Column" in Attribute name means no token If an attribute name includes the word "Column", don't use an @Data token in the value; just use the column name by itself. 18. Use Shared Elements to reuse code, save time Use Shared Elements to optimize the reuse of repetitive code and to provide "single-source" maintenance. Always collect your shared elements into a separate report definition of their own - do not mix them into other report definitions. 19. Give Excel export a Worksheet name When exporting to Excel, always provide a name for the Pattern Block element's Worksheet attribute. 20. Multi-Selects need IN and SingleQuote Token When working with user inputs that allow multiple selections, use the IN( ) function in your SQL WHERE clause and use the @SingleQuote token as a prefix to wrap the resulting comma-delimited input values in single quotes in the query. For example, SELECT * FROM MyTable WHERE Color IN(@SingleQuote.Request.MySelectList~) 21. Test Templates with Dummy Data Always populate Excel Template support files with dummy data to test formatting and formulae 139 Getting Started with Logi Info and Logi Report for Java Debugging Reports This chapter introduces developers to debugging techniques for use with Logi Studio. It provides you with information about the tools and techniques available in Studio to help you understand what's happening within your application, especially if things don't work as expected. Previewing and. Browsing A Logi application may have one or more report definition files and, while actually browsing a report shows you the big picture, doing so can be cumbersome if you have multiple definitions and have to “drill-down” every time. Studio's Preview tab provides the developer with a fast way to view report definitions without changing the Default Report attribute in the _Settings definition. 1. To preview a Report definition in Studio, first open the definition in the Workspace editor. 2. Click the Preview tab at the bottom of the Workspace Panel, as shown above. 3. Browse and interact with the report definition using the toolbar at the top of the Preview panel. Logi Info developers can also test their Process definitions in a similar way: 140 Getting Started with Logi Info and Logi Report for Java 1. 2. 3. 4. In the Application Panel, select and open the process definition to test. In the Test Parameters Panel, set values for any parameters the process task requires. At the bottom of the Workspace Panel, select the individual process task to test in the task list. Click the Run button at the bottom of the Workspace Panel, as shown above. Using Live Preview The Live Preview feature allows you preview your work in a separate, "live" desktop window. The Main Menu's Live Preview item is shown above. The live preview will be displayed in a separate window and any changes made to the definition will immediately be reflected in that window. You can resize and relocate the new preview window as desired; you can even drag it onto a separate display, if you have one. You can also switch to Live Preview from regular Preview mode: To start Live Preview, first preview the report definition, using the Preview tab, and then click the Live Preview icon, circled above. The preview will be displayed in a separate window, and Studio will switch back to its Definition tab. You can resize and relocate the new preview window as desired; you can even drag it onto a separate display, if you have one. Any subsequent changes you make to the definition code will immediately be reflected in the Live Preview window. 141 Getting Started with Logi Info and Logi Report for Java If you don't want definition changes to be updated immediately in the Live Preview window, you can pause and restart them, using the Pause and Play icons in the Live Preview window, circled above. To exit Live Preview, just click the Live Preview window's Close (X) icon. Browsing the Default Report Definition In a Logi application, one of the report definitions is designated (in the _Setting definition) as the "default" report - the page that will be shown if no definition is specified in the URL. If you don't change it, this is usually the Default report definition. You can browse the default report by clicking the Run Application menu item, shown above, in Studio's Main Menu, or by pressing the F5 key. Your computer's default browser (the one associated with .htm/.html file extensions) will be used for this. You can change the "default" report designation using two methods: 142 Getting Started with Logi Info and Logi Report for Java As shown above, left, in the Application panel, select the desired report definition, right-click it, and select Set As Default from its context menu. This sets the Application element's Default Report attribute, shown above, right, in the _Settings definition. You can also manually edit this attribute value directly in the _Settings definition. Using the Run Application menu item will save all open, unsaved definitions before displaying the report. Using Comments, Remarks, and Application Notes As an application grows in size and complexity, it's often helpful for developers to leave in-line comments and descriptive notes within the definitions. The Note element holds these comments and can be placed anywhere in a report definition; it's ignored when the report is executed. In the above example, Note elements have been placed in the _Settings definition to provide instructions for other developers. Placing the Notes in different levels of the tree establishes context for the reader, as show by the final note element above. Blue is the default note text color, but you can change this using Studio's Tools → Options menu. To add a comment: 1. 2. 3. 4. Double-click the Note element to add it to the definition. Select the newly added Note element to define its attributes. Double-click the Note attribute to open the Zoom window, type your comment, and click OK. To prevent Notes from appearing in the generated HTML page, remark them (see below). Remarking Elements During development, it may be helpful to temporarily "comment out" certain elements. The developer can remark a single element or an entire hierarchy of sub-elements in order to temporarily hide them from execution. This can be an important debugging tool as it allows you to selectively prevent execution of parts of the application. A common troubleshooting technique is to remark a definition repeatedly, successively reducing it down to fewer and fewer basic parts, in order to isolate the source of a difficult-to-find error. 143 Getting Started with Logi Info and Logi Report for Java In the example above, the first two Divisions in the element tree are active. A third Division element has been remarked and appears in a green font; it is therefore inactive. Green is the default color but you can change this using Studio's Tools Options menu. Remarked elements do not affect the appearance or functionality of the application but remain present in the definition file. At runtime, the Logi Server Engine ignores remarked elements and they are not rendered into the HTML page output. To remark an element: 1. Select the element to remark from the definition file. 2. Right-click it and choose Remark from the pop-up menu. Because elements are structured in a hierarchical tree, if a parent element is remarked, all of its child elements in the tree are also remarked. Writing Application Notes It's often useful to write detailed notes about topics that affect the entire application, such as database modifications or session variable names, and the Note element isn't useful for this purpose. Instead there's an Application Notepad for each Logi Studio application. To access it, switch to the Welcome tab in the Workspace panel. 144 Getting Started with Logi Info and Logi Report for Java To write Application Notes: 1. Click Edit Notes to begin writing the application notes. 2. Type the notes in the provided textbox. 3. Click Save Notes to commit the changes. The following formatting options are available when writing application notes: Bold, Italic, and Underline Bulleted List Numbered List Decrease Indent Increase Indent Insert Link Using the Test Parameters Panel One of Studio's least well-known panels is the Test Parameters panel. Studio makes this panel visible when the current definition expects to receive and use parameters. It provides a way for developers to supply request variable values for their definitions when previewing them in Studio and it makes experimenting with different values very easy. The example above shows this panel in use. Studio will automatically populate the left column with the tokens for any request variables expected by the currently selected definition in the Workspace. You can enter values for those tokens, and they'll be fed to the definition when you Preview it in the Workspace panel, or right-click it in the Application panel and select "Run in Browser". 145 Getting Started with Logi Info and Logi Report for Java The token values in Test Parameters are not fed to the application when you click the Run Application menu item or press the F5 key. Using the Application Debugger Logi Studio provides debugging features for an application, but they have to be enabled to work. They are not enabled by default. You can turn on debugging for all your report pages by clicking the Debug menu item, shown above, in Studio's main menu in the Home tab, and selecting Debugger Link from the options. Selecting a debugger style in the toolbar sets an attribute value in the General element, in the _Settings definition, as shown above. This value can also be set manually. 146 Getting Started with Logi Info and Logi Report for Java Now, when run, each report page will include a debugger link at the bottom. As shown in the examples above, the link itself changed beginning in v11.0.127. When activated, the original text link was always at the bottom of the page; the new debug icon "floats" in the lower right-hand corner of the browser window so that you don't have to scroll down to use it. Click this link to display the Debugger Trace Page (discussed below). Any charts on the page will have their own separate debugger links. Beginning in v10.0.299, you can right-click the link to open the debug page, open it in a new tab, or in a new window, etc. Each chart will have its own debug icon or link, as well, and a separate debug trace page. The other debugging modes include: Debugger Link No Data - Produces the same report as Debugger Link, but does not include links to, nor cache, the XML data retrieved. For more discussion of this option, see below. Error Detail - Appends detailed error at the bottom of a page only when an error occurs. No Details - Prevents any debugger information from appearing when there's an error, so the user cannot see sensitive system security information. Use this option for system deployment. Redirect - Redirects the browser when an error occurs to a custom error page, at the URL you must specify in the "Redirect Error URL" attribute. The default value is No Details. Using Debugger Link No Data Why is Debugger Link No Data useful? When you debug using the standard Debugger Link setting, debug data files are generated for all of the datalayer elements inside your report. Creating these files requires a significant amount of processing overhead and your reports will run slower. How much slower depends on how much data there is, but expect ~2x slower for each datalayer element. However, if you wish to debug for performance reasons and want to inspect the timings of different events, you can use the Debugger Link No Data setting, which creates no debug data files and incurs no processing overhead, to produce a more accurate execution time profile. 147 Getting Started with Logi Info and Logi Report for Java About the Debugger Trace Report When the Debugger Style has been set to Debugger Link or Debugger Link No Data, the Debugger Trace Report can be accessed in two ways: using the Debug icon or link discussed earlier, or from a link that appears on a runtime error page. The trace report appears either in the Preview panel or in your browser, depending on which method you were using to view your report. 148 Getting Started with Logi Info and Logi Report for Java As shown above, the Debugger Trace Report includes step-by-step events, values, and time notations for the report run. Tracing application execution is very useful for troubleshooting, especially for data retrieval issues. Here are some of the items you'll find in the trace report: 1. The Trace Report shows valuable information about the system environment. 2. The Trace Report shows the Request parameters being passed to the report, which can be helpful in determining what values are being passed from other reports or as a result of user input. 3. Datalayer activity, such as a SQL query issued to a database, is shown. This is especially useful if some of the query includes tokens that are resolved at runtime. SQL queries shown here can be copied and pasted into Studio's Query Builder or other tools in order to run and test them independently. Data retrieval and manipulation operations are optimized under one or more "data operation plans" to reduce data cache reads and writes. Plan information now appears in this section of the debug report. 4. If the Debugging Style selected was Debugger Link, you can view the underlying XML data to verify the retrieval of data from a SQL database; if the XML data is absent or incomplete, then the SQL query syntax should be examined. 5. If the Debugging Style selected was Debugger Link, the data in the datalayer, after retrieval and subsequent processing with condition filters, calculated columns, grouping, etc., can be viewed. 6. A bar chart is integrated into the column, which gives you a visual reference for performance during each step. 7. If you're working with a Logi Java application, the Trace Report will also include a special section near the top that presents information about your Java configuration. 149 Getting Started with Logi Info and Logi Report for Java In addition, if an error has occurred, a detailed error report, shown above, including the stack trace will also appear, often with a more detailed error message to aid in debugging. Debugging Scripts You can also cause debugging to extend to scripts: To enable this, configure the General element's Script Source Debugger Style attribute. Its None value is the default, or you can set it to OnError, in which case the View Script File link shown above appears in the Debugger Trace Page when an error occurs. This link displays the script as generated when the report was run. If the script is a simple, single line of script, the actual error may appear here instead of a link. A third value option, Always, causes the link to appear in the trace page at all times. The routine use of Always is discouraged as it will incur a significant performance hit. Logging Errors If errors are intermittent or difficult to reproduce, then logging the errors may be a good strategy for observing them. 150 Getting Started with Logi Info and Logi Report for Java Error logging is enabled in the application's _Settings definition, as shown above, by setting the General element's Log Errors attribute to True. This setting will write out the Debugger Trace Report as an HTML page when an error occurs. Normally, these debugger pages will be written to the <application folder>\rdErrorLog folder, however the General element's Error Log Location attribute can be used to direct them to another location in the web server file system. This attribute value must be a fully qualified file path and the target folder will be created if it does not exist. Tokens can be used here as part of the path, such as: @Function.AppPhysicalPath~\MyErrorLogs Keep in mind that the account the web server uses to run the Logi pplication requires full access rights to the target folder. If the folder does not exist, then the application folder must have these rights so that the target folder, when created, inherits them. To use a custom location in a web farm environment, specify a network folder and change the application's identity to a network account. 151 Getting Started with Logi Info and Logi Report for Java Hello World! Tutorial This chapter walks you through the process of building a simple Logi application. This tutorial assumes that you have: Microsoft IIS web server and .NET Framework 4.x installed, - OR – A supported Java web server and Sun JDK 1.6 1.7, or 1.8, or JRockit, installed; And an un-expired trial license or a regular or OEM license file installed in C:\Program Files\LogiXML IES Dev\LogiStudio. Begin by launching Logi Studio, using its desktop icon or Start → All Programs → Logi Info → Studio. 1. In Logi Studio, close the Getting Started dialog box and click New Application in the Welcome Panel, as shown above. 152 Getting Started with Logi Info and Logi Report for Java 2. Logi v10 Studio is capable of producing both .NET and Java web applications. For this tutorial, we'll select the Java option, as shown above. 3. Provide an application name: HelloWorld - DO NOT insert a space between the two words and use the exact capitalization shown! Choose the location for the new HelloWorld application folder, which should be the standard web application location specific to your web server. With Tomcat, for example, this is the webapps folder. 153 Getting Started with Logi Info and Logi Report for Java For a JBOSS server, and other Java servers that use auto-deploy, append a ".war" extension to the application folder name, as shown above. Click OK to create the application. The deployment progress indicator, shown above, will appear and required sub-folders and files will be created in your HelloWorld folder. Java web servers may complain as the wizard adds files to the folders; this is normal behavior. 4. The Prepare a New Application Wizard, shown above, will start. The next step is to configure the basic application settings and register it with your web server. Click Next. 154 Getting Started with Logi Info and Logi Report for Java 5. The wizard will now test the web server and configure your application, as described. Click Next. The results of the diagnostic tests will displayed, as shown above. If all test results are "OK", click Next. The failure of any test indicates that something is wrong with your web server environment's ability to run the new application. This could be caused by a number of things, such as failing to install the new Logi version as an Administrator, or having incorrect file permissions on the application folder, or failing to have the correct version of .NET installed. Contact Logi Support for assistance. 155 Getting Started with Logi Info and Logi Report for Java 6. Next you'll be asked to select a Theme for your application. Use the default, Signal, and click Next. 7. Next, enter a caption for the application, and click Next. 156 Getting Started with Logi Info and Logi Report for Java 8. When the wizard prompts you to create a Data Visualization, click Cancel. 9. In Studio's Application panel (at the upper-left), double-click the Default report definition and it will open in the Workspace panel. 157 Getting Started with Logi Info and Logi Report for Java 10. In the Default definition, right-click the Body element and navigate the pop-up menus as shown above, finally clicking on the Label menu item. A Label element will be added to the definition.. 11. Click the Label element and, in the Attributes panel, enter the text "Hello World!" in the Caption attribute, as shown above. Then, in the Class attribute, select ThemeTextLargest from its pull-down list of style class options. 158 Getting Started with Logi Info and Logi Report for Java 12. Click the Preview tab at the bottom of the Workspace panel to save your definitions and run the Default report. Your "Hello World" message should be displayed, as shown above. Congratulations on completing your first Logi report! 159 Getting Started with Logi Info and Logi Report for Java Glossary AJAX An acronym for Asynchronous JavaScript and XML, AJAX is a technology used in creating interactive web applications. The intent is to make web pages feel more responsive by exchanging small amounts of data with the server behind the scenes, so that the entire web page does not have to be reloaded each time the user requests a change. This is meant to increase the web page's interactivity, speed, and usability. Application Path In a Logi application, the Application Path is the URL of the application. It's a standard HTTP URL including the web server name and virtual directory name that has been registered for your application. Examples: http://localhost/myfirstapp http://194.255.255.10/helloworld Attribute A customizable, predefined property of an element, consisting of a name and value. Some attributes, such as ID, are common to all elements and some are required for application execution. Attribute Name The identifier portion of an attribute; a user-defined application setting for a specific attribute name. Attribute Value The data portion of an attribute; a user-defined application setting for a specific attribute name. BLOB Acronym for Binary Large Object. In a database context, refers to binary data such as images, music files, videos, or executable files that are stored as an object in a single data table column. Child Element An element that hierarchically belongs to the element above it (its parent) in the element tree in a definition. Child elements stay with their parent elements when the parent element is copied, moved, or deleted. CLOB Acronym for Character Large Object. In a database context, refers to text data such as documents, HTML pages, and logs that are stored as an object in a single data table column. Condition An element attribute that controls whether the element is processed or ignored. If the value or formula in this attribute value evaluates to True, the element is processed; if it evaluates to False, it’s ignored. Connection String A value used to make a connection to a database or datasource. May contain a variety of information such as server, database, user id, password, etc. Example: Provider=SQLOLEDB.1;Persist Security Info=False;User ID=sa;Initial Catalog=Northwind;Data Source=MYDATASERVER 160 Getting Started with Logi Info and Logi Report for Java CSS An acronym for Cascading Style Sheet, CSS is a style sheet language used to create style classes that describe the presentation of an HTML document. Its purpose in Logi applications is to control appearance, alignment, location, and other presentation aspects in report definitions. The CSS specifications are maintained by the World Wide Web Consortium (W3C). Debugger Trace Page A diagnostic HTML page that provides information about program execution. It contains columns for the event, object, data value, and time of occurrence. Clicking a debug link (which appears when turned on in an application's _Settings definition) will display this page, as will fatal errors. Division An element used within the element tree in a report definition as a container for other elements. The Division element can be conditionally shown or hidden, causing all of the elements it contains (its child elements) to be shown or hidden. Also useful for organizing elements for improved definition readability and for copying groups of elements. Results in a SPAN or DIV tag in the report HTML output. Element A reusable, XML-based component, usually represented by an icon in Logi Studio, used as the visual building block of a Logi application. Elemental Development The process of creating robust and flexible web-based reporting applications with reusable XML-based components. Flow Positioning The process of defining layout based upon the hierarchical structure of elements within a report definition. Analogous to Flow Layout. Formula Attribute A category of element attributes that are able to accept a literal value or a formula. When a formula is used, the first character in the value is the equals sign (=). This is followed by a formula using intrinsic or JavaScript functions which is evaluated at runtime. Examples include the Label element's Caption attribute and the Calculated Column element's Formula attribute. Heat Map The Heat Map chart element provides a graphical representation of data consisting of a rectangular arrangement of many smaller rectangles, where the size and color of each small rectangle represents a data value. Heat maps are used for purposes such as DNA tracking in Molecular Biology and stock market analysis. Layout Positioning The process of defining layout using fixed or absolute positions for an element or group of elements within a report definition. Analogous to Grid Layout. Process Definition An XML source code file used in Logi applications, consisting of one or more Task elements, which contain hierarchical collections of elements that define a specific server-side task to run. Tasks are used to manipulate data, send email, test data conditions, and perform other processing and are used for automated and scheduled events. Process definitions are not available in Logi Report. 161 Getting Started with Logi Info and Logi Report for Java Query String That portion of a web page URL that is used to pass data to the web server. In this example, the Query String follows (but does not include) the question mark (?): http://www.logianalytics.com/rdPage.aspx?rdReport=myPage&rdMethod=Post Remarked Element An element (including child elements) that have been disabled or "commented out" of a report definition. By default, remarked elements appear in a green font within Studio. Report Definition An XML source code file used in Logi applications, created by a developer, which contains hierarchical collections of elements, processed by the Logi Engine to produce report pages. Request Parameters That portion of a web page URL used to identify individual data parts to be passed to the web server. In this example, the request parameters consist of a "name" and a "value" pair connected by an equals sign. Each name-value pair is separated from the next by an ampersand (&): http://www.logianalytics.com/rdPage.aspx?rdReport=myPage&rdMethod=Post&rdTime=EDT In a Logi report definition, these parameters are available using @Request tokens. In the above example, the final request parameter is available as @Request.rdTime~ and its value is "EDT". Shared Element A container element that holds other elements, defined in one report definition but available to be referenced from other report definitions so that elements can be defined once but used many times. This is especially useful for implementing standardized headers and footers. Shared Element elements are referenced in other definitions using the Include Shared Element element. Show Modes A mechanism that makes it possible to hide and show elements in reports based on a data value. The value is often passed to report pages in a Request parameter named "rdShowModes". Style Sheet A developer-created file that contains style classes that control the presentation aspects of Logi reports. See CSS above. Support Files Style sheets, images, XML data files, HTML documents, and Scripts included with a Logi report application. Token A "placeholder" for a value which is evaluated by the Logi Server Engine at runtime. Analogous to a "macro". Tool Tip An attribute for some elements that causes explanatory text to appear when the mouse is hovered over the element. This is very useful for providing immediate context help for elements like Input Text and Input Text Area. 162 Getting Started with Logi Info and Logi Report for Java Validation The process of ensuring that all required elements are present in a Logi application, with values defined for all required attributes. Virtual Directory In the context of Microsoft Internet Information Server (IIS), a virtual directory is an alias for a physical directory on the web server. This alias is used in a web page URL to request a page from the physical directory. The following example contains the virtual directory "HelloWorld": http://localhost/HelloWorld When an application is registered in Studio, a virtual directory is created for it. Under Windows, the IIS Manager program can also be used to create virtual directories. By using a virtual directory in the URL, browsers are not required to be given any of the physical storage details. Web Service A Web API that can be accessed over the Internet and executed on a remote system hosting the requested services. A web service provides specific processing and/or data, over the Internet, that developers can incorporate into their own applications. Fees are sometimes charged for the use of a web service. XML The Extensible Markup Language (XML) is a W3C-recommended general-purpose markup language that supports a wide variety of applications. In Logi applications, the source code for definitions is an XML document and the results returned from a datasource into a datalayer are cached as XML data. 163 Getting Started with Logi Info and Logi Report for Java Resources and Support The following resources are available if you need additional information or support: Corporate Headquarters Phone: 1-888-564-4965 (703) 752-9700 Fax: (703) 995-4811 Email: [email protected] Address: 7900 Westpark Drive, Suite A200 McLean, VA 22102 Web site: www.logianalytics.com Developer Network: http://devnet.logianalytics.com Sales Department Email: [email protected] Customer Service and Support Email: 164 [email protected] Getting Started with Logi Info and Logi Report for Java
© Copyright 2024