customizing domino web access to fit your needs

© 2006 Wellesley Information Services. All rights reserved.

Customizing Domino Web Access to Fit Your Needs

Rob NovakSNAPPS

2

What We’ll Cover

• Introducing Domino Web Access customization• Understanding Domino Web Access architecture• Customizing look and feel with skins• Customizing and adding features• Administering changes to DWA

3

What We’ll Cover


4

But First, a Word From IBM…

• Which looks suspiciously like the iNotes Deployment Guide statement (circa 2000):

“The ability to customize iNotes Web Access…was not one of the design goals for this release. As such, customized templates are neither certified nor supported…”

• Like any of that is really going to stop us!

5

Why Consider UI Customization?

6

Domino Web Access Customization

• Languages and skillsHTML: IntermediateCSS: IntermediateJavaScript: Intermediate - ExpertDomino architecture: Intermediate – ExpertGeneral hacking: Expert

• IBM support for UI customizationR5 iNotes: Nonexistent … LS2002 (SNAPPS)ND6: Reluctant admission … unsupported tool … LS2004ND7: More exposure via file resources … still unsupported …But an IBM RedPaper was written!

7

Domino Web Access Customization: Difficulty Scale

• Overall level of difficulty?R5 iNotes:

DWA in ND6:

DWA in ND7:

Novice

Novice

Apprentice

Apprentice

Expert

Expert GURU!

GURU!

Novice Apprentice Expert GURU!

8

What We’ll Cover…

• Introducing Domino Web Access customization• Understanding Domino Web Access architecture• Planning for customization – considerations and

caveats• Customizing look and feel with skins• Customizing and adding features• Administering changes to DWA

9

DWA Architecture

• Like any Domino application, DWA is comprised of forms, views, and design elements

• The DWA template inherits from the mail template to give the user their Notes Mail experience

• The user’s mail file inherits from the DWA template and references the formsx.nsf database for DWA forms

Late-bindingUses a very unfamiliar naming schemeCompiles forms based on proxy documents

• Most customization work is done in this formsx.nsfdatabase

10

DWA Architecture (cont.)

• A small number of design elements reside in the dwax.ntf or iNotesx.ntf templates:

Standard views and foldersTasks View named (Haiku_TasksAll)TOC views named (Haiku_TOC) and (iNotes_ArchiveTOC)Proxy document view named (iNotes)Meeting Notices view named (iNotesNotices)Contacts View named (iNotes_Contacts)Notebook View named ($Journal)

One agent – Synchronize Journal• Unlikely you’ll ever touch any of these

11

DWA Architecture (cont.)

• Formsx.nsf – the shared forms database• Found in the <domino data>\inotes\ subdirectory• Contains the following:

Forms and SubformsGraphicsJavaScriptSkins (HTML and CSS files used to define the general layout of pages) Forms Map Table (maps Notes forms to corresponding Domino Web Access forms)

12

DWA Architecture (Geek out in the icon note!)

• DWA-based mail files – and the DWA template itself –maintain a special relationship with the formsx.nsfdatabase

• This relationship is maintained with field values in the design element of the icon note:

A catch-all repository used when exposure to server processes is needed at the database levelA place where IBM can put random settings to make it as difficult as possible to find, interpret and change

• For DWA, the icon note values are:$HaikuFlags$WebHybridDb$FormsTemplateFile

13

DWA Architecture: Anatomy of a DWA Page

1. A request is made of the server for a DWA database2. The server inspects the icon note for the presence of

$WebHybridDb (value of 1) and if it’s there, goes down a new code path to start treating the database like DWA instead of a plain old Domino web application

3. This code path inspects the icon note again for the location of the forms database ($FormsTemplateFile) and starts the process of reading design elements from that source for layout and presentation

4. DWA generates pages on demand – also called late-binding – based on a combination of standard HTML/JavaScript and proprietary tags

14

DWA Architecture: Anatomy of a DWA Page (cont.)

• The late-binding forms, subforms, images, JavaScript, and custom tags do their thing:

Insert skinsInsert skin components (more on this in a moment)Insert subformsEvaluate compiled custom @formulasDetermine persisted and computed-only items

• In the background, the server also has picked up any server-wide settings from notes.ini and configuration documents and applied them during rendering

• See? Easy! Right.

15

DWA Architecture: Anatomy of a DWA Page (cont.)

• The main form used from formsx.nsf is h_PageUI• Almost all “main pages” use this form and its subform

calls – here it is represented in a URL:http://mail.snapps.com/mail/rview.nsf/($Drafts)/$new/?EditDocument&Form=h_PageUI&PresetFields=h_EditAction;h_New,s_NotesForm;Memo

• Some pages, notably dialog boxes, do not use h_PageUIbut a custom DWA-specific form:

http:// mail.snapps.com/mail/rview.nsf/iNotes/Proxy/?OpenDocument&Form=s_DeliveryOptions

16

DWA Architecture: Scene One, You’ve Scene Them All

• During rendering of all h_PageUI – based pages, a skin component loads that brings in a “Scene” – the instructions for DWA to render pages based on a set of rules that build as the page builds

• DWA uses common read and edit scenes for almost all renderings, making it possible to share code and markup among many different pages

• The “scene” in use and its “subscenes” define the subforms to be pulled in for various page renderings, such as the calendar or inbox

17

DWA Architecture: Skinny Dipping

• Skins define the layout, HTML and CSS for a DWA page• They follow a hierarchy and are defined based on

documents in the formsx.nsf database:Skin Group (called via h_ShimmerSkin)Skin Type (or just Skin)

h_ListFolderh_Edith_Pageh_MailPageh_Portal

Skin ComponentsToo many to list…

18

DWA Architecture: Mapping the Forms

• A forms mapping document (the form for which is creatively called “FormsMap”) in formsx.nsf exists for mapping Notes form names to DWA form names

• A view in the formsx.nsf database System\Forms lists all of the out-of-the-box forms and their equivalents, as well as the standard read and edit scenes for each

19

DWA Architecture: Special Tags

• Server-side tags tell the DWA “engine” to do specific things:

<InsertNotesSubForm Name=SubFormName><QuickPlaceSkin><QuickPlaceSkinComponent Name=xxx>

• Please, suspend your confusion…I’ll get to that QuickPlace stuff in a second

• Extensible tags include two ways of calling a special set of @DbCommands called the “Haiku” commands:

@DbCommand(“Haiku”; “Command Name”; arguments)<dwa:command [arguments] />

20

DWA Architecture: URL Arguments

• Special URL arguments are used to control environment settings and the context of how documents are displayed:

Form overrides using &Form=Default field values using $PresetFields=&CacheResults&MaxExpires&TimeStamp&ui (a short but powerful little argument)&unh

21

What We’ll Cover…


22

DWA User Interface Customization: Roots

• Historical perspective: It’s a hack; there’s no better way to describe it

• Resources: IBM RedbooksiNotes Web Access Deployment and Administration (Chapter 6)Customizing DominoWeb Access RedPaper(July 2006)Customizing QuickPlace RedBook (2001)Dirty little secret!

23

QuickPlace, the Grandfather of DWA

Why not? The architecture for late binding had been perfected in QuickPlace, and since nobody would ever see it who cares?

<QuickPlaceSkinComponents>

More field names, these ones built after the QuickPlace h_ fields had been pilfered and reused.

s_Anything

The original code name for iNotes Web Access, because compared to WebMail, the new interface would “Shimmer” and shine. Nobody would ever want to customize it.

Shimmer

Field names and variable values related to the original architecture of QuickPlace, where h_ fields were used (related to the Haiku code name)

h_Anything

The original code name for QuickPlace (not the original product name). Still very prevalent throughout the codestreamfor QuickPlace and DWA.

Haiku

24

Quick Side Note: QuickPlace Skins

• Something important to consider before embarking on a customization project for a product that doesn’t support it…

• Find one that does, in our case QuickPlace, and understand how it has been enabled (demo)

• Next, make a lot of noise with IBM and let them know this capability is very important for DWA too!

25

Very Important Slide Before you Start

26

DWA Skin Customization: Components

• For a truly customized experience, there are several areas that must be modified (and one sort-of-unrelated)

Style Sheet (CSS)h_ShimmerSkinForms and SubformsNew Skin ComponentsCustom login screen (this is the unrelated one – but good practice)

27

DWA Skin Customization: CSS

• First you need some tools• Tools to see which style is associated with a particular

HTML elementWeb Developer or DOM Inspector – FirefoxDeveloper Toolbar – IEPlug-ins – IE7

• Tools to work with CSSBradbury TopStyleAdobe DreamWeaver 8+Notepad derivatives

• The DWA CSS has 3412 lines…knowing where you want to start is pretty ‘important’

28

DWA Skin Customization: CSS (cont.)

• What do you change in CSS?ColorsBackgroundsFontsSizes

• Where?Data\iNotes\Forms7.nsf: Shared Resources Files h_ShimmerSkin-h_StyleSheet

• How?Export to a .css named file, then edit with your tool of choice, then Refresh from the file

• Demo

29

DWA Skin Customization: CSS (cont.)

• For Firefox, do that same thing but with:Data\iNotes\Forms7.nsf: Shared Resources Files h_ShimmerSkin_Gecko-h_StyleSheet

• You can typically ignore:h_ShimmerSkin_ACC-h_StyleSheet (Accessible, not used)h_ShimmerSkin_UB-h_StyleSheet (Unsupported browser)

• CSS tip – if something isn’t working try using the “!Important” CSS tag, it places precedence on a style even if it’s called twice

30

DWA Skin Customizations: Layout Files

• Various layout files are used in different parts of DWA for arranging presentation at a high level

• To know which one you’re using, view source on the page and search for:

h_CurrentSkinNameh_CurrentSkinType (and optionally h_SkinTypeOverride)

• Concatenate these values and go find the matching file resource to makechanges

31

DWA Skin Customizations: Forms and Subforms

• Review: CSS defines styles to be used in the HTML and JavaScript throughout skins and formsLayout HTML is high-level design, or placement of DWA componentsForms and Subforms contain the code to perform specific display and edit actions in those placesCaveats:

DWA subforms are not as “modern” as QuickPlaceDWA subforms are hard to read as they are unformattedDWA has not de-obfuscated all of their JavaScript variables

32

DWA Skin Customizations: Forms and Subforms (cont.)

• Some interesting customizations include a new logo and changes to overall colors (why this isn’t in the CSS I don’t know)

• Logo:Add a new file resource something close to 210x26Open the Custom_Banner subform and re-write it to point to your new image<script>SV('<div id="ProductLogo"><imgalt=“My Corporate Logo.." title=“SNAPPS" width="260“ height=“26" src="'+BYp(“snappslogo.gif")+'"></div>');

</script>

33


• Overall color scheme:Open the s_SessionInfo form and find the sTmp2 arrayThis is a list of HTML colors that maps to 15 areas in DWAA list of the mapped values is in the DWA 7 Customization RedPaper, for example we know that Highlighted Text is in position 3 (starting with 0):

var sTmp2="#dee3ef, #adc3d6, #336699, #ffffff, #e0e0e0, #000000, #ffffff, #e8e8e8, #eff3f7, #cc3300, tan, darktan, #999999, #f6f3e2, #dee3ef";

We can change this to whatever we want here:var sTmp2="#dee3ef, #adc3d6, #336699, #cc3300, #e0e0e0, #000000, #ffffff, #e8e8e8, #eff3f7, #cc3300, tan, darktan, #999999, #f6f3e2, #dee3ef";

34


• Other kinds of form and subform changes? The options are not limited…

Showing and hiding features based on role membershipAdding mail quota calculations to the front endAdding header information for pagesOverriding default behaviorsetc. etc. etc.

• Best practice – when modifying forms and subforms, use a new color for new code

• Note: Using HTML comments may not always work to hide old code, especially in JavaScript – the DWA engine processes before the browser gets hold of it!

35

What We’ll Cover



36

DWA Feature Customizations

• Now that you have an understanding how CSS, File Resources, Forms and SubForms work, you can start to imagine how to add new features to DWA

• Examples might include:Creating a new menu item to perform a new functionOverwriting a current menu item to capture information before proceedingRemoving actionsAdding new forms (similar to Notes “store form with document” for sending mail!)

• Demo: New form

37

What We’ll Cover



38

Administrating Changes to DWA

• Really two topics – administering changes (that developers need to know about) and administrativechanges or customizations

Providing different DWA experiences for different audiences on the same serverNotes.ini settingsDWA redirect database customizationLogin form customization

39

Administrating Changes to DWA: Different Experiences

• Code can be used to change the forms file being used by a mail file:Sub Initialize

Dim sess As New NotesSessionDim db As NotesDatabaseDim agent As NotesAgentDim doc As NotesDocumentDim item As NotesItemDim n As StringSet db = sess.CurrentDatabasen = "FFFF0010"Set doc = db.GetDocumentByID(n)Set item = doc.ReplaceItemValue("$FormsTemplateFile", "iNotes/Custom7.nsf")Call doc.save(True,True)

End Sub

40

Administrating Changes to DWA: Different Experiences (cont.)• Assuming a new formsx.nsf file is created for

customizations, it can be made into a “valid” forms database with a notes.ini setting:

iNotes_WA_FormsFiles=iNotes/Custom7.nsf,iNotes/Forms7.nsf• The default forms file can also be changed with a

Notes.ini setting:iNotes_WA_DefaultFormsFile=iNotes/Custom7.nsf

41

Administrating Changes to DWA: Notes.ini

• With DWA 6, several notes.ini settings were moved to the Configuration document

• Others remain, and are necessary for coexistence on the same server (mostly related to Sametime awareness)

• I’ve compiled a color-code chart for all versions of the configuration document – use as you like!

42

Resources

• RedPaper 4188: Customizing Domino Web Access 7ftp://www.redbooks.ibm.com/redbooks/REDP4188

• Deploying iNotes Web Access 6 RedBook• Customizing QuickPlace RedBook• Tools for development:

NotesPeek or MartinScott® MoteMan™Firefox ExtensionsIE Web Developer toolbarBest-of-breed HTML and CSS editors, although you CAN use just Domino Designer!

43

7 Key Points to Take Home

• DWA is getting “better” at allowing customization – it’s not quite to where QuickPlace is yet, but keep asking IBM

• Familiarize yourself with the architecture, it will seriously impact how long it takes to find and customize a DWA element

• Over-think the issue before tackling new subforms; there might be an easier way to accomplish your goal

• Copy, paste and steal wherever possible

44

7 Key Points to Take Home (cont.)

• ALWAYS back up forms7.nsf before starting any work! You may have to revert at a moment’s notice

• Use the free developer tools and inspectors for Firefoxand IE – they will save a lot of time figuring out what you need to change, and where you need to change it

• Consider the external factors for a complete branded UI experience – Portal themes and skins, QuickPlace custom themes, a custom login form, and a custom DWA redirect database. It all reflects on your company or client’s experience with Lotus products

customizing domino web access to fit your needs

Business

customizing domino web

needsrob novak snapps

wellesley information