yona-projects / yona star
Yi EungJun 2013-02-27
doc: Import technical documents from Dropbox.
@52f12f3de1560e5bb6eba3535dce9e6c519d1d42
 
52f12f3
docs/technical/markdown.md (added)
+++ docs/technical/markdown.md
@@ -0,0 +1,19 @@
+This document describes how to enable markdown support.
+* Use a textarea as a markdown editor.
+* Render plaintext written in markdown syntax.
+
+Usage
+-----
+
+First, Set `markdown` attribute on the HTML element to be used as an editor
+
+    <textarea markdown></textarea>
+
+or be rendered.
+
+    <div markdown>@issue.body</div>
+
+Then call @views.html.markdown in your scala template, to enable the markdown
+support.
+
+    @views.html.markdown()
 
52f12f3
docs/technical/name-validation.md (added)
+++ docs/technical/name-validation.md
@@ -0,0 +1,52 @@
+URL의 path segment로 사용되는 상황에 대한 고려
+==============================================
+
+다음과 같이 URL의 path segment가 될 수 있는 이름들은,
+
+* 프로젝트 이름
+* 사용자 이름
+
+알파벳, 숫자, `-`,  `.`,  `_`,  `~` 만으로 구성하는 것을 권장한다.
+
+    name  = ALPHA / DIGIT / "-" / "." / "_" / "~"
+
+왜 그래야 하는가
+----------------
+
+path segment가 될 수 있는 이름(사용자 이름, 프로젝트 이름 등)에 `/` 이나 `?` 같은 예약된 문자를 사용하면 [percent encoding](http://tools.ietf.org/html/rfc3986#section-2.1)이 되는 것을 피할 수 없다.
+
+예를 들어 프로젝트 이름이 "엔포지" 라면, 프로젝트에 대한 url은 다음과 같이 만들어 질 것이다.
+
+    http://nforge.com/foo/%EC%97%94%ED%8F%AC%EC%A7%80
+
+이렇게 되면 아래와 같은 단점이 있다.
+
+* nforge에서 디코딩을 빼먹으면 버그를 유발하게 됨
+* nforge를 이용해 뭔가를 만들어보려는 개발자 입장에서도 percent encoding이 되는 상황을 고려해야 하는 것은 불편함
+* 보기도 좋지 않음
+
+예외
+----
+
+첨부파일 이름은 통제하기 어려우니 모든 문자를 사용할 수 있도록 허용.
+
+파일 이름이나 디렉토리 이름이 될 수 있는 상황에 대한 고려
+=========================================================
+
+다음과 같이 파일이름이나 디렉토리 이름이 될 수 있는 모든 이름들은,
+
+* 프로젝트 이름
+* 사용자 이름
+* 첨부파일 이름
+
+중복 방지를 위한 이름 비교시 반드시 case insensitive 하게 비교해야 한다.
+
+왜 그래야 하는가
+----------------
+
+대소문자를 구분하지 않는 파일시스템(HFS+ 등)에서도 잘 동작하게 하기 위해
+
+주의
+----
+
+비교할때만 case insensitive하게 비교하고, 실제로 저장하거나 사용자에게 보여줄 때는 대소문자를 구분할 것.
 
52f12f3
docs/technical/uploader.md (added)
+++ docs/technical/uploader.md
@@ -0,0 +1,88 @@
+This document describes how to use Uploader and Downloader.
+
+Uploader
+--------
+
+This allows users to upload files and attach them to a specific resource(issue,
+post, comment, ...).
+
+#### Usage
+
+First of all, uploader module should be loaded.
+
+    <script src="@getJSLink("uploader")" type="text/javascript"></script>
+
+Call fileUploader javascript function to activate Uploader. The function
+requires two three arguments -- a HTML element object wrapped by jQuery in
+which upload form will be rendered, textarea in which a link to a uploaded file
+will be added, and the url to files.
+
+You can get the url using "@routes.AttachmentApp.newFile" or
+"@routes.AttachmentApp.getFileList".
+
+You have to specify `resourceType` and `resourceId` as attributes of the HTML
+element, because they are required to upload files to the specific resource.
+
+e.g.
+
+    <textarea id="comment-editor" name="contents" class="span8 textbody .inputxx-large" rows="5" markdown></textarea>
+    <div id="upload" resourceType=@Resource.ISSUE_POST resourceId=@issue.id></div>
+    <script>fileUploader($('#upload'), $('#comment-editor'), filesUrl);</script>
+
+However, you don't need to specify `resourceId` if the resource is not created yet,
+for instance, while you try to post new issue.
+
+e.g.
+
+    <textarea id="comment-editor" name="contents" class="span8 textbody .inputxx-large" rows="5" markdown></textarea>
+    <div id="upload" resourceType=@Resource.ISSUE_POST></div>
+    <script>fileUploader($('#upload'), $('#comment-editor'), filesUrl);</script>
+
+#### Server-side implementation
+
+You need some server-side implementation to attach uploaded files to a specific resource or get files attached to a specific resource.
+
+If a user upload files, they are stored in the user's temporary area. `Attachment.attachFiles` attaches them to a specific resource. The files which have been attached are removed in the temporary area.
+
+e.g. You should put this code on an event handler called update or create a issue to attach uploaded files to the issue.
+
+    Attachment.attachFiles(UserApp.currentUser().id, project.id, Resource.ISSUE_POST, issueId);
+
+You can delete all files attached to a specific resource using `Attachment.attachFiles` method.
+
+e.g. You may put this code on an event handler called after deleting a comment to delete all files attached to the comment.
+
+    Attachment.attachFiles(UserApp.currentUser().id, project.id, Resource.ISSUE_COMMENT, commentId);
+
+Downloader
+----------
+
+This list files attached to specific resource(issue, post, comment, ...), and
+allow users to download them.
+
+#### Usage
+
+First of all, uploader module should be loaded.
+
+    <script src="@getJSLink("uploader")" type="text/javascript"></script>
+
+Call fileDownloader javascript function to activate Downloader. The function
+requires two two arguments -- a HTML element object wrapped by jQuery in which
+a list of files will be rendered, and the url to files.
+
+You can get the url using "@routes.AttachmentApp.newFile" or
+"@routes.AttachmentApp.getFileList".
+
+You have to specify `resourceType` and `resourceId` as attributes of the HTML
+element, because they are required to get the files only attached to the
+specific resource.
+
+e.g.
+
+    <div class="attachments" resourceType=@Resource.BOARD_POST resourceId=@post.id></div>
+    <script>
+    attachments = $('.attachments');
+    for (var i = 0; i < attachments.length; i++) {
+      fileDownloader($(attachments[i]), "@routes.AttachmentApp.newFile");
+    }
+    </script>
Add a comment
List