CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 4/API
Class

CKEDITOR.plugins.indent.specificDefinition

class
See source

A base class for specific indentation command definitions responsible for handling a pre-defined set of elements i.e. indentlist for lists or indentblock for text block elements.

Commands of this class perform indentation operations and modify the DOM structure. They listen for events fired by CKEDITOR.plugins.indent.genericDefinition and execute defined actions.

NOTE: This is not an editor command. Context-specific commands are internal, for indentation system only.

Filtering

Properties

  • database : Object

    See source

    Stores created markers for the command so they can eventually be purged after the exec function is run.

    Defaults to {}

  • readonly

    enterBr : Boolean

    See source

    Determines whether the editor that the command belongs to has config.enterMode set to CKEDITOR.ENTER_BR.

    CKEDITOR.config.enterMode

    Defaults to false

  • readonly

    indentKey : Object

    See source

    A keystroke associated with this command (Tab or Shift+Tab).

  • readonly

    isIndent : Boolean

    See source

    Determines whether the command belongs to the indentation family. Otherwise it is assumed to be an outdenting command.

    Defaults to false

  • readonly

    jobs : Object

    See source

    An object of jobs handled by the command. Each job consists of two functions: refresh and exec as well as the execution priority.

    • The refresh function determines whether a job is doable for a particular context. These functions are executed in the order of priorities, one by one, for all plugins that registered jobs. As jobs are related to generic commands, refreshing occurs when the global command is firing the refresh event.

      Note: This function must return either CKEDITOR.TRISTATE_DISABLED or CKEDITOR.TRISTATE_OFF.

    • The exec function modifies the DOM if possible. Just like refresh, exec functions are executed in the order of priorities while the generic command is executed. This function is not executed if refresh for this job returned CKEDITOR.TRISTATE_DISABLED.

      Note: This function must return a Boolean value, indicating whether it was successful. If a job was successful, then no other jobs are being executed.

    Sample definition:

    command.jobs = {
    // Priority = 20.
    '20': {
        refresh( editor, path ) {
            if ( condition )
                return CKEDITOR.TRISTATE_OFF;
            else
                return CKEDITOR.TRISTATE_DISABLED;
        },
        exec( editor ) {
            // DOM modified! This was OK.
            return true;
        }
    },
    // Priority = 60. This job is done later.
    '60': {
        // Another job.
    }
};

    For additional information, please check comments for the setupGenericListeners function.

    Defaults to {}

  • readonly

    relatedGlobal : Object

    See source

    The name of the global command related to this one.

Methods

  • execJob( editor, priority ) → Boolean

    See source

    Executes the content-specific procedure if the context is correct. It calls the exec function of a job of the given priority that modifies the DOM.

    Parameters

    editor : editor

    The editor instance this command will be applied to.

    priority : Number

    The priority of the job to be executed.

    Returns

    Boolean

    Indicates whether the job was successful.

  • getContext( node ) → element

    See source

    Checks if the element path contains the element handled by this indentation command.

    Parameters

    node : elementPath

    A path to be checked.

    Returns

    element

  • refreshJob( editor, priority ) → Number

    See source

    Calls the refresh function of a job of the given priority. The function returns the state of the job which can be either CKEDITOR.TRISTATE_DISABLED or CKEDITOR.TRISTATE_OFF.

    Parameters

    editor : editor

    The editor instance this command will be applied to.

    priority : Number

    The priority of the job to be executed.

    Returns

    Number

    The state of the job.

  • private

    setupGenericListeners( command )

    See source

    Attaches event listeners for this generic command. Since the indentation system is event-oriented, generic commands communicate with content-specific commands using the exec and refresh events.

    Listener priorities are crucial. Different indentation phases are executed with different priorities.

    For the exec event:

    • 0: Selection and bookmarks are saved by the generic command.
    • 1-99: Content-specific commands try to indent the code by executing their own jobs (jobs).
    • 100: Bookmarks are re-selected by the generic command.

    The visual interpretation looks as follows:

      +------------------+
  | Exec event fired |
  +------ + ---------+
          |
        0 -<----------+ Selection and bookmarks saved.
          |
          |
       25 -<---+ Exec 1st job of plugin#1 (return false, continuing...).
          |
          |
       50 -<---+ Exec 1st job of plugin#2 (return false, continuing...).
          |
          |
       75 -<---+ Exec 2nd job of plugin#1 (only if plugin#2 failed).
          |
          |
      100 -<-----------+ Re-select bookmarks, clean-up.
          |
+-------- v ----------+
| Exec event finished |
+---------------------+

    For the refresh event:

    • <100: Content-specific commands refresh their job states according to the given path. Jobs save their states in the evt.data.states object passed along with the event. This can be either CKEDITOR.TRISTATE_DISABLED or CKEDITOR.TRISTATE_OFF.

    • 100: Command state is determined according to what states have been returned by content-specific jobs (evt.data.states). UI elements are updated at this stage.

      Note: If there is at least one job with the CKEDITOR.TRISTATE_OFF state, then the generic command state is also CKEDITOR.TRISTATE_OFF. Otherwise, the command state is CKEDITOR.TRISTATE_DISABLED.

    Parameters

    command : command

    The command to be set up.