3. Starting fresh

Read this chapter whatever your experience with 4D. It takes a new project from nothing to a running application in the Custom Menus environment, with Foundation doing the work.

Install the component

Create a new 4D project (or open the one you are adding Foundation to) and quit 4D.
Download Foundation for your 4D version from https://foundation.open4dshell.com and put Foundation.4dbase in the project's Components/ folder, beside Project/. Where your 4D's dependency manager supports GitHub components, you will be able to declare it in Project/Sources/dependencies.json instead, once a GitHub release carries it.
Reopen the project. The Foundation methods appear in the Explorer under Component Methods.

To develop with Foundation's source instead, put the Foundation project folder itself in Components/ or declare its path; it then runs interpreted inside your host.

Call Foundation from the database methods

// On Startup, and On Server Startup
Fnd_Shell_OnStartup

// On Exit, and On Server Shutdown
Fnd_Shell_OnExit

That is the whole integration. Fnd_Shell_OnStartup initialises every module, creates any missing Fnd_Host_* method, runs your Fnd_Hook_Shell_* hooks, shows the startup dialog, opens the navigation palette and installs the menu bar. Fnd_Shell_OnExit saves the lists, asks every Foundation window to close and waits for them.

Tables and fields

Create your tables and fields as you normally would. Three things decide what Foundation shows:

A table or field marked invisible in the structure never appears: not in the navigation palette, the Open Table dialog, Find, Sort or a list window.
A field's indexed and searchable/sortable attributes decide whether Find and Sort offer it, unless a hook says otherwise.
The first field of each table is taken to be its key, a long integer, for sequence numbers and record identity. If yours is elsewhere, say so in Fnd_Hook_SqNo_SetIDField (an example is in HooksAndHosts/).

Foundation's optional tables (Fnd_Pref for shared preferences, Fnd_Log for a log kept in the data, Fnd_Reg for licensing, Fnd_List and Fnd_SqNo) are created on request: in an interpreted host the module offers to add the table the first time it is needed; compiled, it reports and does without.

Forms

Each visible table needs two forms:

an input form, the record window, named Input, inheriting Fnd_IO_InputForm. Chapter 6 is the full guide. The short version: copy Forms/Fnd_IO_InputTemplate from Foundation Product Sales, enable the eight events it lists, call Fnd_IO_InputFormMethod from the form method, replace the sample fields with yours.
a list window, which in Foundation 6 is not a classic output form at all. Fnd_Out draws a listbox over an entity selection and lets the user choose, order, size and style the columns; the developer decides which fields are offered. Chapter 5 is the guide. The classic Output form inheriting Fnd_Tlbr_Toolbar, with Header, Detail and Footer lines, still works for a host that has one, and is what the 5.4 manual describes.

Tell Foundation about your database

Fnd_Hook_Shell_Setup is called once at startup. Give it at least the four database facts:

Fnd_Gen_SetDatabaseInfo("DatabaseName"; "A Great Database")
Fnd_Gen_SetDatabaseInfo("DatabaseVersion"; "1.0 beta 1")
Fnd_Gen_SetDatabaseInfo("DatabaseCopyright"; "Copyright © 2026 Your Company")
Fnd_Gen_SetDatabaseInfo("DatabaseURL"; "https://www.example.com/")

The name appears in the startup dialog, the About box and the About menu item, and names the local preferences file, so give every database its own. The version and copyright are for display. The URL is clickable in the About box. Fnd_Art_VersionHistory takes HTML for the About box's history tab; FPS shows the form.

If you localise, read the four values with Fnd_Loc_GetString from your own lists, as FPS does.

Run it

Choose Test Application. Foundation starts, shows the startup dialog with your database name, and opens the navigation palette with a button per visible table. Click one: a list window opens on the table. Double-click a row: the record opens in its input form. From the Select menu, Find lists the table's searchable fields and Sort its sortable ones. The About menu item shows your name, version, copyright and URL.

To return to Design while interpreted, choose Quit: Foundation treats an interpreted host as a developer at work, resets itself and hands you back to Design instead of quitting 4D. Hold Option (Alt) while choosing Quit to quit for real. Compiled, Quit quits.

Customise it

Everything you saw is a default a hook can change:

Want to	Hook
choose which tables and buttons the palette shows	`Fnd_Hook_Shell_NavPalette`, with `Fnd_Nav_AddButtonTable` and `Fnd_Nav_AddButtonMethod`
offer a different set of Find or Sort fields	`Fnd_Hook_Shell_Find`, `Fnd_Hook_Shell_Sort`
control which tables Open Table lists	`Fnd_Hook_Shell_OpenTable`
set a window's title, type or buttons before it opens	`Fnd_Hook_IO_DisplayRecord`, `Fnd_Hook_IO_DisplayTable`
validate before Save, or react to any input-form button	`Fnd_Hook_IO_InputFormButton`
set defaults on a new record, or veto a delete	`Fnd_Hook_Rec_New`, `Fnd_Hook_Rec_Delete`
style list rows, or give them a context menu	`Fnd_Hook_Out_RowStyle`, `Fnd_Hook_Out_ContextMenu`
run your own startup code, initialise plugins	`Fnd_Hook_Shell_Startup`, `Fnd_Hook_Shell_InitPlugins`
rename tables and fields for the user	`Fnd_Hook_Shell_VirtualStructure`
add your own menu items to the Special Functions dialog	`Fnd_Hook_Shell_SpecialFunctions` with `Fnd_List_AddItem`

Chapter 4 describes each one. Every hook in FPS is a working example to copy.

Compile

Compile early and often. Foundation's typing methods (Compiler_Fnd_*) travel with the component; your own hooks and host methods are typed by the Compiler_* methods Foundation generated with them, so keep the pair together if you ever delete one.