Custom Files

Custom Files enables you to add your own files to the project. A Custom File is a simply blank page with the layout of the project (optional) for you to add your own content so it will have a consistent look and feel like other generated files.

 

How to Use

To create a Custom File, simply right click the database pane or click Edit in the main menu, then select Add File, the following form will show:

File Name File name with extension.
Notes
  1. Do not include path in the file name, you can enter Path separately (see below).
  2. Do not use characters not allowed as a file name on your machine or on your server. Alphanumerical characters only is recommended.
  3. If file name on your server is case-sensitive, make sure you enter the file name in correct lettercase. If you have selected Lowercase routes in Generate tab (see Generate Settings), the file name (the View only) will be converted to lowercase during generation.
  4. The file name cannot be same as any other table (including view, report, etc.) name.
Caption The caption of the page. This is similar to table caption for a table and will be shown up in the menu and in the Breadcrumbs of the page.
Includes common files For .php file only. Specify whether to include the common files (mainly header, menu and footer) in the file so it will be consistent with other generated scripts and able to use PHPMaker classes and functions.
Path The path of the page. There are 2 cases:

##### Case 1 - PHP file with "Includes common files" ENABLED This is usually an additional page **with HTML output** (with layout and content) accessible by users., e.g.
![Case 1](images/customfilecase1.png)
The **Path** is the **route** for the page, e.g. "/myroute" (no quotes). If unspecified, the file name without extension will be used as the route, e.g. "/home". The page class of the file is generated in the "models" folder and the content of the file is generated in the "views" folder. The output folders cannot be changed.
**Notes** 1. A **route** is NOT a physical output folder for your file, DO NOT try to specify a route like a folder path (e.g. "myfiles/"). A route must begin with a leading slash, but no trailing slash, e.g. "/myroute". You can include optional named placeholders, e.g. "/myroute/{id}", see Routing for details. To get the route value in your page content, you can use the global function ``Route()``, e.g. ``Route("id")``. 1. **Always access your custom file by its route (e.g. "/myroute"), NEVER try to access it by its physical path (e.g. "/views/mycustomfile.php").** 1. If you only want to output a single value or JSON, you should not use this case, you'd better use [Route_Action](customscripts.html?id=route_action) or [Api_Action](customscripts.html?id=api_action) server event.
##### Case 2 - PHP file with "Includes common files" DISABLED, or NOT PHP file
**The file is a standalone file**, e.g.
![Case 2](images/customfilecase2.png)
The **Path** is the **output folder** relative to the project folder. For example, if your project folder is *D:\websites\myproject* and you want to generate the page in *D:\websites\myproject\myfiles*, then you should enter "myfiles/" (no quotes).
**Notes** 1. This is a very powerful feature, basically you can use this to add ANY non-binary file to your project. For example, you can use this to add your own classes to your project, see examples below. 1. Do NOT use leading slash for the output folder path, but there must be a trailing slash, e.g. "myfiles/". 1. Do NOT use parent path ".." or the file will be generated outside the project folder leading to some unexpected results.

After entering above properties, click OK button to save. The Custom File will show up in the database pane under the Custom Files node:

To edit the Custom File properties, right click the Custom File in the database pane and select Edit File.

To delete a Custom File, right click the Custom File in the database pane and select Delete File.

To enter server events or content for the file, select the Custom File in the database pane , then select the Code tab (which contains Server Events, Client Scripts and Custom Templates) in the right pane.

To enter server event, go to Server Events -> Table-Specific -> Custom File:

To enter content for the file, Scroll down the treeview or collapse the Server Events and Client Scripts node, select the Custom Templates -> Table-Specific -> Custom File -> Content node, then you can enter or paste your content in the editor:



Then just save your project, generate and run your scripts as usual.

**IMPORTANT** Although it is convenient to save your own files in the project, you should avoid saving all the contents in the project or the project will become so large that the performance of the UI will be affected. If the file content is very large or they are many custom files, you should consider making [extensions](extension.html).

 

**Example 1**

Add a Bootstrap Card in the page to show some news.

The result:


**Example 2**

Add multiple Bootstrap Cards in the page as a dashboard page. Use helper function to execute SQLs and display data as HTML table.

Result:

**Note** Other than ``Route()`` and ``ExecuteHtml()``, there are other useful helper functions, refer to [Global Functions](functions.html) for details.

 

**Example 3**
Add your own class such as custom list action to the project: - **File Name** - Use a unique file name with file extension *.php* and **the file name MUST be same as the class name**, e.g. *MyCustomAction.php* for your class ``MyCustomAction``. - **Include Common Files** - **DISABLE IT.** Your class is standalone. - **Caption** - NOT used. - **Path** - Set the path as *"src/"* (no quotes). - **Content** - Enter your whole class, note that you should use the special placeholder ``{ProjectNamespace}`` as your namespace, e.g.

 

**Example 4**
Add your own controller and action(s) to the project: - **File Name** - Use a unique file name with file extension *.php* and **the file name MUST be same as the class name**, e.g. *MyController.php* for your class ``MyController``. If you want to generate API controller, the file name should be like _*ApiController.php_ (i.e. ending with *ApiController.php*), e.g. *MyApiController.php*. - **Include Common Files** - **DISABLE IT.** Your class is standalone. - **Caption** - NOT used. - **Path** - Set the path as *"controllers/"* (no quotes). Note that only files under this folder will be considered as controllers. - **Content** - Enter your whole class, note that you should use the special placeholder ``{ProjectNamespace}`` as your namespace, e.g.
Note that the routes of actions are defined by PHP attributes. **Make sure you add your PHP attribute with each action.** The arguments of the attribute ``Route`` are: - ``$path`` _(string)_ - Route pattern, see [Route placeholders](https://www.slimframework.com/docs/v4/objects/routing.html#route-placeholders). - ``$methods`` _(string|array)_ - HTTP methods: "GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH" - ``$defaults["middlewares"]`` _(string|array)_ - Middleware class name(s) for the route. If you want to protected your action by JWT (for API actions only), you can add the JwtMiddleware, e.g. ``JwtMiddleware::class``. - ``$name`` _(?string)_ - Optional. See [Route names](https://www.slimframework.com/docs/v4/objects/routing.html#route-names). **Note** You can omit the argument name ``path:`` if you specify the route pattern as the first parameter. Other arguments should be used with argument names so you don't need to care about the argument position.

 

 ©2002-2025 e.World Technology Ltd. All rights reserved.