DJMD

# djmd **Repository Path**: a785748863/djmd ## Basic Information - **Project Name**: djmd - **Description**: DJango editorMD - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2020-04-13 - **Last Updated**: 2020-12-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # DJango editor.MD v0.2 > by kevinsunxy > 开发与测试使用的django版本: 1.11.28 > 创建时间: 2020 03 25 > 最后更新: 2020 04 13 ## 简介 - 将editor.md进行封装方便在django中使用 - 简化将editor.md编辑器添加到页面的过程和在前端展示markdown的过程, 无需手动在前端写editor.md所需要的标签结构以及对依赖的css和js的引入 - 支持多种图片上传与图片储存的处理方式 - 配置与使用方式简单灵活 - 按功能可以将djmd的内容分为以下三类: - 直接支持图片上传的类(下文中简称为**uploading**类): - 在Model中使用的字段类 `EditorMDUploadingField` - 在ModelForm或Form中使用的字段类 `EditorMDUploadingFormField` - 在ModelForm或Form中使用的插件类 `EditorMDUploadingWidget` - 默认不支持图片上传的类(配置后可支持): - 在Model中使用的字段类 `EditorMDField` - 在ModelForm或Form中使用的字段类 `EditorMDFormField` - 在ModelForm或Form中使用的插件类 `EditorMDWidget` - 将markdown转换为html展示的自定义Django模板标签 - `markdown_to_html` ## 快速入门 ### 通用 - 将djmd文件夹放在项目根目录下 - 将djmd作为项目的一个APP安装 ### 不使用图片上传 - 非**uploading**类没有任何必须的配置, 直接导入使用即可 ### 使用自动配置 - **仅适用于还没有设置`MEDIA_URL`, `MEDIA_ROOT`以及相关URL的情况** - 自动配置可以将djmd的配置过程进一步简化 (**仅有uploading类支持使用自动配置**) - 自动配置不修改任何文件, 仅在内存中添加需要的配置 - 在 `settings` 文件中添加下面一行来使用自动配置 - ```python DJMD_UPLOAD_AUTO_CONFIG = True ``` - 自动配置的内容: - 假如settings中没有设置, 将自动设置`MEDIA_URL` - 假如settings中没有设置, 将自动设置`MEDIA_ROOT` - 上传图片的储存目录 - 接收图片上传请求的url - 处理图片访问请求的url ### 手动进行上传配置 - 配置图片上传使用的url - 示例: - ```python # urls.py ... url(r'前缀', include("djmd.urls")), ... ``` - 配置图片上传后储存的根目录`MEDIA_ROOT` (不配置会直接存在项目根目录, 不推荐) - 示例: - ```python # settings.py ... MEDIA_ROOT = os.path.join(BASE_DIR, "media") ... ``` - 配置`MEDIA_URL` 与处理图片访问请求的url - 示例: - ```python # settings.py ... MEDIA_URL = '/media/' ... ``` - ```python # urls.py ... from django.views.static import serve from django.conf import settings ... urlpatterns = [ ... # 假设 MEDIA_URL = '/media/' url(r"^media/(?P.*)", serve, {"document_root": settings.MEDIA_ROOT}), ... ] ``` ### 自定义图片上传 - 当**uploading**类的图片上传功能无法满足需求时, 比如需要使用动态的图片上传url, 或者图片并不存在本地, 而是经由服务器转存到云端, 此时可以根据需要对**非uploading类**进行配置, 使其支持图片上传 - 图片上传相关编辑器配置(详见**配置**): - `"imageUpload"`: 必须设置为 "true" - 可以根据需要来设置`"imageFormats"`来限制允许上传的图片的格式 - 图片上传路径可以通过`"imageUploadURL"`在配置中设置, 也可以在实例化字段时作为实参(image_upload_url)传入 - Django配置 - 在urls.py中添加图片上传的url - 图片上传时被调用的视图函数 - editor.md图片上传插件所需的json返回值的格式: - ```json { "success": 0或1(0代表失败, 1代表上传成功), "message": 返回的提示信息, "url": 上传的图片的访问链接, } ``` - 其它配置 ### 导入 - 使用两个插件类时需要从 `djmd.widgets`中导入 - 使用字段类时需要从`djmd.fields`中导入 ### 使用字段或插件 - 字段类与插件类的使用方式与一般字段和插件一样 - 实例化时选填的参数(适用于所有类): - `config_name` : 编辑器使用的配置的名字, 必须在settings的`DJMD_CONFIGS`中 (详见**配置**) - `include_jquery` : 是否在页面中导入jQuery, 默认为True, 假如页面中已经导入了jQuery可以设为False防止再次导入 - `image_upload_url` : 处理图片上传请求的url, 在所有关于图片上传url的配置中有最高的优先级, 即这里传入的url将最终被用于处理图片上传 - `extra_js_files` : 可以帮助用户在页面上导入需要的其它js文件, 必须是一个元组或者列表, 内容为js文件的路径 (详见**额外的js文件**) ### 渲染编辑器 - 假设模板接到的表单对象是form, 在页面渲染editor.md编辑器只需要3步: - 在模板页面的`head`标签中添加: - ```htmldjango {% form.media.css %} ``` - 在`body`标签的结尾处添加: - ```htmldjango {% form.media.js %} ``` - 编辑器所对应的字段对象只需要正常使用`{{ }}`来进行渲染即可 - html模板示例代码: - ```html DJMD {{ form.media.css }} {{ form.media.js }} ``` ### 将markdown转换为html展示 - 将markdown转为html进行展示只需要两步: - 加载djmd - ```htmldjango {% load djmd %} ``` - 使用`markdown_to_html`标签进行转换 - ```htmldjango {% markdown_to_html text %} ``` - `markdown_to_html`还可以接收另一个参数`include_jquery` (默认为True), 假如已经在页面导入了jQuery, 可以将此参数设置为False防止再次导入 - 完整示例代码: - ```html DJMD {% load djmd %} {% markdown_to_html article.content %} ``` ## 配置 - 在settings.py中可以对djmd进行配置, 可选配置如下: - 仅对**uploading类**有效的配置: - `DJMD_UPLOAD_AUTO_CONFIG` : 是否使用自动配置 - `DJMD_UPLOAD_PATH` : (在`MEDIA_ROOT`中)图片上传后储存位置的根目录 - `DJMD_USE_DATE_DIRS` : 储存图片时是否根据上传日期创建并使用日期目录结构 - `DJMD_USE_DATE_TIME_PREFIX` : 是否在储存时给图片名加上上传日期时间的前缀 - 对所有类有效的配置: - `DJMD_CONFIGS` : 编辑器相关配置 ### `DJMD_UPLOAD_AUTO_CONFIG` - 仅对**uploading类**有效 - 说明: 是否使用自动配置. - 值类型: bool - 自动配置的内容: - 假如settings中没有设置, 将自动设置`MEDIA_URL` - 假如settings中没有设置, 将自动设置`MEDIA_ROOT` - 上传图片的储存目录 - 接收图片上传请求的url - 处理图片访问请求的url - 详细说明: - 自动配置的最佳使用场景是settings.py中没有设置`MEDIA_URL`以及`MEDIA_ROOT`的情况 - 一般来讲, 当`MEDIA`相关的配置已经有值的时候, `MEDIA`访问请求的处理一般也已经配置完了, 如果要使用djmd进行图片上传, 只需要简单配置一下图片上传的url即可. 使用自动配置反而可能会出现问题 - 使用自动配置时, 需要渲染编辑器的页面响应速度可能会稍有降低 - 自动配置可以与其它djmd配置同时使用 ### `DJMD_UPLOAD_PATH` - 仅对**uploading类**有效 - 说明: (在`MEDIA_ROOT`中)图片上传后储存位置的根目录 - 值类型: str - 默认值: "djmd" - 例子: 假如`MEDIA_ROOT`设置的值是项目根目录下的`media`目录, 那么在使用默认值的情况下上传图片储存的根目录就是`media/djmd` ### `DJMD_USE_DATE_DIRS` - 仅对**uploading类**有效 - 说明: 储存图片时是否根据上传日期创建并使用日期目录结构. 可以按上传日期将图片分别存放, 方便管理. 由于使用Django的默认文件系统进行图片储存, 图片重名问题由默认的文件系统解决 - 值类型: bool - 默认值: True - 示例: `.../djmd/2020/04/13/test.jpg` ### `DJMD_USE_DATE_TIME_PREFIX` - 仅对**uploading类**有效 - 说明: 是否在储存时给图片名加上上传日期时间的前缀, 日期时间使用的是UTC时间. 如果存储图片时不想创建额外的文件夹, 为了方便图片的管理, 可以使用此选项代替`DJMD_USE_DATE_DIRS` (两者也可以同时使用). - 前缀格式: `年月日_时分秒_UTC_` - 值类型: bool - 默认值: False - 示例: `20200412_064120_UTC_test.jpg` ### `DJMD_CONFIGS` - 说明: 编辑器相关配置 - 值类型: dict - 键 (str): 配置的名称 - 值 (dict): 具体配置内容 - 示例: - ```python DJMD_CONFIGS = { "global": { "theme": "dark", "editorTheme": "pastel-on-dark", "previewTheme": "dark", }, "mini": { "toolbarIcons": "mini", }, } ``` #### 编辑器全局配置 - `global`全局配置是选填的 - 在 `DJMD_CONFIGS`的`global`中可以定义编辑器全局配置, 比如上面的例子中的`global`就让所有编辑器都使用深色的颜色主题 - 全局配置可以被覆盖. 假如在某个配置中也有`theme`, 那么使用这个配置的编辑器将会使用新的`theme`颜色主题 #### 编辑器具体配置的格式 - 所有的键都是str类型 - 键的内容是editor.md编辑器可用的初始化配置中的配置名 - editor.md与djmd的配置的值的类型对照表: | editor.md | djmd | 示例-editor.md | 示例-djmd | | :-------: | :-----------------------: | :------------------------------------ | :------------------------------------------ | | 布尔型 | 字符串"true" 或者 "false" | imageUpload: true | "imageUpload": "true" | | 数字型 | 数字 | height: 500 | "height": 500 | | 字符串 | 字符串 | theme: dark | "theme": "dark" | | 对象 | 字典 | toolbarIconTexts: {btn:"DJMD"} | "toolbarIconTexts": {"btn":"DJMD"} | | 数组 | 列表 | imageFormats : ["jpg", "gif", "png"] | "imageFormats" : ["jpg", "gif", "png"] | | 函数 | 函数字符串 | onload:function(){this.previewing();} | "onload": "function(){ this.previewing();}" | - 在渲染编辑器时, djmd会根据配置的需要自动将值的类型转换为所需的类型, 比如函数字符串将被渲染成函数, 而普通字符串依然是字符串 - `width`与`height`配置不止支持数字格式的值, 也支持百分比的字符串, 比如`"50%"` - 可用的编辑器配置请参考editor.md官网, 或者djmd内的`editormd_config_options.txt`文件 #### 额外的js文件 - 在编辑器的具体配置中, 还可以使用一项非editor.md的配置: `"extra_js_files"` - `"extra_js_files"`的值是元组或者列表, 内容为将要在渲染编辑器时导入的js文件的路径 - 这个选项可以解决在配置中不方便使用字符串来编写复杂的函数的问题, 比如上面表格例子中编辑器`onload`事件的回调函数, 如果回调函数比较复杂, 我们可以将函数的定义写在一个js文件中, 在配置的函数字符串中只写上函数的调用, 然后将这个js文件通过`extra_js_files`导入到页面来实现同样的效果 - 示例: - ```js // prev.js function preview(){ this.previewing(); } ``` - ```python # settings.py ... "onload": "preview();", "extra_js_files": ["path/to/prev.js"] ... ``` #### 配置的优先级 - djmd默认编辑器配置 **<** 自动配置 **<** global全局编辑器配置 **<** 单独编辑器配置 **<** 实例化实参 ## uploading类存储图片使用的文件系统 - djmd的**uploading**类使用Django默认的文件系统, 目前不支持使用其它文件系统 ## 操作Editor.MD - 编辑器加载初始化时会实例化一个editormd对象, djmd将这个对象保存在**全局变量** `EDITORMD`中. 假如需要对编辑器进行其它操作, 可以使用这个对象 - djmd将编辑器的初始化封装在`initEditorMD`函数中, 在页面加载完成时会自动被调用. 假如需要重新初始化编辑器, 可以再次调用这个函数 ## 常见问题 ### 在Bootstrap模态框中使用时无法编辑 - 在模态框出现后重新初始化编辑器就可以解决无法编辑的问题 - 注意, 无论使用哪种方式让bootstrap模态框出现(标签的data-toggle等属性, 或是自己绑定点击事件然后调用模态框的modal("show")), 都必须在模态框出现**后**再调用初始化函数, 建议使用setTimeout函数 - 示例代码: ```html ```