Coded something up in Couch in an interesting way? Have a snippet or shortcode to share? Post it here for the community to benefit.
8 posts Page 1 of 1

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.

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' );

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 -

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.

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.

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).

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 -
Day of the month without leading zeros

Day of the month, 2 digits with leading zeros

Numeric representation of a month, without leading zeros

Numeric representation of a month, with leading zeros

A two digit representation of a year

A full numeric representation of a year, 4 digits

24-hour format of an hour without leading zeros

24-hour format of an hour with leading zeros

Minutes with leading zeros

Seconds, with leading zeros

Following is an example of a field using the full gamut of available parameters -
Code: Select all
    label='Invoice Number'
    desc='will be generated automatically'

The ID generated for the field above could be -

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.


Thank you very much KK! This is something I really needed for my current project.
Works like a charm!

So if I understand correctly, there's no way to change that ID number once it's created, right?

Thanks again
I am glad it helped :)

So if I understand correctly, there's no way to change that ID number once it's created, right?

That is correct - once created, the ID is immutable.
Is there a particular reason why the generated data cannot be found with the search field in the admin? I tried searching for 426 in a longer code, but it's not working.

As expected, this addon will be used for templates with hundreds, if not thousands, cloned pages for invoices, orders, customer-management and whatnot. It becomes a necessity to quickly jump between such pages, but there are hiccups:

1. Search in backend doesn't find the UID
2. It is tedious and time-consuming to look for *exact* page which contains a certain UID even for small number of pages
3. Need to go back to list-view and lose paginated position in admin's list-view
4. If some page was deleted, then it will be complicated to find which UID does not exist anymore.

As a solution that in my view helps to cover all problems, I attach a Navigational Slider.
UID page navigation theme
(82.68 KiB) Downloaded 7 times

Zip contains a theme with all required files. Check Readme.txt inside for complete instruction (very easy). In a minute you'll have it running.

Code-wise I did my best to make code of this slider very user-independent and it is proof of multitude situations.
It is based only on stock CouchCMS code and is well commented and readable.
Code is tested on ten thousand pages and appears to work perfect and quick.
Slider appears only on saved-established pages, including unpublished, and only if there is more than one page.

Slider's handle can be dragged towards required UID among all available UIDs.
+ A value hint below helps see (and copy-paste) value without suffixes.
+ If mouse hovered over slider - value will also change to help you pinpoint desired location event before click or slide.
+ Button activates once new value has been set, so you can click and redirect to page with selected UID.
+ Slider has an option to base its values on exact available UID values of all *present* pages (default setting). Also a simpler option available, based on min-max values which features not-so-snappy sliding.
+ Slider is configured to react to left-right keys. If you need to find deleted page's value - use keys and slider will stop before deleted value.

In my screenshot there are over 10 000 pages and once I moved slider at proximity of desired page, I can use keys to fine-tune the value. In this screenshot, the page I currently stay on is "7517", but since I wanted to visit "9094" I hovered-dragged-used keys to set the new value and now I can click the button "Jump" and go.

thousands of pages and keyboard support
2018-03-06-008.png (8.9 KiB) Viewed 144 times

Hope you like it.
Is there a way to make the field findable using the search field in the admin, without using that slider? Thanks!
@larin555, I have made some changes to the addon - please download it again from the original post above.

With the modified addon your pages should now become searchable by UID numbers in the admin-panel.
However, there are some points to keep in mind -

1. The 'search_type' parameter used in your editable region's definition will now need to be changed to 'text' (instead of the original ;integer'). e.g.
Code: Select all
<cms:editable type='uid' name='my_uid' search_type='text' />

Make sure to visit the modified template as super-admin for the change to persist.

2. The value to search will be the raw unformatted number (as opposed to the formatted, i.e.prefixed and suffixed, display value). This is because the display format can be changed any time but the internal value remains immutable.

3. As has been discussed in several posts, the MySQL fulltext function powering Couch search does not take into consideration any word less than 4 characters long. As a workaround that limitation, if an UID being saved is less than 4 chars, the addon pads it with leading zeroes to make up the required length.

Which means that if you are searching for an invoice numbered '13', the value to search would be '0013'.
You might like to add a note about this in the admin screen for your users.

4. Finally, if you already have pages created using the earlier version of this addon they all will, at this point, have IDs assigned. Even after you upgrade to the new version, those ID will not change (as, of course, they are immutable). Which means that their 'search value' will not get saved. Effectively your existing pages won't be searchable.

To work around this, you may remove the editable region's definition from the template.
Once the field is deleted for the admin-panel all the pages will lose their UIDs.
Add the definition once again to recreate the field.
Save each of the existing pages to assign them new IDs which will be searchable.

Hope it helps.
Thanks KK! That will do the trick :)
8 posts Page 1 of 1

Who is online

In total there are 3 users online :: 0 registered, 0 hidden and 3 guests
(based on users active over the past 5 minutes)

Users browsing this forum: No registered users and 3 guests