API Docs Web Site

Communities ColdBox HMVC
1

Hi

I’m trying to understand the API docs site - this is probably a newbie question but I can’t find the answer - I don’t think there is a video on it or any examples…

For example - I’ve installed the CBI18N module and that is working… I’m trialing it using views, which can access the module through implicit injection.

Why would #getFwLocale()# work and #getFwLocaleDisplay()# not work?

If anybody could point me in the direction of working examples that I could get my head around I would really appreciate it!

Thanks

Tony

2

OK - AFAIK the non working function is because only certain functions are automatically registered on CBI18N installation.

It would appear that the handler needs the injection of

property name="i18n" inject="i18n@cbi18n";

So that the non registered functions are found and can be used with prc in the view.

If this is wrong or not best practice could somebody enlighten me please

Thanks

Tony

3

I’m confused. How is cbi18n an API docs site question?

What does “not work” mean in this case?

If you need the i18n object injected in order to reach/call those methods from within a view, then yeah. The documentation seems pretty clear on that:

Once you have access to those objects you can leverage their methods to your :heart:’s content.

4

The documentation is here, https://coldbox-i18n.ortusbooks.com/

5

You need to understand the API docs site to know what methods etc are available for CBI18N.

The confusion comes when only some of the methods are automatically registered on installation and for the rest you need to put in the injection into the handlers.

Obviously when you know that it’s trivial but why make life difficult? The package methods surely should all be registered or not at all. Or even this fact should be mentioned in the API docs.

AFAIK does ‘not work’ means that an error is thrown when trying to use the method. I cut my coding teeth with Golang where issues like this have been explicitly removed - these problems with Coldbox, for a newbie, are very disheartening as they can be avoided completely by management of the learning resources available.

I’ve lost count of the times I’ve had to repeat areas because things just are not clear!

Coldbox has the opportunity to increase its user base but making documentation difficult is not the way forward.

6

@Eggely This page includes the helper methods that are injected in to handlers, interceptors, and views: Coding for i18n - cbi18n

Otherwise, you can just inject ResourceService@cbi18n and then call getResource( "my.resource.key" )

In views, though, you can just use #$r( "my.resource.key", "My default text" )#

If you want to spend time with the API Docs, they are here: Generated Documentation (cbi18n v3.3.0)

7

The cbi18n documentation is open source. If a portion of it is unclear, I suggest opening a pull request. We’d be happy to see your contributions, we’re always looking to improve our Box tools and simplify documentation! :grin:

With that said… your issue with missing methods is clearly noted in the getting started section. I’m not sure how this could be any more straightforward.

The documentation cannot help you if you do not read it.

8

I went back to reread the getting started section - It’s no help at all. It says the following methods are registered but no mention of the ones that haven’t been registered.

Things like this are critical in trying to understand how the system works. All anybody needs is an example of how to get this working - saying things like

/**
 * Get Access to the i18n Model
 */
function i18n()

After lots of trial and error AFAIK it means the following…

To access the methods of i18n you need to use it like this -

#I18N().getFWCountry()# in a view

“prc.bContacts” = i18n.getFWCountry(); in a handler

There were no examples that I could find, no tutorials, no questions asked by others.

I’d be happy to rewrite the docs for CBI18N when I can actually understand it…

9

I’m not really sure I’m following the use case for documenting what is not registered. The i18n() method is available and the documentation already demonstrates the usage of that object and its methods here: Coding for i18n | cbi18n

10

Surely the documentation needs to explain the caveats. I agree that it’s not difficult IF you have an understanding of the way ColdBox is constructed. There is a very steep learning curve for this, full of magic that only becomes clear after many many hours of study.

However for somebody new this is really hard and necessitates lots of extra work to understand as nothing works first or second time.

Thank you for your time on this though

Tony

11

Thanks, Tony! We do value your input. Please note that managing over 350 different Open-Source libraries gets complicated for a small team. We need help in many ways, either as patrons or people who contribute their time to assist us with sources or docs. So if you can assist us in making the docs more straightforward for new developers, that would be fantastic.

Writing documentation is one of the hardest things to do since you are targeting multiple people at multiple education levels, multiple experience levels, and multiple learning ability levels. They are, quite frankly, living docs. Since you have hit several roadblocks, sending us the contributions that would assist others in your position would be great. As I said, it’s impossible for us to determine how someone will learn our tools, and ultimately there can be many oversights as things are in our heads.

Thanks!

1 Like