1.0.0.0 이상

설명

파일 다운로드를 시작한다.

파일을 다운로드하려면 서버에 존재하는 대상의 경로 정보를 얻을 수 있어야 하는데, 가상 파일의 속성을 사용한다.

기본적으로 하나의 가상 파일만 다운로드할 수 있다. 그러므로 flag에 맞는 대상들 중에서 첫번째 파일만 다운로드 대상이 된다. 만일 다중 파일 다운로드(1.1.0.0부터 지원)를 하고자 한다면 useMD 파라미터를 true로 설정하면 다중 파일 다운로드 방식으로 처리가 되며, flag에 맞는 대상 모두가 순차적으로 다운로드 된다.

다운로드는 하려는 가상 파일은 반드시 downUrl 속성에 다운로드할 수 있는 서버 측 주소가 설정되어야 한다. (1.4.1.0 버전부터 url 속성으로도 가능하다.)

대상 경로는 서버의 기능을 사용하여, 반드시 Content-disposition 응답 헤더 값이 attachment 상태이도록 설정되어야 한다.

파일 다운로드의 경우 대상의 존재 유무를 판단하기 위해서 HEAD 메소드 요청을 보내며, HTTP 응답 코드가 오류가 아닌 경우에 다시 다운로드를 수행한다.

<script>
  function onDX5Created(id) {
    var dx = dx5.get(id);
    // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
    dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
    // 다운로드 경로가 있으면 다운로드할 수 있다.
    dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, downUrl: "http://domain/path/common-download.do?key=FID0001" });
  }
  function download(id) {
    // 플래그 값에 따라 다운로드를 수행한다.
    // AUTO: 첫 번째 가상 파일을 다운로드한다.
    // SELECTED: 선택된 대상 중에 첫 번째 가상 파일을 다운로드한다.
    // CHECKED: 체크된 대상 중에 첫 번째 가상 파일을 다운로드한다.
    dx5.get(id).download("AUTO");
  }
  function multidownload(id) {
    // 플래그 값에 따라 다운로드를 수행한다.
    // AUTO: 모든 가상 파일 항목을 다운로드한다.
    // SELECTED: 선택된 가상 파일 항목 모두를 다운로드한다.
    // CHECKED: 체크된 가상 파일 항목 모두를 다운로드한다.
    dx5.get(id).download("AUTO", true);
  }
</script>
<button type="button" onclick="download('component-id');">단일 파일 다운로드</button>
<button type="button" onclick="multidownload('component-id');">다중 파일 다운로드</button>

download 메소드를 사용할 때, 1.0.0.0 버전과 차이점이 존재한다. 단일 파일 다운로드의 경우, 1.0.0.0 버전에서는 flag 값에 해당하는 대상이 downUrl이 명시가 되지 않는 경우, 다운로드가 취소가 되었지만, 1.1.0.0 버전에서는 flag 값에 해당하는 대상이 downUrl이 명시가 되지 않았다면, 다음의 적합한 대상을 찾는다. 그러므로 정확히 지정된 대상을 다운로드하려면, download가 아니라 downloadById를 사용하는 것을 권장한다.

1.1.0.0 버전부터 추가된 다중 파일 다운로드 기능은 플러그인 기술을 사용하지 않고 순수 브라우저의 기능만으로 구현되었다. 플러그인을 사용한 다운로드처럼, 진행창을 제공은 하지만, 브라우저가 최종적으로 파일을 저장하는 단계(제품이 관여할 수 없는)가 존재하기 때문에, 다운로드가 완료되었다하더라도, 브라우저에서 질의하는 메시지들이 보여질 수 있다. 더불어 macOS 환경에서는 Safari 브라우저의 경우 10.1 버전 이상만 지원한다. 그리고 iOS, iPad 환경에서는 Safari 브라우저가 17 버전 이상인 경우 다중 파일 다운로드를 지원(10개 이하의 파일만 가능하다.)한다.

<script>
  function onDX5Created(id) {
    var dx = dx5.get(id);
    // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
    dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
    // 다운로드 경로가 있으면 다운로드할 수 있다.
    dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001" });
  }
  function download(id) {
    // 플래그 값에 따라 다운로드를 수행한다.
    // AUTO: 모든 가상 파일 항목을 다운로드한다.
    // SELECTED: 선택된 가상 파일 항목 모두를 다운로드한다.
    // CHECKED: 체크된 가상 파일 항목 모두를 다운로드한다.
    dx5.get(id).download("AUTO");
  }
</script>
<button type="button" onclick="download('component-id');">다운로드</button>

형식

// 1.1.0.0 이상 
object.download(flag[, useMD]);

파라미터

1.0.0.0 이상

설명

주어진 고유 아이디에 해당하는 가상 파일을 다운로드한다.

파일을 다운로드하려면 서버에 존재하는 대상의 경로 정보를 얻을 수 있어야 하는데, 가상 파일의 속성을 사용한다.

다운로드는 하려는 가상 파일은 반드시 downUrl 속성에 다운로드할 수 있는 서버 측 주소가 설정되어야 한다.(1.4.1.0 버전부터 url 속성으로도 가능하다.)

<script>
  function onDX5Created(id) {
    var dx = dx5.get(id);
    // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
    dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
    // 다운로드 경로가 있으면 다운로드할 수 있다.
    dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, downUrl: "http://domain/path/common-download.do?key=FID0001" });
  }
  function download(id) {
    var dx = dx5.get(id);
    // 두 번째 가상 파일을 선택한다.
    var itemId = dx.getItemId(1);
    dx.downloadById(itemId);
  }
</script>
<button type="button" onclick="download('component-id');">다운로드</button>

다운로드 경로는 서버 측 컴포넌트를 사용하여, 반드시 Content-disposition 응답 헤더 값이 attachment 상태이어야 한다.

더불어 대상의 존재 유무를 판단하기 위해서 HEAD 메소드 요청을 보내며, HTTP 응답 코드가 오류가 아닌 경우에 다시 다운로드를 수행한다.

<script>
  function onDX5Created(id) {
    var dx = dx5.get(id);
    // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
    dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
    // 다운로드 경로가 있으면 다운로드할 수 있다.
    dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001" });
  }
  function download(id) {
    var dx = dx5.get(id);
    // 두 번째 가상 파일을 선택한다.
    var itemId = dx.getItemId(1);
    dx.downloadById(itemId);
  }
</script>
<button type="button" onclick="download('component-id');">다운로드</button>

형식

component.downloadById(id);

파라미터

2.0.0.0 이상

설명

주어진 고유 아이디에 해당하는 가상 파일을 HD 응용프로그램을 사용하여 다운로드한다.

파일을 다운로드하려면 서버에 존재하는 대상의 경로 정보를 얻을 수 있어야 하는데, 가상 파일의 속성을 사용한다.

가상 파일은 url 속성에 다운로드할 수 있는 서버 측 주소가 설정되어야 한다.

1.4.1.0 버전부터 downUrl, url 두 속성을 사용할 수 있다.

<script>
    function onDX5Created(id) {
        var dx = dx5.get(id);
        // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
        dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
        // 다운로드 경로가 있으면 다운로드할 수 있다.
        dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001", chunkSize: 10 });
    }
    function download(id) {
        var dx = dx5.get(id);
        // 두 번째 가상 파일을 선택한다.
        var itemId = dx.getItemId(1);
        dx.downloadByIdToHD(itemId);
    }
</script>
<button type="button" onclick="download('component-id');">다운로드</button>

HD 응용프로그램을 사용하여 다운로드를 할 때에는 다운로드 요청에 대한 서버의 Content-disposition 응답 헤더가 attachement 혹은 inline인 경우와 상관 없이 강제로 파일을 다운로드할 수 있다.

다운로드할 대상과 동일한 이름을 갖는 항목이 이미 존재할 때, 개발자는 이 항목을 추가(중복)하거나 무시할 수 있도록 콜백 함수(duplicated)를 사용할 수 있다.

var dx = dx5.get(id);
// 두 번째 가상 파일을 선택한다.
var itemId = dx.getItemId(1);
dx.downloadByIdToHD(itemId, function (fileName) {
    if (confirm(fileName + " 파일이 이미 존재한다. 그래도 추가하시겠습니까?")) {
        // return 0; 또는 반환값이 없으면 중복과 상관없이 추가한다.
    } else {
        // 무시한다.
        return 1;
    }
});

반환 값에 따른 내부 처리 방식은 다음과 같는다.

• 1: 항목을 추가하지 않는다.
• 2: 항목을 추가하며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 추가된다.
• 3: 항목을 추가하지 않으며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 무시된다.
• 그 외의 값: 항목을 추가한다.

형식

component.downloadByIdToHD(id[, duplicated]);

파라미터

2.0.0.0 이상

설명

HD 응용프로그램을 사용하여 다중 파일 다운로드를 시작한다.

파일을 다운로드하려면 서버에 존재하는 대상의 경로 정보를 얻을 수 있어야 하는데, 가상 파일의 속성을 사용한다.

다운로드는 하려는 가상 파일은 반드시 url 속성에 다운로드할 수 있는 서버 측 주소가 설정되어야 한다.

1.4.1.0 버전부터 downUrl, url 두 속성을 사용할 수 있다.

<script>
    function onDX5Created(id) {
        var dx = dx5.get(id);
        // 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
        dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
        // 다운로드 경로가 있으면 다운로드할 수 있다.
        dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001", chunkSize: 10 });
    }
    function download(id) {
        // 플래그 값에 따라 다운로드를 수행한다.
        // AUTO: 가상 파일들을 다운로드한다.
        // SELECTED: 선택된 가상 파일들을 다운로드한다.
        // CHECKED: 체크된 가상 파일들을 다운로드한다.
        dx5.get(id).downloadToHD("AUTO");
    }
</script>
<button type="button" onclick="download('component-id');">파일 다운로드</button>

특별한 코드 처리없이 "AUTO" 파라미터 값을 가지고 업로드를 처리하려 한다면, 컴포넌트 생성 시점에 btnDownloadToHDAuto 속성 값을 사용하여 자동으로 바인딩하여 사용할 수 있다.

<button id="btn-download" type="button">다운로드</button>
<script>
    dx5.create({
        ...,
        // 파일 다운로드 기능이 자동으로 연결된다.
        btnDownloadToHDAuto: "btn-download"
    });
</script>

btnDownloadToHDAuto 속성 외에, btnDownloadToHDSelected, btnDownloadToHDChecked를 사용할 수 있다.

다운로드할 대상과 동일한 이름을 갖는 항목이 이미 존재할 때, 개발자는 이 항목을 추가(중복)하거나 무시할 수 있도록 콜백 함수(duplicated)를 사용할 수 있다.

var dx = dx5.get(id);
dx.downloadToHD("AUTO", function (fileName) {
    if (confirm(fileName + " 파일이 이미 존재한다. 그래도 추가하시겠습니까?")) {
        // return 0; 또는 반환값이 없으면 중복과 상관없이 추가한다.
    } else {
        // 무시한다.
        return 1;
    }
});

반환 값에 따른 내부 처리 방식은 다음과 같는다.

• 1: 항목을 추가하지 않는다.
• 2: 항목을 추가하며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 추가된다.
• 3: 항목을 추가하지 않으며, 이후 발생하는 중복 건에 대해서 콜백 호출 없이 자동으로 무시된다.
• 그 외의 값: 항목을 추가한다.

버튼에 자동으로 바인딩을 하여 사용할 경우에는 중복 처리를 위한 콜백 함수를 적용할 수 없다.

형식

component.downloadToHD(flag[, duplicated]);

파라미터

2.0.0.0 이상

설명

HD 응용프로그램에 설정된 다운로드 경로를 반환한다.

dx.getDownloadPathOfHD(function (path) {
  // HD 응용프로그램의 다운로드 경로이다.
  console.log(path);
});

HD 응용프로그램을 사용하는 경우에 사용될 메소드들은 대부분 내부적으로 비동기 작업을 수행한다. 비동기를 작업을 수행하기 때문에 반환 값을 받기 전까지 스레드가 대기하지 않으며, 요청에 대한 결과 값을 받기 위해서 콜백 함수를 이용해야 한다.

형식

component.getDownloadPathOfHD(success);

파라미터

2.0.0.0 이상

설명

다운로드 경로를 설정한다.

// 드라이브 문자열로 시작하면 절대 경로가 설정된다.
dx.setDownloadPathOfHD("c:\\temp");
// <home> 문자열로 시작하면 사용자 폴더 하위 경로가 설정된다.
dx.setDownloadPathOfHD("<home>\\temp");
// <doc> 문자열로 시작하면 문서 폴더 하위 경로가 설정된다.
dx.setDownloadPathOfHD("<doc>\\temp");
// <desktop> 문자열로 시작하면 바탕화면 폴더 하위 경로가 설정된다.
dx.setDownloadPathOfHD("<desktop>\\temp");
// <downloads> 문자열로 시작하면 다운로드 폴더 하위 경로가 설정된다. (2.5.0.0 버전부터 지원)
dx.setDownloadPathOfHD("<downloads>\\temp");

만일 다운로드 경로를 변경한 후, 그 변경 값을 바로 알고 싶다면 콜백 함수(success)를 사용해야 한다.

dx.setDownloadPathOfHD("<doc>\\temp", function (path) {
  console.log(path);
});

HD 응용프로그램을 사용하는 경우에 사용될 메소드들은 대부분 내부적으로 비동기 작업을 수행한다. 비동기를 작업을 수행하기 때문에 작업 처리 결과를 받기 전까지 스레드가 대기하지 않으며, 요청에 대한 결과 값을 받기 위해서 콜백 함수를 이용해야 한다.

형식

component.setDownloadPath(path[, success]);

파라미터

1.0.0.0 이상

설명

현재 다운로드 상태 정보를 갖는 객체를 반환한다.

파일이 다운로드 중인 과정에 사용하면, 업로드 상태 정보를 알아낼 수 있다.

이 함수를 사용하여 반환된 객체는 시간에 따라 다른 값을 갖는 것이 아니라, 함수 호출 시점의 상태를 복사한 값만 갖는다.

다운로드하는 과정의 변화를 계속 얻으려면 setTimeout과 같은 함수를 사용해야 한다.

function toggleDownloadStatus(isBegin) {
  function downloadProgress() {			
    var dx = dx5.get("dext5"), 
        out = document.getElementById("downstatus-value"), 
        status = dx.getDownloadStatus();
    out.innerHTML = "" + 
      "name: " + status.currentName + "<br/>" + 
      "speed: " + status.totalSpeed + "(sec)<br/>" + 
      "count(completed/total): " + status.completeCount + "/" + status.totalCount + "<br/>" + 
      "current rate: " + status.currentRate + " % <br/>" + 
      "current size(received/total): " + status.currentReceiveSize + "/" + status.currentSize + " (bytes)<br/>" + 
      "current time(past/remained): " + status.currentTime + "/" + status.remainedCurrentTime + "<br/>" + 
      "total rate: " + status.totalRate + " % <br/>" + 
      "total size(received/total): " + status.totalReceiveSize + "/" + status.totalSize + " (bytes)<br/>" + 
      "total time(past/remained): " + status.totalTime + "/" + status.remainedTotalTime + "<br/>" + 
      "";
    if (window.isDownloading === true) {
      setTimeout(downloadProgress, 1000);
    }
  }
  window.isDownloading = isBegin;
  if (isBegin) downloadProgress();
}

형식

status = component.getDownloadStatus();

반환

다운로드 전송 상태 값을 갖는 객체

다음은 객체가 갖는 속성에 대한 설명이다.

2.0.0.0 이상

설명

HD 응용프로그램의 다운로드 폴더를 변경하기 위해 폴더 선택 다이얼로그 창을 띄웁니다.

여러개 파일을 다운로드하기 때문에, 다운로드할기 전에 다운로드할 위치를 설정해야 한다.

다운로드 위치를 변경하지 않는다면 기본 위치(문서 폴더 하위 DEXTUploadX5 HDM 폴더)가 사용된다.

function changePath(id) {
  var dx = dx5.get(id);
  dx.openDownloadPathDialogOfHD();
}

openDownloadPathDialogOfHD 메소드는 사용자에게 다운로드 경로를 선택할 기회를 주는 용도로 사용된다.

다운로드 경로가 변경이 되면 콜백 함수를 사용하여 변경된 경로를 얻을 수 있다.

function changePath(id) {
  var dx = dx5.get(id);
  dx.openDownloadPathDialogOfHD(function (path) {
    // 변경된 다운로드 경로를 얻을 수 있다.
    console.log(path);
  });
}

형식

component.openDownloadPathDialogOfHD([success]);

파라미터

2.4.0.0 이상

설명

HD 응용프로그램에 설정된 옵션 정보를 콜백 함수로 반환한다.

dx.getOptionsOfHD(function (option) {
  // option 파라미터는 HD 응용프로그램의 옵션 정보를 가지고 있는 JSON 객체이다.
});

옵션 객체는 다음과 같다.

{
	// 파일이 추가되면 프로그램 자동으로 활성화
	autoActivation: true,
	// 파일이 추가되면 자동으로 다운로드를 시작
	autoDownload: true,
	// 파일을 삭제하면 로컬에 남겨진 임시 파일 정보도 함께 삭제
	deleteTemporary: false,
	// 다운로드가 중단된 파일 있을 때, 프로그램이 활성화되면 바로 다운로드 시작
	resumeDownload: true,
	// 파일이 다운로드될 때, 프로그램이 닫히더라도 임시 정보로 남겨지는 항목 대상
	saveStatus: {
		// 대기 또는 중지된 항목
		waitStop: true,
		// 다운로드 중이었던 항목
		downloading: true,
		// 다운로드가 완료된 항목
		complete: true,
		// 오류가 발생한 항목
		error: true
	}
}

형식

component.getOptionsOfHD(success);

파라미터

2.4.0.0 이상

설명

HD 응용프로그램의 옵션을 한 번에 설정한다.

dx.setOptionsOfHD({
	autoActivation: true,
	autoDownload: true,
	deleteTemporary: false,
	resumeDownload: true,
	saveStatus: {
		waitStop: true,
		downloading: true,
		complete: true,
		error: true
	}
}, function () { ... });

형식

component.setOptionsOfHD(option[, success]);

파라미터

{
	// 파일이 추가되면 프로그램 자동으로 활성화
	autoActivation: true,
	// 파일이 추가되면 자동으로 다운로드를 시작
	autoDownload: true,
	// 파일을 삭제하면 로컬에 남겨진 임시 파일 정보도 함께 삭제
	deleteTemporary: false,
	// 다운로드가 중단된 파일 있을 때, 프로그램이 활성화되면 바로 다운로드 시작
	resumeDownload: true,
	// 프로그램이 닫히더라도 유지되는 항목 대상
	saveStatus: {
		// 대기 또는 중지된 항목
		waitStop: true,
		// 다운로드 중이었던 항목
		downloading: true,
		// 다운로드가 완료된 항목
		complete: true,
		// 오류가 발생한 항목
		error: true
	}
}

2.4.0.0 이상

설명

자동 활성화 옵션 값을 설정한다

자동 활성화란 다운로드 하고자 하는 파일 항목을 HD 응용프로그램에 등록했을 때, HD 응용 프로그램을 활성 상태로 바꾸는 것을 말한다. 이 값이 true이면, 숨겨져 있던 응용 프로그램이 창 모드로 보이게 된다.

// 자동 활성화 옵션을 true로 변경한다.
dx.setAutoActivationOptionOfHD(true, function () {
    ...
});

형식

component.setAutoActivationOptionOfHD(value[, success]);

파라미터

2.4.0.0 이상

설명

자동 다운로드 옵션 값을 설정한다.

자동 다운로드란 다운로드 하고자 하는 파일 항목을 HD 응용프로그램에 등록했을 때, HD 응용 프로그램을 대상을 바로 다운로드하는 것을 말한다.

// 자동 다운로드 옵션을 true로 변경한다.
dx.setAutoDownloadOptionOfHD(true, function () {
    ...
});

형식

component.setAutoDownloadOptionOfHD(value[, success]);

파라미터

2.4.0.0 이상

설명

임시 파일 삭제 옵션 값을 설정한다.

임시 파일 삭제란 응용 프로그램에서 다운로드 항목들을 삭제할 때, 항목의 임시 파일도 함께 삭제하는 것을 말한다. 파일 다운로드을 시작하고 난 후, 다운로드가 완료되지 않으면 항상 임시 파일이 남아있다.

// 임시 파일 삭제 옵션을 true로 변경한다.
dx.setDeleteTemporaryOptionOfHD(true, function () {
    ...
});

형식

component.setDeleteTemporaryOptionOfHD(value[, success]);

파라미터

2.4.0.0 이상

설명

재(다시) 다운로드 옵션 값을 설정한다.

재(다시) 다운로드란 다운로드가 완료되지 않은 항목이 있는 상태에서 프로그램이 종료된 후, 다시 프로그램이 실행이 되면, 완료되지 않은 대상 파일을 자동으로 다운로드한다.

// 재(다시) 다운로드 옵션을 true로 변경한다.
dx.setResumeDownloadOptionOfHD(true, function () {
    ...
});

형식

component.setResumeDownloadOptionOfHD(value[, success]);

파라미터

2.4.0.0 이상

설명

종료 후 유지 대상 옵션 값을 설정한다.

종료 후 유지 대상이란 프로그램이 종료된 후, 다시 프로그램이 실행이 되었을 때, 유지할 항목을 가리킨다.

// 종료 후 유지 대상을 변경한다.
dx.setSaveStatusOptionOfHD(15, function () {
    ...
});

downloading 값(2)이 누락된다면, 재(다시) 다운로드 옵션 설정에 영향을 받는 항목이 없기 때문에, 자동으로 다운로드할 항목이 유지되지 않는다.

형식

component.setSaveStatusOptionOfHD(value[, success]);

파라미터

1.1.0.0 이상

설명

파일 다운로드를 중지한다.

DEXTUploadX5는 컴포넌트 자체에 다운로드를 중지하는 버튼이나 GUI 요소가 없다.

대신 스크립트를 사용하여 중지할 수 있도록 함수를 제공하고 있다.

<button type="button" onclick="stop('component-id');">중지</button>
<script>
function stop(id) {
  dx5.get(id).stopDownloading();
}
</script>

컴포넌트 생성 시점에 btnStopDownloading 속성 값을 사용하여 자동으로 바인딩하여 사용할 수 있다.

<button id="btn-stop-downloading" type="button">중지</button>
<script>
  dx5.create({
    ...,
    // 다운로드 중지 기능이 자동으로 연결된다.
    btnStopDownloading: "btn-stop-downloading"
  });
</script>

다중 파일 다운로드 작업만 중단할 수 있다. downloadById 혹은 다운로드 아이콘을 사용하여 대상을 다운로드하는 경우에는 stopDownloading 함수를 사용해도 작업이 중단되지 않는다.

형식

component.stopDownloading();