ALeX
This extension is a productivity tool for ALeX developers.
Features
Main extension features:
- Upload PHP actions and parts of XML files with a single key stroke.
- Snippets to speed up configuration authoring.
For more details see:
The extension is activated once an XML or PHP file is opened or once a connection is selected.
Quick start
- Create connection ini file.
- Select connection.
- Edit XML configuration file:
- Put cursors inside an
<alex-update>
block and upload the block.
- Select several
<alex-update>
blocks and upload them.
- For both use ALeX: Upload selection command.
- Edit PHP action file and upload it.
Commands
ALeX: Connection: Select
Use ALeX: Connection: Select
to select connection ini file that defines IS ALeX endpoint. IS ALeX endpoint is defined with
url
- ALeX base URL, e.g. http://localhost/ALeX/current
db
- ALeX database name
user
- ALeX user name, db owner or another powerful user is a good choice
password
- Optional password, define it for development environments only!
Connection ini file example:
url="http://localhost/ALeX/current"
db="alex"
user="root"
; Never store password for production systems.
;pass="mysecretpassword"
The command searches the path from the directory of the active document to the root folder looking for .*.ini
and *.ini
files. User is offered the list of connection files to select one.
Once you select a connection file, its endpoint details are printed to output. The selected connection file is then used for all commands that talk to ALeX server (like ALeX: Upload
).
ALeX: Upload selection
Ctrl+Alt+U
Cmd+Alt+U
Use ALeX: Upload selection
to upload the selected part of your XML configuration file to ALeX.
The selected part is
- the current selection block, or
- the closest
<alex-update>
block surrounding the current cursor position, if the current selection is empty.
You can use multiple cursor positions to select several blocks.
Command requires a connection file with ALeX endpoint details. Use command ALeX: Connection: Select
to select one.
ALeX: Upload PHP file
Ctrl+Alt+U
Cmd+Alt+U
Use ALeX: Upload PHP file
to upload the current PHP action file to ALeX.
Command requires a connection file with ALeX endpoint details. Use command ALeX: Connection: Select
to select one.
ALeX: Upload XML file
Use ALeX: Upload XML file
to upload the current XML file to ALeX.
Command requires a connection file with ALeX endpoint details. Use command ALeX: Connection: Select
to select one.
ALeX: Compile selection
Ctrl+Alt+K
Cmd+Alt+K
Use ALeX: Compile selection
command to compile the selected part of your XML configuration file (see ALeX: Upload selection
for definition) and save the result to a file.
Compiled XML is saved to build/part.
file
.compiled.xml
if called from file
.xml
.
Command does NOT upload anything to ALeX server.
ALeX: Compile XML file
Use ALeX: Compile XML file
command to compile the whole current file.
Compiled XML is saved to build/
file
.compiled.xml
if called from file
.xml
.
Command does NOT upload anything to ALeX server.
ALeX: Connection: Set password
Use ALeX: Connection: Set password
to set password if one is missing in connection file. Once password is set VSCode remembers it until workspace is closed or a different connection file is selected.
If password is set and connection file contains password too, the one set in VSCode is used.
ALeX: Connection: Reset password
Use ALeX: Connection: Reset password
to unset password set with ALeX: Connection: Set password
.
ALeX: Connection: Info
Use ALeX: Connection: Info
command to print the current ALeX endpoint details to output.
ALeX: Make commands
Use a set of ALeX: Make
commands to invoke alex make
command from VSCode. There is a command for each of the most used targets.
Command |
Meaning |
ALeX: Make All |
Asks whether to reset db. Then it builds and uploads configurations. |
ALeX: Make Build |
Builds configurations. Built configurations can be found in build folder next to alex.json . |
ALeX: Make Config |
Builds and uploads configurations. |
ALeX: Make Test |
Builds and uploads test configurations. |
Invoke command in one of the following ways.
- From context menu of
alex.json
file in file explorer.
- As a usual command with
Ctrl+Shift+P
- it will ask you to select one of alex.json
files VSCode will find on the paths from the active document to root.
More on alex.json
in usage help of alex make
command.
alex make --help
Run command ALeX: Create PHP metadata
to create .metadata.php
in a folder
with your root alex.json
file. The .metadata.php
file provides your PHP
classes with code completion.
How it works. The command derives PHP types for all your parameter groups and
folders and it also injects type definitions into PHP actions in your projects.
All type definitions are comments-only so they never break your existing code.
The code completion on nodes respects node type, parameter group and parameter
types. So it offers the correct functions and properties as needed. It also
tries to guess the correct types for childNodes()
and parentNode()
.
Jump start
ALeX: Make: Build
on your root alex.json
file.
ALeX: Create PHP Metadata
on your root alex.json
file.
- Check code completion in some of your PHP action classes.
Prerequisites
- Extension PHP Intelephense installed
- Extension PHP Language Features disabled
Class names
Class names for derived types:
Class |
Description |
NodeByPg_<pginfix> |
Class for a parameter group. |
NodeByPrefix_<prefix> |
Class for a node defined by its prefix. Useful for base folders. The slashes in prefix are replaced by double underscore __ , e.g. folder with prefix /invoices/all will have a class NodeByPrefix_invoices__all . |
NodeByType_<nodetype> |
Class for a node defined by its type. These are usually used only internally or for more types that cannot be derived from XML. |
Explicit type
Usually, traversing ALeX nodes in PHP API should provide correct types for code
completion. However, if traversing ALeX nodes in PHP API does not end up with a
proper code completion, you can explicitly define the type you need.
// The following line sets class `Node_invoice_item` as the class for variable `$node` for code completion.
// Use it if the $node has PG `invoice_item`.
/** @var NodeByPg_mypg $node */
Node by id or prefix
For the types to work well, always provide type when you get node by its id or prefix.
foreach ($ids as $id) {
/** @var NodeByPg_invoice_item $node */
$node = $env->getNodeById($id);
// ...
}
A good idea is to provide a single static helper function on some common PHP
action to provide typed nodes by prefix.
class Action_invoice_folders {
/**
* @param Environment $env
* @return NodeByPrefix_invoices__all
*/
public static function GetInvoicesAll($env) {
return $env->getNodeByPrefix('/invoices/all');
}
}
Then from your PHP action class you get your folder with all invoices like this,
passing in the environment with $env
:
// This will have the type of folder
$invoices = Action_invoice_folders::GetInvoicesAll($env);
// Child nodes in folder will be typed correctly
foreach ($invoices->childNodes() as $inv) {
// $inv provides invoice attributes code completion
$inv->inv_ // If you type this then code completion offers inv_arrival, inv_amount, etc.
}
This way you refer to /invoices/all
prefix at only one place in your project.
Everywhere you need that folder you get it with the GetInvoicesAll()
function,
thus you always get it it with the proper type and code completion works
automatically.
Tuning: Type derivation source
By default, all types are derived from complete project's XML. Therefore ALeX: Make: Build
has to be run first. We prefer this way for current projects.
Alternatively, it is possible to derive the types from an existing database.
This can be helpful when XML definition is incomplete.
To derive types from db, set the following in alex.json
in your root
configuration directory.
"php_metadata": {
"source": "db"
}
As long as the above is set in your alex.json
configuration file, the command
ALeX: Create PHP Metadata
will derive all types from db only.
You can also create your PHP metadata explicitly from the selected source by
calling ALeX: Create PHP metadata from db
or ALeX: Create PHP metadata from XML
.
Tuning: Avoid memory limit issue
Deriving types can be a memory intensive task on your ALeX server, especially
for large databases. If you encounter Allowed memory ... exhausted error, try to
set a larger memory limit for the PHP metadata request by setting the memory
limit in your root alex.json
file.
"php_metadata": {
"memory": "512M"
}
If setting the memory limit does not help, it may be caused by non-rewritable
memory limit set in your Apache / HTTP server configuration.
Snippets
Document initialization
Abbreviation |
Description |
aus |
Basic XML settings for ALeX XML configuration and <alex-update-sequence> root element |
Update blocks
Abbreviation |
Description |
au |
General <alex-update> block |
auj |
<alex-update> for jobs |
aup |
<alex-update> for parameters |
aupg |
<alex-update> for parameter groups |
auphp |
<alex-update> for PHP actions |
aur |
<alex-update> for a role |
Universal blocks
Abbreviation |
Description |
an |
<alex-node> |
aa |
<alex-attribute> |
al |
<alex-link> |
Parameter group blocks
Abbreviation |
Description |
pg |
<alex-node> for a parameter group |
ad |
<alex-display> |
adf |
<alex-display> block with flags |
ap |
<alex-link> to a parameter |
aacpa |
ALeX actions custom panel - set custom actions |
aacpo |
ALeX actions custom popup - set custom actions |
act |
<alex-action> |
call |
<call> in action definition |
aapa |
ALeX actions panel - modify standard actions |
aapo |
ALeX actions popup - modify standard actions |
aaxi |
<xi:include> to modify standard actions |
Parameter blocks
Abbreviation |
Description |
p |
<alex-node> for a general parameter |
pdat |
<alex-node> for a date parameter |
pmulti |
<alex-node> for a multicatalog parameter |
pref |
<alex-node> for a catalog parameter |
pstr |
<alex-node> for a string parameter |
ptab |
<alex-node> for a table parameter |
Rights blocks
Abbreviation |
Description |
aur |
<alex-update> for a role |
ar |
<alex-right> |
PHP
Abbreviation |
Description |
php |
<alex-node> for a PHP action |
classa |
class Action_ template (for PHP) |
trigger |
Trigger method template (for PHP) |
Jobs blocks
Abbreviation |
Description |
ajf |
<alex-node> for a filtering job |
ajp |
<alex-node> for a PHP job |
Filter blocks
Abbreviation |
Description |
af |
<alex-filter> |
afc |
<alex-condition> |
Editor title bar
An upload action is displayed in editor title bar (in top-right corner) in XML and PHP files. For XML files it uploads the current selection.
If Alt
is pressed, then compile action is available instead upload in XML files.
Requirements
This extension requires command alex
to be installed.
Extension Settings
Path
Set path to alex executable, if it is not on path including alex
, alex.bat
, or alex.php
.
On Windows it's better to set path to alex.php
.
{
"alex.path": "/path/to/bin/alex",
// or
"alex.path": "C:\\mypath\\alex.php"
}
PHP
If path to alex.php
is set in alex.path
, you can set path to PHP binary to run it, otherwise php
is expected on path.
{
"alex.php": "/path/to/bin/php"
}
This setting is ignored if alex.path
is not set to a path to alex.php
but e.g. to alex
or alex.bat
.
Known Issues
- Check you have the latest alex-tools installed.