|
1 CrossReference Plugin for CKEditor 4 |
|
2 ================================= |
|
3 |
|
4 Adds cross references links with optional auto-numeration for chapters, images, tables and references. Other types of references can be defined in config. |
|
5 |
|
6 ## Description |
|
7 |
|
8 Two main conceptions - anchor and link to anchor. There are 4 type of references defined by default: chapter, image, table, reference. Example of anchor of type `image` in raw html: |
|
9 ```html |
|
10 <a |
|
11 class="cross-reference cross-anchor" |
|
12 cross-reference="image" |
|
13 cross-anchor="" |
|
14 cross-guid="7d24373b-0756-481d-bf97-5a17ffdf3a28" |
|
15 cross-name="Experimental result" |
|
16 cross-number="1" |
|
17 name="image-7d24373b-0756-481d-bf97-5a17ffdf3a28" |
|
18 > |
|
19 Fig. 1. Experimental result. |
|
20 </a> |
|
21 ``` |
|
22 Example of link to this anchor in raw html: |
|
23 ```html |
|
24 <a |
|
25 class="cross-reference cross-link" |
|
26 cross-reference="image" |
|
27 cross-link="" |
|
28 cross-guid="7d24373b-0756-481d-bf97-5a17ffdf3a28" |
|
29 cross-name="Experimental result" |
|
30 cross-number="1" |
|
31 href="#image-7d24373b-0756-481d-bf97-5a17ffdf3a28" |
|
32 title="Fig. 1. Experimental result." |
|
33 > |
|
34 1 |
|
35 </a> |
|
36 ``` |
|
37 After every inserting of anchor or links to anchor all references will be updated to be a concerted. Or you can manually update cross-references by selecting option in menu (for example after deleting of anchors). |
|
38 |
|
39 ## Configuration |
|
40 |
|
41 You can switch which types is active by config option `config.crossreference.activeTypes = ['type1', 'type2']`. You can define other types also. |
|
42 |
|
43 ### Default config: |
|
44 |
|
45 ```javascript |
|
46 { |
|
47 activeTypes: ['chapter', 'image', 'table', 'reference'], |
|
48 overrideTypes: false, |
|
49 types: { |
|
50 chapter: { |
|
51 name: 'Chapter', |
|
52 anchorTextTemplate: '${number}. ${name}.', |
|
53 linkTextTemplate: '${number}', |
|
54 numeration: { |
|
55 enabled: true, |
|
56 firstNumber: '1', |
|
57 increase: function(number) { |
|
58 var n = parseInt(number); |
|
59 return ++n; |
|
60 } |
|
61 }, |
|
62 anchorsProvider: 'default', |
|
63 allowCreateAnchors: true, |
|
64 groupAnchors: false |
|
65 }, |
|
66 image: { |
|
67 name: 'Figure', |
|
68 anchorTextTemplate: 'Fig. ${number}. ${name}.', |
|
69 linkTextTemplate: '${number}', |
|
70 numeration: { |
|
71 enabled: true, |
|
72 firstNumber: '1', |
|
73 increase: function(number) { |
|
74 var n = parseInt(number); |
|
75 return ++n; |
|
76 } |
|
77 }, |
|
78 anchorsProvider: 'default', |
|
79 allowCreateAnchors: true, |
|
80 groupAnchors: false |
|
81 }, |
|
82 table: { |
|
83 name: 'Table', |
|
84 anchorTextTemplate: 'Table ${number}. ${name}.', |
|
85 linkTextTemplate: '${number}', |
|
86 numeration: { |
|
87 enabled: true, |
|
88 firstNumber: '1', |
|
89 increase: function(number) { |
|
90 var n = parseInt(number); |
|
91 return ++n; |
|
92 } |
|
93 }, |
|
94 anchorsProvider: 'default', |
|
95 allowCreateAnchors: true, |
|
96 groupAnchors: false |
|
97 }, |
|
98 reference: { |
|
99 name: 'Reference', |
|
100 anchorTextTemplate: '[${number}] ${name}.', |
|
101 linkTextTemplate: '[${number}]', |
|
102 numeration: { |
|
103 enabled: true, |
|
104 firstNumber: '1', |
|
105 increase: function(number) { |
|
106 var n = parseInt(number); |
|
107 return ++n; |
|
108 } |
|
109 }, |
|
110 anchorsProvider: 'default', |
|
111 allowCreateAnchors: true, |
|
112 groupAnchors: false |
|
113 } |
|
114 } |
|
115 } |
|
116 ``` |
|
117 | Property | Description | Type | Default value | |
|
118 | --- | --- | --- | --- | |
|
119 | `activeTypes` | Which type of anchors would be activated. | Array | `['chapter', 'image', 'table', 'reference']` | |
|
120 | `overrideTypes` | If you define your own types, enabling this option lead to mixing of your types with types from default config which not yet defined in your config. | Boolean | false | |
|
121 | `types` | Types definition. | Object | see [Default config](https://github.com/indvd00m/crossreference#default-config) section| |
|
122 |
|
123 ### Example of type definition |
|
124 |
|
125 ```javascript |
|
126 image: { |
|
127 name: 'Figure', |
|
128 anchorTextTemplate: 'Fig. ${number}. ${name}.', |
|
129 linkTextTemplate: '${number}', |
|
130 numeration: { |
|
131 enabled: true, |
|
132 firstNumber: '1', |
|
133 increase: function(number) { |
|
134 var n = parseInt(number); |
|
135 return ++n; |
|
136 } |
|
137 }, |
|
138 anchorsProvider: 'default', |
|
139 allowCreateAnchors: true, |
|
140 groupAnchors: false |
|
141 } |
|
142 ``` |
|
143 | Property | Description | Type | Required | |
|
144 | --- | --- | --- | --- | |
|
145 | `name` | Type name. | String | Yes | |
|
146 | `anchorTextTemplate` | Template for anchor text. This text will be put in `a` tag. You can use variables in format `${variableName}`. Variables is a properties of an anchor object (see [Example of an anchor object](https://github.com/indvd00m/crossreference#example-of-an-anchor-object) section). | String | No | |
|
147 | `linkTextTemplate` | Template for link text. This text will be put in `a` tag. You can use variables in format `${variableName}`. Variables is a properties of an anchor object (see [Example of an anchor object](https://github.com/indvd00m/crossreference#example-of-an-anchor-object) section). | String | No | |
|
148 | `numeration` | Definition of type numeration. See [Example of a numeration config](https://github.com/indvd00m/crossreference#example-of-a-numeration-config) section. | Object | No | |
|
149 | `anchorsProvider` | See [Example of type with anchors provider](https://github.com/indvd00m/crossreference#example-of-type-with-anchors-provider) section. | String 'default' or function | No | |
|
150 | `allowCreateAnchors` | Can user create anchors of this type in anchors dialog. | Boolean | No | |
|
151 | `groupAnchors` | If `true`, anchors can be filtered by group in link dialog. | Boolean | No | |
|
152 |
|
153 ### Example of a numeration definition |
|
154 |
|
155 ```javascript |
|
156 numeration: { |
|
157 enabled: true, |
|
158 firstNumber: '1', |
|
159 increase: function(number) { |
|
160 var n = parseInt(number); |
|
161 return ++n; |
|
162 } |
|
163 } |
|
164 ``` |
|
165 | Property | Description | Type | |
|
166 | --- | --- | --- | |
|
167 | `enabled` | Enabling/disabling numeration of anchors. | Boolean | |
|
168 | `firstNumber` | First number. For example you may define `firstNumber` as `I` for Roman numerals. | String | |
|
169 | `increase` | Function which must return number (as string) which is next after `number` argument (string). | Function | |
|
170 |
|
171 ### Example of an anchor object |
|
172 |
|
173 JSON object: |
|
174 |
|
175 ```javascript |
|
176 { |
|
177 type: 'image', |
|
178 guid: '7d24373b-0756-481d-bf97-5a17ffdf3a28', |
|
179 name: 'Experimental result', |
|
180 number: '1', |
|
181 text: 'Fig. 1. Experimental result.', |
|
182 groupName: 'Group name', |
|
183 groupGuid: '6c848dff-cde3-421f-b926-695c8de37d80' |
|
184 } |
|
185 ``` |
|
186 | Property | Description | Type | Required | |
|
187 | --- | --- | --- | --- | |
|
188 | `type` | Type name of this anchor (`config.types.typeName`). | String | Yes | |
|
189 | `guid` | Unique guid of this anchor. | String | Yes | |
|
190 | `name` | Name of this anchor. | String | Yes | |
|
191 | `number` | Number of this anchor (if type contains numeration definition). | String | Depends of type | |
|
192 | `text` | Text of this anchor. Optional property because of text will generated by `type.anchorTextTemplate` template. | String | No | |
|
193 | `groupName` | Name of anchor group. | String | No | |
|
194 | `groupGuid` | Unique guid of anchor group. | String | No | |
|
195 |
|
196 ### Example of type with anchors provider |
|
197 |
|
198 You can define your own anchors provider. By default plugin search anchors in content of editor and use this anchors for links. But if you want refer to anchors outside of editor you can define another type of anchor with `anchorsProvider` function. |
|
199 |
|
200 ```javascript |
|
201 myType: { |
|
202 name: 'My type', |
|
203 anchorTextTemplate: '${name}', |
|
204 linkTextTemplate: '${name}', |
|
205 anchorsProvider: function(callback, editorAnchors, type, editor) { |
|
206 var anchors = []; |
|
207 anchors.push({ |
|
208 type: 'myType', |
|
209 guid: '7d24373b-0756-481d-bf97-5a17ffdf3a28', |
|
210 name: 'Anchor name', |
|
211 number: '1' |
|
212 }); |
|
213 callback(anchors); |
|
214 }, |
|
215 allowCreateAnchors: false, |
|
216 groupAnchors: false |
|
217 }, |
|
218 ``` |
|
219 |
|
220 `anchorsProvider` method attributes: |
|
221 |
|
222 | Name | Description | Type | |
|
223 | --- | --- | --- | |
|
224 | `callback` | Callback method which must be called with arrays of anchors as argument. | Function | |
|
225 | `editorAnchors` | Anchors of this type (`myType` in this case) which already contains in editor. You can merge this anchors with your own anchors if need. | Array | |
|
226 | `type` | Type definition (Object `myType` in this case). | Object | |
|
227 | `editor` | Instance of ckeditor. | Object | |
|
228 |
|
229 |
|
230 ## Requirements |
|
231 |
|
232 CrossReference Plugin require CKEditor 4.5+ version and dependent from plugins: dialog, notification. |
|
233 |
|
234 ## Installation |
|
235 |
|
236 1. Download the plugin. |
|
237 |
|
238 2. Extract (decompress) the downloaded file into the plugins folder of your |
|
239 CKEditor installation. |
|
240 Example: http://example.com/ckeditor/plugins/crossreference |
|
241 |
|
242 3. Enable the plugin by using the extraPlugins configuration setting. |
|
243 Example: CKEDITOR.config.extraPlugins = 'crossreference'; |
|
244 |
|
245 ## Roadmap |
|
246 |
|
247 See https://github.com/indvd00m/crossreference/issues. |
|
248 |
|
249 ## Icons: |
|
250 |
|
251 https://icons8.com/web-app/15117/anchor |
|
252 |
|
253 https://icons8.com/web-app/38051/link |
|
254 |
|
255 https://icons8.com/web-app/21100/refresh |
|
256 |
|
257 ## License & Author |
|
258 |
|
259 CrossReference Plugin is distributed under GPL/LGPL/MPL. For license terms, see LICENSE.md. |
|
260 |
|
261 CrossReference Plugin is written by David E. Veliev. |