|
1 | 1 | ## Description |
2 | 2 |
|
3 | | -The clone pattern lets the website user clone elements in the page. |
| 3 | +Copy part of the DOM tree and show it as code. |
| 4 | + |
4 | 5 |
|
5 | 6 | ## Documentation |
6 | 7 |
|
7 | | -The clone pattern is typically used in case you want to create a form on which it is unknown how many instances the user will need of a certain field or group of fields. |
8 | | -For instance if you want to ask the user to fill out the name and birthdate of each family member. |
| 8 | +The clone-code copies a part of the DOM tree and wraps it in a `<pre><code>` structure as plain text. |
| 9 | + |
| 10 | +This pattern is especially useful when writing interactive documentation and showing the code at the same time. |
| 11 | + |
9 | 12 |
|
10 | 13 | ### Usage |
11 | 14 |
|
12 | 15 | This pattern is enabled by adding the `pat-clone` class on a container element which contains the original element and any clones of it that may have beeen added. |
13 | 16 | The first element inside the .pat-clone container is by default assumed to be the original element may be cloned by the user. |
14 | 17 |
|
15 | | -Consider the following markup: |
16 | | - |
17 | | - <h3>List of family members</h3> |
18 | | - |
19 | | - <div class="pat-clone"> |
20 | | - <!-- The first element inside the .pat-clone container is by default |
21 | | - assumed to be the original element which will be cloned. |
22 | | - --> |
23 | | - <fieldset class="clone"> <!-- By default, pat-clone will consider elements with the "clone" class to be clones. --> |
24 | | - <legend>Family member 1</legend> |
25 | | - <input name="name-1" type="text" placeholder="Name" /> |
26 | | - <input name="date-1" type="date" placeholder="birthdate" /><br/> |
27 | | - <button type="button" class="remove-clone">Remove</button> |
28 | | - </fieldset> |
29 | | - <!-- Now comes the clone trigger, a button which when clicked will cause |
30 | | - a new clone of the above fieldset to be created. |
31 | | - --> |
32 | | - <button type="button" class="add-clone">Add an extra family member</button> |
| 18 | + <div class="pat-clone-code"> |
| 19 | + <p>Hello.</p> |
33 | 20 | </div> |
34 | 21 |
|
35 | | -Each time the user clicks on the button saying 'Add an extra family member', the |
36 | | -pattern will make a copy of the first element inside the |
37 | | -`.pat-clone` element, unless the `template` property is used to configure a |
38 | | -different clone template. The `template` property takes a CSS selector as |
39 | | -value. |
40 | | - |
41 | | -Typically when using a template element, such an element would be hidden from view. |
42 | | - |
43 | | -The new clone is always appended at the end, inside the `.pat-clone` element. |
| 22 | +This will result in: |
44 | 23 |
|
45 | | -When creating a `.pat-clone` element containing existing clones, it's |
46 | | -important that each existing clone either gets the `clone` CSS class or that you |
47 | | -pass in a unique CSS selector for each clone via the `clone-element` |
48 | | -property. This allows the pattern to properly determine how many existing |
49 | | -clones there are to start with. |
| 24 | + <pre class="pat-syntax-highlight language-html"> |
| 25 | + <code class="language-html hljs"> |
| 26 | + <span class="hljs-tag"><<span class="hljs-name">p</span>></span>Hello.<span class="hljs-tag"></<span class="hljs-name">p</span>></span> |
| 27 | + </code> |
| 28 | + </pre> |
50 | 29 |
|
51 | | -#### Incrementation of values in clones |
52 | | - |
53 | | -The pat-clone pattern will automatically add up any number in the values of name and value attributes. |
54 | | -For instance, if you have `name="item-1"` in your markup, then the first clone will be |
55 | | -`name="item-2"` and the one after that `name="item-3"` etc.. If you want to print a number |
56 | | -— for instance in a header of each clone — then you can use the syntax: `#{1}`. This string |
57 | | -will be replaced by an number that's also increased by 1 for each clone. |
58 | | - |
59 | | -### Example with a hidden template |
60 | | - |
61 | | -The markup below would have exactly the same effect as the first example, but using a hidden template. This might come in handy when the first instance shown should either contain different information, or if it will have pre-filled values by the server. |
62 | | - |
63 | | - <h3>List of family members</h3> |
64 | | - |
65 | | - <div class="pat-clone" data-pat-clone="template: #my-template"> |
66 | | - <!-- First visible instance and also template --> |
67 | | - <fieldset class="clone"> |
68 | | - <legend>Family member 1</legend> |
69 | | - <input name="Mary Johnson" type="text" placeholder="Name" /> |
70 | | - <input name="1977-04-16" type="date" placeholder="birthdate" /><br/> |
71 | | - <button type="button" class="remove-clone">Remove</button> |
72 | | - </fieldset> |
73 | | - |
74 | | - <!-- Template markup --> |
75 | | - <fieldset id="my-template" hidden> |
76 | | - <legend>Family member #{1}</legend> |
77 | | - <input name="name-1" type="text" placeholder="Name" /> |
78 | | - <input name="date-1" type="date" placeholder="birthdate" /><br/> |
79 | | - <button type="button" class="remove-clone">Remove</button> |
80 | | - </fieldset> |
81 | | - |
82 | | - <!-- Clone trigger --> |
83 | | - <button type="button" class="add-clone">Add an extra family member</button> |
84 | | - </div> |
85 | | - |
86 | | -### Example with a hidden template which includes a pattern |
87 | | - |
88 | | -Patterns in templates are initialized after cloning. |
89 | | -However, the patterns in the template itself are not initialized if the template has the attribute ``hidden`` or the class ``disable-patterns``. |
90 | | -This is to prevent double-initialization within the template and after being cloned. |
91 | | - |
92 | | - <div id="template" class="disable-patterns" hidden> |
93 | | - <input name="date-1" type="date" class="pat-date-picker" /> |
94 | | - </fieldset> |
95 | | - |
96 | | - <div class="pat-clone" data-pat-clone="template: #template"> |
97 | | - <button type="button" class="add-clone">Add a date</button> |
98 | | - </div> |
99 | 30 |
|
| 31 | +### Excluding markup from copying |
100 | 32 |
|
| 33 | +You can exclude markup from copying by adding the `clone-code` class to it. |
| 34 | +If that class is present, the whole `clone-code` markup subtree is ignored. |
101 | 35 |
|
102 | 36 |
|
103 | 37 | ### Option reference |
104 | 38 |
|
105 | | -| Property | Description | Default | Allowed Values | Type | |
106 | | -| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------- | --------------------------------- | |
107 | | -| template | Selects the element that will be cloned each time. You might often want to refer to a piece of template markup for this that is hidden with though the CSS. | :first | | CSS Selector | |
108 | | -| max | Maximum number of clones that is allowed | | | Integer | |
109 | | -| trigger-element | Selector of the element that will add the clone when clicked upon. | .add-clone | | CSS Selector | |
110 | | -| remove-element | Selector of the element that will remove the clone when clicked upon. | .remove-clone | | CSS Selector | |
111 | | -| remove-behaviour or remove-behavior | What should happen when the user clicks on the element to remove a clone? Two choices exist currently. Show a confirmation dialog, or simply remove the clone immediately. | "confirm" | "confirm", "none" | One of the allowed string values. | |
112 | | -| clone-element | Selector of the individual clone element(s). | .clone | | CSS Selector | |
| 39 | +| Property | Description | Default | Type | |
| 40 | +| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------- | |
| 41 | +| source | CSS selector to define the source from where the markup should be copied. | :first-child | CSS Selector | |
| 42 | +| features | List of features to activate. Currently only `format` is implemented. Format does prettify the HTML markup with the library `prettier`. | null | Comma seperated list of strings. | |
| 43 | + |
0 commit comments