$_bx Library Documentation

🔧 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', 'Custom HTML')

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.