Merge branch 'maint'
[org-mode.git] / contrib / lisp / ox-deck.el
blobbdcdcbc8e79693c581a867c1e78c91d58479aa3b
1 ;;; ox-deck.el --- deck.js Presentation Back-End for Org Export Engine
3 ;; Copyright (C) 2013 Rick Frankel
5 ;; Author: Rick Frankel <emacs at rickster dot com>
6 ;; Keywords: outlines, hypermedia, slideshow
8 ;; This file is not part of GNU Emacs.
10 ;; This program is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; This program is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; This library implements a deck.js presentation back-end for the Org
26 ;; generic exporter.
28 ;; Installation
29 ;; -------------
30 ;; Get a copy of deck.js from http://imakewebthings.com/deck.js/ or
31 ;; the gitub repository at https://github.com/imakewebthings/deck.js.
33 ;; Add the path to the extracted code to the variable
34 ;; `org-deck-directories' There are a number of customization in the
35 ;; org-export-deck group, most of which can be overrriden with buffer
36 ;; local customization (starting with DECK_.)
38 ;; See ox.el and ox-html.el for more details on how this exporter
39 ;; works (it is derived from ox-html.)
41 (require 'ox-html)
42 (eval-when-compile (require 'cl))
44 (org-export-define-derived-backend 'deck 'html
45 :menu-entry
46 '(?d "Export to deck.js HTML Presentation"
47 ((?H "To temporary buffer" org-deck-export-as-html)
48 (?h "To file" org-deck-export-to-html)
49 (?o "To file and open"
50 (lambda (a s v b)
51 (if a (org-deck-export-to-html t s v b)
52 (org-open-file (org-deck-export-to-html nil s v b)))))))
53 :options-alist
54 '((:html-link-home "HTML_LINK_HOME" nil nil)
55 (:html-link-up "HTML_LINK_UP" nil nil)
56 (:deck-postamble "DECK_POSTAMBLE" nil org-deck-postamble newline)
57 (:deck-preamble "DECK_PREAMBLE" nil org-deck-preamble newline)
58 (:html-head-include-default-style "HTML_INCLUDE_DEFAULT_STYLE" nil nil)
59 (:html-head-include-scripts "HTML_INCLUDE_SCRIPTS" nil nil)
60 (:deck-base-url "DECK_BASE_URL" nil org-deck-base-url)
61 (:deck-theme "DECK_THEME" nil org-deck-theme)
62 (:deck-transition "DECK_TRANSITION" nil org-deck-transition)
63 (:deck-include-extensions "DECK_INCLUDE_EXTENSIONS" nil
64 org-deck-include-extensions split)
65 (:deck-exclude-extensions "DECK_EXCLUDE_EXTENSIONS" nil
66 org-deck-exclude-extensions split))
67 :translate-alist
68 '((headline . org-deck-headline)
69 (inner-template . org-deck-inner-template)
70 (item . org-deck-item)
71 (link . org-deck-link)
72 (template . org-deck-template)))
74 (defgroup org-export-deck nil
75 "Options for exporting Org mode files to deck.js HTML Presentations."
76 :tag "Org Export DECK"
77 :group 'org-export-html)
79 (defcustom org-deck-directories '("./deck.js")
80 "Directories to search for deck.js components (jquery,
81 modernizr; core, extensions and themes directories.)"
82 :group 'org-export-deck
83 :type '(repeat (string :tag "Directory")))
85 (defun org-deck--cleanup-components (components)
86 (remove-duplicates
87 (car (remove 'nil components))
88 :test (lambda (x y)
89 (string= (file-name-nondirectory x)
90 (file-name-nondirectory y)))))
92 (defun org-deck--find-extensions ()
93 "Returns a unique list of all extensions found in
94 in the extensions directories under `org-deck-directories'"
95 (org-deck--cleanup-components
96 (mapcar ; extensions under existing dirs
97 (lambda (dir)
98 (when (file-directory-p dir) (directory-files dir t "^[^.]")))
99 (mapcar ; possible extension directories
100 (lambda (x) (expand-file-name "extensions" x))
101 org-deck-directories))))
103 (defun org-deck--find-css (type)
104 "Return a unique list of all the css stylesheets in the themes/TYPE
105 directories under `org-deck-directories'."
106 (org-deck--cleanup-components
107 (mapcar
108 (lambda (dir)
109 (let ((css-dir (expand-file-name
110 (concat (file-name-as-directory "themes") type) dir)))
111 (when (file-directory-p css-dir)
112 (directory-files css-dir t "\\.css$"))))
113 org-deck-directories)))
115 (defun org-deck-list-components ()
116 "List all available deck extensions, styles and
117 transitions (with full paths) to a temporary buffer."
118 (interactive)
119 (let ((outbuf (get-buffer-create "*deck.js Extensions*")))
120 (with-current-buffer outbuf
121 (erase-buffer)
122 (insert "Extensions\n----------\n")
123 (insert (mapconcat 'identity (org-deck--find-extensions) "\n"))
124 (insert "\n\nStyles\n------\n")
125 (insert (mapconcat 'identity (org-deck--find-css "style") "\n"))
126 (insert "\n\nTransitions\n----------\n")
127 (insert (mapconcat 'identity (org-deck--find-css "transition") "\n")))
128 (switch-to-buffer-other-window outbuf)))
130 (defcustom org-deck-include-extensions nil
131 "If non-nil, list of extensions to include instead of all available.
132 Can be overriden or set with the DECK_INCLUDE_EXTENSIONS property.
133 During output generation, the extensions found by
134 `org-deck--find-extensions' are searched for the appropriate
135 files (scripts and/or stylesheets) to include in the generated
136 html. The href/src attributes are created relative to `org-deck-base-url'."
137 :group 'org-export-deck
138 :type '(repeat (string :tag "Extension")))
140 (defcustom org-deck-exclude-extensions nil
141 "If non-nil, list of extensions to exclude.
142 Can be overriden or set with the DECK_EXCLUDE_EXTENSIONS property."
143 :group 'org-export-deck
144 :type '(repeat (string :tag "Extension")))
146 (defcustom org-deck-theme "swiss.css"
147 "deck.js theme. Can be overriden with the DECK_THEME property.
148 If this value contains a path component (\"/\"), it is used as a
149 literal path (url). Otherwise it is prepended with
150 `org-deck-base-url'/themes/style/."
151 :group 'org-export-deck
152 :type 'string)
154 (defcustom org-deck-transition "fade.css"
155 "deck.js transition theme. Can be overriden with the
156 DECK_TRANSITION property.
157 If this value contains a path component (\"/\"), it is used as a
158 literal path (url). Otherwise it is prepended with
159 `org-deck-base-url'/themes/transition/."
160 :group 'org-export-deck
161 :type 'string)
163 (defcustom org-deck-base-url "deck.js"
164 "Url prefix to deck.js base directory containing the core, extensions
165 and themes directories.
166 Can be overriden with the DECK_BASE_URL property."
167 :group 'org-export-deck
168 :type 'string)
170 (defvar org-deck-pre/postamble-styles
171 `((both "left: 5px; width: 100%;")
172 (preamble "position: absolute; top: 10px;")
173 (postamble ""))
174 "Alist of css styles for the preamble, postamble and both respectively.
175 Can be overriden in `org-deck-styles'. See also `org-html-divs'.")
177 (defcustom org-deck-postamble "<h1>%a - %t</h1>"
178 "Non-nil means insert a postamble in HTML export.
180 When set to a string, use this string
181 as the postamble. When t, insert a string as defined by the
182 formatting string in `org-html-postamble-format'.
184 When set to a function, apply this function and insert the
185 returned string. The function takes the property list of export
186 options as its only argument.
188 This is included in the document at the bottom of the content
189 section, and uses the postamble element and id from
190 `org-html-divs'. The default places the author and presentation
191 title at the bottom of each slide.
193 The css styling is controlled by `org-deck-pre/postamble-styles'.
195 Setting :deck-postamble in publishing projects will take
196 precedence over this variable."
197 :group 'org-export-deck
198 :type '(choice (const :tag "No postamble" nil)
199 (const :tag "Default formatting string" t)
200 (string :tag "Custom formatting string")
201 (function :tag "Function (must return a string)")))
203 (defcustom org-deck-preamble nil
204 "Non-nil means insert a preamble in HTML export.
206 When set to a string, use this string
207 as the preamble. When t, insert a string as defined by the
208 formatting string in `org-html-preamble-format'.
210 When set to a function, apply this function and insert the
211 returned string. The function takes the property list of export
212 options as its only argument.
214 This is included in the document at the top of content section, and
215 uses the preamble element and id from `org-html-divs'. The css
216 styling is controlled by `org-deck-pre/postamble-styles'.
218 Setting :deck-preamble in publishing projects will take
219 precedence over this variable."
220 :group 'org-export-deck
221 :type '(choice (const :tag "No preamble" nil)
222 (const :tag "Default formatting string" t)
223 (string :tag "Custom formatting string")
224 (function :tag "Function (must return a string)")))
226 (defvar org-deck-toc-styles
227 (mapconcat
228 'identity
229 (list
230 "#table-of-contents a {color: inherit;}"
231 "#table-of-contents ul {margin-bottom: 0;}"
232 "#table-of-contents li {padding: 0;}") "\n")
233 "Default css styles used for formatting a table of contents slide.
234 Can be overriden in `org-deck-styles'.
235 Note that when the headline numbering option is true, a \"list-style: none\"
236 is automatically added to avoid both numbers and bullets on the toc entries.")
238 (defcustom org-deck-styles
240 #title-slide h1 {
241 position: static; padding: 0;
242 margin-top: 10%;
243 -webkit-transform: none;
244 -moz-transform: none;
245 -ms-transform: none;
246 -o-transform: none;
247 transform: none;
249 #title-slide h2 {
250 text-align: center;
251 border:none;
252 padding: 0;
253 margin: 0;
255 "Deck specific CSS styles to include in exported html.
256 Defaults to styles for the title page."
257 :group 'org-export-deck
258 :type 'string)
260 (defcustom org-deck-title-slide-template
261 "<h1>%t</h1>
262 <h2>%a</h2>
263 <h2>%e</h2>
264 <h2>%d</h2>"
265 "Format template to specify title page section.
266 See `org-html-postamble-format' for the valid elements which
267 can be included.
269 It will be wrapped in the element defined in the :html-container
270 property, and defaults to the value of `org-html-container-element',
271 and have the id \"title-slide\"."
272 :group 'org-export-deck
273 :type 'string)
275 (defun org-deck-toc (depth info)
276 (concat
277 (format "<%s id='table-of-contents' class='slide'>\n"
278 (plist-get info :html-container))
279 (format "<h2>%s</h2>\n" (org-html--translate "Table of Contents" info))
280 (org-html--toc-text
281 (mapcar
282 (lambda (headline)
283 (let* ((class (org-element-property :HTML_CONTAINER_CLASS headline))
284 (section-number
285 (when
286 (and (not (org-export-low-level-p headline info))
287 (org-export-numbered-headline-p headline info))
288 (concat
289 (mapconcat
290 'number-to-string
291 (org-export-get-headline-number headline info) ".") ". ")))
292 (title
293 (concat
294 section-number
295 (replace-regexp-in-string ; remove any links in headline...
296 "</?a[^>]*>" ""
297 (org-export-data
298 (org-element-property :title headline) info)))))
299 (cons
300 (if (and class (string-match-p "\\<slide\\>" class))
301 (format
302 "<a href='#outline-container-%s'>%s</a>"
303 (or (org-element-property :CUSTOM_ID headline)
304 (concat
305 "sec-"
306 (mapconcat
307 'number-to-string
308 (org-export-get-headline-number headline info) "-")))
309 title)
310 title)
311 (org-export-get-relative-level headline info))))
312 (org-export-collect-headlines info depth)))
313 (format "</%s>\n" (plist-get info :html-container))))
315 (defun org-deck--get-packages (info)
316 (let ((prefix (concat (plist-get info :deck-base-url) "/"))
317 (theme (plist-get info :deck-theme))
318 (transition (plist-get info :deck-transition))
319 (include (plist-get info :deck-include-extensions))
320 (exclude (plist-get info :deck-exclude-extensions))
321 (scripts '()) (sheets '()) (snippets '()))
322 (add-to-list 'scripts (concat prefix "jquery-1.7.2.min.js"))
323 (add-to-list 'scripts (concat prefix "core/deck.core.js"))
324 (add-to-list 'scripts (concat prefix "modernizr.custom.js"))
325 (add-to-list 'sheets (concat prefix "core/deck.core.css"))
326 (mapc
327 (lambda (extdir)
328 (let* ((name (file-name-nondirectory extdir))
329 (dir (file-name-as-directory extdir))
330 (path (concat prefix "extensions/" name "/"))
331 (base (format "deck.%s." name)))
332 (when (and (or (eq nil include) (member name include))
333 (not (member name exclude)))
334 (when (file-exists-p (concat dir base "js"))
335 (add-to-list 'scripts (concat path base "js")))
336 (when (file-exists-p (concat dir base "css"))
337 (add-to-list 'sheets (concat path base "css")))
338 (when (file-exists-p (concat dir base "html"))
339 (add-to-list 'snippets (concat dir base "html"))))))
340 (org-deck--find-extensions))
341 (if (not (string-match-p "^[[:space:]]*$" theme))
342 (add-to-list 'sheets
343 (if (file-name-directory theme) theme
344 (format "%sthemes/style/%s" prefix theme))))
345 (if (not (string-match-p "^[[:space:]]*$" transition))
346 (add-to-list
347 'sheets
348 (if (file-name-directory transition) transition
349 (format "%sthemes/transition/%s" prefix transition))))
350 (list :scripts (nreverse scripts) :sheets (nreverse sheets)
351 :snippets snippets)))
353 (defun org-deck-inner-template (contents info)
354 "Return body of document string after HTML conversion.
355 CONTENTS is the transcoded contents string. INFO is a plist
356 holding export options."
357 (concat contents "\n"))
359 (defun org-deck-headline (headline contents info)
360 (let ((org-html-toplevel-hlevel 2)
361 (class (or (org-element-property :HTML_CONTAINER_CLASS headline) ""))
362 (level (org-export-get-relative-level headline info)))
363 (when (and (= 1 level) (not (string-match-p "\\<slide\\>" class)))
364 (org-element-put-property headline :HTML_CONTAINER_CLASS (concat class " slide")))
365 (org-html-headline headline contents info)))
367 (defun org-deck-item (item contents info)
368 "Transcode an ITEM element from Org to HTML.
369 CONTENTS holds the contents of the item. INFO is a plist holding
370 contextual information.
371 If the containing headline has the property :slide, then
372 the \"slide\" class will be added to the to the list element,
373 which will make the list into a \"build\"."
374 (let ((text (org-html-item item contents info)))
375 (if (org-export-get-node-property :STEP item t)
376 (replace-regexp-in-string "^<li>" "<li class='slide'>" text)
377 text)))
379 (defun org-deck-link (link desc info)
380 (replace-regexp-in-string "href=\"#" "href=\"#outline-container-"
381 (org-html-link link desc info)))
383 (defun org-deck-template (contents info)
384 "Return complete document string after HTML conversion.
385 CONTENTS is the transcoded contents string. INFO is a plist
386 holding export options."
387 (let ((pkg-info (org-deck--get-packages info))
388 (org-html--pre/postamble-class "deck-status")
389 (info (plist-put
390 (plist-put info :html-preamble (plist-get info :deck-preamble))
391 :html-postamble (plist-get info :deck-postamble))))
392 (mapconcat
393 'identity
394 (list
395 (org-html-doctype info)
396 (let ((lang (plist-get info :language)))
397 (mapconcat
398 (lambda (x)
399 (apply
400 'format
401 "<!--%s <html %s lang='%s' xmlns='http://www.w3.org/1999/xhtml'> %s<![endif]-->"
403 (list `("[if lt IE 7]>" "class='no-js ie6'" ,lang "")
404 `("[if IE 7]>" "class='no-js ie7'" ,lang "")
405 `("[if IE 8]>" "class='no-js ie8'" ,lang "")
406 `("[if gt IE 8]><!-->" "" ,lang "<!--")) "\n"))
407 "<head>"
408 (org-deck--build-meta-info info)
409 (mapconcat
410 (lambda (sheet)
411 (format
412 "<link rel='stylesheet' href='%s' type='text/css' />" sheet))
413 (plist-get pkg-info :sheets) "\n")
414 (mapconcat
415 (lambda (script)
416 (format
417 "<script src='%s' type='text/javascript'></script>" script))
418 (plist-get pkg-info :scripts) "\n")
419 (org-html--build-mathjax-config info)
420 "<script type='text/javascript'>"
421 " $(document).ready(function () { $.deck('.slide'); });"
422 "</script>"
423 (org-html--build-head info)
424 "<style type='text/css'>"
425 org-deck-toc-styles
426 (when (plist-get info :section-numbers)
427 "#table-of-contents ul li {list-style-type: none;}")
428 (format "#%s, #%s {%s}"
429 (nth 2 (assq 'preamble org-html-divs))
430 (nth 2 (assq 'postamble org-html-divs))
431 (nth 1 (assq 'both org-deck-pre/postamble-styles)))
432 (format "#%s {%s}"
433 (nth 2 (assq 'preamble org-html-divs))
434 (nth 1 (assq 'preamble org-deck-pre/postamble-styles)))
435 (format "#%s {%s}"
436 (nth 2 (assq 'postamble org-html-divs))
437 (nth 1 (assq 'postamble org-deck-pre/postamble-styles)))
438 org-deck-styles
439 "</style>"
440 "</head>"
441 "<body>"
442 (format "<%s id='%s' class='deck-container'>"
443 (nth 1 (assq 'content org-html-divs))
444 (nth 2 (assq 'content org-html-divs)))
445 (org-html--build-pre/postamble 'preamble info)
446 ;; title page
447 (format "<%s id='title-slide' class='slide'>"
448 (plist-get info :html-container))
449 (format-spec org-deck-title-slide-template (org-html-format-spec info))
450 (format "</%s>" (plist-get info :html-container))
451 ;; toc page
452 (let ((depth (plist-get info :with-toc)))
453 (when depth (org-deck-toc depth info)))
454 contents
455 (mapconcat
456 (lambda (snippet)
457 (with-temp-buffer (insert-file-contents snippet)
458 (buffer-string)))
459 (plist-get pkg-info :snippets) "\n")
460 (org-html--build-pre/postamble 'postamble info)
461 (format "</%s>" (nth 1 (assq 'content org-html-divs)))
462 "</body>"
463 "</html>\n") "\n")))
465 (defun org-deck--build-meta-info (info)
466 "Return meta tags for exported document.
467 INFO is a plist used as a communication channel."
468 (let* ((title (org-export-data (plist-get info :title) info))
469 (author (and (plist-get info :with-author)
470 (let ((auth (plist-get info :author)))
471 (and auth (org-export-data auth info)))))
472 (date (and (plist-get info :with-date)
473 (let ((date (org-export-get-date info)))
474 (and date (org-export-data date info)))))
475 (description (plist-get info :description))
476 (keywords (plist-get info :keywords)))
477 (mapconcat
478 'identity
479 (list
480 (format "<title>%s</title>" title)
481 (format "<meta http-equiv='Content-Type' content='text/html; charset=%s'/>"
482 (or (and org-html-coding-system
483 (fboundp 'coding-system-get)
484 (coding-system-get
485 org-html-coding-system 'mime-charset))
486 "iso-8859-1"))
487 (mapconcat
488 (lambda (attr)
489 (when (< 0 (length (car attr)))
490 (format "<meta name='%s' content='%s'/>\n"
491 (nth 1 attr) (car attr))))
492 (list '("Org-mode" "generator")
493 `(,author "author")
494 `(,description "description")
495 `(,keywords "keywords")) "")) "\n")))
496 (defun org-deck-export-as-html
497 (&optional async subtreep visible-only body-only ext-plist)
498 "Export current buffer to an HTML buffer.
500 If narrowing is active in the current buffer, only export its
501 narrowed part.
503 If a region is active, export that region.
505 A non-nil optional argument ASYNC means the process should happen
506 asynchronously. The resulting buffer should be accessible
507 through the `org-export-stack' interface.
509 When optional argument SUBTREEP is non-nil, export the sub-tree
510 at point, extracting information from the headline properties
511 first.
513 When optional argument VISIBLE-ONLY is non-nil, don't export
514 contents of hidden elements.
516 When optional argument BODY-ONLY is non-nil, only write code
517 between \"<body>\" and \"</body>\" tags.
519 EXT-PLIST, when provided, is a property list with external
520 parameters overriding Org default settings, but still inferior to
521 file-local settings.
523 Export is done in a buffer named \"*Org deck.js Export*\", which
524 will be displayed when `org-export-show-temporary-export-buffer'
525 is non-nil."
526 (interactive)
527 (if async
528 (org-export-async-start
529 (lambda (output)
530 (with-current-buffer (get-buffer-create "*Org deck.js Export*")
531 (erase-buffer)
532 (insert output)
533 (goto-char (point-min))
534 (nxml-mode)
535 (org-export-add-to-stack (current-buffer) 'deck)))
536 `(org-export-as 'deck ,subtreep ,visible-only ,body-only ',ext-plist))
537 (let ((outbuf (org-export-to-buffer
538 'deck "*Org deck.js Export*"
539 subtreep visible-only body-only ext-plist)))
540 ;; Set major mode.
541 (with-current-buffer outbuf (nxml-mode))
542 (when org-export-show-temporary-export-buffer
543 (switch-to-buffer-other-window outbuf)))))
545 (defun org-deck-export-to-html
546 (&optional async subtreep visible-only body-only ext-plist)
547 "Export current buffer to a deck.js HTML file.
549 If narrowing is active in the current buffer, only export its
550 narrowed part.
552 If a region is active, export that region.
554 A non-nil optional argument ASYNC means the process should happen
555 asynchronously. The resulting file should be accessible through
556 the `org-export-stack' interface.
558 When optional argument SUBTREEP is non-nil, export the sub-tree
559 at point, extracting information from the headline properties
560 first.
562 When optional argument VISIBLE-ONLY is non-nil, don't export
563 contents of hidden elements.
565 When optional argument BODY-ONLY is non-nil, only write code
566 between \"<body>\" and \"</body>\" tags.
568 EXT-PLIST, when provided, is a property list with external
569 parameters overriding Org default settings, but still inferior to
570 file-local settings.
572 Return output file's name."
573 (interactive)
574 (let* ((extension (concat "." org-html-extension))
575 (file (org-export-output-file-name extension subtreep))
576 (org-export-coding-system org-html-coding-system))
577 (if async
578 (org-export-async-start
579 (lambda (f) (org-export-add-to-stack f 'deck))
580 (let ((org-export-coding-system org-html-coding-system))
581 `(expand-file-name
582 (org-export-to-file
583 'deck ,file ,subtreep ,visible-only ,body-only ',ext-plist))))
584 (let ((org-export-coding-system org-html-coding-system))
585 (org-export-to-file
586 'deck file subtreep visible-only body-only ext-plist)))))
588 (defun org-deck-publish-to-html (plist filename pub-dir)
589 "Publish an org file to deck.js HTML Presentation.
590 FILENAME is the filename of the Org file to be published. PLIST
591 is the property list for the given project. PUB-DIR is the
592 publishing directory. Returns output file name."
593 (org-publish-org-to 'deck filename ".html" plist pub-dir))
595 (provide 'ox-deck)
597 ;;; ox-deck.el ends here