Working with UI Page Libraries
Contents
Overview
In Lianja App Builder, Pages can be saved in a Visual Page Library (.vpx) as reusable UI Page components.
This provides developers with the ability to lay out pages in the Pages Workspace (with all of the power and functionality of related sections) and reuse these pages in dialogs and desktop navigation Panels.
- Create a Page
- Save it to the Pages Library
- Reference the Page from another App
The screenshot above shows an example of a UI Page in the 'Lianja Demo' App (lianjademo) called with the following code in the Customer section Custom section menu delegate.
Lianja.showDialogPanel("Customer List", "customerlist")
The customerlist Page was created in the ui_mypagelibrary App, then saved to the Pages Library.
Web/Mobile
From v9.1.4 Lianja supports the use of custom UI page libraries in Web/Mobile as well as Desktop.
- These should have JavaScript specified as their scripting language and the page name must be unique in your App.
- Always name your pages with a meaningful name, e.g. pagelibCustomers. This prevents conflicts of page names and delegate names.
- The page name(s) must be specified in the Page libraries App Setting, as shown below.
- For Web/Mobile Apps, prior to Lianja v9.1.4, the Page should be saved to the App UILib as detailed below.
Saving to the UI Page Library
When creating a Page to be saved to the Pages Library, it must be given a unique name, i.e. one not shared by another Pages Library Page.
Pages are saved as '.vpx' files in the pages sub-directory of the library. They can be viewed in the Library workspace, where they are listed in the 'Page Library Files' category in the Library Files tab in the App Inspector. Double-click a '.vpx' file to view the Page.
Click the Headerbar toolbutton Save in the Page Library to save the Page.
As shown above, you can also check the 'Autosave in Page Library' Page Attribute to automatically save that page to the UI Page Library when an App is saved.
Custom Event Delegates
The customerlist Page from the ui_mypagelibrary has a Double Click delegate, defined as an Inline Delegate calling two chained showdocument() actions to perform a search on the customers page, then hide the dialog:
$("page:customers?action=search&text={customers.companyname}||hidedialogpanel")
Where delegates are defined as procedures or functions in a Custom library, the Custom library should be called from a shared location, i.e. the Library, or the Pages Library.
To specify this, add the appropriate prefix to your Custom library name:
Library:
| Custom library | lib:/lib_customerlist_section.prg |
Pages Library:
| Custom library | pagelib:/lib_customerlist_section.prg |
The Custom library then needs to be added to the specified location. This can be done in the Files tab in the Apps Workspace from the Additional Commands:
or from the Context Menu (right-clicking in the App Files panel displays the files context menu):
Using UI Page Library Files
UI Page Library files can be displayed in dialogs, dialog panels, dialog pages and Page navigation panels.
App Setting: Page libraries
To use custom UI page libraries in Web/Mobile Apps (supported from v9.1.4), the Page libraries App Setting must contain the name or comma-separated names of the library/libraries.
Click the [...] button to display a popup of available UI page libraries to choose from:
As shown above, the example_webapp1 App included in the App Builder distribution has the Page libraries App Setting set to:
my_ui_customerlist
showdialog
On the desktop client, the showdialog action or the Lianja.showDialog() method can be used to pop up a dialog with an embedded Page from the UI Page Library.
Lianja.showDocument("showdialog:page?title=cTitle
[&width=nWidth]
[&height=nHeight]
[&buttons=lButtons]
[&ontop=lOntop]
[&modal=lModal]
[&action=cAction]
[&text=cText]
[&resizable=lResizable]")
This can also be used as an Inline Delegate:
$("showdialog:page?title=cTitle
[&width=nWidth]
[&height=nHeight]
[&buttons=lButtons]
[&ontop=lOntop]
[&modal=lModal]
[&action=cAction]
[&text=cText]
[&resizable=lResizable]")
The Lianja.showDialog() method pops up a standard dialog and embeds the specified page from the page library into it.
Lianja.showDialog(title as Character,
page as Character
[, width as Numeric
[, height as Numeric
[, buttons as Logical
[, ontop as Logical
[, modal as Logical
[, action as Character
[, text as Character
[, resizable as Logical]]]]]]]]
Note: Prior to v6.0, when using Lianja.showDialog() on the web/mobile client, the page must be a .rsp or .jssp script. From v6.0, App UILibs are supported and allow embedded pages to be displayed.
Examples
// Display the 'ui_employees' page and search for 'Davolio' Lianja.showDocument("showdialog:ui_employees?Find Employee&; width=460&height=460&buttons=.T.&ontop=.T.; &modal=.T.&action=search&text=Davolio&resizable=.T.") // or Lianja.showDialog("Find Employee", "ui_employees", 460, 460, .T., .T., .T., "search", "Davolio", .T.)
// Display the 'ui_employees' page and add a new record for editing Lianja.showDocument("showdialog:ui_employees?Add Employee&width=460&height=460&buttons=.T.&; ontop=.T.&modal=.T.&action=add&resizable=.T.") // or Lianja.showDialog("Add Employee", "ui_employees", 460, 460, .T., .T., .T., "add", "", .T.)
showdialogpanel
On the desktop client, the showdialogpanel action or the Lianja.showDialogPanel() method can be used to slide in a dialog panel with an embedded Page from the UI Page Library.
Lianja.showDocument("showdialogpanel:page?title=cTitle
[&width=nWidth]
[&action=cAction]
[&text=cText]")
This can also be used as an Inline Delegate:
$("showdialogpanel:page?title=cTitle
[&width=nWidth]
[&action=cAction]
[&text=cText]")
The Lianja.showDialogPanel() method slides a dialog panel in from the right of the main window and embeds the specified page from the page library into it. If width is a negative number, the dialogPanel will slide from the left.
Lianja.showDialogPanel(title as Character,
page as Character
[, width as Numeric
[, action as Character
[, text as Character]]]
Note: Prior to v6.0, when using Lianja.showDialogPanel() on the web/mobile client, the page must be a .rsp or .jssp script. Specifying a width of "100%" will animate the dialog panel in place and it will occupy the whole page viewport on the web/mobile client. From v6.0, App UILibs are supported and allow embedded pages to be displayed.
Prefix the page specification with '-' to disable the default 'Done' and 'Cancel' buttons, e.g. '-page:page5'.
Examples
// Display the 'ui_employees' page and search for 'Davolio' Lianja.showDocument("showdialogpanel:ui_employees?Find Employee&width=460&action=search&text=Davolio") // or Lianja.showDialogPanel("Find Employee", "ui_employees", "search", "Davolio")
// Display the 'ui_employees' page and add a new record for editing Lianja.showDocument("showdialogpanel:ui_employees?Add Employee&width=460&action=add") // or Lianja.showDialogPanel("Add Employee", "ui_employees", 460, "add")
showdialogpage
The Lianja.showDialogPage() method animates a dialog page over the whole Page viewport.
Lianja.showDialogPage(title as Character,
page as Character
[, zoomout as Boolean])
By default, the title is centered in the titlebar, which includes a righthand x to close. The title can be specified as an empty string ("") to omit the titlebar.
Dialog pages are stacked. They can be removed from the stack using the Lianja.hideDialogPage() method.
The dialog page 'zooms out' by default. In the web/mobile client, if zoomout is false, the dialog page 'fades in'.
Examples
// Title bar displayed with 'Customer List', zoom out Lianja.showDialogPage("Customer List","my_ui_customerlist"); // No title, fade in Lianja.showDialogPage("","my_ui_customerlist",false); // Hide most recent dialog page Lianja.hideDialogPage(); // Hide previous dialog page Lianja.hideDialogPage();
Page Navigation Panels allow the specification of a UI Page as the panel display on desktop Apps.
Here, the same customerlist UI Page as above is used as a Navigation Panel:
App UILibs
App UILibs are available from v6.0 and are supported in desktop, web and mobile Apps.
Pages are designed visually as normal then the page attribute "Register in UiLib" is checked.
This automatically adds the page to the App UiLib enabling it to be used with the Lianja.showDialog() and Lianja.showDialogPanel() methods.
The page is not included in the Pages Menu but can be used with dialogs by specifying "page:pagename" as the file name.
The 'Lianja Tablet Web UI Demo' App (example_webapp1) included in the distribution demonstrates this behavior.
A new page, 'page5', with a grid section has been added and its Register in UILib attribute checked.
The Customers section menu has been modified to display the page in a dialog panel using the Lianja.showDialogPanel() method.
Lianja.showDialogPanel("Edit Example", "page:page5", 700);
Preview live in browser and click the menu item.
This opens the dialog panel and displays the embedded page5.
Clicking the grid 'Edit' or 'Add' icons, overlays the edit mode dialog.
And closing the editing dialog, returns to the page5 grid.
