Project Code Box

ProjectCodeBox is designed to simulate a complete project by displaying the entire source code.

Elements of Project Code Box

In addition to code view and file elements (described here), a project code box can also include folder structure configuration elements and commands. The following code sample shows what an element for a project code box might look like.

<!-- project code box -->
<div id="MyProjectCodeBox">
    <!-- folder structure -->
    <ul data-cb-folders>
        <li>
            src
            <ul>
                <li>main</li>
            </ul>
        </li>
        <li data-cb-opened>test</li>
    </ul>

    <!-- code view -->
    <pre data-cb-name="MyApp.java" data-cb-package="io.github.jirkasa" data-cb-active><code>package io.github.jirkasa;

public class MyApp {
    public static void main(String[] args) {
        System.out.println("Hello world!");
    }
}</code></pre>

    <!-- code view -->
    <pre data-cb-name="README.txt"><code>This is example app.</code></pre>

    <!-- file -->
    <div data-cb-name="Image.png" data-cb-file="../../static/Image.png" data-cb-folder="assets/img"></div>

    <!-- commands -->
    <script data-cb-commands type="application/json">
        [
            {
                "command": "rename project",
                "name": "code-box-example"
            },
            {
                "command": "add code view highlight",
                "identifier": "README.txt",
                "start": 1
            }
        ]
    </script>
</div>

Additional data attributes for code views and files

In addition to the attributes data-cb-name, data-cb-active, and data-cb-file, code views and files in a project code box can also contain the following data attributes.

In a project code box, it is acceptable to have multiple code views or files with the same data-cb-name attribute because the identifier is composed of both the folder and the name.

Folder structure configuration

If the data-cb-folder attribute is used for a code view or file and the folder does not exist, it will be created. However, if you need to create folders that do not contain any content, you can use a folder structure configuration element. This element allows you to define a specific folder structure, as shown in the following example. The folder structure configuration element is marked with the data-cb-folders attribute. To have a folder opened on initialization, you can mark it with the data-cb-opened attribute.

<ul data-cb-folders>
    <li>
        src
        <ul>
            <li>
                main
                <ul>
                    <li>java</li>
                </ul>
            </li>
        </ul>
    </li>
    <li data-cb-opened>test</li>
</ul>

Commands

A project code box can include a script element with commands to be executed, such as renaming a folder, removing a file, and so on. The script must have its type attribute set to application/json to prevent it from being executed. Commands are written as objects within an array in JSON format, as demonstrated in the following example. Each object should have a command property that specifies the type of command, along with other properties depending on the command type.

<script data-cb-commands type="application/json">
    [
        {
            "command": "rename project",
            "name": "code-box-example"
        },
        {
            "command": "remove folder",
            "folderPath": "src/main"
        },
        {
            "command": "open folder",
            "folderPath": "js/common",
            "openParentFolders": true
        }
    ]
</script>

Usage Example

The following example demonstrates how to create a ProjectCodeBox. Simply instantiate the ProjectCodeBox class by passing a reference to the root element of code box. You can also provide additional options as a second parameter.

<div id="MyProjectCodeBox">
    <ul data-cb-folders>
        <li>
            src
            <ul>
                <li>
                    main
                    <ul>
                        <li>java</li>
                        <li>resources</li>
                        <li>webapp</li>
                    </ul>
                </li>
                <li>
                    test
                    <ul>
                        <li>java</li>
                        <li>resources</li>
                    </ul>
                </li>
            </ul>
        </li>
        <li>target</li>
    </ul>

    <pre data-cb-name="MyApp.java" data-cb-package="io.github.jirkasa" data-cb-active><code>package io.github.jirkasa;

public class MyApp {
    public static void main(String[] args) {
        System.out.println("Hello world!");
    }
}</code></pre>

    <pre data-cb-name="pom.xml"><code>&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"&gt;
    &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
    &lt;groupId&gt;io.github.jirkasa&lt;/groupId&gt;
    &lt;artifactId&gt;example-app&lt;/artifactId&gt;
    &lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;
    &lt;packaging&gt;war&lt;/packaging&gt;
    &lt;name&gt;example-app&lt;/name&gt;
&lt;/project&gt;</code></pre>
</div>

import { ProjectCodeBox } from "@jirkasa/code-box";

new ProjectCodeBox(document.getElementById("MyProjectCodeBox"), {
    minCodeViewLinesCount: 20,
    projectName: "example-app",
    packagesFolderPath: "src/main/java",
    foldersDelimiterForPackages: ".",
    svgSpritePath: "./img/icon-sprite.svg",
    svgSpriteIcons: {
        codeFile: "file",
        file: "file-2",
        download: "download",
        panelOpenButton: "double-arrow-right",
        folderArrow: "arrow-right",
        folder: "folder",
        project: "inventory",
        package: "package"
    }
});

package io.github.jirkasa;

public class MyApp {
    public static void main(String[] args) {
        System.out.println("Hello world!");
    }
}

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>io.github.jirkasa</groupId>
    <artifactId>example-app</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>war</packaging>
    <name>example-app</name>
</project>

If you want to create multiple project code boxes, you can use the ProjectCodeBoxCreator. For more information, refer to the chapter on creators.

Inheritance

Project code boxes have the ability to inherit from other project code boxes. When creating an instance of a ProjectCodeBox, you can pass a parent project code box as the third parameter. The newly created project code box will inherit all code views, files, folders, and packages from its parent code box. Additionally, the new code box can add its own code views or files, delete some, or make other modifications as needed. The following example shows how to create a project code box that inherits from a parent code box.

<div id="CodeBox1">
    <pre data-cb-active data-cb-name="style.css" data-cb-folder="css" data-cb-active><code>h1 {
    font-size: 16px;
    color: red;
}</code></pre>
</div>

<br>

<div id="CodeBox2">
    <pre data-cb-name="main.js" data-cb-folder="js" data-cb-active><code>let x = 1;
let y = 2;

console.log("result: " + (x + y));</code></pre>
</div>

import { ProjectCodeBox } from "@jirkasa/code-box";

const codeBox1 = new ProjectCodeBox(document.getElementById("CodeBox1"), {
    minCodeViewLinesCount: 10,
    svgSpritePath: "./img/icon-sprite.svg",
    projectName: "example-app",
    svgSpriteIcons: {
        codeFile: "file",
        file: "file-2",
        download: "download",
        panelOpenButton: "double-arrow-right",
        folderArrow: "arrow-right",
        folder: "folder",
        project: "inventory",
        package: "package"
    }
});

new ProjectCodeBox(document.getElementById("CodeBox2"), {
    minCodeViewLinesCount: 10,
    svgSpritePath: "./img/icon-sprite.svg",
    svgSpriteIcons: {
        codeFile: "file",
        file: "file-2",
        download: "download",
        panelOpenButton: "double-arrow-right",
        folderArrow: "arrow-right",
        folder: "folder",
        project: "inventory",
        package: "package"
    }
}, codeBox1);

h1 {
    font-size: 16px;
    color: red;
}

let x = 1;
let y = 2;

console.log("result: " + (x + y));

Most of the time, you will likely use ProjectCodeBoxCreator to avoid manually creating each code box and redundantly specifying options.

What is inherited

The following things are inherited:

• code views
• files
• folders
• packages
• folder path for packages
• project name
• createFoldersForPackages option
• foldersDelimiterForPackages option

What is not inherited

The following things are not inherited:

• open/close state of panel
• open/close state of folders
• open/close state of packages
• highlights of code views

Note on packages

The packages of overwritten code views and files are not changed unless a new package is explicitly assigned.

Commands

As mentioned previously, a project code box can include a script element with commands to be executed. The following commands are available:

rename project

Renames project.

Properties

add folder

Creates new folder(s) (if not created yet).

Properties

remove folder

Removes folder and all its contents. This might also remove packages if their folders are removed (if generation of folders for packages is enabled via createFoldersForPackages option).

Properties

rename folder

Renames folder. This can also change (rename) folder for packages and rename packages.

Properties

open folder

Opens folder.

Properties

close folder

Closes folder.

Properties

add package

Creates new package (if it does not exist yet).

Properties

remove package

Removes package.

Properties

rename package

Renames package. This can also rename folders for package if generation of folders is enabled via createFoldersForPackages option.

Properties

open package

Opens package.

Properties

close package

Closes package.

Properties

remove code view

Removes code view from code box.

Properties

rename code view

Changes file name of code view.

Properties

move code view to folder

Moves code view to folder (if folder does not exist, it is created; package is not changed).

Properties

change code view package

Changes package of code view.

Properties

remove code view package

Removes code view from package.

Properties

remove all code views

Removes all code views from code box.

add code view highlight

Adds new highlight to code view.

Properties

remove code view highlight

Removes highlights from code view based on specified range (all intersecting highlights are removed).

Properties

set active code view

Sets code view as active (displays it in code box).

Properties

set no active code view

Displays no code view in code box.

remove file

Removes file from code box.

Properties

rename file

Changes name of file.

Properties

move file to folder

Moves file to folder (if folder does not exist, it is created; package is not changed).

Properties

change file package

Changes package of file.

Properties

remove file package

Removes file from package.

Properties

remove all files

Removes all files from code box.

Options

ProjectCodeBox accepts the following options and all options from the base CodeBox class.

svgSpritePath : string

Default value: undefined

Specifies path to the SVG sprite that contains icons.

svgSpriteIcons : object

Default value: {}

Specifies names of the icons in the SVG sprite in a form of object with the following properties:

• codeFile - name of icon for code view button
• file - name of icon for file button
• download - name of icon that is displayed for button of downloadable file
• panelOpenButton - name of icon for panel open/close button
• folderArrow - name of icon for folder arrow
• folder - name of icon for folder
• project - name of icon for project (root) folder
• package - name of icon for package

// ...
svgSpriteIcons: {
    codeFile: "file",
    file: "file-2",
    download: "download",
    panelOpenButton: "double-arrow-right",
    folderArrow: "arrow-right",
    folder: "folder",
    project: "inventory",
    package: "package"
}
// ...

folderStructureHeading : string

Default value: "Folder structure"

Data attribute alternative: data-cb-folder-structure-heading

Specifies folder structure heading.

packagesHeading : string

Default value: "Packages"

Data attribute alternative: data-cb-packages-heading

Specifies packages heading.

projectName : string

Default value: "unnamed"

Data attribute alternative: data-cb-project-name

Specifies the name of project (root) folder. This option is not used if the code box has parent code box.

packagesFolderPath : string

Default value: "/"

Data attribute alternative: data-cb-packages-folder-path

Specifies path to folder for packages. This option is not used if the code box has parent code box.

defaultPackageName : string

Default value: "default"

Data attribute alternative: data-cb-default-package-name

Specifies name under which the default package should be displayed.

createFoldersForPackages : boolean

Default value: true

Data attribute alternative: data-cb-create-folders-for-packages

Specifies whether folders should be created for packages. This option is not used if the code box has parent code box.

foldersDelimiterForPackages : string

Default value: undefined

Data attribute alternative: data-cb-folders-delimiter-for-packages

Specifies delimiter to be used when creating folders for packages. For example, if the delimiter is "." and the package name is "io.github.jirkasa", folders "io/github/jirkasa" are created. This option is not used if the code box has a parent code box.

folderAnimationSpeed : number

Default value: 200

Data attribute alternative: data-cb-folder-animation-speed

Specifies speed of folder open/close animation (in milliseconds).

folderAnimationEasingFunction : string

Default value: "ease-in-out"

Data attribute alternative: data-cb-folder-animation-easing-function

Specifies CSS easing function for folder open/close animation.

openActiveCodeViewFolderOnInit : boolean

Default value: true

Data attribute alternative: data-cb-open-active-code-view-folder-on-init

Specifies whether folder and its parent folders containing the active code view should be opened on initialization.

openActiveCodeViewPackageOnInit : boolean

Default value: true

Data attribute alternative: data-cb-open-active-code-view-package-on-init

Specifies whether package containing the active code view should be opened on initialization.

preventActiveCodeViewFolderOpenOnInitIfPackage : boolean

Default value: false

Data attribute alternative: data-cb-prevent-active-code-view-folder-open-on-init-if-package

Specifies whether the folder and its parent folders containing the active code view should not be opened on initialization when the code view is within a package. This option overrides openActiveCodeViewFolderOnInit when set to true and the active code view is within a package.

openRootFolderOnInit : boolean

Default value: true

Data attribute alternative: data-cb-open-root-folder-on-init

Specifies whether the project (root) folder should be opened on initialization. This option has effect only in certain situations (openActiveCodeViewFolderOnInit option takes precedence).

openPanelOnInit : boolean

Default value: false

Data attribute alternative: data-cb-open-panel-on-init

Specifies whether the side panel should be opened on initialization.

closePanelOnCodeViewSelect : boolean

Default value: true

Data attribute alternative: data-cb-close-panel-on-code-view-select

Specifies whether the side panel should be closed when code view is selected by clicking on its button.

openPanelButtonAriaLabel : string

Default value: "Open panel"

Data attribute alternative: data-cb-open-panel-button-aria-label

Specifies value of the panel open/close button aria-label attribute when panel is closed.

closePanelButtonAriaLabel : string

Default value: "Close panel"

Data attribute alternative: data-cb-close-panel-button-aria-label

Specifies value of the panel open/close button aria-label attribute when panel is opened.

Methods

ProjectCodeBox has the following methods. Many of these methods are also described in the chapter about the base CodeBox class. However, some of them have a return type that is a subclass of CodeBoxCodeView or CodeBoxFile - specifically, ProjectCodeBoxCodeView or ProjectCodeBoxFile. For clarity, these methods are also listed in this chapter.

appendTo

appendTo(element: HTMLElement): void

Appends code box to element.

Params

detach

detach(): void

Detaches code box from its parent element.

init

init(): void

Initializes code box if it hasn't been initialized yet. When lazy initialization is disabled, the code box is initialized immediately after it is created.

isInitialized

isInitialized(): boolean

Checks whether the code box is initialized.

Returns

addOnInitListener

addOnInitListener(callback: () => void): void

Registeres function to be called when code box is initialized.

Params

addCodeView

addCodeView(identifier: string, codeView: CodeView): boolean

Adds new code view to code box (copy of passed code view is made).

Params

Returns

getCodeViews

getCodeViews(): ProjectCodeBoxCodeView[]

Returns all code views of code box.

Returns

getCodeViewsByFolderPath

getCodeViewsByFolderPath(folderPath: string, includeSubfolders: boolean = false): ProjectCodeBoxCodeView[]

Returns code views in folder.

Params

Returns

getCodeViewsByPackage

getCodeViewsByPackage(packageName : string | null): ProjectCodeBoxCodeView[]

Returns code views in package.

Params

Returns

getCodeView

getCodeView(identifier: string): ProjectCodeBoxCodeView | null

Returns code view based on identifier.

Params

Returns

getCodeViewByFolderPath

getCodeViewByFolderPath(folderPath: string, fileName: string): ProjectCodeBoxCodeView | null

Returns code view based on folder path and name.

Params

Returns

getCodeViewByPackage

getCodeViewByPackage(packageName: string | null, fileName: string): ProjectCodeBoxCodeView | null

Returns code view based on package and name.

Params

Returns

removeCodeView

removeCodeView(identifier: string): boolean

Removes code view from code box.

Params

Returns

removeAllCodeViews

removeAllCodeViews(): void

Removes all code views from code box.

changeCodeViewIdentifier

changeCodeViewIdentifier(identifier: string, newIdentifier: string): boolean

Changes identifier of code view in code box. It can change folder path and name of code view but it never changes package of code view.

Params

Returns

changeCodeViewPackage

changeCodeViewPackage(identifier: string, packageName: string | null, keepFolderPath: boolean): boolean

Changes package of code view.

Params

Returns

removeCodeViewPackage

removeCodeViewPackage(identifier: string): boolean

Removes code view from package.

Params

Returns

getCodeViewPackage

getCodeViewPackage(identifier: string): string | null | undefined

Returns package of code view.

Params

Returns

setActiveCodeView

setActiveCodeView(identifier: string): boolean

Sets code view as active (displays it in code box).

Params

Returns

setNoActiveCodeView

setNoActiveCodeView(): void

Displays no code view in code box.

getActiveCodeView

getActiveCodeView(): ProjectCodeBoxCodeView | null

Returns currently active code view.

Returns

addFile

addFile(identifier: string, downloadLink: string | null): boolean

Adds new file to code box.

Params

Returns

getFiles

getFiles(): ProjectCodeBoxFile[]

Returns all files of code box.

Returns

getFilesByFolderPath

getFilesByFolderPath(folderPath: string, includeSubfolders: boolean = false): ProjectCodeBoxFile[]

Returns files in folder.

Params

Returns

getFilesByPackage

getFilesByPackage(packageName : string | null): ProjectCodeBoxFile[]

Returns files in package.

Params

Returns

getFile

getFile(identifier: string): ProjectCodeBoxFile | null

Returns file based on identifier.

Params

Returns

getFileByFolderPath

getFileByFolderPath(folderPath: string, fileName: string): ProjectCodeBoxFile | null

Returns file based on folder path and name.

Params

Returns

getFileByPackage

getFileByPackage(packageName: string | null, fileName: string): ProjectCodeBoxFile | null

Returns file based on package and name.

Params

Returns

removeFile

removeFile(identifier: string): boolean

Removes file from code box.

Params

Returns

removeAllFiles

removeAllFiles(): void

Removes all files from code box.

changeFileIdentifier

changeFileIdentifier(identifier: string, newIdentifier: string): boolean

Changes identifier of file in code box. It can change folder path and name of file but it never changes package of file.

Params

Returns

changeFilePackage

changeFilePackage(identifier: string, packageName: string | null, keepFolderPath: boolean): boolean

Changes package of file.

Params

Returns

removeFilePackage

removeFilePackage(identifier: string): boolean

Removes file from package.

Params

Returns

getFilePackage

getFilePackage(identifier: string): string | null | undefined

Returns package of file.

Params

Returns

changeFileDownloadLink

changeFileDownloadLink(identifier: string, newDownloadLink: string | null): boolean

Changes download link of file.

Params

Returns

addFolder

addFolder(folderPath: string): void

Creates new folder(s) (if not created yet).

Params

removeFolder

removeFolder(folderPath: string): boolean

Removes folder and all its contents. This might also remove packages if their folders are removed (if generation of folders for packages is enabled via createFoldersForPackages option).

Params

Returns

renameFolder

renameFolder(folderPath: string, newName: string): boolean

Renames folder. This can also change (rename) folder for packages and rename packages.

Params

Returns

openFolder

openFolder(folderPath: string, openParentFolders: boolean = false, animate: boolean = true): void

Opens folder.

Params

closeFolder

closeFolder(folderPath: string, closeChildFolders: boolean = false, animate: boolean = true): void

Closes folder.

Params

folderExists

folderExists(folderPath: string): boolean

Checks whether folder exists.

Params

Returns

isFolderOpened

isFolderOpened(folderPath: string): boolean

Checks whether folder is opened.

Params

Returns

getSubfolderNames

getSubfolderNames(folderPath: string): string[] | null

Returns names of folder subfolders (only direct subfolders).

Params

Returns

addPackage

addPackage(name: string): void

Creates new package (if it does not exist yet).

Params

removePackage

removePackage(name: string, removePackageFoldersAndContents: boolean = true, removeAllCodeViewsAndFiles: boolean = false): boolean

Removes package.

Params

Returns

renamePackage

renamePackage(name: string, newName: string): boolean

Renames package. This can also rename folders for package if generation of folders is enabled via createFoldersForPackages option.

Params

Returns

openPackage

openPackage(packageName: string | null, animate: boolean = true): void

Opens package.

Params

closePackage

closePackage(packageName: string | null, animate: boolean = true): void

Closes package.

Params

packageExists

packageExists(packageName: string): boolean

Checks whether package exists.

Params

Returns

isPackageOpened

isPackageOpened(packageName: string | null): boolean

Checks whether package is opened.

Params

Returns

getPackages

getPackages(): string[]

Returns all packages.

Returns

getPackagesFolderPath

getPackagesFolderPath(): string

Returns path to folder that is currently used for packages.

Returns

changePackagesFolderPathAndRemoveAll

changePackagesFolderPathAndRemoveAll(newPackagesFolderPath: string): void

Sets new folder path for packages and removes all code views, files, folders and packages (everything needs to be removed, when folder path for packages is changed).

Params

getProjectName

getProjectName(): string

Returns project name.

Returns

setProjectName

setProjectName(newName: string): void

Sets new project name.

Params

openPanel

openPanel(): void

Opens panel.

closePanel

closePanel(): void

Closes panel.

isPanelOpened

isPanelOpened(): boolean

Checks whether panel is opened.

Returns

reset

reset(): void

Resets code box to its post-initialization state.

createMemento

createMemento(): CodeBoxMemento

Creates memento (saved state of code box).

Returns

applyMemento

applyMemento(memento: CodeBoxMemento): void

Applies memento (sets code box to the state defined by the provided memento).

Params