Foxit PDF SDK for iOS

How to customize UIExtensions with JSON in Foxit PDF SDK for iOS

Through a configuration file, developers can easily choose the features module, set the rights management and the properties of UI elements without needing to write any additional code or redesign the app’s UI. That helps users easily transfer their UI to a newer upgrade version of the Foxit PDF SDK.

Contents

Introduction to JSON file
Configuration items description
Configure feature module
Configure rights management
Configure UI settings
Instantiate a UIExtensionsManager object with the configuration file
Examples for customizing UI through a configuration file

Introduction to JSON file

The configuration file can be provided as a JSON file or implemented directly in code. We recommend you to use the JSON format which is more intuitive and clearer to view and configure the items.

You can refer to the JSON file found in “samples\complete_pdf_viewer\Source\Resource\” folder of Foxit PDF SDK for iOS package. It looks like as follows:

{
    "modules": {
        "readingbookmark": true,
        "outline": true,
        "annotations": {
            "highlight": true,
            "underline": true,
            "squiggly": true,
            "strikeout": true,
            "insert": true,
            "replace": true,
            "line": true,
            "rectangle": true,
            "oval": true,
            "arrow": true,
            "pencil": true,
            "eraser": true,
            "typewriter": true,
            "textbox": true,
            "callout": true,
            "note": true,
            "stamp": true,
            "polygon": true,
            "cloud": true,
            "polyline": true,
            "distance": true,
            "image": true,
            "audio": true,
            "video": true
        },
        "thumbnail": true,
        "attachment": true,
        "signature": true,
        "search": true,
        "navigation": true,
        "form": true,
        "selection": true,
        "encryption": true
    },
    "permissions": {
        "runJavaScript" : true,
        "copyText" : true,
        "disableLink" : false
    },
    "uiSettings": {
        "displayMode" : "Single",
        "colorMode" : "Normal",
        "zoomMode" : "FitWidth",
        "mapForegroundColor" : "#5d5b71",
        "mapBackgroundColor" : "#00001b",
        "disableFormNavigationBar" : false,
        "highlightForm" : true,
        "highlightLink" : true,
        "highlightLinkColor" : "#16007fff",
        "highlightFormColor":"#200066cc",
        "fullscreen" : false,
        "annotations": {
            "continuouslyAdd" : false,
            "highlight": {
                "color" : "#ffff00",
                "opacity" : 1.0
            },
            "underline": {
                "color" : "#66cc33",
                "opacity" : 1.0
            },
            "squiggly": {
                "color" : "#ff6633",
                "opacity" : 1.0
            },
            "strikeout": {
                "color" : "#ff0000",
                "opacity" : 1.0
            },
            "insert": {
                "color" : "#993399",
                "opacity" : 1.0
            },
            "replace": {
                "color" : "#0000ff",
                "opacity" : 1.0
            },
            "line": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2
            },
            "rectangle": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2
            },
            "oval": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2
            },
            "arrow": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2
            },
            "pencil": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2
            },
            "polygon": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2
            },
            "cloud": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2
            },
            "polyline": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2
            },
            "typewriter": {
                "textColor" : "#0000ff",
                "opacity" : 1.0,
                "textFace" : "Courier",
                "textSize" : 18.0
            },
            "textbox": {
                "color" : "#ff0000",
                "textColor": "#0000ff",
                "opacity" : 1.0,
                "textFace" : "Courier",
                "textSize" : 18.0
            },
            "callout": {
                "color": "#ff0000",
                "textColor": "#0000ff",
                "opacity" : 1.0,
                "textFace" : "Courier",
                "textSize" : 18.0
            },
            "note": {
                "color" : "#ff6633",
                "opacity" : 1.0,
                "icon" : "Comment"
            },
            "attachment": {
                "color" : "#ff6633",
                "opacity" : 1.0,
                "icon" : "Pushpin"
            },
            "image": {
                "rotation" : 0,
                "opacity" : 1.0
            },
            "distance": {
                "color" : "#ff0000",
                "opacity" : 1.0,
                "thickness" : 2,
                "scaleFromUnit" : "inch",
                "scaleToUnit" : "inch",
                "scaleFromValue" : 1,
                "scaleToValue" : 1
            }
        },
        "signature": {
        "color" : "#000000",
        "thickness" : 4
        }
    }
}

Note:

The values in the above JSON file are the default settings for the configuration items. If some configuration items are not in the JSON file, the default settings will be used. For example, if you comment out “highlight”: true,”, it is still enabled.
Only the attachment annotation in the Annotation setting bar (See Error! Reference source not found., to find the Annotation setting bar, just click Comment at the bottom bar, and then click the three dots button) is not controlled by the subitems in “annotations”. ““attachment”: true,” controls the attachments panel and attachment annotation. If you set it to “false”, both of them will be disabled. If you want to hide “Comment” in the bottom bar, you should set both “annotations” and “attachment” to “false“.

Figure 4-1

The above picture does not display all of the annotation tools. You can swipe left on the setting bar to see the other annotation tools.

Configuration items description

The JSON configuration file includes three parts: feature modules, rights management, and UI settings (for example, UI elements properties). This section will set forth the configuration items in detail.

Configure feature module

Note: The value type of the feature module items is bool, where “true” means that the feature module will be enabled, and “false” means that the feature module will be disabled. The default value is “true”.
[table id=38 /]

Configure rights management

Note: The value type of the configuration items is bool, where “true” means that the permission will be enabled, and “false” means that the permission will be disabled. The default value of runJavaScript and copyText is “true”, and the default value of disableLink is “false”.
[table id=39 /]

Configure UI settings

UI Items	Description/ Property Items	Value Type	Available Value/Note	Default value	Note
displayMode	Page display mode	String	Single/ Continous/ Facing/ CoverLeft/ CoverMiddle/ CoverRight/ Reflow	Single	For iOS phone, it only supports Single/Continous/Reflow modes. For dynamic XFA files, it doesn’t support Reflow mode.
zoomMode	Page zoom mode	String	FitWidth/FitPage	FitWidth
colorMode	Page color display mode	String	Normal/Night/Map	Normal	“Night” is a special “Map” mode.
mapForegroundColor	Foreground color of page display	RGB	—	#5d5b71	It is valid only when “colorMode” is set to “Map”.
mapBackgroundColor	Background color of page dispay	RGB	—	#00001b	It is valid only when “colorMode” is set to “Map”.
disableFormNavigationBar	Whether to disable the supplementary navigation bar of the form	Bool	true/false	false
highlightForm	Whether to highlight form field	Bool	true/false	true
highlightFormColor	The highlight color of forms	ARGB		#200066cc	It includes alpha channel, and it is invalid for dynamic XFA document.
highlightLink	Whether to highlight hyperlink	Bool	true/false	true
highlightLinkColor	The highlight color of links	ARGB		#16007fff	It includes alpha channel.
fullscreen	Whether to display in full-screen mode	Bool	true/false	false	It will be in full-screen mode immediately when opening a document if “fullscreen” is set to “true”. If the user clicks on the page, the toolbar will be displayed. After 5 seconds, if it is in full-screen mode, the toolbar and other auxiliary tool buttons will be hidden automatically.
annotations	continuously add		Bool	true/false	false	Whether to add annotation continuously
	highlight	color	RGB		#ffff00
		opacity	numeric	[0.0-1.0]	1.0
	underline	color	RGB		#66cc33
		opacity	numeric	[0.0-1.0]	1.0
	squiggly	color	RGB		#ff6633
		opacity	numeric	[0.0-1.0]	1.0
	strikeout	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
	insert	color	RGB		#993399
		opacity	numeric	[0.0-1.0]	1.0
	replace	color	RGB		#0000ff
		opacity	numeric	[0.0-1.0]	1.0
	line	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
	rectangle	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
	oval	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
	arrow	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
	pencil	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
	polygon	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
	cloud	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
	polyline	color	RGB		#ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
	typewriter	textColor	RGB		#0000ff
		opacity	numeric	[0.0-1.0]	1.0
		textFace	String	Courier/ Courier-Bold/ Courier-BoldOblique/ Courier-Oblique/ Helvetica/ Helvetica-Bold/ Helvetica-BoldOblique/ Helvetica-Oblique/ Times-Roman/ Times-Bold/ Times-Italic/ Times-BoldItalic	Courier	Text font name. If set to an invalid value, the default value will be used.
		textSize	Integer	>=1	18
	textbox	color	RGB		#ff0000
		textColor	RGB		#0000ff
		opacity	numeric	[0.0-1.0]	1.0
		textFace	String	Courier/ Courier-Bold/ Courier-BoldOblique/ Courier-Oblique/ Helvetica/ Helvetica-Bold/ Helvetica-BoldOblique/ Helvetica-Oblique/ Times-Roman/ Times-Bold/ Times-Italic/ Times-BoldItalic	Courier	Text font name. If set to an invalid value, the default value will be used.
		textSize	Integer	>=1	18
	callout	color	RGB		#ff0000
		textColor	RGB		#0000ff
		opacity	numeric	[0.0-1.0]	1.0
		textFace	String	Courier/ Courier-Bold/ Courier-BoldOblique/ Courier-Oblique/ Helvetica/ Helvetica-Bold/ Helvetica-BoldOblique/ Helvetica-Oblique/ Times-Roman/ Times-Bold/ Times-Italic/ Times-BoldItalic	Courier	Text font name. If set to an invalid value, the default value will be used.
		textSize	Integer	>=1	18
	note	color	RGB		#ff6633
		opacity	numeric	[0.0-1.0]	1.0
		icon	String	Comment/ Key/ Note/ Help/ NewParagraph/ Paragraph/ Insert	Comment	If set to an invalid value, the default value will be used.
	attachment	color	RGB		#ff6633
		opacity	numeric	[0.0-1.0]	1.0
		icon	String	Graph/ PushPin/ Paperclip/ Tag	PushPin
	image	rotation	numeric	0/90/180/270	0	If set to an invalid value, the default value will be used.
		opacity	numeric	[0.0-1.0]	1.0
	distance	color	RGB		ff0000
		opacity	numeric	[0.0-1.0]	1.0
		thickness	numeric	[1-12]	2
		scaleFromUnit	String	pt/m/cm/mm/inch/p/ft/yd	inch	The original unit of the scale. If set to an invalid value, the default value will be used.
		scaleToUnit	String	pt/m/cm/mm/inch/p/ft/yd	inch	The target unit of the scale. If set to an invalid value, the default value will be used.
		scaleFromValue	numeric		1	The original value of the scale
		scaleToValue	numeric		1	The target value of the scale
signature	color	RGB		#000000
	thickness	numeric	[1-12]	4	z

Instantiate a UIExtensionsManager object with the configuration file

We have already introduced how to initialize UIExtensionsManager, and in this way, all the built-in UI framework would be loaded by default. In this section, we will provide another method to initialize UIExtensionsManager that uses the configuration file, so that developers can easily customize the UI as desired.

Please refer to the following code to instantiate a UIExtensionsManager object with the configuration file.

Note: You should prepare the JSON configuration file, and then add it to your project. Here, we assume that you have already added a JSON file named “uiextensions_config.json“.

In ViewController.m: (Objective-C)

UIExtensionsManager* extensionsManager;
...
// Instantiate a FSPDFViewCtrl object with the size of the entire screen.
FSPDFViewCtrl* pdfViewCtrl;
pdfViewCtrl = [[FSPDFViewCtrl alloc] initWithFrame: [self.view bounds]];
// Get the path of the JSON configuration file.
NSString* configPath = [[NSBundle mainBundle] pathForResource:@"uiextensions_config" ofType:@"json"];
// Initialize a UIExtensionsManager object and set it to pdfViewCtrl.
extensionsManager = [[UIExtensionsManager alloc] initWithPDFViewControl:pdfViewCtrl configuration:[NSData dataWithContentsOfFile:configPath]];
if (nil == extensionsManager) {
        return;
}
pdfViewCtrl.extensionsManager = extensionsManager;

In ViewController.swift: (Swift)

var extensionsManager: UIExtensionsManager!
...
// Initialize a FSPDFViewCtrl object with the size of the entire screen
var pdfViewCtrl: FSPDFViewCtrl!
pdfViewCtrl = FSPDFViewCtrl.init(frame:self.view.bounds)
// Get the path of the JSON configuration file.
let configPath = Bundle.main.path(forResource: "uiextensions_config", ofType: "json")
var data: Data?
if nil != configPath {
     data = NSData(contentsOfFile: configPath!) as Data?
}
// Initialize a UIExtensionsManager object and set it to pdfViewCtrl.
extensionsManager = UIExtensionsManager.init(pdfViewControl: pdfViewCtrl, configuration: data)
if nil == extensionsMgr  {
   return
}
pdfViewCtrl.extensionsManager = extensionsManager;

Note: Here, we use a configuration file to initialize the UIExtensionsManager. If you do not want to use the configuration file, please refer to the Objective-C and Swift versions.

Examples for customizing UI through a configuration file

In this section, we will show you how to customize feature modules, rights management and UI settings (for example, UI elements properties) in your project. You will find it is extremely easy! You only need to modify the configuration file. Below you can see some examples of how to do it.

Note: For your convenience, we will try it in the “complete_pdf_viewer” (Objective-C) and “complete_pdf_viewer_swift” (Swift) demos found in the “samples” folder.

Open the demos in Xcode. Find the configuration file “uiextensions_config.json” under “complete_pdf_viewer\Resource” or “complete_pdf_viewer_swift\Resource”.

Example 1: Disable “readingbookmark” and “navigation” feature modules.

In the JSON file, set the values of “readingbookmark” and “navigation” to “false” as follows:

"readingbookmark": true,
"navigation": true,

Then, rebuild and run the demo to see the result. Following lists the comparison diagrams:

Before:

After:

The “readingbookmark” and “navigation” feature modules are removed.

Example 2: Disable hyperlinks.

In the JSON file, set the value of “disableLink” to “true” as follows:

"permissions": {
     "runJavaScript": true,
     "copyText": true,
     "disableLink": true
},

Then, rebuild and run the demo to see the result, and you will find that there is no response when clicking the hyperlinks.

Example 3: Set the highlight color from yellow to red.

In the JSON file, set the color property of “highlight” to “#ff0000” as follows:

"highlight": {
    "color" : "#ff0000",
    "opacity" : 1.0
},

Then, rebuild and run the demo to see the result.

Updated on May 20, 2019

Documentation