“I have to admit that, at first, the informal tone of the book took me bysurprise. After reading it carefully, I see that the “informal tone" isanother of the many great ideas that the authors have had. In myopinion, this book is a great contribution to the knowledge of the RochaVersion and the huge change it represents, so that the GeneXusCommunity can prepare for its launch in 2008."

Breogán Gonda, EngineerArtech President

Diego and Mary run into each other after many years. Long gone are thedays and nights of studying, laughing and talking in the classrooms andhallways of the School of Engineering, when Mary was always so full oflife and Diego would let himself be carried away by her laughter. Untilthe chance meeting shakes the dust off that memory... and Diego happilyfinds himself able to help his old friend solve some big problems at workand get back to being the cheerful, outgoing woman he knew (andloved?) so long ago.

Diego, Mike and Julia have three weeks to develop a web application fora travel agency, including the application's back-end and front-end.Mary is going through a difficult time professionally; she's a projectmanager who is so overburdened by maintenance chores that it'saffecting her health.

GeneXus is the thread that interweaves the characters' journeys throughthese pages. Discovering and showing. Showing and discovering. Overand over again: the Rocha Version.

EpisodeO

ne

Episode One

Cecilia Fernández is GeneXus instructorand has worked in Artech's TrainingDepartment since 2001. She teachesGeneXus courses in Uruguay and abroad,writes manuals and creates distance-learning courses. She attended the Schoolof Engineering, University of Uruguay, andis currently pursuing a Bachelor of Arts inLiterature at the School of Humanities andEducational Sciences.

Daniel Márquez Lisboa, is a GeneXusanalyst, technical writer and consultant, aswell as a freelance writer, who hasdeveloped large systems in GeneXus andother languages. He has authored or co-authored four books, including "GeneXusKnowledge-based Development," whichwas presented at the GeneXusInternational Meeting in 2006.

GeneXus RochaEpisode One

Daniel Márquez Lisboa - Cecilia Fernández

GeneXus RochaEpisode One

GeneXus Rocha - Episode One

No part of this book may be reproduced, digitized, or transmitted in any form or by anymeans, electronic or mechanical, including photocopying, recording, or by any othermeans, without prior written permission from the Copyright holders.

EDITORIAL GRUPO MAGRODr. Gastón Ramón 2312 bisTel. (598 2) 708 54 98 - 708 03 86Email: info@grupomagro.comwww.grupomagro.comMontevideo - Uruguay

© Daniel Márquez Lisboa - Cecilia Fernández

Editor: Fernando DíazDesign: Claudio de los SantosCover art: Fiorella FranziniTranslation: Rosario Pérez

Legal Dep. No. 343,109 / 07

Printing and binding: ZONALIBROGral. Palleja 2478 - Tel. (598 2) 208 78 19Email: zonalibro@adinet.com.uyMontevideo - Uruguay

Printed in Uruguay - Impreso en Uruguay

Foreword

The entire Artech team is working intensively on the Rocha Version of GeneXus,which is not just another version: in many ways it represents a great leap forward,especially with regard to its capability of being integrated and extended whether byArtech or the GeneXus Community itself.

The GeneXus Community has been enthusiastically testing the product’s CTP ver-sions, using them and, in many cases, building extensions. At the XVII GeneXusMeeting, the first beta version will be launched.

Within this context, we have entrusted Daniel Márquez Lisboa (author of “GeneXus,Knowledge-Based Development – A Practical Guide,” published by Magró in 2006)and Cecilia Fernández, a highly experienced instructor of our courses, to write anintroductory book about the Rocha Version of GeneXus.

I have to admit that, at first, the informal tone of the book took me by surprise.After reading it carefully, I see that the “informal tone” is another of the many greatideas that the authors have had. In my opinion, this book is a great contribution tothe knowledge of the Rocha Version and the huge change it represents, so that theGeneXus Community can prepare well for its launch in 2008.

I hope this book will be very well received and I congratulate in advance the au-thors on their work, wishing them great success.

Breogán Gonda, EngineerArtech President

Dear reader

Some time ago we were asked to write about a version of GeneXus that was stillunder development: the Rocha version. At first, we were suspicious. “They want usto write a book about a version that is going to be continuously changing as wewrite?!” And as if that weren’t bad enough, it was rumored that the version we werebeing asked to write about was more than just a new version: the product wasbeing refounded. When we were told that they also wanted a book that would bareGeneXus, a book that would reveal its personality and appearance, its body andsoul, that would bring it closer to those who wished to discover or rediscover it, abook that would be enjoyable, entertaining, that could be read like a story…” whenwe heard that… we were delighted!

Because, how could we not have fun making up characters, incidents, understand-ings and misunderstandings! Discovering and showing. Showing and discovering.Over and over again: the Rocha version.

We thought a lot about you, dear reader, trying to picture who you’d be, what you’dwant to know, and how, when, and just how much you’d want to learn, whether youknew a lot, a little or nothing at all about GeneXus… what you’d find amusing, whatwould bore you… but when it got to the point that we were dizzy with so muchspeculation, and our hands were starting to tremble, we decided to do the healthything: enjoy ourselves. So we moved on, confident that a job done with pleasurewould produce a contagious result. And if it turns out we were wrong, we hopeyou’ll forgive us. In any case, nothing will spoil the fun we had writing it!!

You may be an expert on GeneXus that picks up this book to discover the Rochaversion, or this might be your very first experience with the tool. We hope thatwhen you read these pages you’ll share the excitement we felt when we werewriting them, and that you can adapt your reading to your interest and needs.Some chapters are more technical than others; in particular, Chapter 3, whichdeals with Patterns. We couldn’t resist the temptation of showing it in all its power,and that led to our peeling away more and more layers as we moved forward.Those who want to see more will read it all thoroughly, and those who don’t cansimply browse the pages. You’re free to choose either path, just as we felt free tounleash our enthusiasm and discover, discover, discover. The last chapters are prob-ably the lightest and most enjoyable. This is where the story gets really interesting— because the best is always saved for last. We have also included an annex,

where we focus on the most outstanding features of the Rocha version. This annexwill be particularly useful for those with experience in previous versions of GeneXus.It differs from the natural structure of the book, which is why we included it sepa-rately.

The version of GeneXus Rocha on which we based this “novel” is the CTP 5, build7304. When this book reaches your hands, the first beta version will probably beavailable. For this reason, you’ll have to forgive any changes you find. We trustthey won’t be too many or too great.

A good idea would be for you to follow the application that our characters developthroughout the book. You can choose the generator and DBMS you prefer; wechose the default options.

In this book you’ll find several quotes from a white paper by Breogán Gonda andNicolás Jodal, titled “Knowledge-based Development. Philosophy and TheoreticalFoundation of GeneXus,” published in May 2007.

Lastly, we’d like to thank everyone who contributed to this task by reading thedrafts of the chapters, criticizing them, giving us their feedback or simply cheeringus on. Alejandra Pereiro, Armin Bachmann, Gustavo Carriquiry, Gustavo Proto, GastónMilano, Eugenio García, José Luis Chalar, Alfredo Bordagorry, Pablo Mazzilli, FlavioCaiafa, Dane Drotts. Also Matías Hernández, Silvia Keymetlián, Ana Berta, JoséLamas Ríos, Rodrigo Álvarez, Jorge Mastropietro and David Waszuk for their tech-nical support. Marcela Fernández for the inspiration she gave us over lunch oneday, and Rodolfo Roballo, for his ideas and permanent support. María José Serrés,who worked with us until we had the graphic design we wanted. Rosario Pérez, ourtranslator, for her infinite patience. Nicolás Jodal, this project’s predecessor, and inparticular Breogán Gonda, for carefully reviewing the text, for his constant joy, andfor the support he gave us, working side by side.

To everyone: Thank you!

Mary, Diego, Mike and Julia are anxiously waiting to be discovered…

Read and enjoy!

The authors

Montevideo, September 2007

Abstract

Chapter 1: The Encounter. A man and a woman who haven’t seen each othersince college meet unexpectedly after many years, and set out on a journey, handin hand with GeneXus.

Chapter 2: Once Upon a Time... There Was a Project. Julia, Mike and Diegodefine and begin the analysis and development of a Web system for a travel agency.At the same time, Diego introduces Mary to the GeneXus Rocha’s IDE and thecreation of the first objects in the project.

Chapter 3: Machine-made, Hand-finished. As Julia’s productivity sky-rocketsthanks to GeneXus patterns, Diego unleashes his creativity, proving that customerdemands don’t always translate to insurmountable obstacles. There are also WorkWith Patterns, Web Panels, Web Components, Master Pages and User Controls todiscover.

Chapter 4: Flight to the World of Subtypes. Working at high speed, Diegoshows Mary why Subtypes are the solution to problems like multiple references inthe design as he finishes the last transactions. He also introduces her to the GeneXusCommunity and Extensions.

Chapter 5: When the “What” Is Not Enough. Mary’s enthusiasm grows everyday as she learns more about GeneXus. She still has many questions, and Diegoknows it. She discovers the Procedure object, Business Components and the capa-bility to display pdf reports.

Chapter 6: Winds of Change. We know that all good things come to an end, butMary has just realized that this could only be the beginning. Categorization, FullText Search, Themes, Versioning, Data Providers, Data Selectors, Built-in GXflowand GXportal also take the stage in this chapter.

Annex: Building the Future. Discover why Artech, and the Community as a whole,are also part of the GeneXus Rocha machinery. Creating GeneXus is a comprehen-sive and cooperative group effort.

1

Chapter 1The Encounter

Two old college friends ran into each other while waiting in line at a bank.They hadn’t seen each other in many years and were very happy about the unex-pected reunion. They were immediately comfortable and picked up right wherethey had left off – it was just like old times.

“How are you, Mary? How are things going?” the man asked in his deep, firmvoice, an intent look in his eyes.

“I’m fine, Diego; things are well,” Mary said, although she looked tired. “I waspromoted to development team manager two years ago, actually.”

“I guess I should congratulate you! But why do you look so down? Trouble inthe department? I’ve heard that your systems are not only big but trustworthy...”

“They are. But they are really difficult to maintain!” Mary said, obviouslyupset. “I’m getting sick, Diego. I can’t sleep; I have far too many responsibilities,long hours, not enough sleep. I feel in my chest...”

“...this pressure,” Diego finished. “I get it, Mary,” he continued, gently touch-ing his old friend’s arm. “How are you working? What tools are you using?”

“A bit of this, a bit of that... In the end, they’re all the same. We’re still usingthe traditional schema with traditional tools –they’ve been upgraded, of course,”Mary answered, seemingly unaware of how close Diego was. “I have this largeteam working on maintenance and development, but we can’t keep up.”

“Mmm... Not all of them are the same! Would you like to get a cup of coffeeafter we finish up here so you can tell me more?” suggested Diego.

2

GeneXus?

At the coffee shop, Diego listened attentively to Mary’s problems. He remem-bered how strong and driven she used to be, and was concerned about how muchshe seemed to have changed. He was excited to share some information and expe-rience that would be able to help his old friend.

“How many projects are you working on right now?” asked Diego.

“Just one. It involves mostly maintenance tasks. Our clients are asking fornew things all the time, but we can’t meet the new requirements. Besides, mainte-nance is really expensive and I can’t justify hiring more people. It’d mean too muchoverhead.”

“Maybe the systems are too old... Have you thought about reengineeringeverything?” he asked lightly.

“Yes, I have suggested that but we’re on a really tight schedule. And as I said,we may have already exceeded our budget. I don’t know what to do... I’m ex-hausted Diego, and I don’t see a way out.”

“I know exactly what you mean! Do you know how many people are in yoursituation? I’ve seen it a million times. Applications are increasingly complex, andmanual tools make it impossible to develop or even maintain those systems. They’rebecoming unmanageable. But there’s hope, Mary; solutions exist today. The alter-native is to automate the work done by humans, so that we can focus on newcomplexities instead of coding, which can be done by a program. For instance, atmy company, we’re handling several large projects at once somewhat easily. Haveyou heard of GeneXus?”

“GeneXus... Yes, I’ve heard something but I haven’t had time to look into it.Do you use this tool? As far as I know, even non-technical people can use it andthat’s why I’m curious.”

“Look, I’m not saying GeneXus is a cure-all but I know it solves many ofthe problems your company is facing. It’s a program that makes programs. Itautomates the creation and maintenance of your applications and database. Ofcourse, it’s in a higher abstraction level than other tools. Tell me, if you had aprogram that allowed you to do this automatically, would you use it?”

“Absolutely!” she said, sitting up straight. “See, that’s exactly our problem,we have to do almost everything manually.”

3

In Diego’s opinion, the problems Mary’s company was facing were very com-mon. They find it impossible to take on new projects due to maintenance times ofcurrent systems, which are based on traditional technologies. For a software devel-opment company, this is a red flag alert.

And as for you, dear reader, the question you may be asking (even if youdon’t say it out loud) is “How does it work?”

“How does it work?” asked Mary enthusiastically.

“Isn’t it reasonable to think that given a set of views on data,” interruptedDiego, “there’s a unique minimum relational model for it?”

“Hmmm… Maybe, I’m not sure.”

“And if that’s true,” Diego continued, ignoring her hesitation, “don’t you thinkit’s possible that a reverse engineering process can use the set of views to createthis minimum relational database schema? If you need to see it to believe it... let’smake a bet, for old times’ sake. Believe me, you’re going to lose!”

A Bet

The objective of GeneXus is to achieve high-quality automated management ofbusiness systems knowledge [by describing users’ views].Breogán Gonda, Nicolás Jodal

GeneXus is a tool that starts from users’ views, captures their knowledge andsystematizes it in a Knowledge Base. Using this Knowledge Base, GeneXus auto-matically designs, generates and maintains the database structure and applicationprograms; that is to say, programs that users need to manage their own views ondata.

4

GeneXus works with pure knowledge, which is relevant regardless of the then cur-rent technologies.

«GeneXus stores in a Knowledge Base all the necessary elements to build theapplication and then uses it to develop the system. It automatically builds thenormalized data model, using the desired programming language and database. Inthis way, you obtain a project with the company’s knowledge...»

“Okay! That’s it!”

“Yes,” Diego interrupted eager to finish the idea. “It provides you with some-thing very valuable, the future portability of your application. All that knowledge –business rules, dialogs, controls, reports- that are now in a certain programminglanguage, can be converted to other languages without starting from scratch. Thismeans that knowledge is reused because the Knowledge Base is platform-indepen-dent.”

5

Knowledge Base and External, Relational Models

The two friends continued talking at the coffee shop. At that point, Mary wasparticularly interested in this software tool and Diego in...

“On one hand, we have the Relational Model that, as you know, is aimed ataccurately representing data in a database by satisfying certain conditions.”

“True...” she said, “eliminating redundancies and introducing a small set ofrules to avoid the greatest sources of data inconsistency.”

“That’s right, rules that check uniqueness and referential integrity. Also, theyprovide a set of operators for quality data management,” added Diego, satisfiedwith how things were flowing.

“Sure, that’s why everyone uses it. Doesn’t GeneXus use it?”

“Well, yes, I’m coming to that. Do you remember the External Model,where external views are represented? GeneXus focuses on this model be-cause that’s where the actual knowledge is located; that’s the most importantmodel for users and developers. It gathers the external knowledge and every-thing else, such as auxiliary models, can be automatically inferred from thisExternal Model.”

“The External Model... It can’t contain any physical or internal elements suchas files, tables, entities, entity relationships, indexes... right?”

“Exactly! Or any other element that can be automatically inferred,” said Di-ego; he’d always liked talking to Mary, and was enjoying his time with her. “TheExternal Model will be used to obtain and store knowledge. It aims at representingreality in the most direct and objective way possible.”

“And you’re free from implementation concerns, thanks to a high-level sys-tem description that doesn’t change unless user views are modified. Am I right?”Mary asked

“Exactly! That’s why we take users’ views and store them in the model. Then,all the knowledge contained in them is captured and systematized to maximize itsinference capabilities.”

6

“Okay, I find that hard to believe. It sounds a bit far-fetched... Are you sayingthat I only have to provide a description, and a tool will magically create the appli-cation?” Mary asked, sounding skeptical.

“Well, I wouldn’t say it’smagic. After all, it’s a piece of soft-ware. And you have to do a bit ofprogramming, but it’s minimal. InGeneXus you’ll have some proce-dural code, but the language thatyou write is not the one you’re usedto. You don’t need to name tables,indexes or any physical element ofa database.”

“But... I don’t understand where the Relational Model comes in,” Mary said.

“It’s the one used to represent and handle data, that’s the internal or physicalmodel. But it won’t be created by you; it will be inferred by GeneXus using reverseengineering. It was a tricky bet.”

“And how do you describe users’ views, the External Model, so that reverseengineering can be applied to them and obtain everything you say? This descrip-tion must be accurate to avoid ambiguities and allow a program to infer everythingthat programmers still do by hand.”

“Yes, it is,” Diego assured her. “Descriptions are made through certainGeneXus object types that represent the ‘what.’ Through them, GeneXus finds the‘how.’ That’s why to use GeneXus, you need to learn to describe, that is, to usethese object types. You don’t need deep technical knowledge... far from it, actu-ally.”

Diego kept talking. Even though they hadn’t seen each other for so long, hestill knew Mary very well. He knew that her silence meant that he could go on. Hecouldn’t believe his good luck. Thank you, GeneXus, he said to himself and went onslowly and confidently.

“To achieve all this, GeneXus has a Knowledge Base that is initially associatedwith a set of inference mechanisms and general rules, such as those that ensureconsistency. For instance, referential integrity rules. When the GeneXus analystdescribes reality by creating objects, these descriptions –the External Model- are

7

automatically systematized and stored in the Knowledge Base. Besides, from thisknowledge it obtains a set of results that enhance the accuracy of future infer-ences.”

“It’s an inference ma-chine!” said Mary.

“Exactly! For example,given a set of views on data,it can automatically infer thenecessary program tohandle it.”

GeneXus works permanently over the Knowledge Base. All the knowledge in the KnowledgeBase is equivalent to that of the External Model (a subset of the Knowledge Base). It consistsof the External Model, plus rules and inference mechanisms which are independent from thisExternal Model, and a set of other elements automatically inferred from it.The developer can change the External Model by changing objects of the user’s reality. Thosechanges will automatically propagate to all the elements that need it, such as other elementsof the Knowledge Base, database and application programs. Likewise, the developer can’tdirectly change any element that doesn’t belong to the External Model.

ALL the knowledge is contained in the External Model and because of that, we could supportthe Knowledge Base in a completely different way tomorrow, and our customers’ knowledgewould still be reusable without any problems at all.

Breogán Gonda, Nicolás Jodal

«Diego, I have to go now, but I want to know more. Let’s meet next week,same place, same time. Sounds good?»

“Sure,” he replied, trying to sound calm.

8

9

Chapter 2Once Upon a Time,There Was a Project

Travel Agency & Co., a new tourism operator, has hired the software firmACME Business Software Solutions to develop a Web site that allows customers tosearch for destinations, flights and services offered, as well as book flights andmake travel reservations. The project also includes the creation of a backend sys-tem to maintain the data.

ACME, which has used successive versions of GeneXus for quite some time,employs several IT specialists. The team members selected for this project areJulia, Diego and Mike. Diego and Mike are GeneXus Analysts who work on anyproject assigned to them. In particular, Diego usually develops applications andMike is in charge of testing them. Julia, on the other hand, is not proficient inGeneXus. Even though she has gathered requirements for many projects, her areaof expertise is documentation and moderation of team meetings as benchmarksare achieved. In this workgroup everyone has a voice and decision-making power.

The first tasks fall on Julia and Diego, while Mike tests other applicationsbeing developed by ACME for other customers.

Julia has long used text processors for her documentation work. In largeprojects, it’s very difficult for her to manage dozens of folders with hundreds offiles, share them with the developers, and coordinate team discussions, amongother tasks. Surely you’ll understand why she was thrilled to know that GeneXusRocha provided an embedded documentation feature that would make her life easier.

10

Time is of the Essence

A short while ago, the board of directors and the development team agreedon a short-term project of approximately three weeks. They reduced the usual timeframe by half because they would start working with GeneXus Rocha, and theyknew its great usability and increased productivity would expedite the project.

«A dramatic increase in [system development] productivity is necessary, but pro-gramming language productivity has long reached a plateau. ... So, how can weachieve this necessary increase in productivity? With knowledge-based –not pro-gramming-based– development: the solution is to describe instead of programming!»Breogán Gonda, Nicolás Jodal

Luckily, Travel Agency & Co.’s internal operations were rather efficient andwell documented. This was a great advantage for the development team. Julia,Diego and Mike decided that they had to meet with people involved in differentareas and gather their views.

“Every user has one or more views of the data he/she uses daily. Among theseviews, we can make a first group with those used to manage data (with restrictedpermissions to add, modify, delete and view it). These user views are called Transac-tions and are the first GeneXus object type.»Breogán Gonda, Nicolás Jodal

They wanted to start representing the company’s reality as soon as possible.Among other things, they learned that Travel Agency & Co. focused on leisuretravel to a variety of destinations worldwide. What did this mean? First of all, sincedestinations were tourist attractions in cities around the world, they needed a placeto store this data.

The team met and, after exchanging notes and ideas, decided that Julia shoulddescribe the first guidelines obtained. Meanwhile, the rest –especially Diego– woulduse GeneXus to represent the most clearly described user views.

11

The IDE at a Glance

It’s time to go into the GeneXus Rocha development environment. If you like,you can follow Julia’s steps to get to know the elements that make up this environ-ment. In this way, you’ll create the project Knowledge Base and the first Transac-tion object.

Commonly known by its initials, this IDE (Integrated Development Environ-ment) goes way beyond its name. Why? Because an IDE is an environment thatoffers a high level of comfort, windows to choose elements, windows to write code,toolboxes, source codes, and so on. In this case, the functionality of GeneXusRocha’s IDE exceeds basic requirements.

Julia opens a session and sees a start page similar to the one below:Initially,we can see two clearly defined content areas. On the left is the KnowledgeBaseNavigator, which offers different views. It’s made up by an area in the middle (nowblank) that will display a tree with the elements of the opened Knowledge Base,and a set of horizontal panels with the names of other views.

Panels

12

On the right is a main window (that’s how we will refer to it, as we’ll do mostof our tasks there). It is basically another item with multiple functions. In the topleft corner of the main window is the Start Page tab, which is the first opened itemin the main window. As you work, new tabs will indicate other work spaces contain-ing project elements such as navigation reports, diagrams, transaction structures,and so on.

Now, let’s look at the only tab we have, which includes other sections con-taining information. For example, Recent Knowledge Bases displays a list of re-cently opened Knowledge Bases with last updated dates, and provides links tocreate new Knowledge Bases or open existing ones.

Below is an Extensions section with tools developed by Artech or third par-ties. They are free to install and use, and allow increasing the tool’s power.

The section labeled GeneXus Community displays an RSS feed of Rocha Com-munity news, with “More...” links to read the complete stories.

The Address cell allows you to search the Web or your file system withoutleaving the IDE.

After this first look at the IDE, let’s see what Julia is doing.

13

New Project, New Knowledge Base

The first task of developing an application with GeneXus is to create theKnowledge Base.

The next time Diego and Mary met at the coffee shop, she asked with aconcerned look on her face:

“You said that GeneXus automates the creation of databases and programs.How does it know in which environment and in which language to build theseprograms? For example, if you had to develop an application in Java and anotherapplication, or the same one, in C# (.Net)...”

“Let’s see... When you create the Knowledge Base –we usually call it KB–you can set the project to be generated in Java. As we said, the KB is platform-independent: if you generate the application in Java, you can later reuse thisknowledge to generate it in C#. You don’t have to describe the objects fromreality again, and you only have to associate this knowledge with another envi-ronment. When you associate an environment, you’ll find a place to set every-thing related to it. For example, in Java, you’ll have to set the location of theclasses in the webapp, which doesn’t make sense in .Net. This means that de-pending on the selected environment, the program displays the properties neededto set it. That’s how GeneXus can make your application come true and imple-ment it as you asked.”

As it happens, while Diego and Mary exchanged words and looks at the coffeeshop, Julia followed the steps below, which you can follow, as well.

1. On the File menu, click New, and then click Knowledge Base (or click theNew Knowledge Base link in the Start Page). Following is the dialog boxdisplayed.

14

TravelAgency

From here, the project is associated with an implementation environment.Leave «C# Environment,» which is the default option.

2. Click [Create]. GeneXus will create an empty Knowledge Base. After that, thescreen displayed should be similar to the one below.

15

Note that some contents have changed. There’s a tree in the Folder Viewpanel; the parent node is the Knowledge Base (with the name that you gave it) andthe children are the elements that make it up: Domains, Tables, Themes,Images, Documentation, Objects, etc.

A new section called Knowledge Navigator has been added to the Start Page.It has shortcuts to the most common tasks that you most commonly do after cre-ating or opening a Knowledge Base.

This Knowledge Base will also be used by the rest of the team. Julia is nowready to start documenting the project.

Documenting from the Inside

Documents, notes, task lists are only examples of the documentation sur-rounding any software development process. Documentation, when it’s up-to-dateand easily accessible, is an important part of any application.

This is why GeneXus’ documentation features are built into the KB.

Documents, files, diagrams, and objects can all be linked, and easily acces-sible to every team member. For this reason, we say that it’s active, integrateddocumentation that constitutes an actual wiki.

16

Files

The department managers had emailed Julia several documents describingtheir system requirements, priorities and descriptions of their areas, some processflows, and so on.

Because the documents were created by the end users, she decided that theyhad to be added, unchanged, to the Knowledge Base for future reference. Theactual words of the users are very important.

So, she expanded the Documentation tree node and double-clicked Files. Inthe new Files tab that was displayed in the main window, she clicked Add New File.A window was displayed to search her file system and choose each file to be addedto the KB. Below is the resulting Files tab.

Images

She had also received the company’s logo, so she clicked the Images nodeof the Folder View tree, imported the Logo.bmp file and saved it in the KB. Later,it would be used as a header for the application’s pages. In the same email, shereceived dozens of image files of tourist attractions that later would be stored inthe database. She temporarily saved them here as well, to have them centralizedin the KB.

17

Main Document

Now, Julia gets ready to write the main page of the KB’s wiki. Note that belowthe Documentation node is a Main Document object. Each team has different ap-proaches to documentation. In ACME, this main page is used to describe an over-view of the system being developed, and to access documentation elements.

The project’s Master Plan may also be created here, instead of inserting it asa file. But you and your development team are free to use this page as you see fit.

Julia opens Main Document and a new tab called Document: main is dis-played in the main window. Since she wants to start writing, she clicks the Editselector in the lower menu bar and enters the text shown below. Next, she clicksPreview and obtains a normalized view of the text. Finally, she saves the changes(Preview changes to Browse).

Note that we’ve done some formatting changes to the text through the for-matting toolbar.

18

1 The GeneXus IDE provides dockable function panels that stick to any side of the window. Also, theycan be automatically hidden when the focus shifts so that they don’t take up space in the main window.To activate them, open the View menu and choose Tool Windows.

Julia has changed the font type and size, and set the topictitle in bold.

In addition, she needed to add links to the documents shehas received and just saved in the KB, which is crucial for anintegrated documentation. To do so, she dragged the Table itemfrom the toolbox1 to the page. After inserting the table, shewrote the following.

She wanted a preview so she clicked the Preview selector. Satisfied with herwork, she saved it and the following window was displayed.

Note that due to the symbols she used in the table’s second column, thedocuments are now underlined: they are links to the stored files.

19

As a result, the documentation is very dynamic and actively integrated to theproject through the KB.

The GeneXus documentation editor uses two opening square brackets ([[)and two closing brackets (]]) in the text to create links.

If you’re following this example, you may have noticed that right after typingthe second opening bracket, the editor prompted you with a list of valid objects tochoose from, as shown in the figure below.

Julia selected File and after typing a period (.) the list of available files wasdisplayed (she could also have dragged the File object from the toolbox, obtainingthe same result as by writing «[[File.»).

Next, she selected each desired file and pressed <Enter>. The text was endedwith two closing square brackets.

20

Creating the First Transaction: Attraction

Back at the coffee shop, while talking to Mary, Diego thinks that he shouldenter the first views obtained by interviewing staff from Travel Agency & Co.’sTourist Information Section. This section searches for information to add or removedestinations and itineraries that the company offers to customers. He thinks thatas soon as he gets back to work, he should create the Attraction transaction, whenMary interrupts his thoughts:

“You know, I don’t understand how you can accurately describe users’ viewsto avoid ambiguities and automatically infer everything.”

“Do you remember the new project we’re working on? Well, I’ve been meet-ing with users who handle data on tourist attractions in every country and city, inorder to offer them to customers. They use the attraction’s name, such as“Centenario Stadium,” “Roman Coliseum” or “Disney World,” and the name of thecountry and city where the attraction is located, with images of each attraction.They also told me that attractions are grouped in categories. For example, theCentenario Stadium belongs to a Great Monuments category, and Disney World toEntertainment. These are their views on the data.”

“I see... And how do you objectively describe these views?”

“With attributes... and Transaction objects. Let me explain …. Attributes arethe reference framework for other descriptions. It’s not exactly the same as arelational model attribute. Here, attributes are the basic semantic element. Pre-cise, unique semantics are assigned to their names, and that’s why attributes areso important in GeneXus.”

Diego scribbled a few names on a napkin: AttractionName, CountryName,CityName, AttractionImage, AttractionCategoryDescription. Then, he went on:

“These attribute names have clear semantic content that any person canunderstand without any context. They are not just ‘Name’ or ‘Description.’ Thereis a strong relationship between an attribute’s name and its meaning. That name,in turn, is a sequence of characters, something syntactic, unique, with whichany program can work without ambiguity. If I write or speak of

21

AttractionCategoryDescription anywhere, we both know it’s a description of theattraction category. GeneXus knows this too.”

“So,” she cut in, “you can’t use the same attribute name to refer to otherdata, because that would cause confusion and ambiguity.”

“Exactly. An attribute must have the same name everywhere it’s used, andthere won’t be two different attributes –with different meanings– that share thesame name. That’s the basic concept. There’s one exception, but I don’t want toconfuse things. These views described by users are used to handle data (add,edit, delete, view it) and are represented in GeneXus through the Transactionobject type. Every transaction has a set of elements: structure, rules, formulas,display elements. In other words, in one object we’re killing several birds withone stone: when you set what information will be used, you’ll also design thescreen that the end user will work with, define the data’s behavior as it is entered,and so on.”

Diego grabbed his napkin and wrote the following:

Then he said: “Data is displayed according to a structure that must be accu-rately represented. This would be the structure of the Attraction transaction. Theasterisk next to AttractionId stands for uniqueness: there’s only one AttractionId.That is, it’s an identifier that makes an attraction unique. All the information hasto be identifiable, so an attraction must be identified through one or more at-tributes.”

22

“Hold on Diego, I have some questions... Are you talking about the concept ofprimary key of a relational model table? The attributes you listed, won’t they becolumns of a physical table that will store this information? Ultimately, aren’t youdesigning a table with this transaction?”

“Yes, indirectly. And no, because I’m not concerned about designing a physicaltable of the relational model. I’ve only specified the attributes that the end userwill interact with to enter attractions into the system. I’ve specified a user view,not a table. Here comes the reverse engineering and Relational Model inferred byGeneXus. If the KB didn’t have any more transactions than this one, GeneXuswould infer a physical table containing all the listed attributes. However, whenrelated transactions are added, things change and normalization may occur. But Idon’t want to rush so I’ll explain that later.”

“I think I’m getting it, Diego. However, I see that in the transaction structureyou added attributes without saying that they were mentioned by the users. All theones ended in Id... Also, why didn’t you use the attraction’s name as identifier?”

“Because the attraction’s name may be used in many places all over theworld. For instance, Disney World is in Paris, Miami, Las Vegas, Orlando. I mayhave chosen a set of attributes like AttractionName, CityName, CountryName butI’m not sure there are no exceptions (attractions with the same name, in thesame city and country). In this case, we need a unique attribute for the set ofinformation elements that make up an attraction. Every transaction structureshould have one or more attributes that identify each instance. In this transac-tion, it will match the inferred table’s primary key, but that’s not always the case.Later, you’ll see it in a two-level transaction; don’t worry about it now. Now, wecan tell GeneXus that AttractionId will be a numeric attribute and set it asAutonumber.”

“What about the AttractionCategoryId, CountryId, and CityId attributes? Arethey identifiers too?”

“Yes, they’ll be identifiers in other transactions. Countries, cities, and attrac-tion categories belong to entities that are independent from tourist attractions. Forexample, we haven’t discussed this with the customer yet, but flights will also havearrival and departure cities. Obviously, we’ll have to create a transaction to repre-sent and enter data about countries and cities, as well as existing attraction cat-

23

egories. As it happens, these identifiers you mentioned will identify each one oftheir details (instances).”

“Let’s see if I have this right. Once you define the other transactions,GeneXus will infer tables to store their data, and will know that the attributesyou added to the Attraction transaction structure (AttractionCategoryId, CountryIdand CityId) will be turned into foreign keys in the associated relational table.”

“You’re as sharp as ever!” Diego exclaimed, with an admiring look.

“But then, why are CountryName, CityName, and AttractionCategoryDescriptionin that structure? In a normalized relational model, they’d never be in that table.”

“And they won’t be. That’s why I was saying that a transaction structuredoesn’t exactly match that of the associated physical table. I’ll explain that later inmore detail. Next time, I’ll bring my notebook. Because there will be a next time,right?” he asked a bit shyly, “then I’ll show you...”

The following day at work, Diego created the first transaction using the GeneXusIDE. Below are the steps he followed.

First, he clicked the New Object link in the Start Page and a dialog box forcreating objects in the KB was displayed. Next, he clicked Transaction in the Selecta Type dialog box containing the GeneXus objects available, and typed Attractionin the Name field. Following is the screen displayed.

24

Finally, he clicked [Create] and the transaction was opened.

Note that in the following figure a new tab with the transaction name hasbeen added to the main window. What’s being edited? The transaction’s structure.

Objects or elements opened in the IDE’s main window are displayed as tabs. Onlythe active one is displayed in the middle of the screen. The opened object can haveseveral elements or sections, and only one of them will be active. At the bottom ofthe window there is a bar to select other sections of the active object.

The structure edit window features a set of columns to create attributes,name them, and set their data types and descriptions.

25

In GeneXus, the structure Diego drew on a paper napkin is represented asshown above. He named the attributes according to the GIK (GeneXus IncrementalKnowledge) naming convention, a standard created by Artech and adopted by theCommunity. Its purpose is to give each attribute a unique name that clearly con-veys its concept, or semantic meaning.

As you may have noticed, in the Type column you can give each attribute aGeneXus-supported data type.

Selectors

26

The Blob data type allows a wide range of data (videos, worksheets, all kindsof documents, audio files, images, etc.) to be stored in the database. The purposeof the AttractionImage attribute is to store an image of the attraction in .bmp, .jpg,or any other format.

In the Description column, you can enter an extended description of the at-tribute. For the moment, we’ll leave the suggestions provided by GeneXus basedon the attribute name.

To add more attributes, press <Enter> after completing a definition and re-peat the process.

Key Attributes: In his drawing on a napkin, Diego marked the key attributewith an asterisk. In GeneXus, key attributes are marked with a key icon.

Descriptor Attribute: What does the magnifying glass icon next to theAttractionName attribute mean? It indicates that if you had to keep only one at-tribute, the one that best describes the entity, this would be the chosen one (theone with more semantic meaning). This information will be used by automationtools, so we won’t deal with it right now.

While setting the AttractionName attribute data type in the Type column,Diego created a Name domain for all the attributes that name something. He alsocreated an Id domain for numeric identifiers.

If you’re not used to working with domains, read the following paragraph foran explanation.

Domains?: Applications usually have attributes that share the same datatype, size and other features. For example, the Attraction transaction has several“Id” attributes (AttractionId, AttractionCategoryId, CityId, and CountryId). Diegohas created a domain called Id containing all the features of identifiers, and willapply it to all the attributes that represent a value which doesn’t exist in reality butwhich is necessary for uniqueness.

27

Each domain is a set of unique features that may be shared by several attributes.This allows for consistency and ease of maintenance, as changing a domain featurepropagates the change to all the attributes based on that domain.

Defining Domains2

Diego double-clicked the Domains node in the Folder View tree, and the tabfor displaying and editing domains was opened in the main window. There, heentered the Id and Name domains. The process is similar to that of creating trans-action attributes.

Some domains are automatically created by GeneXus together with the KB.

After Diego defined the first domains, he finished the transaction as shownabove. The Numeric and Character data types in the Attraction transaction are nowdisplayed as Id and Name.

2 GeneXus often provides several ways to do the same thing, so that you can always find a way thatsuits you. This isn’t the only way to define a domain; in fact, you can also do it when setting anattribute’s data type.

28

3 From now on, table names will be written in uppercase to distinguish them from transaction names.

The ATTRACTION Table

By default, when designing tables GeneXus names them after the transac-tions they are based on.3 At any time, you can view the table’s design (structure,indexes, etc.) by opening the Tables node of the tree in the Folder View panel.Following is the ATTRACTION table structure.

Given the transaction structure, GeneXus will design a form for it. This will bethe screen that end users will use to enter attractions. It can be viewed by clickingthe WebForm selector in the access bar.

29

This form can be customized by moving controls around, by adding, chang-ing, or deleting them, by changing their appearance, and so on. End users willmanage attractions through this screen at execution time.

Satisfied with his work, Diego remembered that he hadn’t documented thetransaction. As a rule, ACME’s team members create documentation as they moveforward, especially regarding entities such as the Attraction transaction.

So, he opened the Main Document, inserted a new table called Objects, andin the first row he added a link to the newly created transaction (just like Julia dida few pages back when she added links to the documents) with a brief description.

We can see that Attraction is a link. What will happen when Diego clicks it? Anew documentation tab will be opened for the transaction, where he will be able toedit or even open the transaction.

30

Suppose that you need to open the transaction to view its structure beforedocumenting it. You can do so by clicking the Open Transaction: Attraction link.Then, to open the documentation edit window you can click the Documentationselector. As you can see, dear reader, in GeneXus it’s also true that many roads leadto Rome.

31

Creating the Second Transaction: Country

Next, Diego created the transaction that would contain data on countries andcities. Its structure was drawn on the paper napkin that he had kept in his pocketafter saying goodbye to Mary the last time they met:

Since he had already opened Main Document, he started from there. He addeda new link in the table, this time to the Country transaction. But he hadn’t createdit yet! Note that the link displayed has a question mark (?) next to it.

When Diego clicks the ?, the transaction will be automatically created andopened in the structure, ready for him to enter attributes. The link will be definedin Main Document. (We don’t want to insist but, what was that about the roads toRome?)

32

Country: A Two-Level Transaction

As we all know, countries have cities, which means that reality determinesthat there are n cities per country. GeneXus can easily represent this reality withtwo-level transactions.

That’s why the Country transaction has two levels. The first level, also knownas prolog or just header, is implicit and we don’t need to identify it. In this case, theheader’s attributes imply that there’s only one instance for each country.

However, since each country has several cities, the method used to representit (on paper: a set of brackets) determines a set of attributes that are repeated inthe header: it is known as “body” or second level.

Note that both levels (header and body) have unique identifiers: the CountryIdattribute is the first level identifier, and CityId is the second level identifier. Thismeans that for any given country (CountryId), a city can’t be used more than once(CityId).

Based on this structure, GeneXus creates two tables: COUNTRY andCOUNTRYCITY. The primary key of the first table is CountryId, and the primary keyof the second table is made up by CountryId and CityId.

The following figure shows the structure after Diego entered it.4

4 Note that new domains have appeared. We assume that Diego created them either before or as heentered those attributes. For example, when entering CountryFullName, in the Type column he couldhave entered: “LongName = Character(50)” with the same result. In the event that Diego had alreadydefined a Details domain as VarChar(500,200), it’s worth noting that when he entered the CountryDetailsattribute, GeneXus would infer the Details domain as its data type (because it’s in the last part of itsname).

33

To add a second level to a transaction, click the preceding attribute and press<Ctrl+L> (in this case, click the CountryFlag attribute). Continue with the rest ofthe attributes as usual. You can also do this by right-clicking the attribute anddisplaying a menu to add a new level, move the attribute and so on. Also, note thatDiego has named the level.

Database Normalization

When the Country transaction was created, important changes took place.More precisely, the contents of the ATTRACTION table have changed because GeneXushas normalized it according to the new functional dependencies that were added.Following are the new table structures.

34

Can you spot the differences? By creating the Country transaction and settingthe CountryId and CityId attributes as identifiers of their levels you’re definingthat:

1. Every country will be (uniquely) identified by a CountryId value; this value willbe associated with (determine) only one CountryName, CountryFullName, etc.In a normalized Relational Model, this causes the creation of a physical tablewith the CountryId primary key to store this data while preserving uniqueness.

2. Every city will be assigned to a country (CountryId) through the CityId value.Therefore, the (CountryId, CityId) pair will determine a CityName andCityInformation. Thus, there must be a physical table with the {CountryId,CityId} primary key to store data about each city.5

So, what does GeneXus do with attributes having the same name in differenttransactions?

Remember the two most important statements of the GeneXus philosophy:

• Identical concepts must have identical attribute names, and

• Different concepts must not have the same attribute names.

5 Note that GeneXus names the table by concatenating the transaction name to the level name:COUNTRYCITY.

35

Normalization takes place when attributes having the same name are foundin different transactions. For example, a new COUNTRY table is defined with CountryIdas primary key, and other attributes including CountryName. A COUNTRYCITY tableis also defined with CountryId and CityId as primary key and other attributes in-cluding CityName. Attributes CountryName and CityName are no longer stored inthe ATTRACTION table. In fact, a foreign key reference to COUNTRYCITY table isdefined as well.

Stored Attributes and Inferred Attributes

Here comes the question that Mary asked Diego about the CountryName andCityName attributes referenced in the Attraction transaction structure. Since theywon’t be included in the associated physical table... why did Diego add them toAttraction?

If you look at the transaction form a few pages back, you’ll find those at-tributes. Why?

That’s because the transaction will be turned into a program that end userswill access through their browsers. In a form designed with the WebForm Editor,users will be able to add attractions (new records in the underlying ATTRACTIONtable).

When end users type a country identifier in the CountryId field and a cityidentifier in CityId, they should view the country’s name (CountryName) and thecity’s name (CityName). This means that CountryName and CityName are invokedat execution time from the COUNTRY and COUNTRYCITY tables through the com-bined {CountryId, CityId} foreign key. In order to be added to the form, attributesaccessed through foreign keys must be in the structure, inferred.

What would happen if the user entered nonexistent values for CountryId,CityId? What if, through the Country transaction, the user tried to delete a city withattractions? If we were allowed to do that, we’d be breaking one of the most impor-tant data consistency rules of relational models: referential integrity.

36

Referential Integrity

Diego told Julia that he had defined the first two transactions. In order toconfirm that the model accurately reflected reality, she drew a Bachman Diagramof the tables inferred by GeneXus based on the transactions.

To do so, she expanded the Tables node in Folder View and pressed <Ctrl+N>.In the New Object window that was displayed, she selected the Diagrams objectand clicked [Create]. Next, she selected all three tables at once and dragged themto the new diagram. The resulting screen is shown in the following figure.

In this diagram, the single arrow head indicates that there’s one instance ofthe pointed table for each instance of the first table; that is to say, for each citythere’s only one country, and for each tourist attraction there’s only one city. Like-wise, the double arrow head indicates several instances of the pointed table foreach instance of the first table; that is to say, for each country there are manyrelated cities, and for each city there are many attractions.

This allows determining the relationships between them. For example, therelationship between COUNTRY and COUNTRYCITY is 1 to n (one to many); theopposite is n to 1 (many to one). COUNTRYCITY and ATTRACTION also have a 1 ton relationship.

37

When adding or editing a record in the ATTRACTION table, the COUNTRYCITYtable must have a related record to ensure referential integrity. When a record isdeleted from the COUNTRYCITY table, there mustn’t be any related records in theATTRACTION table. GeneXus automatically solves this by adding this logic to theAttraction and Country transactions in a way that’s transparent for developers.Similar considerations can be made regarding controls performed on the relatedCOUNTRY and COUNTRYCITY tables.

Base Table and Extended Table

While Julia confirmed that everything was correct, Diego remembered bits ofthe last conversation at the coffee shop:

“Listen, Mary, for practical reasons, the table where you’re positioned at acertain time, the one that you’re focusing on when trying to do something to itsrecords, in any context, is called base table. That’s why we say that the Attractiontransaction’s base table has the same name: every time you work with the transac-tion, you’ll add, change or delete a record of that table. Then, you’ll move to an-other one, and another one, and another one. Besides, when working with onebase table record, you can access data that’s directly related to it and stored inother tables.”

“Following n to 1 relationships, from the record of the –base table?– wherewe’re positioned, to the record containing the information we want. It’s nothingnew.”

“That’s true, only the terminology is new. The extended table of a givenbase table will be the set of tables reached from the base table through n to 1relationships.”

“Let’s see if I’m getting this... If data didn’t have to be scattered in sev-eral tables to avoid redundancies, you’d have it all in one physical table. Forattractions, you’d have one big table with all ATTRACTION attributes, plus theCOUNTRYCITY and COUNTRY attributes. You can’t do that because of the po-tential inconsistencies created by redundant data, but anyway, you name thetable that you’d have. And that’s the idea of an extended table: it’s a tablethat you imagine, even though it doesn’t exist physically.”

38

“Absolutely true. You’ll see that in GeneXus we use this concept extensively,and that’s why it has a name.”

While Diego was lost in his memories, Julia confirmed that data access be-tween tables was ensured.

By looking at a Bachman Diagram you can easily determine the extended table ofeach (base) table. All the tables that can be reached from the base table by followingsingle head arrows (n-1 relationships) will be part of its extended table. The ex-tended table is a concept and is not actually materialized. It allows us to refer toinformation univocally related to the record that we’re using.

Creating the First Prototypes

In order to let Mike play his role as project tester, Diego pressed <F5> to startprototyping.

In GeneXus, there’s no difference between prototyping and implementing a system.A prototype is nothing less than the application generated in a certain platform: justlike the final application! The only difference between them is how they are used.

Remember that the environment had already been selected when the KB wascreated. Therefore, several properties were already set;6 for example, SQL Server,the default DBMS. But something is missing to implement the system... An assis-tant will ask Diego for the DBMS server and database details only once. So, Diegoentered localhost and TravelAgencyTest, respectively.

6 To change one of them, just select the Preferences panel in the KnowledgeBase Navigator and find thepreference to be set; for example, the associated DBMS, implementation language, etc. Then, accessits properties by pressing <F4> (in the window that is opened).

39

Then, GeneXus will generate and execute the Developer Menu,7 so that devel-opers can immediately test the applications. Once the environment is completelyset, every time you press <F5> GeneXus will carry out all the steps needed toexecute the application. Diego expected to see what’s shown in the following fig-ure: the first Impact Analysis of this Knowledge Base.

This Impact Analysis Report (IAR) told him that GeneXus would create thetables shown on the left. Their structures and other details such as indexes, etc.,8

are displayed on the right.

What’s an Impact Analysis Report? GeneXus uses the Knowledge Base todesign the database. The existing objects can be changed at any time, and newobjects may be added to modify the KB. The IAR is obtained from an analysisperformed by GeneXus of the impact of new definitions or changes to the KB on theassociated physical database. Through this analysis, the developer knows aboutthe structural changes that GeneXus will make on the database to update it andmake it consistent with the KB.

7 A simple prototyping menu created by GeneXus (it’s an xml file containing links to the GeneXusobjects created, in order to invoke them quickly and easily as we’ll explain soon.)8 Below are the SQL sentences that will be used to reorganize (in this case, create) that table.

40

9 The term reorganize means to make physical changes.

Diego agreed with the IAR and clicked [Create] to reorganize the database.9

Since the database didn’t exist yet, it would be created in this first step. Later on,it will be reorganized after being changed and restructured. When are the pro-grams generated? Right now, ready for testing! Barely a minute went by sinceDiego pressed <F5> and entered the platform details that were missing until abrowser window was displayed with the ready-to-run Developer Menu. He lookedclosely at some reports previously displayed by GeneXus to make sure that he wasgoing in the right direction.... But don’t rush, dear reader, because we’ll come backto this later and Mike is anxious to step in.

Mike 007... With a License to Kill

It was his turn. He had to destroy them; the transactions, of course.

Looking steadily at the Developer Menu displayed in the browser containinglinks to the transactions, Mike clasped his hands together and cracked his knuck-les. Then he paused. Here we go, he said to himself.

41

The idea was to start the testing immediately –by entering data into thedatabase that GeneXus had just created– and check the transactions’ behavior. Heis going to take notes, so he also gets ready to start a conversation in the transaction’sdocumentation.

He clicked Country and the screen displayed was similar to the followingfigure.

This is the Country transaction at execution time.

Soon, he noticed that the CountryId attribute should be autonumbered. Thismeans that the user shouldn’t have to worry about assigning it a specific valuebecause CountryId doesn’t represent an object from reality. It’s just a number thatmakes new records unique.

42

Likewise, when he found CountryWorldRegion, a one-digit attribute, he didn’tknow which numeric value belonged to each world region (how could they indicatewhether a country is in Africa, North America, Europe, etc.?). We have to show theend user the names of regions and continents to choose from! he thought.

So, he decided to start a conversation with Diego to discuss the subject; thisway, they could all agree to his suggestion. He returned to the KB, accessing theCountry documentation section.

Adding a Conversation

When opening the documentation, Talk is one of the selectors provided. Itallows us to create a space and talk with other users about the object at hand.

Note that the title at the top indicates a Talk document for the transaction. Itends with a question mark, which means that there isn’t a Talk page for this objectyet and that it should be created before writing. When Mike saves this space, apage will be generated with its content.

Upon clicking the question mark, the view switched to edit mode. Next, heentered the text, saved it and viewed it:

43

Setting an Identifier Attributeas Autonumber

Later that day, Diego read what Mike had written and replied in the Countrytransaction’s Talk area. He accepted Mike’s suggestion, and proceeded to do thechanges.

He wanted to automatically number the CountryId attribute, a numeric iden-tifier, through the autonumber feature of the DBMSs that support it.

All GeneXus objects have properties that affect both their look and feel.

Every object’s or attribute’s properties can be edited at any time by pressing <F4>to display them in a floating window.

So, Diego selected the CountryId attribute and pressed <F4>.

44

First, he changed the Autonumber property to True, and set the propertiesshown in the figure above.

An attribute undergoes cosmetic surgery

To complete Mike’s next request in the Talk, Diego went to the transaction’sWebForm, selected the CountryWorldRegion attribute control and pressed <F4>.Inside the control properties window, he set the ControlType property to ComboBox. Next, he selected the Values property to open the Values Editor window andentered the possible attribute values. That was all.

45

If, instead of doing this in the CountryWorldRegion control properties in theform, he had done it in the CountryWorldRegion attribute properties in the struc-ture, the scalpel would have cut deeper: it would mean that every time this at-tribute was added to a form, by default it would be displayed as a Combo Box andnot as an Edit control. When he realized his mistake, Diego made this definition atthe structure level. This is a good example of how knowledge is inferred and reusedin the Knowledge Base.

Reorganizing (reorg)

Diego has changed some properties of two Country transaction attributes.Will this indirectly trigger any changes in the physical table? Following is the Im-pact Analysis Report displayed after Diego pressed <F5>.

46

Yes, GeneXus found that a table needs to be reorganized. Note the wordAutonumber to the right of the CountryId attribute data type. The reorganizationwill have to activate this property at the DBMS level. But, what happened with theother change, the one to CountryWorldRegion? Nothing! It’s not a database change,only the KB was affected. It’s cosmetic, and indicates that in all forms where thisattribute is shown, it should be displayed as a Combo Box. This proves that not allchanges done to a GeneXus object necessarily cause the database to be reorga-nized. We’ll give another example when we explain the transaction’s rules.

Diego can have GeneXus do the reported changes ([Reorganize]) or cancelthe reorganization. If he cancels it, the IAR will be redone the next time he presses<F5>. He chooses to reorganize.

When rereading the talk to reply that everything has been done, Diegorealizes that Mike suggested autonumbering all transaction Ids by default. (Hisconfusion was caused by Mike documenting this in the Country transaction Talk,instead of doing it in the Main Document Talk). To implement this, would he haveto change the attribute properties one by one? No! He remembered that thoseattributes were based on the Id domain. He only had to edit the domain proper-ties and set the Autonumber property at the domain level, just as for CountryId.All current and future attributes based on that domain will automatically inheritthis property!

47

But... Here’s a problem! Diego thought. CityId is not a single primary key. Tobe set as autonumber, attributes must be a single primary key. CityId is part ofCOUNTRYCITY’s primary key.10

How can he prevent this attribute from taking the Autonumber True propertyfrom its Id domain?11 Simply by editing the CityId attribute properties (as withCountryId) and changing the Autonumber property to False. In this way, thedomain’s default behavior is changed for this attribute.

The same applies to the AttractionCategoryId attribute which currently be-longs to Attraction and is not a primary key. However, it will soon become a primarykey when Diego creates the new AttractionCategory transaction. For this reason,Diego decided not to change the Id domain definition at the moment (to activatethe Autonumber). He’ll do it later, when he creates the new transaction (he docu-mented this “To-Do Diego”).

Transactions: Not just a pretty face;they also have personality

Diego added to the transactions the behavior described by users regardingdata management.

“An attraction must never be entered into the system if it doesn’t have aname.” Thus, he opened the Attraction transaction, clicked the Rules selector andtyped the following rule:

Error(‘Attraction must have a name’) if AttractionName.IsEmpty();

If users don’t complete the AttractionName field, the previous message willbe displayed at execution time, and the control won’t let them move on to anotherfield. Saving the record in the corresponding table won’t be allowed, either.

10 To assign consecutive values to this attribute, Diego will have to use the Serial rule. We suggestthat you read about it after looking at the introduction to rules.11 GeneXus is aware of this restriction. For this reason, even if Diego hadn’t spotted the problem, itwould have acted intelligently: it wouldn’t have defined the attribute as autonumber in the database.For didactic purposes, we preferred to make Diego work.

48

“A country must never be entered into the system without a name and fullname. The country’s details can be left blank, but a warning message should bedisplayed to the user in case they were overlooked.” So, he clicked the Rules selec-tor in the Country transaction and typed these three rules, in random order:

Error(‘Country must have a name’) if CountryName.IsEmpty();

Error(‘Country name must be in full’) if CountryFullName.IsEmpty();

Msg(‘No country details were provided. Do you want to continue?) if CountryDetails.IsEmpty();

The third rule also triggers a message, but unlike the Error rule, it allows theuser to move on to the next field and save the record.

Many other rules can be used to program the transaction’s behavior. Notethat they are written in declarative style and, with few exceptions, the order inwhich they are added is not relevant. In our case, they will be triggered dependingon the order of the CountryName, CountryFullName and CountryDetails attributesin the form.

In a two-level transaction, the records of two tables are being handled. There-fore, when the user enters a new country and its n cities through the Countrytransaction form, n+1 records will be added: 1 in the COUNTRY table and n in theCOUNTRYCITY table. They will be added following the same order used to enterthem into the form. A rule may be triggered immediately before or after one ofthese save operations. To this end, rules can be conditioned not only through ifclauses as shown above, but also through trigger events such as BeforeInsert orAfterInsert.

After saving the transaction’s n+1 records (1 header and n lines) a Commit isautomatically performed. It can be disabled by the GeneXus analyst through atransaction property. In addition, rule triggering events capture the momentimmediately before or after the Commit operation. For example, to get a list of thenewly entered country and its cities, you can invoke another kind of GeneXus ob-ject: Procedure. You must invoke it after entering the n+1 records, by sending thenewly entered country Id by parameter. To obtain it before the Commit operation,write the following rule in the rules section:

49

PrintCountry.call(CountryId) on BeforeComplete;12

If you want it after the Commit operation, use the following rule:

PrintCountry.call( CountryId ) on AfterComplete;

Diego documents the changes already made. Think about the changes madeto the KB since pressing <F5> for the last time.

What’s hiding behind <F5>

1. When you press <F5>, GeneXus first makes an impact analysis of the KBchanges on the database. When there’s an impact, it will display the ImpactAnalysis Report, which can be confirmed to physically reorganize the data-base. As we’ve seen, it can also be cancelled.

Diego knows that the changes he made since he last pressed <F5> involverules (of the Country transaction); that’s why he doesn’t expect a reorganizationthe next time he presses <F5>. However, he knows that the following steps will becarried out.

2. GeneXus steps into the specification stage, which is an analysis of every-thing defined in the elements making up the objects that you have changed,be they structures, forms, new rules, etc. This task results in a navigationreport where GeneXus shows the logic interpreted for each object that hasbeen changed since the last <F5>, together with warnings and errors, if any.

In the example involving our friends, Country is the only object that has beenchanged. That’s why after pressing <F5> Diego will view the following report.

12 The Call, a common invocation method in GeneXus, is being used as a rule. Note that the invokedobject’s name appears before the call; in this case it is a Procedure, another GeneXus object. Finally,note that trigger events are identified in the syntax of a rule:

Rule if condition on Event

Condition is a Boolean condition and Event is a valid trigger event. In the product’s documentation youcan read more about other trigger events such as AfterValidate, BeforeInsert, BeforeUpdate, BeforeDelete,AfterInsert, AfterUpdate, AfterDelete, BeforeComplete, AfterComplete, etc.

50

There weren’t any warnings or errors. Note that it shows the tables that willbe saved and the referential integrity checks that will be performed when you try todelete a country or city.

3. After the specification stage comes the generation of the object(s) thatGeneXus deems necessary (if there are objects that haven’t been changedand were generated in a previous <F5>, why do it again?) to completelyperform the execution. The generation entails writing lines of code to imple-ment the programming of objects in your chosen language.

4. Lastly, GeneXus compiles and executes the application in the browser in-stalled in that machine.

This is a completely automatic process. You’ll never have to specify and/orgenerate an object explicitly, because GeneXus is intelligent enough to determinewhich actions to trigger at each time.

That’s how, warned by Diego, Mike opened the Developer Menu and executedCountry, where he added, updated and deleted a few records. Finally, he docu-mented the results in the transaction’s Documentation, changing its status to OK.He still hadn’t tested Attraction (he had found things to change in Country, so hehad decided to put it on hold for a while) when he read in the Talk that Diego hadasked him to delay the test until he created the related transaction that came next.

51

Creating the AttractionCategory Transaction

Diego added the attribute pair AttractionCategoryId andAttractionCategoryDescription to the Attraction transaction, even though he knewthat later he’d create an AttractionCategory transaction to contain them.

This transaction categorizes the attractions of each country’s cities: «Build-ings/Structures,» «Nightlife,» «Relaxation,» «Adventure,» «Gastronomy,» «Safa-ris,» «Business,» etc.

With the Attraction and AttractionCategory transaction structures we’re im-plicitly saying that an attraction belongs to only one category, while a category cancontain n attractions.

The next time <F5> is pressed, GeneXus will have to reorganize the databaseby creating the new ATTRACTIONCATEGORY table and removing theAttractionCategoryDescription attribute from the ATTRACTION table. From now on,this attribute will be inferred from the new foreign key AttractionCategoryId.13

Following is a Bachman Diagram that shows the new relationship betweenthe tables added to the project so far.

13 Suppose that Mike had tested the Attraction transaction and inserted records to it before this reorga-nization. If he had entered an attraction of category Id 1 and Nightlife description, we could ask thefollowing: what would happen in the reorganization when the ATTRACTIONCATEGORY table was cre-ated, and AttractionCategoryId became a foreign key in ATTRACTION, and AttractionCategoryDescriptionwas inferred? What would happen with the ATTRACTION record? For the database to be consistent, arecord of Id 1 and Nightlife description will have to be created in ATTRACTIONCATEGORY. This will bedone by the reorganization program itself. What would happen if there were two or more attractionswith the same category Id and different descriptions? You can give it a try.

52

Before pressing <F5>, Diego remembered to set the Id domain as Autonumber(he had left a note to do it when he created the AttractionCategory transaction.)

Finally, he pressed <F5> and read the corresponding Impact Analysis Re-ports. After clicking [Reorganize] he obtained a new database and newly generatedprograms. He closed the browser because Mike would be in charge of testing, anddocumented the new transaction and Autonumber settings.

Mike read Diego’s notes, prototyped all transactions again, and pressed <F5>...

To free end users from memorizing foreign key codes, GeneXus automatically cre-ates objects called Prompts, which are invoked through the icon displayed next to allforeign key fields at execution time. They are selection lists that show the entiredata of the referenced table for the user to choose from.

While testing the Attraction transaction, Mike tried to enter the attractioncategory of the Eiffel Tower but couldn’t remember the code of the correspondingBuildings/Structures attraction category. So, he pressed the icon next to thecategory Id field. A category selection list, automatically created by GeneXus,was displayed as shown in the following figure.

53

Mike will select the first option on the list, Buildings/Structures, and the con-trol will return to the Attraction transaction. The AttractionCategoryId field willdisplay the value 1; the focus will be there and the user will be able to move on tothe next field (in this case, country Id, for which the process can be repeated).

To confirm that the referential integrity checks were being made, he entereda nonexistent category value in AttractionCategoryId. At execution time, he ob-tained an error message about it.14

14 Seconds later, he would try to delete a category with related attractions from the AttractionCategorytransaction. He expected it to fail in order to ensure referential integrity. Dear reader, you can also trythis for yourself.

54

GeneXus can «disguise» an attribute at execution time so that end usersdon’t have to open these selection lists every time they enter foreign key values.Mike suggested this and Diego implemented it by changing two properties of theAttractionCategoryId attribute. As a result, to enter the Buildings/Structures cat-egory, Mike only needs to remember and type the first letters, and they will beautocompleted.

The attribute where the end user will enter the description is actually theAttractionCategoryId foreign key, which is «disguised» as AttractionCategoryDescription.In this way, even though the end user enters descriptions, the corresponding Id isretrieved from the table and stored in a transparent way.

They still had to improve the project’s usability and appearance, so theywrote about the need to use other GeneXus tools, such as GXpatterns. Maybethey could all meet and discuss whether to put a part of the application in produc-tion in the agency’s Tourism section. This would allow them to test it, enter coun-tries and cities, and send the feedback they found.

“Prototyping is a great resource and, if used appropriately, it avoids an exaggerateddependency on the final test, or even on deployment (D-Day, when everything hap-pens and Murphy’s Law especially applies).”Breogán Gonda, Nicolás Jodal

GeneXus’ features allow testing everything at any time, so that every objectcan be prototyped at the most convenient time. This is a crucial capability thatstems directly from the GeneXus theory, more specifically from the automatic propa-gation of changes.

55

Chapter 3Machine-made,Hand-finished

Immediate Plans

The Travel Agency & Co. project is well under way, enough to move severalparts to pre-production. It’s time to be tested by the end users as the systemcontinues to be developed.

Problem: A Pretty Plain Application

Julia meets with the end users to get their first impressions and addresspossible sidetracks. When they try entering data through the transactions, theylike the controls and data input method, but ask for queries with more sophisti-cated views and increased functionality. For example, they want to work with coun-tries in a more visual and user-friendly way. They’d like to view all existing coun-tries in a grid and be able to choose one to update or delete it, or even view all thecountry’s details, including their cities and related data.

Solution: An Appealing Application 3 Clicks Away

Patterns, here we go, Julia said to herself without hesitation. With the Coun-try transaction in Edit view, three clicks and one <F5>, she asked the users, “Isthis what you have in mind?”

56

1 See Chapter 2, p18. When entering attributes in a transaction structure, the first attribute of Charac-ter or VarChar type is marked as descriptor. You can change descriptors by right-clicking the newdescriptor in the structure and clicking the Toggle Description Attribute option in the displayed contextmenu. But, as we’ll see soon, Julia will have another option to do it.2 The default value is 10 records per page (that is, it loads 10 grid lines). We’ve changed it down to 3in a centralized location of the Work With pattern that we’ll talk about later.3 The Transaction object has a predefined variable, &Mode, which identifies its mode at a certaintime (Insert, Update, Delete, Display) depending on the operation to be performed. If the mode issent by parameter and this variable is received, the transaction will know what operation will beperformed.

The end users view a new link in the Developer Menu, Work With Country.Clicking it opens a new object in the browser, WWCountry, which not only displaysa grid with all the existing countries in the system, sorted by their most meaningfulattribute, name1 , but also allows filtering by name in that same grid (as the enduser enters data in the filter variable, it is automatically filtered in the grid). Inaddition, it provides automatic paging of the grid.2

In addition, it allows performing the following tasks:

• Insert a new country by clicking the icon displayed in the grid’s upperright corner. This will call the Country transaction in Insert3 mode (to add acountry and its cities) and return.

Grid filter

For browsinggrid pages

57

• Update a country’s data by clicking the icon displayed on the grid linecorresponding to that country (it will also call the Country transaction, inUpdate mode this time, to update that country and return).

• Delete a country from the system (by clicking the icon). It will also call thetransaction in Delete mode and return.

• Display all the information on a certain country (note the link on the country’sname). Clicking it opens ViewCountry, a new object (automatically created)that will show all the country’s related data (in tabs):

Essentially, a real Work With Countries has been created. Users could ask forthe same functionality to work with other entities such as attractions and attractioncategories.

Patterns Anyone?

Overall, you may already know what patterns are about: they are commonknowledge that can be applied to different situations. A GeneXus pattern is verypowerful; not only does it free you from manually creating functionally versatile

58

objects, it also enables knowledge reuse. In addition, it’s an open tool: if you needit, you can create your own patterns. They greatly enhance productivity and gener-ate high-quality applications with more uniform interfaces and consistent logic.Patterns generate knowledge from knowledge.

All Julia did was apply the Work With pattern (one of the available ones) tothe Country transaction, obtaining part of an application that implements every-thing needed to “Work With...” the related information, in our case: “countries.”

We can think of the Work With pattern (and of many others) as a machinewhose input is a transaction (and the KB), and whose output is a set of new GeneXusobjects (some of them were shown running), plus changes to some KB properties,plus the modified transaction itself4...

Customization: There’s Always a «But»

The end users’ answer to Julia’s question was “Yes, that’s what we wanted but...

1. In the grid we only want to view the country’s name and world region (theother details are not relevant to us).

2. We also want the displayed countries to be sortable not only by name, butalso by world region and by the {world region, country name} pair. Finally,we want the ability to:

3. ... filter the grid by world region (in addition to by name.)”

4 More specifically, the transaction must declare that it receives parameters, as now we want to invokeit from the Work With Countries object (WWCountry).

59

To apply the Work With pattern, Julia only opened the Country transaction,clicked the Work With selector at the bottom (1st click), selected the “Apply thispattern on save” check box (2nd click) as you can see in the following figure, andsaved (3rd click). Then she pressed <F5> (after which the users could see theapplication running).

However, in the figure below you can see that the Work With selector not onlylets you select the check box, but also edit a tree structure that Julia didn’t evenlook at in the previous steps. Here’s where she will have to work to make therequested changes.

This figure shows an «instance» of the Work With pattern, the Country in-stance, which lets you customize it.5 We can view a hierarchical structure with

5 We still haven’t defined “instance”. It can be thought of as the statement of how the pattern will beapplied to the particular case of this object.

Sets up theWWCountryweb panel:

Sets up theWWCountryweb panel:

60

nodes and a set of properties whose values determine the appearance and behav-ior of what’s generated by the pattern for this instance.

Among other things, the Work With pattern will generate two new GeneXusobjects that we’ve seen running, and that we’ve included for you over the instancefigure. They are of a type that we haven’t discussed yet: Web Panel. Overall, itlets you make user-friendly, interactive queries to the database.6

In the figure we’ve indicated which nodes of the pattern instance allow set-ting up which web panel’s features. The end users have asked Julia to change thefirst web panel. For the moment, they haven’t said anything about the second webpanel (but they may do so...).

Look at the first thing displayed under the «Level (Country)» node. Remem-ber that CountryName was the transaction’s descriptor attribute (the one withmore semantic meaning): you can also update it from here. Does the descriptorattribute have any effects on what’s generated by the pattern? Yes, many. Forexample, it defines which attribute of the WWCountry grid will be linked to theViewCountry web panel that is automatically created to display this country’s de-tails. But this is just an example; as we’ll see, it is used in many places...

WWCountry web Panel: Selection(Work With Countries)

Note that the Selection node has three subnodes: Attributes, Orders andFilter (besides these actions: Ins, Upd, Del, Dis).

By default, the Attributes subnode shows all the attributes of the Countrytransaction’s first level, and they are those listed (by chance?) in the grid of thegenerated WWCountry (Work With Country)7 web panel.

6 On one hand we have a web panel that, among other things, lets us list countries filtered by name.And on the other hand, we have another web panel that shows all the information on a given countryand its cities (the latter in a grid within a tab).7 In the GeneXus Rocha version used to write this book, the WWCountry web panel’s description is inthe singular: “Work With Country.” However, in its screen it’s displayed as “Work With Countries.”Hence, to mention it we’ll use either the singular or the plural, depending on what sounds more naturalfor the context in which it is referenced.

61

Requirement No. 1 is ready!

The Orders subnode indicates the desired default order to retrieve the datathat will be loaded in the grid. This default order is (by chance?) that of CountryName,the descriptor attribute. The end users asked to be able to choose between thisorder and CountryWorldRegion, as well as another one made up by both.

How can the user decide, at execution time, by which order to sort the infor-mation to be retrieved? Through a combo box that shows all the available options.Julia will have to add the new sorting orders requested under the Orders subnode,and give them names (World Region, Both) that will be the options viewed by theend user at execution time in the combo box automatically inserted by the pattern.

Following is the resulting instance and the generated web panel (running):

The users asked Julia to display only CountryName and CountryWorldRegion,so she simply has to delete from this node, by pressing <Del>, the rest of theattributes except for CountryId. This last attribute cannot be deleted carelessly.Even though it’s not displayed to the end user in the grid, it must be included(hidden) as we will justify soon. Therefore, in this case Julia will click that attributenode and press <F4> to edit its properties, setting the Visible property to False.The resulting instance is shown below, where you can view the effects running.

62

Note this: at execution time, you can also order what you have loaded in the grid at a certaintime, by one column, simply by clicking it. But, be careful! If you’re working with paging,only the loaded page is ordered here.

Requirement No. 2 is ready! Only No. 3 to go.

The end users also want the ability to filter the countries to be loaded in thegrid by world region. The obvious answer: Filter subnode. Note what’s displayedby default below this node (see p.5). Again, it happens to be CountryName. Take amoment, dear reader, to deduce what the Attributes and Conditions subnodes mean,by looking at the WWCountry web panel implemented by GeneXus and the in-stance in page 5. How about we show you what Julia did in the instance and theeffects it had on the web panel?

63

When the CountryWorldRegion attribute is added under the Attributes subnode,a variable with the same name, &CountryWorldRegion8, will be automatically cre-ated. It will be placed on the web panel grid and allow the end user to select aworld region, causing the grid to display only the countries in that region (why is itdisplayed as a combo box9 ?

How does it know that it has to apply this filter? From what Julia wrote underthe Conditions subnode. Note some details: two filters were defined (country nameand world region). Which one should be applied? Both, unless one of them must notbe applied (look at each filter’s “when” clauses. For example, &CountryWorldRegionis empty (IsEmpty()) when it has the value 0, that is, with the “(None)” descriptionof the combo box. In this case, the filter will not be applied).

Requirement No. 3 is ready!

Interestingly, and not by chance, when Julia explained to the users how toupdate or delete a country at execution time, the Country transaction was opened,and the country selected from the grid was edited. To do so, the Work With patternhad to change the transaction’s rules by adding some to the ones we had declared.What for? To instantiate, edit, the country received by parameter. Let’s take a look:

8 You may have noticed that throughout the GeneXus code, variables are identified by an ‘&’ added asa prefix to the variable name.9 Remember that in the CountryWorldRegion attribute properties, Diego indicated that when it is a formcontrol, it should be displayed as a combo box with the values he set (to the first one, 0, he gave it the“(None)” description). This is a variable based on that attribute, so look how it inherits the samebehavior, without setting anything.

64

To declare the parameters received and returned, all GeneXus objects use theParm rule.

When you use «Work With Countries» to choose a country from the grid toupdate it, this transaction will be invoked through the «UPD» mode that is receivedin the &Mode variable. In addition, the corresponding CountryId will be sent (that’swhy we had to leave it hidden in the grid). To insert, ‘INS’ is sent together with theempty value as second parameter, and so on...

ViewCountry web Panel:View (Country Information)

When we click the country name at execution time, the ViewCountry webpanel is opened to display the data on that country (see page 3). Let’s see whatdata is displayed: the country name received by parameter (again, CountryName,by chance?). Then, in a General tab, it displays all the attributes of the Country

65

transaction’s first level for that country and two buttons for calling the transaction,passing that country by parameter (to update and delete it, respectively). In a Citytab, it displays a grid with all the country’s cities.

Pay close attention to the “View (Country in-formation)” node of the Country Work With in-stance. If, in addition to the country’s name, the userasked to view the country’s full name, only theCountryWorldRegion, CountryDetails and CountryFlagattributes would be displayed in the General tab;and if he also wanted the City tab, the cities’ grid, todisplay only their names, what changes would hehave to do to these nodes? What if the user didn’twant a City tab at all?

In the instance, there will be a “Tab” for eachsubordinate table (many to 1)10... but Julia could addother Tabs... with other things... but let’s not rush...

In sum: when Julia selects “Apply this pattern on save” in the Country WorkWith selector, GeneXus objects such as those we’ve seen running will be generatedupon saving. They can be accessed in the Folder View, below the transaction. Like-wise, every time the instance is modified, saving will cause the automatic regen-eration of the corresponding objects.

10 COUNTRY only has COUNTRYCITY in this relationship (many cities for each country) and that’s whythere’s only one Tab. Note that the chosen name was the description of the Country transaction’s level2 (the description of the lines, which was City).

66

Without batting an eyelash, Julia clicked the instance root node and changedthe AfterUpdate property value shown here to «Go to View»...

Note that first it takes a “<default>” value, which has to be indicated some-where (the same goes for the others). This value sets the default behavior of allinstances (this one is Country, but we may also want Work With Attractions andWork With AttractionCategories). If we want most or all of the application’s WorkWith objects to default to View after updating, we don’t need to manually edit thisproperty in each transaction instance. Instead, we can change the “<default>”value in one centralized location. Where is this centralized location?

It’s below the Pattern Settings node of the Folder View. Note that in thefollowing figure only the Work With is displayed. But there will be other patternscreated by you, by Artech, and by others...

(“Extensibility”... “Integrability”... these are key pieces of the Rocha ideol-ogy).

More?

End users asked Julia that after updating a country, they didn’t want to goback to the caller, WWCountry. Instead, they wanted to view the entire data on thenewly updated country (that is, go to the “View Country”).

67

This figure shows all the default behaviors to be inherited by individual WorkWith instances for each transaction. For example, all the features related to theWork With grids, such as paging, are displayed as properties of the Grid node.11

Interested readers can search for more about the general settings that can beconfigured here. For example, you can change the appearance and names of thepages, the icons for Insert, Update, Delete operations and much more.

Reflect upon what it means to “work with.” What else could the difficult enduser ask for? Just ask Julia and she’ll tell you that in that same meeting, it occurredto this end user that he wanted to:

A. Export the country data that he was working with to an Excel spreadsheet.Can you believe it? Also, they didn’t want:

B. Countries to be deleted from the Work With Countries. If this weren’t enough,they wanted to:

C. Add another action for countries besides Insert and Update . It wouldopen a new window with each country and its cities –together!– in a morevisually appealing format. (It sounds a bit vague to us... and to Julia as well.)

11 If you look at the Page property of the Grid node in your KB, you’ll find that it has the “Page.Rows”value. What’s a Page? It’s a numbered domain, automatically created, which contains only one value,Rows; its default value is 10 and we have changed it to 3.

68

Julia was secretly amused: every time the demanding end user asked for anew requirement, she made a few clicks and that was it. Except for the last one —don’t forget that Julia isn’t an IT specialist, so back at the office she’d ask Diego forhelp.

Actions Available from Work With Countries

Here are the actions offered by theWork With pattern for implementation onthe WWCountry data that it works with.Note that there’s an Export option. “De-fault” values, again! Yes, again. They willbe set in the WorkWith object that we’veseen before, which centralizes all this. Inour case, the “default” values for Deleteand Export were True and False, respec-tively. To disable the delete action andenable the export action for a country,Julia only had to change the above comboboxes, setting them to False and True,respectively. Requirements A and B areready to go!

Now only the last requirement, C, is missing: adding an action that is notpredefined. But the object to be invoked by this action is not created by the WorkWith pattern; it should be custom-made for this specific data, so it’s not like anyusual “work with.” This is a job for Diego, who’ll implement that object in GeneXus.In the WorkWithCountry Documentation selector, under a “To-Do Diego” title,

Export

69

12 Coming up, you’ll see that Diego will easily find Julia’s note in the documentation that seems to be“scattered” among so many KB objects, thanks to the Dynamic Categories that he’ll talk about inchapter 6.

Julia writes that this task is pending. It will be implemented by Diego when hegets down to it.12

Insatiable as Usual: “I Want More!”

Back from her meeting with the users, Julia received an email from… the users!They wanted the list of countries from “Work with” to include at least part of eachcountry’s details, CountryDetails, so they could provide their customers with brief infor-mation on each. They also wanted to view the number of attractions in each country.

So she needed to add two new columns to the Work With Countries grid –onefor the brief description and another for the number of attractions. But she didn’tknow how to do this, since this information wasn’t stored in database attributes.Instead, it had to be obtained through some data processing. She was planning tocall Diego anyway so he could teach her how to implement the pending require-ment, C; that’s why she called him immediately.

Diego created a ShortDetails domainof the Character(30) type. Then he openedthe Country Work With Pattern Instance.Through the “Add” command he added avariable to the grid.

70

Note that, in the properties dialog, a name and a domain must be assigned tothe variable being inserted (that’s what the icon means). Diego names it ShortDetailsand assigns it the newly created domain of the same name. He only needs todetermine the value to be taken for each line in the grid.

“As you can rightly guess, Julia, when you put the attributes under this node,you didn’t need to do more: GeneXus would run through the COUNTRY table and,for each record complying with the conditions in the specified filters (in our case,they are CountryName and CountryWorldRegion), it would load a new line in the“Work with” grid, with those attribute values in each column. If users wanted thefull country description, you’d only need to include the CountryDetails attribute,but what they actually want is to shorten it to 30 characters. So, all we need to dois specify, in the LoadCode property of the variable we’ve entered, the value to betaken for each line. This will mean keeping the first 30 characters in the string,13

that is: &ShortDetails = Substr(CountryDetails,1,30). Yes, CountryDetails is the attribute.That simple. You can do it on your own now.”

“I see. Then for the other requirement, for displaying the number of attrac-tions in each country…”

«Well, that’s not as simple because the processing needed to load the vari-able containing that information is more complex. Think of this: every time a coun-try is being loaded in a grid line, all the country’s attractions have to be run throughto count them. There are two choices here. One is to program the code that allowsyou to run through the information,14 in the LoadCode, again. The other is to addan attribute containing that information to the Country transaction, let’s say, aCountryTotalAttractions. This way, you only need to add this attribute to the At-tributes instance node and that’s it!”

“But, I don’t understand... When entering information on a given countrythrough the transaction, will the user enter the number of attractions it will con-tain? What if it doesn’t match the actual number of attractions? Users won’t likethat.”

13 GeneXus offers multiple functions for working with different data types. In particular, there is thesubstr function, which allows retrieving a substring from a given string.14 The for each command, which will be described later.

71

“Julia, you’ll be able to do my job soon! That’s exactly right. It wouldn’t makeany sense if the user had to enter a number that results from a calculation ofdatabase values. This attribute, CountryTotalAttractions, will be of a special kind.In GeneXus it’s called a formula. Look, I’ll just enter this new attribute in theCountry transaction structure and then I’ll let GeneXus know that I have moreinformation –that I know how it must be calculated, so it mustn’t store it in thedatabase but calculate it every time its value is requested, as I’ve determined.”

«Count(AttractionName)? Uh-huh, this indicates that you want the numberof associated values15 in AttractionName to be counted for that country, right? Now,how does GeneXus know that it needs to count the number of attractions for thatcountry and not for all others?”

“Well, remember that GeneXus knows the relationships between data andthat a given attraction belongs to a given country and a given city. Also, that eachcountry-city belongs to one country. That’s enough.”

“And what advantage does this solution offer us, as compared to the otherone –adding a variable in the pattern instance and establishing how to make thecalculation (which, by the way, I don’t know how to do)?”

15 For you as an IT expert (because you are one, aren’t you?): for each country, count the number ofassociated records in the table where AttractionName is located; right now it’s ATTRACTION.

72

16 Author’s note: The Latin phrase “Quod natura non dat, Salmantica non praestat” means that “whatnature does not give, Salamanca does not provide.” In other words, the Spanish University of Salamancacannot miraculously make a person intelligent.

“Well, you’ve implemented a general solution here. In other cases, in otherobjects, when you retrieve a country and want to know the number of attractions itoffers, you’ll only need the formula attribute and the calculation will be triggered –you won’t have to program it manually. Now, you just have to add this formulaattribute to the instance Attributes node. Voila! The two requirements in the emailare solved!”

There are various kinds of formulas in GeneXus (for adding, counting, searching,maximizing, minimizing, etc). Note that they are virtual attributes –they won’t bestored in the database.

Quod Pattern Non Dat, GeneXus Praestat 16

In the time it took Julia to pour herself a cup of coffee, say hi to a coworker andwalk back with her cup of steaming coffee, Diego was able to implement the lastrequirement (C, which was pending). Since they were not sure whether what they hadimplemented was what the users wanted, they emailed them the following screenshot:

73

“How could you do it so quickly, Diego? Will you show me? I’m sure it’s notthat difficult.”

“Of course it’s not. All I did was create a new object in GeneXus, of the WebPanel type. It’s the one you can see running on the screen. What you want to do isdisplay information on countries and cities (each country’s cities). Forget the coun-tries for a moment, and let’s say you only want to list information on the cities, ina grid. All you need to do is insert a control of this type in the web panel form andspecify which attributes will make up the columns. Simply by doing this, when youpress <F5> you’ll see all existing cities listed at execution time. From the at-tributes present, GeneXus infers which table you want to browse (called a basetable). Look, it created a Cities web panel in a snap, inserted the grid through thetoolbox offering all the controls that may be inserted in a form and chose theCityName attribute. The resulting object form can be seen in this figure. In ourcase, the attributes we included in the grid (CityName) come from the COUNTRYCITYtable, which will be the one that GeneXus will navigate.”

«The grid we’ve inserted is known just as Grid, standard grid, since it allowsdisplaying the information from a record in a table (and in its extended table), withone information element per column (note that our grid has only one column, withone title, corresponding to the CityName attribute, but if we had another one, itwould place it in another column). Now, forget the cities for a moment and supposethat you want to do something very similar with the countries. However, you wantto display each country’s information in a more flexible way and not in fixed col-umns, as you can see in the screen we’ve sent to the customers. Look at the webpanel I made while you went to get your cup of coffee:»

74

«Note that now the cities grid is displayed, with the CountryFlag andCountryName attributes, within a rectangle. What’s that? Another type of grid. It’scalled Free Style, since, as you can see, the information on the country you want tolist is displayed not in columns but together, in any design you choose. But it’s alsoa grid. Therefore, it’ll display as many countries as there are in the country table.Note that among its properties, there’s one called Columns where I changed itsvalue from ‘1’ to ‘3.’ That’s why you can see three countries per row in the image wesent to the users. Rows ‘0’ means that there’s no paging; all existing countries willbe displayed. Then, note that within Free Style we can enter any control, includinganother grid. By doing this, we allow GeneXus to find the relationships amongtables. That’s why it’s listing cities per country in the grid, without us needing toindicate anything; it does it automatically. You can see it for yourself in the naviga-tion report that will be displayed after the specification, following the <F5>. Let’ssee if you can figure it out...»

75

The countrybeing loadedin the grid…

«What I can figure is why you implemented this so quickly... it’s not that‘Nature gave it to you;’ rather, ‘GeneXus lent it to you.’ You pretty much didn’t haveto do anything! Don’t give me that look, Diego. I was just joking. Will your girl-friend come over today?»

“Hmmm... We could also make another web panel (invoked through a Tabfrom the country View) that, given the country, graphically displays the number ofattractions per city. For example, in a 3D pie chart. I’d like to do something toimpress…” Diego fell silent.

“Impress users? … Well, Diego, you are not getting my jokes today. Beforeyou go on, we still need to be able to call this web panel that you’ve just imple-mented from the Work With Countries.”

“True. But you already know how to do that. Simply add a new action to thepredetermined ones (insert, update, etc.) in the Country Work With instance. We’llassociate it with a button outside the grid and indicate that, as a result of the action,we want to invoke the CitiesPerCountry web panel I’ve just created.”

76

Right-click the Selection (Work With Countries) node, select “Add ac-tions” and then repeat the procedure while positioned on the new Actions node.Look what our friends have done, and its effects at execution time:

Requirement C is ready!

New Tab in View Country

Diego wanted to impress someone… (may be you, dear reader) with a newrequirement: adding a new Tab control to the ViewCountry that shows a 3D piechart with the number of attractions per city in that country. In order to do this,he adds a Tab node in the Work With pattern instance corresponding to theView, which will be loaded with the content from another GeneXus object that

77

CountryId must be passed as aparameter to the Web Componentimplementing the chart.

17 Actually, it will be a web panel with the Type property set as Type = “Component”

Diego will have to program. It could be a web panel, but in fact it needs to be anobject that can be executed within another (in our case, within ViewCountry).It’ll be a Web Component. To all other purposes, it’ll be the same as a webpanel.17 He’ll call it AttractionsXCity and he’ll indicate, in the new Tab, that itwill be loaded with it.

Another Side to Extensibility: User Controls

GXchart is an online service that instantly creates any chart you need to viewin an HTML page. You only need to define the desired chart and the GXchart serverwill provide you with the relevant image.

In addition to the standard controls you usually insert in your panels (at-tribute, grid, text block, etc.), GeneXus Rocha allows you to create your own cus-tomized controls: user controls. Once a user control is installed, it can be used inthe same way as any standard control. GeneXus Rocha comes with some preinstalleduser controls: GXchart is one of them. In the image below we can see that Diegoinserted a control of this kind in the web component form. Then, all he had to dowas set its properties and load the values he wanted to see in the X axis (thecountry’s cities) and those he wanted to see in the Y axis (the number of attrac-tions). Upon inserting this control in the form, a structured data type is automati-

78

cally created, better known as SDT, which allows building record lists of variablelength in a flexible way. In turn, it creates two variables, &GxChartData and&GxChartSeries, and uses them to load these lists (cities and attractions). Thecode by which they are loaded can be seen within the Start system event, pro-grammed by Diego. Don’t worry if you don’t understand this code right now. Wejust wanted to show you how easy it is to comply with this requirement.

Consistent Look & Feel without Sweating?

“Having a consistent look & feel is today’s must for any Web application.Creating and maintaining each page in a Web application, ensuring consistencythroughout the site, takes a great deal of programming time,” Julia read out from atechnology magazine on Diego’s desk.

“Not with Master Pages,” Diego replied. “As I’ve said before, a web panelcan implement an ordinary web page like the one we made, CitiesPerCountry (withthe Free Style and standard grids). That is, an independent web page that will beinvoked by another (in our case, by WWCountry). Or it can implement a web pagethat will be a component of another page, like the chart that was a Web Componentpart of the ViewCountry. Or, finally, a master page, which is a page that centralizeswhat will be common to all the pages in the site, such as the header and footer

79

you’ve seen everywhere. They even tend to havea vertical menu on the left, so that it is only inone location and, if you want to change it, youonly need to do it once.”

“Of course! At the beginning of the project Isaw Mike running transactions that had all the same header and footer (now I seethat Work With Countries and View Country also have them). Since those sectionsweren’t included in the objects’ form, I wondered how it was done. A master pageprograms that common look, right?”

«Exactly. Look at this,» Diego said while se-lecting the Country transaction and accessing itsproperties. «You’ll see the same in all transactionsand web panels created by patterns: AppMasterPageis a master page automatically created with the KB,and contains that header and footer that keeps show-ing up.

Let’s open this web panel and look at its prop-erties. What does this tell you?

And not only the com-mon form is programmedhere, but you can also pro-gram common behavior. Pagesin a site are quite usually re-stricted to authorized users,who must log in to the systemto be able to browse them. Inthe past, validation of a userauthorization had to be re-peated for every web pageaccessed. However, with mas-ter pages, the validation codeonly needs to be written once,here, and that’s it! We makesure all associated pages will carry out this validation and the code will not bescattered everywhere.”

“That’s great! I mean, for you, because less work is needed to achieve consis-tency. I’m going out to lunch and then I’ll impact the pattern on the rest of thetransactions we have. Have you had lunch already?”

80

81

Chapter 4Flight to the World

of Subtypes

The project was moving forward on schedule, and the team members werefocused on their specific roles. Thanks to GeneXus’ incremental philosophy, theyfelt confident about facing changes or innovations that may arise. The model en-compassed everything necessary, and nothing else.

Completing Transactions on the Fly

It was past lunch time, but Diego wasn’t hungry. He decided to wait a whilebefore creating the remaining transactions. The truth is, he had offered to showMary GeneXus Rocha in action, and wanted to make a good impression. Instead oftaking his notebook to the coffee shop, he had suggested meeting that afternoon inhis office at ACME.

“Hi, Mary! You look good, how are you?”

“Hi, I’m doing better. I appreciate your offer, considering that we’re in com-peting companies. It’s really kind of you.”

“Hmmm... It’s not like that,” he mumbled as he wrote ‘the Community’ on theboard. “Please, don’t get me wrong. I mean, the rivalry, the competition isn’t likethat. There are thousands of GeneXus developers and they’re all linked by what’scalled the Community. It’s very motivating. ‘Synergistic,’ some would say. You maybe wondering whether it’s a club. Well, there aren’t any social or sports activities –for now,” he added with a smile, trying not to sound nervous. “It’s like a network forsharing knowledge and solutions related to GeneXus and its associated tools.

82

Many programs and extensions have been created by Community members tomeet different needs. There’re many Web sites to download them, and to publishthem as well. The Community is very active, with dozens of forums to exchange allkinds of solutions. I’m on several subscription lists and consider myself an activemember.”

“It sounds nice, but... Does it work? Do they really help you out or is it ajoke?”

“As the saying goes, ‘one hand washes the other...’ Everyone needs help some-times. If, instead of competitors we’re collaborators, we all benefit; we work better,are more motivated and reach better solutions. We have a common goal: to makethe Community grow for everybody’s sake. It may sound naive, but the truth is itworks. GeneXus Rocha itself is formed by GeneXus extensions. That is to say,Community members can expand GeneXus Rocha with their own extensions. Infact, GeneXus itself can be considered as an extension.”

Diego was happy to see her bright, familiar look and went on, more confi-dently:

“Look,” he said, opening the Extensions Manager window through the Toolsoption in the GeneXus menu. “This is the current list of extensions in GeneXusRocha. Most of them were developed by Artech and the rest by Community mem-bers who made them available to everyone.”

“I see that the Start Page has a section called ‘Extensions,’ with an abstractby the author and a link to install it.”

“Yeah, and if you read it through, you’ll notice that some of them don’t say ByArtech. These extensions were created by third-party Community members.”

As far as the project was concerned, at thatpoint reality required that more transactions beadded. After a quick review, Diego created the Air-line transaction to store the names of airlines re-lated to Travel Agency & Co.

83

1 Since we’re simplifying reality, we assume that there will never be more than one airport percity.2 When we say “city” we always mean a real city, such as Paris. To identify a city, we must provide the{CountryId, CityId} pair. Due to the transactions’ design, there can’t be any cities that aren’t related totheir countries. For example, there’s a city called Rosario in Argentina and another one in Uruguay, butRosario doesn’t exist independently from a country.

Flight Transaction: Destination Subtypes

Diego read his notes and was glad that the next transaction was a complexone. Mary used to like a challenge.

“We’re going to create the next transaction, but you’ll have to focus,” hewarned, as this could be a surprise. “Take a look at this case. The transaction willcontain flight information such as description, airline, departure time, and maxi-mum number of passengers; this data is easy to understand and infer. On the otherhand, we’ll have a departure and arrival city,1 which is data from reality that weneed to know and store. At the coffee shop I told you that when attributes sharethe same concept they must have the same name. Do you remember?”

“Yes, when you showed me how to create the Country transaction. I remem-ber there was an exception...”

“It’s time to clear that up. Sometimes, we have to use different names forbasically the same attributes, which breaks the rule. The flight transaction has aproblem that causes this exception. In every flight there are two countries and twocities involved, which play different roles: one departure country and city, and onearrival country and city. We have two references to the same table, COUNTRYCITY.Look, if we only wrote this that I’m drawing on a paper:

We could say that the CountryId and CityId attributes in the Flight transac-tion represent a country’s city, because they have the same name as the Country

transaction identifiers. This meansthat they’ll be a foreign key of theCOUNTRYCITY table. So far so good,but now we need to add another city2

with another role: the arrival city. Inother words, a city has to be refer-enced twice: as departure city in onerole and as

84

arrival city in the other. How do we do this? We won’t be able to add oneattribute pair to the same transaction twice. Otherwise, how could those attributesbe distinguished? However, we could do something like this...” He took a pen andadded two new attributes; the first two were prefixed with a D (Departure) and thelast two with an A (Arrival).

“Hmm... But if GeneXus infers that they’re different things because theyhave different names, there’ll be no connection between flights and cities, right?”

“Right. The solution is to tellGeneXus that these attributes arestill the same concept, even thoughtheir names have been changed todistinguish them. AlthoughDCountryId is no longer calledCountryId, it still has the same func-tion so GeneXus has to maintain ref-erential integrity as before. This is the same as saying that DCountryId is a sub-type of CountryId.3 The complete solution is to group these pairs in two subtypegroups,” he said while redrawing the diagram.

“I see...! Because of that, DCountryId and DCityId will be a FLIGHT foreignkey to the COUNTRYCITY table, just like ACountryId and ACityId. You have twoforeign keys to the same table.”

“That’s right. And allreferential integrity checksmust be automatic,” headded, discovering a newenthusiasm in her. He won-dered if he’d be able to takeback control of the key-board.

“Anyway, the problem doesn’t end here,”continued Diego. “In this transaction, besidesindicating that a flight has departure and arrivalcountries-cities, we want to infer each countryand city name to view them in the form. That isto say, we want to display attributes of the FLIGHT

3 Thus, CountryId is a supertype of DCountryId.

85

extended table. How can we infer them if we have two references to the table? Wecan’t use only CityName because there are two of them. GeneXus wouldn’t knowwhether to use the {DCountryId, DCityId} foreign key, or the other {ACountryId,ACityId} foreign key. There’s an ambiguity!”

“Well, you’ll also have to change the names of the (CountryName, CityName)attributes to be inferred and put them in the corresponding subtype group, Marythought. Then she said, “Show me how to define these groups in GeneXus; goahead, this way you can explain it better.”

As if he had read her mind, Diego selected Subtype Group from the NewObject window and named it Departure. Mary smiled and didn’t say anything.

“As I told you, they really are groups. You create one, name it and add the‘new’ attributes4 pointing to their corresponding supertypes. In this way, GeneXuswill know that the FlightDepartureCountryName attribute will be inferred only throughthe FlightDepartureCountryId attribute, because they belong to the same group –Departure. See the connection?”

4 Note that subtype names follow the GIK naming convention. That’s why they begin with “Flight” (thetransaction’s name) and continue with “Departure” (the group’s name). In this way, the roles they playin the transaction are easy to understand.

86

5 This ambiguity can be removed by changing the name of one CountryId and CityId occurrence.

“Sure,” she replied. “When the user enters a value on the{FlightDepartureCountryId, FlightDepartureCityId} foreign key, the referential in-tegrity check on COUNTRYCITY will bemade. In addition, this country-city code’sname will be inferred from theFlightDepartureCityName attribute, andthe country’s CountryName will be inferredthrough the extended table inFlightDepartureCountryName. Now weshould create the arrivals subtype group.Right?”

“Not necessarily, because the twogroups are clearly separated. The one I’ve just created is the explicit one. Theother is implicit if I add the CountryId, CityId attributes to the transaction struc-ture.5 But for the sake of clarity, we usually group all occurrences. Otherwise, onerole (arrival) wouldn’t be clearly identified. How about you create the other group?”asked Diego, pointing at his laptop.

“Ok, I’ll give it a try...” said Mary, who was excited by what she was learning.

87

Since the FlightClassId attribute can only have up to three possible values (First, Business and Economyclass), do you know, dear reader, what can Diego do to let the user easily select one?

Diego was documenting his work on the KB’s Wiki, when suddenly Mary an-nounced she had to leave. “Thank you so much, Diego. I’ll call you soon.”

Maximum number of passengers

“Great!” Everything was ready to create the Flight transaction. “It’ll be a two-level transaction. Each flight has three classes (First, Business and Economy) withup to three different fares, which makes it a price list (1-n relationship). All flightshave only three different fares. Keep in mind that the flight ID mustn’t beautonumbered because this number is defined by an international standard thatincludes their route and time. For example, Pluna Flight 0174 from Montevideo toBuenos Aires operates on Saturday mornings. If it’s moved to the afternoons, theflight number will change as well.”

The following figure shows the final structure. Note the icon that indicates asubtype attribute.

88

6 Even if the FlightDepartureTime and FlightInstanceTime attributes are of DateTime type (they allowstoring a date + time), we’re only interested in time.

With this design, FlightNumber will be a foreign key. How many FlightInstances can there be for thesame flight (FlightNumber)? Is it as expected?

Some of the attributes here are worth noting. For instance,FlightDepartureTime6 is the scheduled departure time of the flight (it’s inferredfrom FlightNumber). FlightInstanceDate and FlightInstanceTime are the actual dateand time of the actual flight. The actual flight time is predetermined byFlightDepartureTime and can be changed by the user. So, Diego created the follow-ing rule, which is executed only in Insert mode:

default(FlightInstanceTime,FlightDepartureTime);

COUNT(FlightInstancePassengerSeatNumber)

An Actual Flight: FlightInstance Transaction

The Flight transaction handles flight information; for instance, Pluna Flight0174 from Montevideo to Buenos Aires departs daily at 11:15 AM. For each flight0174, there’ll be an actual plane flying on a certain date, with a certain number ofpassengers on board.

The following transaction represents the actual flight, with information suchas date and departure time, number of passengers, reservations, names and seatnumbers. Here, the ID will be autonumbered.

89

He also added another rule:

error(‘Maximum number of passengers has been reached’) if FlightInstanceNumberOfPassengers > FlightTotalCapacity;

The FlightTotalCapacity attribute is inferred through FlightNumber. What aboutFlightInstanceNumberOfPassengers? It’s a formula that counts the number of linesentered in the sublevel. Every time a new passenger is added to the form’s grid, aseat number (FlightInstancePassengerSeatNumber) is added for that actual flight,and the formula is updated. When a passenger exceeds the maximum number, theerror will be triggered so that no more passengers can be entered into the databasefor that flight.

Lastly, Diego declares this rule:

error(‘The flight departure cannot be advanced’) if update and FlightInstanceTime < FlightInstanceTime.GetOldValue()

and FlightInstanceDate < FlightInstanceDate.GetOldValue();

In other words, when updating an actual flight, only the departure date and/or time can be changed, as long as it’s not advanced. Note that the GetOldValue()attribute method is used. It returns the value stored in the database, whereas theattribute now has the value that the user has just entered in the form (it’s inmemory).

The passengers’ information will have to be stored, so Diego will create thelast transaction of this stage.

In the Flesh: Passenger Transaction

90

Once this transaction is created, the PassengerId attribute of the FlightInstancetransaction becomes a foreign key. The following Bachman Diagram represents therelationships between old and new tables.

Everything seemed right, so Diego accessed the Wiki, documented the end ofthis stage, and left to Julia the implementation of Work With objects.

91

Just declare? What about Procedural Descriptions?

That’s what Mary asked a couple of dates later, at the usual coffee shop.They had started seeing each other more often, at his office or the coffee shop,and had discussed several topics such as patterns, web panels and so on. Today,she was in a quiet mood. She understood that transactions allowed describingusers’ views on data in a declarative way, but it didn’t seem enough. She wantedto know about the batch or similar processes that are needed in all applications,because these processes can’t be inferred from the knowledge provided by viewson data.

“So?” she asked.

“A procedural language is missing, I agree,” Diego affirmed. “Considering theGeneXus philosophy, it’ll probably be a very high level language. What’s more, itshould only use references to the External Model, not to the Relational Model. Forinstance, suppose that you must delay the scheduled departure time of all majorflights (which carry more than a certain number of passengers) from a certainairport, at a certain time on a certain date, for whatever reason –say, bad runwayconditions. You’ll have to access all the FLIGHTINSTANCE records where theFlightInstanceDate and FlightInstanceTime values match the date and time whenplanes won’t take off, and belong to flights that depart from a certain airport andcarry more than a certain number of passengers. In those records, you’ll have toreplace the current values of FlightInstanceTime, and maybe FlightInstanceDate,with the new ones. To do so, you could filter the ‘Work With FlightInstance’ by thosevalues. For each line (an actual flight) displayed on the grid, you’d have to call theFlightInstance transaction in Update mode and manually edit the values. Most

Chapter 5When the “What”

Is Not Enough

92

likely, this will be unacceptable for end users. The other alternative is to use vari-ables in a web panel (such as ‘Work With FlightInstance’) for users to enter boththe current and new date and time values for those flights, as well as their country,city and carrying capacity. Finally, an action (button or image) would call a proce-dure that runs through the FLIGHTINSTANCE records and makes the change.”

“Is it a common procedure?”

“Yes, it’s a new GeneXus object type. Here’s my notebook. It’ll be more visualif we create this procedure to try it in GeneXus.”

A few seconds later, Diego was ready to create the Procedure object in orderto implement the previous logic. Following is the edit window of the newly createdprocedure.

Through the Rules selector, Diego declared the received parameters:

parm( in: &CurrentInstanceDate, in: &CurrentInstanceTime, in: &CountryId, in: &CityId, in: &NewFlightInstanceDate, in: &NewFlightInstanceTime, in: &FlightTotalCapacity);

“Wait a second, I got lost. I assume that the For each is a command foraccessing the database by running through a table. But, where do you say thatFLIGHTINSTANCE is the table to be run through? Besides, you’re using attributesfrom another table. Shouldn’t you run through FLIGHT first and, for the recordsthat meet the conditions, make a join with the FLIGHTINSTANCE table?”

93

“It’s not necessary,” Diego replied. “To begin with, you don’t declare the table.That’s the trick! In the For each command that we wrote,1 we said that for eachrecord of the table where the attributes mentioned are located (FlightInstanceDate,FlightInstanceTime, FlightDepartureCountryId, FlightDepartureCityId, andFlightTotalCapacity), the values of the first four should match those of the variablesreceived through the parameter. In addition, the FlightTotalCapacity value shouldbe greater than or equal to the variable that’s received through the parameter. Inthis case, the FlightInstanceDate and FlightInstanceTime values should be replacedwith the new ones.”

“I still don’t get it. Those attributes are in different tables. FlightInstanceDateand FlightInstanceTime are in FLIGHTINSTANCE, but all the others are in FLIGHT…Shouldn’t you run through…?”

“That’s right,” Diego interrupted her. “But FLIGHT is in the extended table ofFLIGHTINSTANCE. In other words, for each actual flight there’s a FlightNumber(foreign key) that belongs to only one record of the FLIGHT table, which has oneFlightDepartureCountryId, one FlightDepartureCityId, and one FlightTotalCapacity.There’s an n to 1 relationship between FLIGHTINSTANCE and FLIGHT. GeneXusdoesn’t need anything else: it’ll run through the FLIGHTINSTANCE table and accesseach record’s counterpart in FLIGHT, by making an automatic join to get theFlightDepartureCountryId, FlightDepartureCityId and FlightTotalCapacity attributevalues. Using this data, it decides whether to keep the record to process it (pro-vided that the FLIGHTINSTANCE record matches the date and time indicated by the&CurrentInstanceDate and &CurrentInstanceTime variables). The condition to keepa record for processing is the And concatenation of all the logical conditions you seein the For each command’s Where clauses. Since we’ve talked of base tables, we’lldo it here as well: it’s the table run through by a For each command. BecauseGeneXus knows the relationships between tables and the attributes’ location whenmaking the analysis, it can infer the data access without you naming any table. Asa consequence, you can change those attributes from one table to another, withoutlosing the procedure’s description.2”

1 Take a deep breath, dear reader; we don’t want you to run out of air.2 As long as the attributes belong to the same extended table; otherwise, GeneXus will give an errorsaying that the attributes couldn’t be related.

94

“Why? It looks a bit like magic... I wouldn’t feel safe programming in this way.”

“Believe me, there’s no magic here. Let’s look at the navigation report toaddress your doubts –and mine. Before executing a procedure to test it, the firsttest is done: it’s the navigation report, which provides information about the thingsthat are making you nervous. That’s why I never execute without reading thisreport. Ok, I’m not going to lie to you. Sometimes I don’t read it and regret itafterwards. Let’s read together...

See? It displays the For each command’s base table, the order that it’ll use toprocess the data,3 and the index suggested to follow this order (if it exists). Be-sides, it shows the navigation filters; that is to say, where it starts and finishesrunning through the table. In this case, it’ll run through the entire table.4 Then,Constraints (filters on the records to run through) are analyzed. Below you can seethat for each FLIGHTINSTANCE record a join is made with the FLIGHT table of itsextended table (to filter by FlightDepartureCountryId, FlightDepartureCityId and

3 The order can be indicated with the Order clause of the For each command. Since it hasn’t beenindicated, there is no database index to optimize the search for records satisfying these conditions.Thus, GeneXus assumes it’s the primary key of the table to be run through.4 If there was an index formed by {FlightInstanceDate, FlightInstanceTime, FlightDepartureCountryId,FlightDepartureCityId, FlightTotalCapacity}, it would use it to optimize the query and avoid runningthrough the entire table. It would inform this in the Navigation filters of the Navigation report. Inthe event that there was an index formed by a subset of those attributes, it would suggest it. (Atany time you can have GeneXus create a user index). We say that it’ll suggest it because thisinformation is valuable for SQL generators, but actually, the DBMS determines the most appropri-ate access plan. On the other hand, it is vital for non-SQL generators (RPG, COBOL, VB-Access,VFP-DBF).

Base table

You shall accessthis tablethrough a Join

95

FlightTotalCapacity). In addition, the FlightInstanceDate and FlightInstanceTimeattributes of the FLIGHTINSTANCE table will be updated. Be honest, Mary. Tell mehow much longer it would take you to implement this with your current tools. You’dmanually make this join. Really, it’s best to keep talking in a high level. Think aboutwhat would happen to your implementation, which most likely will require you toname tables, if you moved the FlightTotalCapacity attribute from FLIGHT toFLIGHTINSTANCE. Here, you don’t need to change anything at all. You just regen-erate this object for GeneXus to infer the new navigation, and that’s it!”

“I see your point. How do you insert and delete records from the database?”

“Well, the For each command allows you to run through a database table andaccess its extended table not only to read but to update attributes. For this reason,it’s a very important command. It can be used not only in procedures but in everyGeneXus object that supports procedural code (such as transaction and web panelevents). For additions and deletions, two new commands have been created: Newand Delete.”5

“Now that I think about it, the procedure doesn’t control the same as theFlightInstance transaction: advancing a flight’s departure date and time is not al-lowed. I remember there was an error rule that prevented it,” Mary said.

“You’re right...” he nodded. Something was obviously on Diego’s mind, andMary looked at him expectantly. He fell silent for a few seconds and finally said, “I’llhave to add this control to the procedure by asking with an If command beforeupdating. Every time I change the date and/or time of an actual flight, in anyobject, I’ll have to redo the same control of the transaction rule, repeating the codeover and over. I may make a mistake or skip it altogether...”

5 Referential integrity is not checked in any case, allowing users to enter records pointing to nonexistentrecords, or to delete records pointed by other records, thus orphaning them. Only uniqueness ischecked. These are programmatic controls, as GeneXus enables referential integrity checks at theDBMS level, where controls will always be made.

96

A sure and easy way:the “what” of Business Components

“Since we know,” he continued with renewed energy, “that transactions areone of the most important objects, because that’s where users’ views, businessrules and formulas are gathered, and the uniqueness and referential integrity con-trols are executed, what would you say about reusing them from any other GeneXusobject?”

“Huh?!” the look on her face made Diego laugh.

“That’s right, reuse them, drawing on all the knowledge they’ve incorporated.For example, if I had a way of encapsulating all the logic of the FlightInstancetransaction, disregarding the interface… that is, if we could have a buffer or some-thing, a temporary structure, like, for instance, a composite, structured variable,where all the data (header and lines) of an actual flight could be loaded… I couldenter it into the database from any object… If the transaction’s logic were reallyencapsulated like that, the insertion would only be allowed if all the conditions forentering that same information through the transaction were met… What I meanis: if I wanted to insert a flight instance associating a nonexistent flight(FlightNumber) to it, or tried to add a nonexistent passenger, it would fail and Iwouldn’t be allowed to make the insertion, just as would happen in the transaction.Or, for example, if I want to add a passenger that actually exists but whose incor-poration exceeds the flight’s capacity, it won’t allow me to perform that insertion,just as it wouldn’t allow me to do it through the transaction, as I have an error rulein the transaction,” Diego explained as he opened the FlightInstance transactionand showed Mary the Rules section.

You, dear reader, can look this up in the previous chapter. So, it’s possible toencapsulate the transaction’s logic, retaining the structure, but discarding the form:it’s called Business Component. It is a data type that GeneXus generates buildingon a transaction.6

“And how do you go about encapsulating all that?” Mary asked. “How do youuse it?”

6 Business Components are obtained from transaction objects, but they can be used from any otherGeneXus object to add, delete or modify data in their tables.

97

“With the transaction you want to use in this other, ‘silent’ way, all you haveto do is change the value of its Business Component property to ‘True.’ Once yousave this change, GeneXus will create a new Business Component data type, whichwill have the same name as the transaction.”

“But how do you use it?” she asked again, intrigued.

“Through variables based on that data type. Every time you want to update,add or delete a flight instance, instead of using For each, New, and Delete, you’ll beable to use all the possibilities provided by the FlightInstance transaction, throughthe properties and methods of a variable based on the FlightInstance data typegenerated by GeneXus. Let’s change our last procedure to perform an update througha Business Component,”

Diego went on with his monologue, while Mary waited expectantly, withoutspeaking. “We need a variable, &FlightInstance, of the data type generated whenwe switched the Business Component property to ‘True.’ In it, we will put all thecontent of the flight instance that we want to change. This variable will naturally bestructured; it will be the ‘buffer’ where we’ll temporarily have the data of the flightwe want to manipulate at a certain time. The code will look more or less like this …”he said, replacing the two direct assignments in the object with the four sentenceswe see in the image below. “Note how here we only use the For each command torun through the base table and to filter, but we don’t update directly.

98

“See? The first thing I do here is load from the database the flight instance tobe modified, in the &FlightInstance variable, according to the FlightInstanceId valuecorresponding to the record that met the filter conditions in the For each command(it’s the record of that iteration). Next, I change only the data that we need tomodify, and then I save, using the Save method. To edit a flight through the trans-action, you’d have placed the identifier in the form’s FlightInstanceId field, andthen you’d have left the field. To do that with the Business Component, we use theLoad method. In the transaction, you’d have changed the values of theFlightInstanceDate and FlightInstanceTime fields in the form, and then clicked [Con-firm]. And in this case? You change the values in the variable, and then run theSave method. What you’ll have as a result is practically the same thing. I mean,what would happen if in the transaction you changed the flight to an earlier dateand time?”

“The error you programmed as a rule would be triggered, and it wouldn’t letus save. That is, the change you wanted to introduce in the record wouldn’t bemade. The record would be left as it was.”

“Exactly. And what do you think will happen here, in the procedure?”

“The… same thing?” she asked.

“Right! The same thing! The rule will be triggered, and as its condition will bemet, it won’t allow you to save the change.”

“And how will I know what happened?”

“Well, in the case of the transaction, since it’s an interactive object, there’s nodoubt there. A Business Component, however, is not interactive, so any messagesand errors resulting from the processing (executing the Load and Save methods, oreven the Delete method) must be stored somewhere. GeneXus places them in acollection (list) of messages associated to the corresponding Business Componentvariable, and you can retrieve this list with a method (GetMessages). Then you canbrowse this list of messages… But if you only want to know if any errors occurred,you have the Fail method, which returns a ‘True’ value whenever there’s an error.So, in our case, you’d write ‘if &FlightInstance.Fail()…’”

“I get it,” Mary said. “And what other errors can occur when you’re manipulat-ing data with a Business Component?”

99

“The same as when you try to insert through the FlightInstance transac-tion. That is, referential integrity (if you tried to change the flight, FlightNumber,which is a foreign key, for one that doesn’t exist), uniqueness (if you wanted toinsert a new flight instance, and you assigned it a FlightInstanceId that alreadyexisted for a different record), data type validations, error rules declared in thetransaction and whose triggering conditions were met…”

“Of course! In this sense, it’s safer to have a procedure using a BusinessComponent. Besides, that way you know that all the business rules are going to betriggered without having to repeat them.”

“All of them?” Mary asked. “If you don’t keep the visual interface, what hap-pens if the transaction has a rule that triggers a call to a web panel, for example?”

“Well, ok, not all of them… GeneXus ignores any rules in the Business Compo-nent that employ user interfaces. The rule you describe won’t be included.”

“Interesting…” she said.

Where do you want to go with this?Tempting attractions… in PDF format

If you’ve been paying close attention, you’ve probably realized the samething Mary did:

“Among the selectors of the Procedure type object there’s a ‘Layout’ selector.What’s it for? Can a procedure allow you to make a visual output?” she asked.

“Actually, it can. As it happens, one of the requirements our users haveincluded in their specifications is that the travel agency’s site should have apage showing attractions per city, and a link of the type ‘View as PDF.’ To dothat, I created a procedure, which I’ve called AttractionsPerCity. Look,” Diegosaid as he opened the object in his notebook and selected Layout.

“I’ll have to tell this procedure that it will have a PDF file as its output. The ideaof the Layout is to declare what I want to have in the output. As a result of theexecution, I want to display for each city, all the attractions it has. The user will

100

obviously have to have Acrobat Reader installed, in order to open from the browserthe PDF file that is generated. To indicate what is to be displayed in the output, andthe format it will have, the Layout contains print areas, which are controls calledprintblocks. In color in the figure, you can see where two of these controls start:City_Block and Attraction_Block. I gave them those names after I added each con-trol. Inside each printblock you enter the information (attributes, variables, images,lines, boxes, etc.) that you want to display in that data area, when it’s invoked fromthe code. For example, note how in City_Block I’ve included the CityId and CityNameattribute controls, because that’s the information I want to display in the list for eachcity.”

“And with that little bit of information GeneXus already knows what to list andhow?”

“Whoa! Mary, hold on. You can’t expect it to do magic! With what we’veentered so far, it can’t know how you want to list the information. We still have toget to the code,” Diego said, raising his eyebrows with a playful look on his facethat made his friend blush.

“Well, you make it sound so great… it wouldn’t surprise me if it could readyour mind.” They smiled at each other.

101

“Can you read my mind?” Diego ventured, moving forward.

“How about you tell me?” Mary returned, staring straight into his eyes.

“Your wish is my command!” After a brief silence, he began again. “I want torun through two tables: COUNTRYCITY and ATTRACTION. For each COUNTRYCITYrecord, I want to go through all the related ATTRACTION records, that is, all therecords corresponding to that country-city. This entails using the two nested Foreach commands.”

Mary moved her chair closer to his, took the mouse from his hand withoutasking his permission, and, smiling all the while, clicked the Procedure selector.The window changed, and showed the following code:

Diego continued:

“Note that you don’t need to set the filter by city for the second For eachcommand: that’s because there’s a direct 1-n relationship between the tables thatare run through, and this is one of the most common cases of nestedFor each commands. The base table of the external For each commandis COUNTRYCITY, and the one for the internal For each command isATTRACTION (because of the attributes of the printblocks involved), and as GeneXusknows the relationships between the tables, it implicitly applies the restriction overthe records to be retrieved. But it’s more powerful than that: it also finds indirect 1-n relationships. For example, if you wanted to list, for each airline, the number offlight instances.”7

7 Between the AIRLINE and FLIGHTINSTANCE tables there is an indirect 1-n relationship (with the FLIGHTtable as intermediary). GeneXus finds indirect 1-n relationships in many other cases and makes the join.

102

Mary didn’t utter a word. She just looked at the screen. Still smiling, sheright-clicked the procedure Tab and selected ‘View Navigation’ from the contextmenu. Diego was looking at her. A new Tab appeared on the screen, with thefollowing window:

“See what I mean? It’s restricting the search,” he explained to Mary, who justwatched and smiled. “This is indicated by the navigation filters of the ATTRACTIONtable in the second For each command. Note the “@.” It’s indicating that it takesthose values from the context. What are the values for @CountryId and @CityId?The ones from the record of the first For each command it works with in thatiteration. These are intentions that GeneXus does discover.”

Diego went on:

“You can also tell it to send the output to some printer within reach of thecomputer running the browser with the application.”

Finally, Mary broke the silence: “Paris looks tempting… Why don’t you comeover to my place for dinner tonight? And you can tell me more about it…”

103

Chapter 6Winds of Change

Straightening up the house: Categorization

That night, Diego brought the wine. And his notebook. The music playing in thebackground created an extremely cozy atmosphere.

“You have to keep your promise,” Mary demanded, smiling, as she filled herwine glass. “Tell me more.”

“About GeneXus? Well, I don’t know what to tellyou…” he seemed nervous, but immediately got holdof himself. “Today, for instance, I was categorizing theobjects of the KB. I don’t know if you remember, butthe IDE has a panel in the KnowledgeBase Navigatorcontainer called Category View, which displays a treewith all the objects that you’ve classified, under theirrespective categories. Hold on, I’ll show you,” he putthe notebook on his knees and his wine glass on theend table near the sofa.

“I’m not sure I see the point…” Mary replied asshe sat down next to him.

“Well,” Diego tried to fill the silence while his note-book started up, “for example, in my company we usu-ally have categories to identify the status of the ob-jects: ‘Operating,’ ‘Under Review,’ ‘Under Construction.’That way, with a quick look you can see which objectsare ready to be tested, simply by opening the ‘UnderReview’ category. In this case, we divide our universeof objects into separate categories. In fact, you can

104

even name this criterion for classifying your universe, precisely with a category:‘Status,’ for example, containing these three subcategories. But, at the same time,we might want to categorize the same universe according to other criteria. What Imean to say is: you can include the same object in several different categories. Forexample, suppose you also want to organize by system, subsystem, etc. Nothingprevents your object from being in the category corresponding to a subsystem andalso in the ‘Under Review’ category in ‘Status.’ Or you can categorize objects ac-cording to whether they will be used in the application’s back-end or front-end.Categories allow us to organize and view the information in our KB according to ourspecific needs.”

“Multi-categorizing…” her eyes were shining intensely. Or at least it seemedto Diego that they were.

“When you select an object from Folder View, under the properties window,you have a container called Categories that starts with a small toolbar where youcan both add categories to the object and eliminate categories from it. But, asalways, there’s more than one road leading to Rome…”

“Today you were categorizing… that means you had to go to every object, oneby one, and assign the corresponding category to each, right? Too much work!”

“Yes,” he said, a little embarrassed. “The thing is, categories are pretty new,and I’m not really comfortable using them yet, even though it was a companydecision to use status categories. Sometimes it’s difficult to change the way you’reused to doing things. We should have created these categories from the very be-ginning, and the objects already with the ‘Under Construction’ category, so that wecould move them across categories as their status change. Today I had to straightenup the house, because the objects in the KB were getting to be too many. But I onlyhad to do this for the ‘Status’ subcategories, because the ‘To-Do Diego’ category isdynamic, and maintains itself.”

“How’s that?” Mary reached out for the wine bottle.

“In this case, as I had to straighten things out anyway, I put comments withthe text ‘To-Do Diego’ in some objects that were pending. Then I created a dynamiccategory. Dynamic categories have a search condition associated to them. All theobjects resulting from the search, become part of the category. In the search con-dition, I indicated that it look for objects with the text ‘To-Do Diego,’ and it found allthe things I have to do –quite a few, by the way…”

105

Seek and you shall find…

Another interesting feature you’ll discover in GeneXus Rocha is its capacity tofind “anything” that’s in the KB. This feature is presented in the same way as whenwe use search engines on the Internet. Based on complex algorithms, GeneXusRocha’s full-text search engine finds what you’re looking for among what could betons and tons of words contained in the objects that make up the KB. And like mostsearch engines, it allows us to use intuitive syntax to limit our searches. In thefollowing image you can see the “To-Do Diego” search…

The full-text search engine browsed the KB and reported all the places wherethe text was found. Note that on the right there’s another search proposed, but inthis case only of properties. For example, if we wanted to locate all the objects withthe Main program property set to “True,” all we’d have to do would be to write“main_program = True.”

Notice also how from this query we can create the dynamic category with thesame name, “To-Do Diego,” that Diego showed Mary above. To do so, you just haveto [Save as Category]. Maybe that’s what Diego did that day…

106

Foundation, mascara, eye-shadow…Making up the application

That same afternoon, several hours earlier, Julia was finishing up the docu-mentation in the KB, when Mike, who was doing the last of the testing remarked:

“I heard from Diego that they want to change the style of the pages. He wastoo busy with some objects he had to finish developing, so he passed that matteron to me. He told me to talk to you about it and ask you for the details.”

“Yeah, I got an email describing more or less how they want it to look, and Icopied the instructions in the Main Document’s Talk; I’ll document it properly later.They left it up to us to decide on the colors and all the rest. And I had already savedtheir logo to the KB some time ago, in the Images node. They want it to be locatedat the top of each page.”

“I can do that right now. I just have to open the AppMasterPage master pagecreated with the KB and used by default by all objects. This centralizes the headerand footer that will appear on all the site pages… then I replace the default ‘Appli-cation Header’… and it’s all set. To do ev-erything else they asked for, we shouldcall Paul, the graphic designer…”

“But Paul doesn’t know anything about GeneXus, and you’re going to let himopen the objects and modify the controls in the forms, changing the color, size, andeverything else?! If I were him, I could never understand…”

Mike laughed: “Julia, look, we should each stick to what we know. I won’t lethim touch our objects. But I need him to configure the design for each control inthe forms. For example, I need him to specify the size, background color, font, etc.,for the transaction buttons, as well as for the grids and other controls. I’d like tocentralize that so that he won’t have to touch the controls ‘in’ the objects. That’swhat we have the Theme type object for. See, here, under the Themes node inFolder View, we have one called Modern. It’s the one GeneXus associated by de-fault to our objects. If I open it, you’ll see that it’s a list, in tree format, of classesof controls (although not only).”

107

“Each control type has several possible classes. In the Button class there’s asubclass, BtnDelete, which by default inherits its properties, but which allows youto change its characteristics. If we now go to any transaction and we edit the form,in the properties of the [Delete] button we’ll be able to see the ones associated tothis class. You can change it for a differ-ent one. With this, you completely sepa-rate the behavior from the design in yourapplication. And look here, what I’m go-ing to do now is export1 the Moderntheme from our KB (we could also cre-ate a new one), send it to Paul so thathe can configure the appearance of theclasses and send it back to me, so that Ican then import it, and voila! Design applied! Paul doesn’t need to have GeneXus,just the Theme Editor, which is a utility program that only allows you to work withthese objects. It’s a specific tool for the graphic designer. Another option is to do itfrom within GeneXus.”

The Master Page and Theme object types are the most important when it comes todesigning the application’s appearance.

1 We hadn’t talked yet about exporting/importing in GeneXus. In this book we will only say that you canexport GeneXus objects and other types of knowledge from a KB, in files with an xpz extension, whichcan later be imported into another or the same KB. For that we have an option in the KnowledgeManager menu.

This is where youconfigure the designaspects for this class.

108

Tell me when and I’ll tell you how you were

Another interesting possibility offered by GeneXus Rocha is that of seeinghow objects in the KB evolve over time. That is, each object will have a historyassociated to it, which will record the changes with the date and time on which theywere made and the user who made them. With that, you can monitor an object’sevolution, starting from that object’s creation.

And what’s more: in the very near future, you’ll be able to know the realstatus that the object had in the version you’ve clicked on. In this next image…

…you can see, on the left, the content of the Latest Changes View panel, and, onthe right, the history of the FlightInstance transaction. Note how there were twochanges since the date it was created; therefore there are three version numbers.You will also be able to compare two versions and see the differences betweenthem. Powerful, right?

109

What the Oracle says…

Legend has it that certain prophets spoke of the Oracle foretelling that, re-gardless of the alignment of the stars, a new era would be coming…

The new protagonists of knowledge: Data Providers

GeneXus’ goal: that you declare, declare and declare. When you declare, yousay the what, without worrying about the how. The how varies with time. We oftendiscover new, better, and more efficient ways of implementing. The what is stable. It’sthe essence. Knowledge that enables automation. Transactions and business compo-nents used to be, then, the stars of GeneXus: they declared the business logic. Theydeclared knowledge. In each stage of its evolution, GeneXus found a how. But a newtime is dawning. A new protagonist emerges: Data Provider. For a wide range of cases,we’ll go from programming procedures, to declaring data providers.

Intelligent components, capable of processing various types of inputs, filter-ing them, sorting them, and producing some form of desired output (like a differentdata structure or a given format).

In every process we can say that we have an input, a transformation, and anoutput. In procedures, the focus is on transformation. In Data Providers what’simportant –declared– is the output.

Are you intrigued by this concept? Would you like to see an example that willgive some substance to this description? Since we like suspense, and we like to keepyou on the edge of your seat right to very end, we’re saving a more detailed discussionon this subject for the annex that comes after this chapter, if you still feel like it...

Masking desires with Data Selectors

We often find ourselves coding the same “situations” (filters and orders foraccessing the database) in different places of our application where we retrievedata, scattering the same logic (or part of it) through several different places,wasting considerable time, which in turn negatively affects our productivity. If welook at the following bits of code…

110

…and compare them, it’s obvious that different results are obtained throughthem, although with the same bit of logic: they both want to filter by Africancities (CountryWorldRegion=1), sorting them by name. The first displays justthat in the output (let’s suppose that City_Block contains the city attributes),and the second displays the attractions of the African cities in the “Safaris”category. Note the code block they have in common, formed by an order and afilter. There could be dozens of GeneXus objects where you’d need African citiesordered by name.

A Data Selector allows you to centralize and reuse navigations, thus avoiding codeduplication.

But it has more advantages. New members of the development staff are oftenunaware of the common criteria or filters of an application. For example, supposethat tourism to Africa is being actively promoted; as it usually happens, someonewho is asked for a list of cities gets one with all cities instead of only the Africanones. Centralizing these criteria greatly shortens the learning curve, allowing staffto quickly become productive and reducing the number of mistakes.

In the previous example, if we gave these common clauses a name, as if theywere a macro that could later expand… we’d have a Data Selector! A name for adata search criteria. In our case: AfricanCities.

The above procedures will now be:

111

The Using clause, which says to “use the content” of the AfricanCities DataSelector, is written to the right of the For each command; and that’s all… If wechange the criteria later on, we do so inside the Data Selector object and it’sautomatically changed everywhere!

The path of processes

People are very good at a lot of things, but in tasks such as searching for adocument among hundreds of others, being on top of when each document is due, andmaking sure the work that’s completed is channeled from one place to another accord-ing to a predefined sequence... hmmm, are we very good at that, do you think?

GXflow, a well-known Artech tool connected with automation of companyprocesses, by determining task flows, is also integrated into GeneXus Rocha. Why?Applications have increasingly more process flows, which require Workflow compo-nents.

Now you will be able to create your own diagrams within GeneXus, greatlysimplifying integration tasks, and connecting activities with KB objects more easily.

In this image we’ve designed a simpleexample that shows the process flow for flightreservations.

The reservation itself, expressed by thefirst box in the diagram, is none other thanthe start-up of the transaction it represents.

A given condition -such as, for example,if the data is correct and complete- is thenevaluated. For illustration purposes, let’s saywe have the following conditions:

Print Tickets IF FlightStatus = ‘AUTHORIZED’Get in contact with Client IF FlightStatus = ‘COR-RECT PERSONAL INFORMATION’

112

These conditions are expressed through a conditions editor. The idea is thatthey be able to express rules, where first the name of the succeeding task isindicated, followed immediately by a condition that must be met in order tocontinue down that path. Simple, practical, and powerful.

If the condition is met, the reservation ticket is printed and sent to the client.Otherwise, the flow detours to the Get in Contact with Client task, the informationis updated (most probably through the transaction corresponding to clients), andthen the flow goes back to the reservation, restarting the cycle.

Were you already a GXflow user? Would you like to see a summary of thechanges? Straight to the annex, then…

Back and Front End - Intra and Inter Net

In this book, we took the liberty of peeping into some moments of our char-acters’ lives, and that way we’ve been able to see how some parts of the applicationhave been implemented. The goal: to see a little bit of everything. But we haven’tseen the full picture. At times, we, the authors, feel a little ashamed of our voyeur-ism, and we look away, to later feel tempted again to turn our eyes back to thestory. This is why we’ve seen objects that will be used in the application’s back-end(for example, Work With objects, as the data for airlines, countries, cities, flights,passengers, etc., can only be updated by company employees, with permits, throughthe Intranet) mixed in with other objects that can be used in the application’s front-end, that is, on the web site that will be consulted by people around the world viathe Internet.

However, Diego, Mike and Julia have done more work than what we’ve beenable to see. They’ve created the home page for the Intranet, slightly modifying thehome page created by the Work With pattern. They’ve added a login section in themaster page… web panels with various queries and different menus.

In fact, that very afternoon, before his date with Mary, while Paul was given atheme to modify, Julia contacted users of the Travel Agency, and Mike finishedtesting, Diego was carefully examining how the home page of the company’s website finally looked:

113

Notice how hotel, car rental and weather information is provided. These arethird-party applications, published as Web Services that can be easily integrated(consumed) within GeneXus. At this point the reader has all the elements neces-sary to have an x-ray of the page and guess what might be behind it: a web panel,web components, master page, theme, images, controls…

However, Diego didn’t use all of that. GXportal, one of GeneXus’ technologies,enabled our friends to develop the web portal with a minimum of effort. Was itDiego who developed it? Or was it Julia?

GXportal allows you to design, manage and maintain scalable portals, without hav-ing to program. Therefore, GXportal users don’t need to have special programmingor design skills. It offers a framework for integrating knowledge, information andapplications through a portal, with the aim of bringing together the different peopleinvolved in the organization and the communities.

114

The End… or the Beginning?

So far we’ve obtained different pieces of a puzzle that you will be puttingtogether, drawing on what’s most important: your imagination.

With it, you will be discovering the remaining pieces of the puzzle in what willbe a continuous search. An unending search. The puzzle is always nearly… but notquite finished. That’s where its secret lies: in keeping us permanently in suspense,searching, thinking, imagining, changing.

“Friends, with faith, with joy, with generosity, with the synergy of thisCommunity, let’s move forward, and preserve the magic.”

Breogán Gonda, Closing Address, 16th GeneXus International MeetingSeptember 20, 2006

What do you think happened with our characters? Was the development projectsuccessful? How did that dinner with background music end? Was Mary finallypersuaded to join the Community? Pieces that are still missing, and that each willfind… like the secrets that are still brewing in the Rocha Age……

…Or could it be that this story is only just beginning?

115

Application development grows increasingly complex with each passing day; GeneXushas its own weapon to combat such complexity, and that weapon is knowledge-based development.

GeneXus has always based its work on the idea that you can generate an entireapplication by building on knowledge (and, as a by-product, maintain the applica-tion automatically). GeneXus Rocha reaffirms the full validity of that idea. In thissense, GeneXus Rocha is not just another version, it is a reformulation of theproduct, and it will be the version that captures and uses the most knowledge.Why? Because one of the key concepts that distinguishes GeneXus Rocha from itspredecessors is the extensibility architecture it was conceived with.

What this means currently is that GeneXus Rocha is not built just by Artech: theentire GeneXus Community contributes to the building process through its ownextensions.

When we say extensibility, we mean extensibility at all levels, from the capturing ofstructured or unstructured knowledge, to participation in the generated applica-tion.

The GeneXus Community, together with Artech, will be in charge of finding newmechanisms to capture knowledge, devising automated development methodolo-gies, and, ultimately, generating future applications.

It will be the Community who benefits the most from extensions (those who par-ticipate proposing extensions, developing extensions, testing them, criticizing them,using them…).

AnnexBuilding the Future

116

Extensibility: A Common Denominator

All of Artech’s products are currently being developed with the concept of extensi-bility in mind.

The GeneXus development environment (IDE), GXpatterns, products such as GXflow,GXquery, GXplorer, and Ruby generator, as well as every feature developed foreach of these products, all rest on Extensibility as one of their pillars.

Extensions refer to all of these things, and are not limited just to the developmentenvironment.

What must be achieved: that knowledge is captured the “GeneXus Way,” that is,with a clear, simple and usable way of enabling the abstraction of such knowledge.

Extensibility, Integration and Usability

In developing our new product architectures, we decided that extensibility wouldneed to have two inseparable allies: Integration and Usability.

Our extensions must be seamlessly integrated into different environments, be theythe development environment, or a batch environment.

Extensibility at the Workflow level, for example, can only be viewed as a real ex-tension if there is a true Integration of the Workflow in my development process, inthe same environment, and with a high degree of Usability.

In all likelihood only those extensions that incorporate Usability as a key aspect willbe well received by the Community.

An Extensible Environment

One of the most important features in terms of extensibility is that of the GeneXusdevelopment environment itself.

The GeneXus development environment is currently extensible through Modules,called packages, which provide a particular functionality.

The environment provides a user interface Framework, with services that enableinteractions with menus, toolbars, windows, management of user interface prefer-ences, etc., and a Universal Data Model to handle concepts such as KnowledgeBase, Model, and Versions, among others.

117

Every new package that is added to the environment defines new concepts, addsfunctionality, and enhances the user interface. GeneXus itself is implemented as apackage of this environment, adding the concepts of Transaction, Domain, Attribute,etc. GXflow adds the concepts of Business Processes; Patterns incorporates gen-eration mechanisms based on GeneXus; and so on.

Therefore, there’s no difference between what can be performed by a third-partypackage and what can be performed, for example, by GXflow, or GeneXus itself.

A package may include the following possibilities, among others:

• Defining new types of objects (for example, WebPanel, Data Provider, ActivityDiagram, etc.)

• Defining new object parts (for example, WebForm, WinForm, Variables, etc.)

• Providing new editors

• Adding menu options

• Adding toolbars

• Defining new properties for the objects or parts

• Subscribing to events

• Creating new services and consuming existing ones

Data Providers: Accessing Knowledge

When designing an application, it is crucial to conceptualize what our businesslogic will be, regardless of the architecture we plan to develop. This businesslogic applied in knowledge-based development is represented naturally throughrules.

Subsequently, with Transactions (and in particular, with Business Components)GeneXus provides a way of capturing these rules and effectively generating andmaintaining them, so that they are complied with when required. Business Compo-nents, therefore, play a major role in the construction of the Business Logic.

However, these rule application and updating components are complemented byother, essential components: those that in a sense define our application’s informa-

118

tion retrieval and presentation services, thus forming what we could refer to as theapplication’s Business Framework.

We’ll call these intelligent components –which are capable of processing varioustypes of inputs, filtering them, sorting them, and producing some form of desiredoutput–1 Data Providers. Together with Business Components, they will play theleading roles in the construction of our applications’ future Business Frameworks.

Declaring our Data Providers

Data Providers are a major step in GeneXus’ evolution, as they are new objects thatwill enable the capturing of automatable knowledge in a declarative way.

The great innovation is in the way GeneXus users will be able to express them, sothat we could say that for a great number of cases we will go from programmingProcedures to declaring Data Providers.

Being declarative in whatever you want enables you to obtain a knowledge thatopens the doors to innumerable variations in terms of generating the application’sdefinitive code. GeneXus will always tend to declare knowledge instead of pro-gramming the application, as the latter is simply an automatic step that follows theformer.

If a Data Provider declares that it wants a set of data with certain filters, that samedata can be obtained through several ways, from various sources, with differenttechnologies. If I have something that is declarative, I won’t have to worry aboutthese parameters when declaring knowledge: this will simply be a decision that isadopted later, and possibly automatically.

What is it that I declare?

In every process we can say that we have an input, a transformation, and anoutput. In Data Providers what’s important and what’s declared is the output.

As we said, by declaring the output, GeneXus will be able to evolve in such a wayas to obtain that output. When we say output, we’re not thinking solely of cases ofoutputs to a certain given format. These are, no doubt, common cases, but theyvary with time.

1 For example, a different data structure or a given format.

119

There are a number of “outputs” that are more important than these, and they areoutputs to, for example, internal components of my Business Framework.

A Data Provider that has an Invoice as input and a set of accounting entries as outputis clearly more important for my Framework than the Data Provider that generatesan RSS with the entries. The latter will surely change over time, as the RSS formatmay no longer exist, while the former is pure knowledge of how to convert an invoiceinto the corresponding entries. Let’s see this in a specific example.

Use case: entering a sales invoice into accounting records

Let’s suppose we have the following invoice for which we want to obtain a corre-sponding accounting entry.

Your accounting entry would be as follows:

Before we go into the specific example, we need to make some observations:

Firstly, the transformation is considerably complex, that is, from a two-line invoicewe need to generate a six-movement entry (four movements are fixed, and theother two vary according to the number of document lines).

120

Secondly, the problem arises in the output, so Data Providers are a natural solution.

And lastly, we’ve declared our intention, and have specified no transformationprocess; we simply declare the output.

Entry{ EntryDate = InvoiceDate EntryDescription = 'Invoice ' + InvoiceId Movements { Movement { AccountId = ObtainAccount.udp('Cash/Bank') MoveType = 'CR' MoveAmount = TotalInvoice } Movement { AccountId = ObtainAccount.udp('Debtors') MoveType = 'DB' MoveAmount = TotalInvoice } Movement { AccountId = ObtainAccount.udp('TAX') MoveType = 'CR' MoveAmount = TotalInvoice * 0.20 } &MoveAmount = 0 Movement { AccountId = AccountForProduct.udp(ProductId) MoveType = 'DB' &MoveAmountItem = ProductCost.udp(ProductId) * InvoiceLineQuantity &MoveAmount = &MoveAmount + &MoveAmountItem MoveAmount = &MoveAmountItem } Movement { AccountId = ObtainAccount.udp('SaleCost') MoveType = 'CR' MoveAmount = &MoveAmount } }}

This declaration is very simple, but that doesn’t make it less powerful in the DataProviders. Notice that the example uses formulas; you could also use filters, differ-ent types of outputs, and many other things that make Data Providers simple andpowerful objects, something that is very difficult to achieve simultaneously.

121

The Path of Processes

GXflow, a well-known Artech tool connected with automation of company processes,by determining task flows, is also integrated into GeneXus Rocha.

Why? Applications have increasingly more process flows, which require Workflowcomponents.

What is accomplished by this approach?

• Process modeling is part of the KB, which means it adds more high-levelbusiness knowledge in the KB itself.

• When modeling business rules through transactions and other objects, it isnot necessary to know beforehand whether they will be used or not in aWorkflow process.

• When dragging an object to a GeneXus activity diagram you’re guaranteeingthat that object will be invoked by the engine with no additional program-ming required.

• You can express conditions through an editor that enables you to describe thetransaction rules based on the relevant attributes and data defined for theprocess.

• All the cross-reference functionalities are available, as the diagrams are justanother object of the KB.

• The GXflow Prototyper will enable quick diagram execution, so as to incre-mentally perform the prototyping. That is, as the diagram is formed, the<F5> key can be used to execute, at which point it will trigger everythingnecessary to execute the diagram, from the impact of the process on themetadata to the generation and compilation of the objects associated to it.

• The GXflow engine and client will be components that are external to the KB,and thus they will not weigh on the KB building process.

And what about queries?

We will add the capability to express within the Knowledge Base queries that canbe used in any object, whether you want to display the data returned by the queryas a pivot table or a chart, or simply read it through. An interface will be providedfor this, to help create queries in the KB, where users will only have to select theattributes (data) they wish to retrieve, and they will be presented with the corre-sponding results.

“I have to admit that, at first, the informal tone of the book took me bysurprise. After reading it carefully, I see that the “informal tone" isanother of the many great ideas that the authors have had. In myopinion, this book is a great contribution to the knowledge of the RochaVersion and the huge change it represents, so that the GeneXusCommunity can prepare for its launch in 2008."

Breogán Gonda, EngineerArtech President

Diego and Mary run into each other after many years. Long gone are thedays and nights of studying, laughing and talking in the classrooms andhallways of the School of Engineering, when Mary was always so full oflife and Diego would let himself be carried away by her laughter. Untilthe chance meeting shakes the dust off that memory... and Diego happilyfinds himself able to help his old friend solve some big problems at workand get back to being the cheerful, outgoing woman he knew (andloved?) so long ago.

Diego, Mike and Julia have three weeks to develop a web application fora travel agency, including the application's back-end and front-end.Mary is going through a difficult time professionally; she's a projectmanager who is so overburdened by maintenance chores that it'saffecting her health.

GeneXus is the thread that interweaves the characters' journeys throughthese pages. Discovering and showing. Showing and discovering. Overand over again: the Rocha Version.

EpisodeO

ne

Episode One

Cecilia Fernández is GeneXus instructorand has worked in Artech's TrainingDepartment since 2001. She teachesGeneXus courses in Uruguay and abroad,writes manuals and creates distance-learning courses. She attended the Schoolof Engineering, University of Uruguay, andis currently pursuing a Bachelor of Arts inLiterature at the School of Humanities andEducational Sciences.

Daniel Márquez Lisboa, is a GeneXusanalyst, technical writer and consultant, aswell as a freelance writer, who hasdeveloped large systems in GeneXus andother languages. He has authored or co-authored four books, including "GeneXusKnowledge-based Development," whichwas presented at the GeneXusInternational Meeting in 2006.