SDK: Improve @dotcms/angular Documentation

[fmontes]

Task description

As a developer using the @dotcms/angular library, I want the documentation to be clear and easy to follow, so that I can easily understand how to use the library in my projects.

Acceptance Criteria

1. The README file should provide a clear introduction to the library and its purpose.
2. The README should include full step by step on how to use the library.
3. Update the README of the example/angular, include env variables, tokens, everything needed to start the example
4. Comprehensive JSDoc comments on all the components inputs, properties, classes, methods etc...
5. Any dependencies or prerequisites needed to use the library should be clearly stated.

Problem

For example the library have this:

Add the dotcms config in the Angular app ApplicationConfig

export const appConfig: ApplicationConfig = {
    providers: [
        provideDotcmsClient(DOTCMS_CLIENT_CONFIG),
        provideRouter(routes),
    ],
};

But is not explaining where provideDotcmsClient is coming from, or how to create or anything, is missing to much context.

Assumptions & Initiation Needs

N/A

[dcolina]

Internal QA: Passed.

[jdcmsd]

The writing is clear, with only a couple of small snags:

• A set of Angular components developer for dotCMS page rendering and editor integration.

• developer -> "developed"

Configutarion

• "Configuration"

Under "Client Usage":

For more information to how to use DotCms Client

• "For more information on how to use the dotCMS Client,"

Otherwise, the copy itself reads well.

As far as testing the code samples myself, I'm unable to even install the library due to dependency tree issues. Any suggestions on this?

jamie@Jamies-MacBook-Air ~ % npm install @dotcms/angular
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: undefined@undefined
npm error Found: @angular/[email protected]
npm error node_modules/@angular/common
npm error   peer @angular/common@"^17.1.0" from @dotcms/[email protected]
npm error   node_modules/@dotcms/angular
npm error     @dotcms/angular@"*" from the root project
npm error   peer @angular/common@"17.3.12" from @angular/[email protected]
npm error   node_modules/@angular/router
npm error     peer @angular/router@"^17.1.0" from @dotcms/[email protected]
npm error     node_modules/@dotcms/angular
npm error       @dotcms/angular@"*" from the root project
npm error   2 more (@angular/platform-browser, @tinymce/tinymce-angular)
npm error
npm error Could not resolve dependency:
npm error peer @angular/common@"18.2.6" from @angular/[email protected]
npm error node_modules/@angular/forms
npm error   peer @angular/forms@">=16.0.0" from @tinymce/[email protected]
npm error   node_modules/@tinymce/tinymce-angular
npm error     peer @tinymce/tinymce-angular@"^8.0.0" from @dotcms/[email protected]
npm error     node_modules/@dotcms/angular
npm error       @dotcms/angular@"*" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.

EDIT: Note, same outcome after ensuring @angular/cli installation

[rjvelazco]

Failed IQA

• Tested on main

Feedback

• Fix Typo in Header: Update "Configutarion" to "Configuration" for consistency and accuracy.
• Specify Code Language: To enhance readability, add typescript as the language specifier in code blocks where applicable, like app.config.ts and the Client Usage section.
• Refine Client Usage Example: Modify the Client Usage example to wrap the client injection inside a YourComponent class. This makes it clearer how the client variable is used within an Angular component.

[rjvelazco]

@jdcmsd I was able to run the Angular example without any issues. Could you check if you’re still experiencing the same problem?

It’s been a while since our last update, and we’ve made updates to our npm packages, SDK, and examples.

Edited: If you run into the same error, record a video if possible

[jdcmsd]

@rjvelazco I can also run the example without issue; the example is great!

The issue I was running into was trying to take a brand new ng new project and use snippets from the SDK readme (this one instead of the example project) to turn a new, blank angular project into a bare-bones working dotCMS project — basically, to figure out the minimum number of changes required to interface successfully with the UVE.

But as Freddy was explaining to me earlier, that's not really the point of that readme, so we don't really need to go into step-by-step instructions, there.

That said, some of the templating commands that Freddy and Jalinson were discussing might be interesting to build at some point, to accomplish what I was thinking of. But it's not really a high priority when we have a perfectly good working example project — especially when a user can even do something like a git sparse checkout to clone only the example directory, etc.

[zJaaal]

IQA Passed

Documentation on code is clear and concise, the readme is well explained and the steps are clear.

[jdcmsd]

This has come a long way, and it looks great! As with any doc, we can spend forever fiddling with it — or likewise return to it later if we learn about any special use-cases that a headless dev might need spelled out, etc. But right now, I'm comfortable calling this issue finished.

[bryanboza]

Fixed, we cal close this one now based on the @jdcmsd feedback