Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow direct append for nodes for complex composition #16

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

sgrigorjev
Copy link

@sgrigorjev sgrigorjev commented Sep 30, 2024

The existing solution with chain methods of document build is well suited for cases when the document structure is predetermined, like so:

$document = (new Document())
    ->bulletlist()
        ->item()
            ->paragraph()
                ->text('item 1')
            ->end()
        ->end()
        ->item()
            ->paragraph()
                ->text('item 2')
            ->end()
        ->end()
    ->end()
;

However, if you need to create a document programmatically, when parts of the document can be repeated or generated independently, a problem arises of how to embed pre-created structures of nodes into the document. When, for example, some nodes must be included in the document under a certain condition, and otherwise must be omitted.
The existing model of document creation does not allow this.
I faced this problem personally when creating articles on Confluence, and thought it would be nice to have it in the library itself.

My proposal is to allow two alternative ways of constructing a document, one existing through a chain of calls, and one through a direct append of nodes.

$document = (new Document())
    ->append(
        (new BulletList())
            ->append(
                (new ListItem())
                    ->append(
                        (new Paragraph())
                            ->append(new Text('item 1'))
                    ),
                (new ListItem())
                    ->append(
                        (new Paragraph())
                            ->append(new Text('item 2'))
                    )
                    
            )
    )
;

In this case, it will be possible to create and append nodes dynamically.

$paragraph = (new Paragraph())->append(new Text('Line 1'));

if (some condition) {
    $paragraph->append(new Text('(doc)', new Link('https://example.com/doc')));
}

$document = (new Document())->append($paragraph);

This will allow to create documents of any complexity and will give developers a powerful tool for working with Atlassian products.

This doesn't require much, just change the visibility scope for method append to public. I also added the ability to append multiple nodes at once.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant