Most of the control panel features are active based on the current file/folder structure. Think of this control panel as a file/folder explorer application on your personal computer, or as a web-based file/folder explorer application provided by your web hosting service, where the location of the files to be controlled is determined based on the current URL structure.

For security reasons, this extension limits the scope of file and folder structure view to those inside the .\lot folder only. You cannot view file and folder structure above that level using the URL sructure in any way. This means that you cannot trick the application into opening the parent folder using parent path syntax such as ../../engine to view the file and folder structure of the .\engine folder.

Limiting the application to display only the file and folder structure of the .\lot folder also makes it easy to automatically generate menu items by scanning the folders that exist just one level down.

These are the default menu items that will appear based on the current folder structure:

And the following is the folder structure that generates those menu items:

.\
└── lot\
    ├── asset\
    ├── cache\
    ├── page\
    ├── user\
    ├── x\
    └── y\

Icons are determined manually based on the folder name, and if no specific icon path is given, it will display a standard folder icon. For example, here I have added a new folder called quran to the structure:

And although the following folder structure is given, a title starting with a capital letter is given to the folder named quran:

.\
└── lot\
    ├── asset\
    ├── cache\
    ├── page\
    ├── quran\
    ├── user\
    ├── x\
    └── y\

Menu titles are automatically determined based on the folder name if it is not explicitly specified. It uses a function called To::title() to automatically convert name to title. But, converting folder name to title does not always give accurate results, and sometimes the folder name itself does not always reflect the title that should be given. Hence, the .\lot\x and .\lot\y folders are given their menu titles manually in this case.

Folder names with . and _ prefixes are treated as hidden folders and therefore do not appear in the menu list. However, their menu item structure is still present with an additional skip attribute with a value set to true. So even if the menu data structure exists, it will not be rendered into the application layout. Empty folders are treated the same way, which is why the “Cache” menu may or may not appear in the list, depending on whether there are files and folders in it or not.

Menu items are arranged alphabetically by default, or more precisely, initially, the items are arranged alphabetically based on their title attribute value (which is automatically generated based on the folder name), and then a for-loop is performed to assign a stack attribute with increasing values for each menu item. This ensures that the application will continue to display the menu items in the same order in the end, even if the position of the menu items is no longer in alphabetical order due to some extension that caused the structure of the menu items array to shift.

After the stack attributes are assigned to the menu items, they will no longer be sorted by the title attribute value, but instead by the weight of each stack attribute value on the menu item. This allows developers to easily change the order of menu items by setting the weight of the stack attribute value on the desired menu item.

The URL structure determines the way the application layout looks. Generally, it will display a list of files and folders if the URL contains a pager indicator, i.e. a path that ends with a number greater than 0. The following is an example of how the application will look like at http://127.0.0.1/panel/get/quran/1:

The same type of layout will be displayed when you open a folder at a deeper level, such as at http://127.0.0.1/panel/get/quran/translations/1, as shown below:

However, if you remove the pager indicator from the URL, you will be presented with a folder name editor that looks like this:

Things get a bit complicated when there are file or folder names that consist only of numeric characters, as this can cause the application to incorrectly interpret the file or folder name as a pager indicator:

For now, if there is no type query specifically set in the URL, it will simply present you with a list of files and folders, as shown in the image above. When you specify a type query to the URL, it will use that type to present the folder content for you, as long as it is supported. If it is not supported, then you will likely be presented with a blank page or an error page stating that the current view type is not supported. For example, a product view type is not supported in the core application, therefore you will get a blank page or an error page if you have ?type=product query set in the URL. However, its type will still be applied to the application (indicated by a class type:product being added to the <html> element). It is just that since the actual view type handler is missing, then it will view a blank page (or a page with incorrect data structure) to the user.

When you open a file/folder through the control panel URL, by default it will present you with a file/folder editor view even without you explicitly adding the type query in the URL. If the URL maps to a valid file, then it is as if it has ?type=file query set in the URL. The same goes for URL that maps to a valid folder, it is as if it has ?type=folder query set in the URL.

Panel URL

Disregarding the protocol and the host part, a valid path to display the control panel is started by the route /panel. This route is not fixed and can be changed in the configuration. This feature allows users to customize the control panel routes, making it harder for attackers to guess your control panel routes (unless you have placed a control panel URL somewhere in the front-end as a quick link, or a certain extension that provides live user management functionality exposes some control panel URLs in the front-end for ease of use). But the default is that a valid control panel page will have this /panel prefix in its path.

Following the prefix is a term that describes the administrative action that is or can be performed. In general web applications, you will probably be familiar with the term CRUD. Here, Mecha provides four types of “terms”, which are then referred to as “tasks”. They are named quite differently, but serve the same basic purposes:

Fire

This task is used to perform a specific function from a URL. This can be the better option if you feel that creating a new control panel route is too complicated or would change the existing flow in a way that could be confusing in the future due to the unfamiliar route pattern. This task does not work alone and must be followed by an identifier that points to the function name within the x\panel\task\fire namespace. For example, visiting the control panel URL at /panel/fire/attach/x/archive will attempt to activate the archive extension. About how the action will be performed is available in the body of the x\panel\task\fire\attach() function, which is simplified as follows:

<?php namespace x\panel\task\fire;

function attach($_) {
    // Check if previous hooks have set a redirection link, so we can immediately skip the actions we want to perform.
    if (isset($_['kick'])) {
        return $_;
    }
    // Check if previous hooks have changed the data structure in a way that reflects a failure of the previous actions.
    if (!empty($_['alert']['error']) || $_['status'] >= 400) {
        return $_;
    }
    // Check if the necessary conditions for this action are met, e.g. whether the `archive` extension is present or
    // not, whether the `archive` extension has been installed already, and so on. If everything is satisfied, then the
    // action to attach the `archive` extension will be performed.
    return $_;
}

Get

This task is generally used to display a previously existing file or folder, which is equivalent to the “READ” part of the term “CRUD”. However, this is only valid if the current request is a GET request. If the current request is a POST request, then this task is equivalent to an “UPDATE” (to modify the previously existing file or folder).

To successfully open a link http://127.0.0.1/panel/get/asset/icon.svg means that file .\lot\asset\icon.svg must be present. If it is not present, then the control panel should display an error page stating that the file does not exist.

Let

This task is generally used to execute a delete command for a file/folder, which is equivalent to the “DELETE” part of the term “CRUD”. It can generally be executed with a GET or POST request. Both require a field named token to prevent unwanted delete execution. For POST request, it’s usually safer because to open the link you have to submit a form. It becomes critical with GET request. Without the ?token= query in the delete link, chance that you will click on it where you actually do not want to delete the file/folder associated with that link:

<form action="/panel/let/asset/icon.svg" method="post">
  <input name="token" type="hidden" value="<?= eat($_['token']); ?>">
  <button type="submit">
    <?= i('Delete'); ?>
  </button>
</form>

<a href="/panel/let/asset/icon.svg?token=<?= eat($_['token']); ?>">
  <?= i('Delete'); ?>
</a>

Set

This task is generally used to open a file/folder that already exists. Using a GET request, it is equivalent to the “DELETE” part of the term “CRUD”. If the file exists, the control panel will present you with a file editor; if the folder exists, the control panel will present you with a folder editor. If a file is considered editable (is plain text), it will also provide a text area so that you can edit the file content, otherwise it will simply provide a text input to rename the file. The folder editor currently provides a text input to rename the folder.

If a folder exists and the last route segment ends with a number greater than 0, the control panel will treat that as a pagination indicator, and instead of presenting you with a folder editor, the control panel will present the contents of the folder as a list of files and folders, with pagination under it if necessary.