Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Form Annotation Docs #145

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Form Annotation Docs #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
800d6fe
Docs for https://github.com/diegomura/react-pdf/pull/2845
PhilippBloss Nov 19, 2024
5d9a3fb
Merge branch 'diegomura:master' into master
PhilippBloss Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 162 additions & 0 deletions docs/form.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
import EditButton from '../src/components/Docs/EditButton'
import GoToExample from '../src/components/Docs/GoToExample'
import NavigationButtons from '../src/components/Docs/NavigationButtons'

<EditButton to="https://github.com/react-pdf/site/blob/master/docs/form.md" />

## Forms

React-pdf includes the ability to use [AcroForm](https://experienceleague.adobe.com/en/docs/experience-manager-learn/forms/document-services/pdf-forms-and-documents#acroforms)-Forms in pdfs. AcroForm is part of interactive pdfs and includes annotations for e.g. text fields, checkboxes. The AcroForm is automatically initialized as soon as one of the form elements is used.

### TextInput

The `<TextInput />` element represents a text field for inputting single- or multiline text.

#### Valid props

| Prop name | Description | Type | Default |
| --------- | :----------------------------------------------------------------: | ------------------------------------------: | ----------: |
| align | Defines the alignment of text | _String_ | _left_ |
| multiline | Defines if the user is allowed to input more than one line of text | _Boolean_ | _false_ |
| password | If set to true the text will be masked with e. g. * | _Boolean_ | _false_ |
| noSpell | If set to true tells the pdf viewer to not spellcheck the text | _Boolean_ | _false_ |
| format | Defines the format the textinput should be formatted to | [TextInputFormatting](#textinputformatting) | _undefined_ |

See also [Common Form Attributes](#common-form-attributes)

<GoToExample name="textinput" />

##### TextInputFormatting

`format` is a definition how the value shall be formatted by the viewer. Take into account that not all viewers support this feature because it involves javascript execution.

| Prop name | Description | Type | Default |
| --------------- | :--------------------------------------------------: | ------------------------------------------: | ----------: |
| type | Defines the alignment of text | [TextInputFormatType](#textinputformattype) | _undefined_ |
| param | Defines a format for certain types | _String_ | _undefined_ |
| nDec | Defines the number of places after the decimal point | _Number_ | _undefined_ |
| sepComma | Defines if the seperator shall be a comma or not | _Boolean_ | _false_ |
| negStyle | Defines style for negative numbers | _String_ | _undefined_ |
| currency | Defines the symbol to be placed as currency sign | _String_ | _undefined_ |
| currencyPrepend | If set to true the currency sign is prepended | _Boolean_ | _false_ |

##### TextInputFormatType

`type` prop can take one of the following values.

| Value | Description |
| -------- | :-----------------------------------------------------------------: |
| date | Expects the param prop to be a valid date format. |
| time | Expects the param prop to be a valid time format. |
| percent | Uses the props nDec, sepComma, negStyle, currency, currencyPrepend. |
| number | Uses the props nDec, sepComma, negStyle, currency, currencyPrepend. |
| zip | Formats for the zip-code standard |
| zipPlus4 | Formats for the zip+4 standard |
| phone | Formats for a phone number |
| ssn | Formats for a ssn number |

For deeper knowledge into the formatting you might want to look into the [pdfkit doc](https://pdfkit.org/docs/forms.html#text_field_formatting) and into the [API Reference for Forms](https://experienceleague.adobe.com/docs/experience-manager-learn/assets/FormsAPIReference.pdf) Page 119.

---

### Checkbox

The `<Checkbox />` element represents one of two states the user can toggle between. Some viewers behave differently based on wether the `name` prop is set or not and wether there are name duplicates or not. This can result in inconsistencies which makes the `name` prop recommendable to use and to achieve a consistent result across various viewers.

#### Valid props

| Prop name | Description | Type | Default |
| --------------- | :--------------------------------------------------------------------------: | --------: | ----------: |
| backGroundColor | It defines the color of the inside of the checkbox it applies to | _String_ | _undefined_ |
| borderColor | Defines the color used to paint the outline of the checkbox | _String_ | _undefined_ |
| checked | If set to true the checkbox is checked | _Boolean_ | _false_ |
| onState | If set to true tells the pdf viewer to not spellcheck the text | _String_ | _Yes_ |
| offState | Defines the format the textinput should be formatted to | _String_ | _No_ |
| xMark | If set to true the onState appears as a X otherwise a checkmark is displayed | _Boolean_ | _false_ |

See also [Common Form Attributes](#common-form-attributes)

<GoToExample name="checkbox" />

---

### Picker

The `<Picker />` element represents a dropdown menu for the selection of predefined options.

#### Valid props

| Prop name | Description | Type | Default |
| --------- | :---------------------------------------------------------------------------------------: | --------: | ------: |
| edit | If set to true allows the user to enter a value in the field | _Boolean_ | _false_ |
| noSpell | If set to true and edit is set to true it tells the pdf viewer to not spellcheck the text | _Boolean_ | _false_ |

For more attributes head to [Picker and FormList Attributes](#picker-and-formlist-attributes).

<GoToExample name="picker-formlist" />

---

### FormList

The `<FormList />` element represents a scrollable list for the selection of predefined options.

#### Valid props

For attributes head to [Picker and FormList Attributes](#picker-and-formlist-attributes).

<GoToExample name="picker-formlist" />

---

### Picker and FormList Attributes

These attributes are shared by the picker and formlist elements.

#### Valid props

| Prop name | Description | Type | Default |
| ----------- | :-----------------------------------------------------------: | ---------: | ------: |
| sort | Defines if the options shall be sorted alphabetically | _Boolean_ | _false_ |
| multiSelect | If set to true the user is allowed to select multiple options | _Boolean_ | _false_ |
| select | Defines the options to show inside the field as an array | _String[]_ | _[]_ |

See also [Common Form Attributes](#common-form-attributes)

---

### FormField

The `<FormField />` element is used to group other form elements together. On the form level this creates a hierarchical structure most important for data extraction and naming clearance. It is fully invisible. The usage of this element is optional and not required by any other element. Because of not beeing a element on its own the FormField is the only element not sharing the common form attributes.

#### Valid props

| Prop name | Description | Type | Default |
| --------- | :-----------------------: | -------: | ----------: |
| name | The name of the FormField | _String_ | _undefined_ |

<GoToExample name="formfield" />

---

### Common Form Attributes

Common form attributes are attributes that are shared by a variety of elements.

#### Supported attributes

| Prop name | Description | Type | Default |
| ------------ | :----------------------------------------------------------------------------------------------------: | -----------------: | ----------: |
| name | Describes the name of the specific element when submitting the form | _String_ | _empty_ |
| required | Describes if the specific element needs to have a value when submitting the form | _Boolean_ | _false_ |
| noExport | If set to true the specific element is not exported at a form submission | _Boolean_ | _false_ |
| readOnly | Defines if the specific element is editable or not. If set to true, the user shall not edit the value. | _Boolean_ | _false_ |
| value | Defines the value of the specific element. For further information look at the element. | _String_, _Number_ | _undefined_ |
| defaultValue | Describes what the default state for the value is. Can be used when resetting the form. | _String_, _Number_ | _undefined_ |

<NavigationButtons
backSrc="/svg"
backText="SVG Images"
nextSrc="/hooks"
nextText="Hooks"
/>
4 changes: 2 additions & 2 deletions docs/hooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,8 @@ The update function takes the new document and does not return anything.
---

<NavigationButtons
backSrc="/svg"
backText="SVG Images"
backSrc="/form"
backText="Forms"
nextSrc="/styling"
nextText="Styling"
/>
4 changes: 2 additions & 2 deletions docs/svg.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,6 @@ SVG presentation attributes are CSS properties that can be used as attributes on
<NavigationButtons
backSrc="/components"
backText="Components"
nextSrc="/hooks"
nextText="Hooks"
nextSrc="/form"
nextText="Forms"
/>
93 changes: 93 additions & 0 deletions examples/checkbox.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
const Multichoice = () => {
const currentYear = new Date().getYear()+1900;
return (
<View>
<Text style={styles.heading}>Questions</Text>
<Question answers={['Flask', 'ReactPDF', 'SolidJS', 'Spring Boot']} name="technology">
Which technology is used to generate this pdf?
</Question>
<Question answers={[currentYear+1, currentYear-2, currentYear, currentYear-1]} name="year">
What year is it?
</Question>
<Question answers={['MacOS', 'TempleOS', 'Windows', 'Ubuntu']} name="os">
What operating system was developed by Apple?
</Question>
<Question answers={['Software', 'Construction', 'Hardware', 'Agriculture']} name="ram">
Where does RAM get used?
</Question>

<FreeSpace free={250}/>
<FormField style={[styles.inlineFlex, styles.break]} name="read">
<Text>I have read all the questions above: </Text>
<Checkbox checked required style={styles.checkbox} />
</FormField>
<FormField style={[styles.inlineFlex, styles.break]} name="knowledge">
<Text>I only used my own knowledge to answer the questions: </Text>
<Checkbox required style={styles.checkbox} />
</FormField>
</View>
)
};

const Question = (props) => (
<FormField name={props.name} style={styles.break}>
<Text style={[styles.question, styles.break]}>{props.children}</Text>
<Answers choices={props.answers}/>
</FormField>
)

const Answers = (props) => (
<View style={styles.verticalFlex}>
{
props.choices.map(choice => (
<View style={styles.verticalFlex}>
<Text>{choice} </Text>
<Checkbox name={choice} style={styles.checkbox} />
</View>
))
}
</View>
)

const FreeSpace = (props) => <View style={{marginTop: props.free}}/>

const styles = StyleSheet.create({
page: {
padding: 60
},
checkbox: {
height: 20,
width: 20
},
heading: {
fontSize: 24,
textAlign: 'center',
marginBottom: 40
},
question: {
fontSize: 20
},
break: {
marginBottom: 10
},
verticalFlex: {
display: 'flex',
flexDirection: 'row',
justifyContent: 'space-around'
},
inlineFlex: {
display: 'flex',
flexDirection: 'row',
justifyContent: 'flex-start'
}
});

const doc = (
<Document>
<Page style={styles.page} size="A4">
<Multichoice />
</Page>
</Document>
);

ReactPDF.render(doc);
91 changes: 91 additions & 0 deletions examples/formfield.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
const Address = (props) => (
<FormField name={props.name.toLowerCase()}>
<Text style={styles.heading}>{props.name}</Text>
<Text>Street</Text>
<TextInput
name="street"
noSpell
required={props.required}
style={styles.textinput}/>
<Text>House Nr.</Text>
<TextInput
name="house"
noSpell
required={props.required}
style={styles.textinput}/>
<Text>Postal code</Text>
<TextInput
name="postal-code"
noSpell
required={props.required}
style={styles.textinput}/>
<Text>City</Text>
<TextInput
name="city"
noSpell
required={props.required}
style={styles.textinput}/>
<Text>Country</Text>
<TextInput
name="country"
noSpell
required={props.required}
style={styles.textinput}/>
</FormField>
)

const Invoice = () => (
<View>
<Text style={styles.heading}>Invoice</Text>
<View style={styles.verticalFlex}>
<View style={styles.flexGrow}>
<Address name="Billing" required/>
</View>
<View style={styles.flexGrow}>
<Address name="Shipping"/>
</View>
</View>

<Text>Name of Product</Text>
<TextInput
name="product"
noSpell
required
style={styles.textinput}/>
</View>
);

const styles = StyleSheet.create({
page: {
padding: 60
},
heading: {
fontSize: 24,
textAlign: 'center',
marginBottom: 40
},
textinput: {
height: 14.4,
marginRight: 50,
marginTop: 10,
marginBottom: 20
},
verticalFlex: {
display: 'flex',
flexDirection: 'row',
justifyContent: 'space-around'
},
flexGrow: {
flexGrow: 1
}
});

const doc = (
<Document>
<Page style={styles.page} size="A4">
<Invoice />
</Page>
</Document>
);

ReactPDF.render(doc);
Loading