Previewing Changes#

This guide shows how to see what an edit would do before you commit it. It covers previewing a drag or a resize, keeping previews in sync with the project's baseline, checking the resource load a change would cause, and trying multi-step edits or a leveling run on a copy of the project.

How previews work#

A solved Project holds one accepted baseline: the dates from its last solve or level. Every preview starts from that baseline.

Project#preview(changes, options) copies the baseline, applies a SchedulingChanges value to the copy and schedules it. When the call returns, the copy is gone. The project stays as it was, so you can call preview as often as the UI needs, for example on every mouse move during a drag.

You get back a regular ScheduleResult:

updates are relative to the baseline. They list the tasks the change would move and the tasks the change itself touched, the same way the solve(null, …) after an apply reports them. An empty change set gives empty updates.
conflicts, cycles and notes describe the previewed state. A preview can show the cycle a new link would create, and the project never holds that cycle.
baselineId names the baseline the preview read.

A preview differs from apply in two ways. It isn't partial: if any operation in the change set is invalid, the whole call throws InputException for the first rejected operation, with its path and message. It also needs a clean, solved baseline. Before the first solve, and after any apply until the next solve, it throws ProjectException with code NO_BASELINE.

For a change that takes more than one step, or for a level run, use Project#copy() instead. A copy is O(1): it shares state with the original, and the first edit on either side gives that side its own data. Edit, solve or level the copy, and the original stays as it was.

You want to see	Use
The effect of one change set (a drag, a resize, a new link)	`preview`
The load a change would put on resources	`preview` with `PreviewOptions.profile`
Several edits in a row, each solved	`copy()`, then `apply` + `solve(null, …)` on the copy
What leveling would do	`copy()`, then `level` on the copy

Previewing an edit#

Build the edit as a SchedulingChanges, the same value you'd pass to apply, and pass it to preview.

import java.util.List;
import org.dhtmlx.plen.*;

public class PreviewDrag {
  static Moment day(int d) {
    return Moment.fromYmdHm(2026, 1, d, 0, 0);
  }

  static TaskData task(String id, int start, double duration) {
    return new TaskData(Id.str(id)).withStartDate(day(start)).withDuration(duration);
  }

  public static void main(String[] args) throws Exception {
    ProjectData data = new ProjectData()
        .withTasks(List.of(task("a", 1, 2.0), task("b", 1, 1.0)))
        .withLinks(List.of(new LinkData()
            .withId(Id.str("ab")).withSource(Id.str("a")).withTarget(Id.str("b"))));
    // All time is working time: plain day arithmetic, no weekends.
    data.config.useCalendars = false;

    Project project = new Project();
    ScheduleResult solved = project.solve(data, new SolveOptions());

    // The user drags task "b" to January 5.
    SchedulingChanges drag = new SchedulingChanges();
    drag.tasks.update.add(new TaskUpdate(Id.str("b")).withStartDate(Patch.of(day(5))));

    ScheduleResult preview = project.preview(drag, new PreviewOptions());
    for (Mutation update : preview.updates) {
      System.out.println("task " + update.id + ": " + update.startDate + " .. " + update.endDate);
    }

    // The project still holds the solved dates: "b" starts on January 3.
    ScheduleResult current = project.solve(null, new SolveOptions());
    System.out.println("unchanged: " + (current == solved));
  }
}

The solve puts b right after a, on January 3. The preview prints task b: 2026-01-05 00:00 .. 2026-01-06 00:00. The project doesn't change: the next solve(null, …) returns the cached result of the first solve, the same object, so the last line prints unchanged: true.

When the user drops the task, send the same SchedulingChanges to apply and then call solve(null, …). See Data Updates.

PreviewOptions takes the same diagnostic switches as SolveOptions:

withSubtree(new Subtree(id)) previews only one branch.
withReasons(true) adds a Reason to each update, which tells you why a task would move.
withAnalytics(...) adds the critical path and slack of the previewed state.

Previews stay sparse: there's no includeUnchanged option. The full list is on the PreviewOptions reference.

Guarding with baseline tokens#

A UI that previews in the background can hit a race. Another request applies an edit or reloads the data, and the preview now runs against a baseline the user never saw. Baseline tokens catch this.

Every solve and level result carries baselineId, an opaque token for the accepted baseline. Pass it back with PreviewOptions.withBaselineId(...) (or in SchedulingChanges.baselineId). If the token no longer names the current baseline, preview throws ProjectException with code STALE_BASELINE instead of returning dates for the wrong state.

import java.util.List;
import org.dhtmlx.plen.*;

public class GuardedPreview {
  public static void main(String[] args) throws Exception {
    ProjectData data = new ProjectData()
        .withTasks(List.of(new TaskData(Id.str("a"))
            .withStartDate(Moment.fromYmdHm(2026, 1, 1, 0, 0))
            .withDuration(2.0)));
    data.config.useCalendars = false;

    Project project = new Project();
    SolveOptions options = new SolveOptions();
    ScheduleResult loaded = project.solve(data, options);

    // The UI keeps the token of the dates it shows.
    String shown = loaded.baselineId;

    SchedulingChanges resize = new SchedulingChanges();
    resize.tasks.update.add(new TaskUpdate(Id.str("a")).withDuration(Patch.of(3.0)));

    PreviewOptions guarded = new PreviewOptions().withBaselineId(shown);
    ScheduleResult preview = project.preview(resize, guarded);
    // A preview reports the baseline it read, so its token works for the next preview too.
    System.out.println("same token: " + preview.baselineId.equals(shown));

    // Meanwhile, another edit is committed.
    project.apply(resize);

    // Until the next solve there is no baseline to preview against.
    try {
      project.preview(resize, new PreviewOptions());
    } catch (ProjectException e) {
      System.out.println(e.code); // NO_BASELINE
    }

    ScheduleResult latest = project.solve(null, options);

    // The old token no longer names the baseline.
    try {
      project.preview(resize, guarded);
    } catch (ProjectException e) {
      if (e.code != ProjectError.STALE_BASELINE) throw e;
      // Refresh the view from `latest`, then preview with its token.
      project.preview(resize, new PreviewOptions().withBaselineId(latest.baselineId));
    }
  }
}

A few rules for tokens:

Take the token from the latest solve or level result. A preview result carries the same token it read, so a chain of previews during one drag can reuse it.
The token changes whenever the data changes: new data, an apply, a solve that moves dates, leveling edits.
Tokens are opaque strings. Don't parse them, store them across runs or compare them between processes. The same data can get a new token on a repeat run.
preview checks PreviewOptions.baselineId and SchedulingChanges.baselineId separately. Leave both null to skip the check.

For how to handle STALE_BASELINE and the other project errors, see Error handling.

Preview with load#

Set PreviewOptions.profile to a ProfileQuery to see the resource load a change would cause. The result then has profile, the same per-bucket load and capacity that loadProfile returns, but computed on the previewed dates. Use it to show a resource histogram while the user drags a task.

import java.util.List;
import org.dhtmlx.plen.*;

public class PreviewLoad {
  static Moment day(int d) {
    return Moment.fromYmdHm(2026, 1, d, 0, 0);
  }

  static TaskData task(String id, int start, double duration) {
    return new TaskData(Id.str(id)).withStartDate(day(start)).withDuration(duration);
  }

  static AssignmentData assign(String task) {
    return new AssignmentData()
        .withTask(Id.str(task)).withResource(Id.str("dev")).withValue(1.0);
  }

  public static void main(String[] args) throws Exception {
    ProjectData data = new ProjectData()
        .withTasks(List.of(task("a", 1, 2.0), task("b", 3, 1.0)))
        .withResources(List.of(new ResourceData().withId(Id.str("dev")).withCapacity(1.0)))
        .withAssignments(List.of(assign("a"), assign("b")));
    data.config.useCalendars = false;

    Project project = new Project();
    project.solve(data, new SolveOptions());

    // Drag "b" one day earlier, onto the last day of "a".
    SchedulingChanges drag = new SchedulingChanges();
    drag.tasks.update.add(new TaskUpdate(Id.str("b")).withStartDate(Patch.of(day(2))));

    PreviewOptions options = new PreviewOptions()
        .withProfile(new ProfileQuery(day(1), day(5)).withTasks(ProfileTasks.OVER));
    ScheduleResult preview = project.preview(drag, options);

    if (preview.profile != null) {
      for (ResourceLoad resource : preview.profile.resources) {
        for (LoadBucket bucket : resource.buckets) {
          if (bucket.load > bucket.capacity) {
            System.out.println(resource.resource + " overloaded at " + bucket.start + ": "
                + bucket.load + " of " + bucket.capacity + " " + bucket.tasks);
          }
        }
      }
    }
  }
}

Both tasks need dev on January 2, so that bucket's load goes over its capacity of 1. With ProfileTasks.OVER, each overloaded bucket also lists the tasks that share it.

The query covers buckets that start in [from, to). By default it reports every resource, and the bucket size (basis) comes from config.durationUnit. Narrow it with withResources(...), or set withBasis(...). ProfileQuery has no baselineId of its own: the preview checks PreviewOptions.baselineId. Every preview also reports overallocations when the project has assignments, so you can skip the profile if you only need the overloaded windows. See Resource load and the ProfileQuery reference.

Copying a project#

preview takes one change set. To see the result of several edits in a row, each one solved before the next, copy the project and work on the copy.

import java.util.List;
import org.dhtmlx.plen.*;

public class DraftCopy {
  static Moment day(int d) {
    return Moment.fromYmdHm(2026, 1, d, 0, 0);
  }

  static TaskData task(String id, int start, double duration) {
    return new TaskData(Id.str(id)).withStartDate(day(start)).withDuration(duration);
  }

  static SchedulingChanges resize(String id, double duration) {
    SchedulingChanges changes = new SchedulingChanges();
    changes.tasks.update.add(new TaskUpdate(Id.str(id)).withDuration(Patch.of(duration)));
    return changes;
  }

  public static void main(String[] args) throws Exception {
    ProjectData data = new ProjectData()
        .withTasks(List.of(task("a", 1, 2.0), task("b", 1, 1.0)))
        .withLinks(List.of(new LinkData()
            .withId(Id.str("ab")).withSource(Id.str("a")).withTarget(Id.str("b"))));
    data.config.useCalendars = false;

    SolveOptions options = new SolveOptions();
    Project project = new Project();
    project.solve(data, options);

    // A cheap copy: it shares state with `project` until one of them is edited.
    Project draft = project.copy();
    draft.apply(resize("a", 4.0));
    draft.solve(null, options);
    draft.apply(resize("b", 3.0));
    ScheduleResult outcome = draft.solve(null, options);

    for (Mutation update : outcome.updates) {
      System.out.println("draft task " + update.id + ": " + update.startDate + " .. " + update.endDate);
    }

    // The original is untouched and still previews against its own baseline.
    boolean clean = project.preview(new SchedulingChanges(), new PreviewOptions()).updates.isEmpty();
    System.out.println("original unchanged: " + clean);

    // The user accepts the draft: keep it as the project.
    project = draft;
  }
}

Edits on one copy never affect the other. The copy is a full Project with its own baseline, cache and baselineId, so you can preview it, level it, evaluate against it or keep editing it. To accept the draft, replace the original with it, or replay the same changes on the original with apply. To discard it, drop the reference.

Copy before level too. level accepts the leveled dates as the project's new baseline, so running it on a copy is how you show the user a leveling proposal before committing it:

static void levelingProposal(Project project) {
  Project draft = project.copy();
  LevelingResult leveled = draft.level(new LevelingOptions());
  for (Mutation update : leveled.schedule.updates) {
    System.out.println("task " + update.id + " delay " + update.levelingDelay);
  }
}

The step-by-step version is in Preview leveling. To compare several alternative change sets with scores, use evaluate instead. It works on disposable copies internally. See Evaluating alternatives.

Copies also help with threads. A Project isn't synchronized, and even copy() updates sharing flags on the original. To use one project from several threads, guard it with a lock, or make one copy per thread on a single thread and hand each thread its own. See Share a project between threads.