DEPRECATION WARNING
This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.
CreateId¶
You need to create a unique ID with auto-increment function but cannot (for various reasons) rely on a database function for that? Then, this is the right callback handler for you. It let's you specify a format, a starting number, a step size and double-checks for double entries. This way, you don't have to worry about unique IDs.
nNumberStart¶
Number. Starting point for the auto-increment. Default is 1, the first entry to be created gets this number.
nNumberStep¶
Number. Step size to be added to the starting number for each entry. Default is 1 so that the second entry gets the number 2 (1 + 1).
bDontForce¶
Boolean. Allows the user to manually set the ID on creation and thus prevent this callback handler from creating an automatic ID. If set to true, an ID is only created if the currently entered value is 0, empty, NULL or false.
sWrap¶
String. You might want to set a string before or after the number to be incremented. Do so here and include a pipe (|) at the position where the number should be filled in. Simple example:
entry|
This gets translated to entry1, entry2, entry3, ...
Anyhow, it might be useful to include other data from the same entry, maybe a category field. Use them with surrounded marker signs (###). Just keep in mind that you may only use data that comes from the form. Example:
entry-###category###-|
This gets, if you have the category set to, say, sysfolder, translated to entry-sysfolder-1, entry-sysfolder-2, etc.
Okay, but what if you offer the user multiple categories to select from, how does the numbering work? Easy: It starts from the nNumberStart for every category. So imagine the following timeline of user interactions:
| nr. | selected category | resulting ID |
|---|---|---|
| 1 | sysfolder | entry-sysfolder-1 |
| 2 | page | entry-page-1 |
| 3 | page | entry-page-2 |
| 4 | page | entry-page-3 |
| 5 | separator | entry-separator-1 |
| 6 | sysfolder | entry-sysfolder-2 |
Alright, any other markers I should know of? Yes, indeed. The usual marker system (see dbal/sWhereGet) is applied as well. This gives you the opportunity to use date markers, user information, system environment variables, etc. And finally, you can even apply a few functions on columns/fields (and on them only) in order to adopt your string ID a little.
| Function | Description | Example |
|---|---|---|
| trim | strip space away | " la" -> "la" |
| lower | convert characters | "LaLa" -> "lala" |
| upper | convert characters | "LaLa" -> "LALA" |
| camel | convert first char | "LaLa" -> "Lala" |
| substring/start/length | extract part | "Lala"/2/1 -> "l", "Lala"/-1 -> "a" |
| resolve | process through column/field handler | ForeignSingle, ... |
You may even combine those but be aware that the processor starts at the inside. Thus, the following example
###camel:substring/6:trim:my_column###
translates the content of my_column in the following order:
| Step | Function | Result (example) |
|---|---|---|
| 1 | my_column | "Hello world " |
| 2 | trim | "Hello world" |
| 3 | substring/6 | "world" |
| 4 | camel | "World" |
Another example that takes a foreign key and uses its first character in uppercase form is this one:
###upper:substring/0/1:resolve:my_foreign_key###
For further explanations of the substring function see http://us1.php.net/manual/en/function.substr.php
nNumberDigits¶
Number. This allows you to set the string length of the numeric part of the created ID. So if you want your ID to always be 8 characters long, starting with MyId followed by the number consisting of 4 digits, you would set this setting to 4 (the first ID would then be MyId0001).