$_bx Library Documentation

The $_bx library is the core JavaScript API for coob.app plugin development. It provides a comprehensive set of methods for plugin-state management, UI interactions, file uploads, messaging, and sys

---

🔧 Core Properties

state

• Type: Object

• Description: The main plugin state object containing all plugin data

• Usage: $_bx.state.propertyName

global

• Type: Object

• Description: Global system state including user info, answer status, and UI controls

• Properties:

  • answerRequired: Boolean - whether answer is required

  • assignmentRequired: Boolean - whether assignment is required

  • hasAnswer: Boolean - whether answer is present

  • answerMessage: String - feedback message

  • user: Object - user information (id, firstName, lastName, email, avatar)

  • saveButtonEnabled: Boolean - save button state

---

📊 State Management Methods

getState()

• Returns: Object - complete plugin state

• Description: Retrieves the current plugin state

• Usage: const state = $_bx.getState()

get(key)

• Parameters: key (String) - dot-notation path to state property

• Returns: Any - value at the specified path

• Description: Gets a nested state property using dot notation

• Usage: const value = $_bx.get('nested.property')

push(key, value)

• Parameters:

  • key (String) - state property name

  • value (Any) - value to set

• Returns: Promise - event emission promise

• Description: Sets a state property and emits change events

• Events: before_push, change_${key}, after_push

• Usage: $_bx.push('title', 'New Title')

clean(key)

• Parameters: key (String) - state property name

• Returns: Promise - event emission promise

• Description: Clears a state property by setting it to empty string

• Events: before_clean, after_clean

• Usage: $_bx.clean('content')

async saveState()

• Returns: Promise<void>

• Description: Saves the current state to the system (syllabus mode only)

• Events: before_save_state, after_save_state

• Usage: await $_bx.saveState()

putState()

• Description: Sends state to parent system with settings

• Events: before_put_state, after_put_state

• Usage: $_bx.putState()

---

⚙️ Settings Management

getSettings(key = null)

• Parameters: key (String, optional) - specific setting key

• Returns: Object|Any - settings object or specific setting value

• Description: Retrieves plugin settings from state._settings

• Usage:

  const allSettings = $_bx.getSettings();
  const specificSetting = $_bx.getSettings('theme');

---

🎯 Answer & Assessment Methods

isCorrect()

• Returns: Boolean - whether the answer is correct

• Description: Checks if the current answer is marked as correct

• Usage: if ($_bx.isCorrect()) { ... }

answerSubmit()

• Returns: Promise<Object> - submission result

• Description: Submits the current answer for evaluation

• Events: before_submit, after_submit

• Usage:

  try {
    const result = await $_bx.answerSubmit();
    console.log('Submission successful:', result);
  } catch (error) {
    console.error('Submission failed:', error);
  }

isAnswerRequired()

• Returns: Boolean - whether answer is required

• Description: Checks if the plugin requires an answer

• Usage: if ($_bx.isAnswerRequired()) { ... }

isAssignmentRequired()

• Returns: Boolean - whether assignment is required

• Description: Checks if the plugin requires an assignment submission

• Usage: if ($_bx.isAssignmentRequired()) { ... }

hasAnswer()

• Returns: Boolean - whether answer is present

• Description: Checks if user has provided an answer

• Usage: if ($_bx.hasAnswer()) { ... }

answerMessage()

• Returns: String - feedback message

• Description: Gets the current answer feedback message

• Usage: const message = $_bx.answerMessage()

parseMessage()

• Returns: Object - parsed message with type and content

• Description: Parses answer message to extract type and content

• Returns: {type: 'success|feedback|wrong|info', content: String}

• Usage: const parsed = $_bx.parseMessage()

isPendingApproval()

• Returns: Boolean - whether answer is pending approval

• Description: Checks if answer requires manual approval

• Usage: if ($_bx.isPendingApproval()) { ... }

---

👤 User & System Information

getUser()

• Returns: Object - user information

• Description: Gets current user information

• Properties: {id, firstName, lastName, email, avatar}

• Usage: const user = $_bx.getUser()

getComponentID()

• Returns: String - component identifier

• Description: Gets the current component ID

• Usage: const id = $_bx.getComponentID()

getResponseId()

• Returns: String - response identifier

• Description: Gets the current response ID

• Usage: const responseId = $_bx.getResponseId()

mode()

• Returns: String - 'light' or 'dark'

• Description: Gets current theme mode

• Usage: const mode = $_bx.mode()

language()

• Returns: String - language code (e.g., 'en', 'ru')

• Description: Gets current language setting

• Usage: const lang = $_bx.language()

isSyllabus()

• Returns: Boolean - whether in syllabus mode

• Description: Checks if component is in syllabus/editing mode

• Usage: if ($_bx.isSyllabus()) { ... }

---

🎨 Theme & UI Methods

isDark()

• Returns: Boolean - whether dark theme is active

• Description: Checks if dark mode is enabled

• Usage: if ($_bx.isDark()) { ... }

isLight()

• Returns: Boolean - whether light theme is active

• Description: Checks if light mode is enabled

• Usage: if ($_bx.isLight()) { ... }

setSaveButtonEnabled(value)

• Parameters: value (Boolean) - enable/disable save button

• Description: Controls the save button state

• Usage: $_bx.setSaveButtonEnabled(false)

isSaveButtonEnabled()

• Returns: Boolean - save button state

• Description: Checks if save button is enabled

• Usage: if ($_bx.isSaveButtonEnabled()) { ... }

---

📤 Messaging & Communication

sendMessage(e)

• Parameters: e (String|Object) - message to send

• Description: Sends message to parent window

• Usage: $_bx.sendMessage(JSON.stringify({type: 'custom', data: 'value'}))

event()

• Returns: EventEmitter - event emitter instance

• Description: Gets the event emitter for custom events

• Usage:

  $_bx.event().on('custom_event', (data) => {
    console.log('Custom event:', data);
  });
  $_bx.event().emit('custom_event', {data: 'value'});

---

📁 File Upload Methods

uploadFile(blob, onProgress, originalFileName)

• Parameters:

  • blob (Blob) - file to upload

  • onProgress (Function, optional) - progress callback

  • originalFileName (String, optional) - original filename

• Returns: Promise<Object> - upload result

• Description: Uploads a file and returns file information

• Usage:

  const result = await $_bx.uploadFile(fileBlob, (progress) => {
    console.log('Upload progress:', progress);
  }, 'document.pdf');
  // Returns: {fileURL, fileSize, fileID}

uploadImage(blob)

• Parameters: blob (Blob) - image file to upload

• Returns: Promise<String> - image URL

• Description: Uploads an image and returns the URL

• Usage: const imageUrl = await $_bx.uploadImage(imageBlob)

uploadVideo(blob, onProgress) ⚠️ DEPRECATED

• Parameters:

  • blob (Blob) - video file to upload

  • onProgress (Function, optional) - progress callback

• Returns: Promise<Object> - upload result

• Description: Uploads a video (deprecated, use uploadTVideo)

• Usage: const result = await $_bx.uploadVideo(videoBlob)

uploadTVideo(blob, mimeType, onProgress)

• Parameters:

  • blob (Blob) - video file to upload

  • mimeType (String) - video MIME type

  • onProgress (Function, optional) - progress callback

• Returns: Promise<Object> - upload result

• Description: Uploads a video with MIME type specification

• Usage:

  const result = await $_bx.uploadTVideo(videoBlob, 'video/mp4', (progress) => {
    console.log('Video upload progress:', progress);
  });
  // Returns: {videoURL, thumbnail, videoID}

fetchFile(fileId)

• Parameters: fileId (String) - file identifier

• Returns: Promise<Object> - file information

• Description: Retrieves file information by ID

• Usage: const file = await $_bx.fetchFile('file_123')

---

🖥️ UI & Display Methods

refreshHeight()

• Description: Automatically adjusts iframe height based on content

• Usage: $_bx.refreshHeight()

fixView()

• Description: Requests view fix from parent system

• Usage: $_bx.fixView()

contentLoaded()

• Description: Notifies system that content has loaded

• Usage: $_bx.contentLoaded()

scroll(scrollTop)

• Parameters: scrollTop (Number) - scroll position

• Description: Sends scroll position to parent system

• Usage: $_bx.scroll(500)

---

💬 Message Box & Modal Methods

showMessageBox(variant, message)

• Parameters:

  • variant (String) - 'success', 'error', 'warning', 'info'

  • message (String) - message text

• Description: Shows a message box with specified variant

• Usage: $_bx.showMessageBox('success', 'Operation completed!')

showModal(title, message)

• Parameters:

  • title (String) - modal title

  • message (String) - modal message

• Description: Shows a modal dialog

• Usage: $_bx.showModal('Confirm', 'Are you sure?')

dangerouslyShowModal(title, html)

• Parameters:

  • title (String) - modal title

  • html (String) - HTML content

• Description: Shows a modal with custom HTML content

• Usage: $_bx.dangerouslyShowModal('Custom', '<div>Custom HTML</div>')

showSuccessMessage(message)

• Parameters: message (String) - success message

• Description: Shows a success message box

• Usage: $_bx.showSuccessMessage('Saved successfully!')

showErrorMessage(message)

• Parameters: message (String) - error message

• Description: Shows an error message box and throws error

• Usage: $_bx.showErrorMessage('Operation failed!')

showWarningMessage(message)

• Parameters: message (String) - warning message

• Description: Shows a warning message box

• Usage: $_bx.showWarningMessage('Please check your input')

showInfoMessage(message)

• Parameters: message (String) - info message

• Description: Shows an info message box

• Usage: $_bx.showInfoMessage('Please wait...')

---

⚙️ Settings & Configuration

isShowSettings()

• Returns: Boolean - whether settings dialog should be shown

• Description: Checks if plugin has settings configuration

• Usage: if ($_bx.isShowSettings()) { ... }

showSettings()

• Description: Opens the settings dialog (syllabus mode only)

• Usage: $_bx.showSettings()

showAbout()

• Description: Shows plugin information dialog (syllabus mode only)

• Usage: $_bx.showAbout()

---

🔄 System Control Methods

reset()

• Description: Resets the plugin state (syllabus mode only)

• Usage: $_bx.reset()

_doubleClickEdit()

• Description: Triggers double-click edit mode

• Usage: $_bx._doubleClickEdit()

_onClick()

• Description: Triggers click event

• Usage: $_bx._onClick()

---

⏰ Lifecycle & Ready Methods

onReady(callback)

• Parameters: callback (Function) - function to execute when ready

• Description: Executes callback when DOM and data are ready

• Usage:

  $_bx.onReady((element) => {
    console.log('Plugin is ready:', element);
  });

waitForElement(elementId, callback)

• Parameters:

  • elementId (String) - element ID to wait for

  • callback (Function) - function to execute when element is found

• Description: Waits for specific element to appear in DOM

• Usage:

  $_bx.waitForElement('my-element', (element) => {
    console.log('Element found:', element);
  });

---

📝 Usage Examples

Basic State Management

// Get state
const state = $_bx.getState();

// Set state property
$_bx.push('title', 'My Plugin Title');

// Get nested property
const content = $_bx.get('content.text');

// Save state
await $_bx.saveState();

File Upload

// Upload file with progress
const fileInput = document.getElementById('file-input');
const file = fileInput.files[0];

if (file) {
  try {
    const result = await $_bx.uploadFile(file, (progress) => {
      console.log(`Upload progress: ${progress}%`);
    });
    console.log('File uploaded:', result.fileURL);
  } catch (error) {
    console.error('Upload failed:', error);
  }
}

Answer Submission

// Submit answer
try {
  const result = await $_bx.answerSubmit();
  if ($_bx.isCorrect()) {
    $_bx.showSuccessMessage('Correct answer!');
  } else {
    const message = $_bx.answerMessage();
    $_bx.showInfoMessage(message);
  }
} catch (error) {
  $_bx.showErrorMessage('Submission failed');
}

Event Handling

// Listen for state changes
$_bx.event().on('change_title', (data) => {
  console.log('Title changed from', data.old_value, 'to', data.new_value);
});

// Listen for before save
$_bx.event().on('before_save_state', (data) => {
  console.log('Saving state:', data);
});

Theme Detection

// Check theme and apply styles
if ($_bx.isDark()) {
  document.body.classList.add('dark-theme');
} else {
  document.body.classList.add('light-theme');
}

// Check language
const lang = $_bx.language();
if (lang === 'ru') {
  // Apply Russian translations
}

---

⚠️ Important Notes

1. Syllabus Mode: Some methods only work in syllabus/editing mode (isSyllabus() returns true)

2. Async Operations: File uploads and answer submission are asynchronous

3. Error Handling: Always wrap async operations in try-catch blocks

4. Event Cleanup: Remove event listeners when components are destroyed

5. Height Management: Call refreshHeight() after dynamic content changes

6. State Validation: Validate state before saving or submitting

---

🔄 Version History

• Current Version: 1.0

• Last Updated: 2024

• Deprecated Methods: uploadVideo() - use uploadTVideo() instead

---

This documentation covers all public methods and properties of the $_bx library. For internal implementation details, refer to the source code.