Hi,
Normally for entities like orders, invoices etc. that are modeled using Couch cloned-pages, the system page_id can serve as their unique IDs.
However, there are certain use-cases where the page_id does not suffice e.g. as in follows -
1. The use-case demands that invoices IDs do not have a gap (i.e. are sequential).
Since page_ids are distributed across all Couch templates, this cannot be guaranteed (e.g. we create a page from invoice template and then create another page from, say, blog template - the blog page will get the next page_id thus creating a gap between invoices).
2. There are already invoices in the system (e.g. imported) so we need to start generating new IDs from a particular value. Again, using the page_id does not offer this control (viewtopic.php?f=4&t=11341&p=29964#p29964).
The addon attached with this post makes available a new type of editable region (type 'uid') that helps in the scenarios mentioned above.
It offers the following features -
1. Allows creating sequential numbers.
2. Allows starting the numbering from any value (e.g. in a setup with existing invoices/orders, we can begin with any number greater than the current largest number).
3. Allows setting a minimum length for the numbers (where the number is automatically padded with zeroes to make up the length).
4. Allows setting a custom number prefix or suffix (these can include current day, month, year, hour, minute, second).
So instead of your invoice/order numbers looking like 43, 78, 137, and so on, they could now be AT-00043-US, AT-00137-US, or whatever format you wish.
Installation:
Unzip the attached zip file to extract a folder named 'uid'.
Place the folder within 'couch/addons' folder.
Edit to add the following line of code in 'couch/addons/kfunctions.php' file (if the file is not present, rename the 'kfunctions.example.php' file found in the same folder to 'kfunctions.php') -
Usage:
Define a field of type 'uid' in your template, e.g., in its simplest form it could be as follows -
Setting the 'search_type' as 'integer', as in the example above, is recommended.
However, if you want to make pages searchable in the admin-panel by this field, you'll have to use 'text' as the 'search_type' instead (viewtopic.php?f=8&t=11372&p=30097#p30097).
Once defined (and having visited the modified template as super-admin), the code above will create a field that will automatically be assigned a sequential number (by default starting from '1') whenever a *new page is saved*.
Once a page is assigned a number, the number will remain immutable i.e cannot be edited or changed.
[
IMP: please not that since the number is assigned by the system when a new page is saved, any existing pages of the template will not automatically be assigned any ID. You have to open the edit screen of those pages and press 'Save' - this process will trigger the number assignment for existing pages that do not yet have an ID.
]
The field supports the following parameters that can be set to use the other features mentioned before -
begin_from
By default the first ID assigned is '1'. This can be set to any other positive number by using this parameter.
Please note that this setting will take effect only if there is no existing page that has an ID greater than the value being set.
For example, if we have already assigned IDs up to 430, setting this parameter to 410 will have no effect - the next new page will be given a value of 431.
min_length
Use this parameter to set a minimum length for the IDs. If an ID has fewer digits than this value, it will be padded with zeroes to make up the specified length. For example, if '5' is set as the 'min_length', an ID with value 431 will be outputted as 00431.
prefix
Use this parameter to set any arbitrary characters as prefix of the IDs.
We also use certain special values (mentioned below) in the prefix to automatically use values from the current date (i.e. date on which the page is created).
suffix
Use this parameter to set any arbitrary characters as suffix of the IDs.
We also use certain special values (mentioned below) in the suffix to automatically use values from the current date (i.e. date on which the page is created).
Special values for use within the 'prefix' and 'suffix' parameters -
[D]
Day of the month without leading zeros
[DD]
Day of the month, 2 digits with leading zeros
[M]
Numeric representation of a month, without leading zeros
[MM]
Numeric representation of a month, with leading zeros
[YY]
A two digit representation of a year
[YYYY]
A full numeric representation of a year, 4 digits
[H]
24-hour format of an hour without leading zeros
[HH]
24-hour format of an hour with leading zeros
[N]
Minutes with leading zeros
[S]
Seconds, with leading zeros
Following is an example of a field using the full gamut of available parameters -
The ID generated for the field above could be -
AT-0000429-20180305
AT-0000428-20180304
A final note -
Internally this field stores the ID values as simple integers e.g. for the two example IDs shown above, internally the values being stored would be 429 and 428. That is to say that the padding of zeroes and the prefix and suffix are only for display purpose. If you wish, for example, to search for an invoice with a particular ID (e.g. using <cms:pages>), you'll have to use a value like '429' instead of say 'AT-0000429-2018'.
To help with this, the field makes available the value stored internally by setting a variable with '__unformatted' appended to the name of the field.
For example, for our example field named 'my_uid' above, the first statement below will output 'AT-0000429-20180305' while the next will output '429'
Hope it helps.
Feed back solicited.
Normally for entities like orders, invoices etc. that are modeled using Couch cloned-pages, the system page_id can serve as their unique IDs.
However, there are certain use-cases where the page_id does not suffice e.g. as in follows -
1. The use-case demands that invoices IDs do not have a gap (i.e. are sequential).
Since page_ids are distributed across all Couch templates, this cannot be guaranteed (e.g. we create a page from invoice template and then create another page from, say, blog template - the blog page will get the next page_id thus creating a gap between invoices).
2. There are already invoices in the system (e.g. imported) so we need to start generating new IDs from a particular value. Again, using the page_id does not offer this control (viewtopic.php?f=4&t=11341&p=29964#p29964).
The addon attached with this post makes available a new type of editable region (type 'uid') that helps in the scenarios mentioned above.
It offers the following features -
1. Allows creating sequential numbers.
2. Allows starting the numbering from any value (e.g. in a setup with existing invoices/orders, we can begin with any number greater than the current largest number).
3. Allows setting a minimum length for the numbers (where the number is automatically padded with zeroes to make up the length).
4. Allows setting a custom number prefix or suffix (these can include current day, month, year, hour, minute, second).
So instead of your invoice/order numbers looking like 43, 78, 137, and so on, they could now be AT-00043-US, AT-00137-US, or whatever format you wish.
Installation:
Unzip the attached zip file to extract a folder named 'uid'.
Place the folder within 'couch/addons' folder.
Edit to add the following line of code in 'couch/addons/kfunctions.php' file (if the file is not present, rename the 'kfunctions.example.php' file found in the same folder to 'kfunctions.php') -
- Code: Select all
require_once( K_COUCH_DIR.'addons/uid/uid.php' );
Usage:
Define a field of type 'uid' in your template, e.g., in its simplest form it could be as follows -
- Code: Select all
<cms:editable type='uid' name='my_uid' search_type='integer' />
Setting the 'search_type' as 'integer', as in the example above, is recommended.
However, if you want to make pages searchable in the admin-panel by this field, you'll have to use 'text' as the 'search_type' instead (viewtopic.php?f=8&t=11372&p=30097#p30097).
Once defined (and having visited the modified template as super-admin), the code above will create a field that will automatically be assigned a sequential number (by default starting from '1') whenever a *new page is saved*.
Once a page is assigned a number, the number will remain immutable i.e cannot be edited or changed.
[
IMP: please not that since the number is assigned by the system when a new page is saved, any existing pages of the template will not automatically be assigned any ID. You have to open the edit screen of those pages and press 'Save' - this process will trigger the number assignment for existing pages that do not yet have an ID.
]
The field supports the following parameters that can be set to use the other features mentioned before -
begin_from
By default the first ID assigned is '1'. This can be set to any other positive number by using this parameter.
Please note that this setting will take effect only if there is no existing page that has an ID greater than the value being set.
For example, if we have already assigned IDs up to 430, setting this parameter to 410 will have no effect - the next new page will be given a value of 431.
min_length
Use this parameter to set a minimum length for the IDs. If an ID has fewer digits than this value, it will be padded with zeroes to make up the specified length. For example, if '5' is set as the 'min_length', an ID with value 431 will be outputted as 00431.
prefix
Use this parameter to set any arbitrary characters as prefix of the IDs.
We also use certain special values (mentioned below) in the prefix to automatically use values from the current date (i.e. date on which the page is created).
suffix
Use this parameter to set any arbitrary characters as suffix of the IDs.
We also use certain special values (mentioned below) in the suffix to automatically use values from the current date (i.e. date on which the page is created).
Special values for use within the 'prefix' and 'suffix' parameters -
[D]
Day of the month without leading zeros
[DD]
Day of the month, 2 digits with leading zeros
[M]
Numeric representation of a month, without leading zeros
[MM]
Numeric representation of a month, with leading zeros
[YY]
A two digit representation of a year
[YYYY]
A full numeric representation of a year, 4 digits
[H]
24-hour format of an hour without leading zeros
[HH]
24-hour format of an hour with leading zeros
[N]
Minutes with leading zeros
[S]
Seconds, with leading zeros
Following is an example of a field using the full gamut of available parameters -
- Code: Select all
<cms:editable
type='uid'
name='my_uid'
label='Invoice Number'
desc='will be generated automatically'
search_type='integer'
begin_from='425'
min_length='7'
prefix='AT-'
suffix='-[YYYY][MM][DD]'
/>
The ID generated for the field above could be -
AT-0000429-20180305
AT-0000428-20180304
A final note -
Internally this field stores the ID values as simple integers e.g. for the two example IDs shown above, internally the values being stored would be 429 and 428. That is to say that the padding of zeroes and the prefix and suffix are only for display purpose. If you wish, for example, to search for an invoice with a particular ID (e.g. using <cms:pages>), you'll have to use a value like '429' instead of say 'AT-0000429-2018'.
To help with this, the field makes available the value stored internally by setting a variable with '__unformatted' appended to the name of the field.
For example, for our example field named 'my_uid' above, the first statement below will output 'AT-0000429-20180305' while the next will output '429'
- Code: Select all
Formatted ID: <cms:show my_uid /><br>
Internal ID: <cms:show my_uid__unformatted /><br>
Hope it helps.
Feed back solicited.