Code Macro | Copy button & Title styling + New macro?

[amilica]

Hello everyone!
Here to discuss some code macro improvements ^^

A new user migrating from Confluence remarked that:

• the macro doesn’t have a copy button attached to it (issue link)
• the title of the code snippet isn’t by default stylized differently than the content itself (issue link).

Our code macro

• the title can be edited like any other text, but the spacing between the title and code can’t be achieved truly just by entering a new line (also, that would mean effort from the user)
• the language is not specified in view mode
• no copy button
• no configurability icon (that could help in discovering/remembering how to configure the macro)

Code macros in other places

Notion

• special button in the top-right with icon and label
• no title field
• caption button for giving more context (this could be used to give a title to the code snippet)
• more options button
  

Obsidian

People really wanted a copy button and someone did a plugin for it.

A plugin was done for adding titles to code blocks:

Confluence

• no title field
• copy button in separate toolbar

Proposal

Better format and add CSS classes to the code related to the macro to enable the styling changes. Currently, I’m not sure if we can style independently the title of the macro (let me know if I’m missing something).

The idea would be to have:

• a button with a label and an icon for copying the content of the macro
• the language showcased
• the title bolded

Case 1: No title, language non specified

Case 2: Title, language specified

Case 3: No title, language specified

Responsive mode

Might need to work on this a bit more. Can’t figure out a nice way of making the title be vertically centered (vertical-align: middle doesn’t work), but probably will.

Code

HTML

I think I may have not used icons the way I’m supposed to, looking for an practical example of doing this. Also, I’d appreciate feedback on the structure and naming of classes.

<div class="box">
<div class="code-toolbar">

                <div class="box-copy-button btn btn-default">
                    <span class="fa fa-clone"></span>
                    <span class="copy-label">Copy</span>
                </div>

                <div class="code-fields">
                    <div class="snippet-title">The beginning</div>
                    <div class="snippet-language">C++</div>
                </div>
                
</div>

<div class="code"><div class="linenoswrapper"><div class="linenos"> ... </div></div></div>

</div>

CSS

I know I need to use theme variables, I will come back on this tomorrow. Apart from colors and font-weight is there something in the following snippet that I should have not hard-coded?

.snippet-title {
    display: inline;
    font-weight: 600;
    margin-right: 7px;
}

.box-copy-button {
    display: inline;
    float: right;
}

.copy-label {
    display: inline;
    margin-left: 2px;
}

.code-fields {
    margin-top: -8px;
    margin-bottom: 15px;
}

.snippet-language {
    display: inline;
    color: #777777
}

Copy Button Implementation

I was thinking we could reuse code from the copy button in the Information Tab (copy the refference of the current page).

Copy Button Macro Idea

It would be great if in addition we’d have a copy button macro that can be placed anywhere in a box, table, table cell. There are many instances where a user may want to allow themselves or others to easily copy a certain content (because of its often use).

Of course, this would need more thought in design, structure and more complex implementation.

What do you think about the proposal and the idea of the copy macro?

[watery]

@amilica

What do you think about the proposal

That the copy button is a much wanted feature, I already voted for it!

We use XWiki in a technical context, so the other features proposed are a plus for me

[mflorea]

+1 for improving the code macro.

@amilica

Case 1: No title, language non specified

Don’t you have a problem if the first line of the code macro is very long? On the other hand some users might prefer to have no top bar even when there’s a language set (either because they want to save space or because the language is implied / redundant). The language might be important if you mix code snippets of different languages, but if you have a documentation about Java, let’s say, you probably don’t want to see “Java” on each code snippet. Thus, maybe we can have instead a boolean showTopBar parameter so that:

• if showTopBar is not set then show the top bar only if the title is set, otherwise use a balloon (like we do for the image lightbox), activated on hover/click.
• if showTopBar is false show the balloon instead
• if showTopBar is true then show it

The content of the top bar and the ballon should be the same: title, language, action buttons.

@amilica

Case 3: No title, language specified

As mentioned above, I think that in some case the users might want to hide the top bar even if the language is set. Moreover, there’s always a specific highlighting applied:

• if you specify the language then it applies the corresponding highlighting, if available, otherwise no highlighting
• if you don’t specify the language is tries to detect the language, AFAIK

So you always have a “language”: either explicitly set or detected automatically.

@amilica

Responsive mode

Might need to work on this a bit more. Can’t figure out a nice way of making the title be vertically centered (vertical-align: middle doesn’t work), but probably will.

For responsive mode I think it would look better to align the action buttons with the title / language.

@amilica

<div class="code-fields">
  <div class="snippet-title">The beginning</div>
  <div class="snippet-language">C++</div>
</div>

I’d use the code- prefix for the CSS classes, and use meta or info instead of fields:

<div class="code-meta">
  <div class="code-title">The beginning</div>
  <div class="code-language">C++</div>
</div>

@amilica

<div class="box-copy-button btn btn-default">
  <span class="fa fa-clone"></span>
  <span class="copy-label">Copy</span>
</div>

If you want to make a generic copy button then it’s fine to not have the code- prefix, but I’m not sure about the box- prefix. Unless you think the button will always be in a box, but I’m not sure about this. I’d use simply copy-button. Then the button should be a button not a DIV, for accessibility reasons. Moreover, if order to make it generic you need to specify on the button where to copy the content from and in which “format” (plain text, HTML, image).

<button class="copy-button btn btn-default" data-source-ancestor=".box"
    data-source=".code" data-format="text/plain">
  <span class="copy-button-icon">
    <span class="fa fa-clone"></span>
  </span>
  <span class="copy-button-label">Copy</span>
</button>

Thanks,
Marius

[amilica]

Thanks a lot! Glad you find this useful! ^^

[vmassol]

I don’t think we should improve the current code macro as we’re now more interested in moving to a client-side solution. See Loading...

[amilica]

Thanks a lot, Marius! Your ideas and help are great & I appreciate them a lot!

Based on the update from @vmassol it seems that we might not need to do all of these changes as we will move in the future to another solution for code blocks. I didn’t see his comment in the issue when I posted this proposal, sorry for that.

[vmassol]

Note that I need to write a proposal on the forum to propose that idea. ATM nothing has been decided yet, but it would be what I’d push for personally. I’ll try to find some time to write the proposal.

[Wardenburg]

+1 for the change
+1 for doing it cleint side for speed

Perhaps it’s interesting to look at the teams implementation of the code bracket aswell;

results in

• Dropdown for the types of supported code formats seems nice
• Text wrap slider can also be usefull
• I like how the title is shown seperately , not neccisarily a fan of how the code is the same font as the title - I’d prefer the Case 2 layout in that regard

[vmassol]

I’ve now sent a proposal, see Change the code macro implementation

[Aliroe]

@vmassol When will the code macro be implemented to have a copy button to copy, and the functions described in this article

[vmassol]

I need to close Change the code macro implementation and then we need some dev to implement it. There’s currently no roadmap for it.

PS: If you wish to sponsor the development of it, see https://dev.xwiki.org/xwiki/bin/view/Community/Contributing#HSponsoraFeatureorBug

[Aliroe]

You mean, there are no developers working on this feature?

[vmassol]

Correct.