Print

PRO: Shortcode-options

The basic structure of a WordPress-Shortcode is explained here.

Use the JCI PRO Plugin by defining a WordPress-Shortcode or a Gutenberg-Block (as of Version 3.7. there is also a Block for the JCI PRO Plugin). This page shows the options for a JCI PRO Shortcode:

[jsoncontentimporterpro nameoftemplate=MY_TEMPLATE_NAME parametername1=parametervalue1]

The JCI PRO Shortcode has these parameters:

Tell Shortcode what JCI Template should be used

  • nameoftemplate=NAME_GIVEN_IN_JCI_TEMPLATE
    By this, the Plugin knows what JCI Template should be used.
  • id=NUMBER_OF_JCI_TEMPLATE
    Instead of nameoftemplate, you also can use the id of a JCI Template.
  • jsonuseset=CODE_OF_USESET
    From Version 3.7 on, you can define “Use Sets”.

Shortcode-Parameter not available in the JCI Template

  • param1=…, param2=…
    Put a ##param1## / ##param2## Placeholder in the URL in the JCI template. In action, those placeholders are replaced by the values of param1 / param2 from the shortcode. This is nice when putting together a JCI-Shortcode in another JCI-Shortcode. Or when using different languages and setting the language in the Shortcode by param1=en or param1=de
    {{param1}} and {{param2}} are also available with their values in the JCI template. There is no param3 etc.!
  • inputtype=xml or =csv
    depending on the settings, the data is converted to JSON
  • inputtypeparam=…, yet used for inputtype=csv only (for converting CSV-text to JSON, the plugin must know how the CSV is structured)
    (tech note: here, the PHP function str_getcsv is used).
    The settings must be encoded in a valid JSON-Set like this: {"delimiter": ",", "enclosure": "#QM#", "escape":"#BS#", "csvline": "#LF#", "skipempty": "yes"}
    For some special chars, placeholders must be used:
    • #QM# stands for a quotation mark
    • #BS# for Backslash
    • #LF# for Linefeed
    • #CR# for carriage return
    • If skip empty is “yes”: empty lines in the CSV are ignored.
  • trytohealjson=yes
    If set, the plugin tries to repair JSON: Remove invalidating chars (e. g. “(” at the beginning of a JSON etc.). Sometimes this helps. If not, the received “almost JSON” can be repaired by twig.
  • mode=...
    If set to “create” the plugin creates Custom-Post-Type pages. So you can create Pages out of a JSON-API-Feed.
  • createoptions=...
    If “mode=create” then “createoptions=…” defines how to create Custom Post Pages.
  • convertjsonnumbers2strings=yes
    If set to “yes” any number in the JSON-Feed is converted to a string. This is importaint for very big or small numbers, as those are otherwise displayed in scientific-notation like 1.4e-20
  • httpstatuscodemustbe200=no
    If set to “no”: it accepts that some APIs deliver valid and usable JSON and an HTTP error (aka no “200”). Without that, the plugin says: No HTTP-ok from the API, hence ignore JSON.
  • secret=...
    If set, the value of the secret is compared with the GET-Parameter “sec” (URL with …?sec=…”). If not equal, the plugin is aborted.
    This is a little security feature to invalidate URLs when needed (e. g. when running Shortcodes for generating CPT).
  • orderofshortcodeeval=NUMBER
    If set, it overrides the settings of “Usage of Shortcodes (JCI or other) in the JCI-twig-Template” at the tab “Shortcode-Settings”. Important when having other shortcodes in the twig-Template.
    • If set to 1 (default), first the twig-code in the JSONContentImporter-Shortcode is executed, and after that remaining Shortcodes.
    • If set to 2, shortcodes are executed and then twig.
    • Any other value: No shortcode execution, which is ok: You can execute shortcodes in Twig by “doshortcode”.
  • showapiresponse=NUMBER
    Upload files via HTML-Form, store them in WordPress, and send them to an API: CURLOPT_UPLOAD_POSTFIELDS (store_upload_in_library=yes). Then the Shortcode parameter setting “showapiresponse=1” adds a JSON-node “apiresponseinfo” with info on the uploaded file (like “attachment_id”) to be able to use this upload in the JCI-template.
  • forcetemplate=NUMBER
    If set to 1, then all settings from the JCI-Template are used (otherwise, a parameter set in the Shortcode overwrites its template parameter)
  • displayapireturn=NUMBER
    If an API does not give JSON, but the pure data (e. g. an images) you can use this parameter. The data is put into an JSON like {{“data”:”…”}}, so {{data}} gives the pure data for display via HTML.
    • displayapireturn=1 (pass directly)
    • displayapireturn=2 (pass base64_encoded)
    • displayapireturn=4 (remove linefeeds)
  • dodisplayonlyif=...
    Default empty, define a POST/GET parameter in the input. Otherwise, nothing is displayed. E.g., POST:varname1:varnamevalue1″ means that in the calling WordPress site, “variablename=variablevalue” must be sent either by POST (GET also possible). Allowed chars for varname1 and varnamevalue1: [0-9a-zA-Z_-.;] This is for checking if such a call comes from a special form.
  • feedsource=...
    By using feedsource=file, you can load JSON feeds from the server-filesystem
  • feedfilename=...
    directories and name of JSON-feed from the server-filesystem (enhanced by basepath, see JCI PRO Plugin-Options: “Shortcode-Settings” > “Load JSON-data from server filesystem”)
  • urladdparam=...
    You can define an URL in the plugin template manager. If at a page, this URL must be extended, you can use the shortcode parameter “urladdparam”.
    Example: [jsoncontentimporterpro urladdparam=”?lets=go” id=3]
    Then “?lets=go” will be added to the URL defined in template 3. So you can work with a template-url and twig code and specify this a bit on the WordPress page. In urladdparam, you can put shortcodes of 3rd party plugins: For that, we have to mask the brackets [ and ] with #BRO# and #BRC#. So it looks like urladdparam= "?mail=#BRO#s2Get%22 user_field=user_email#BRC#" to put the shortcode [s2Get user_field=user_email] into the URL.
  • urlparam4twig=...
    Same as “urlparam” but esp. designed for use in twig-code
  • maskspecialcharsinjson=no
    If set to “no”: switches off some usually very good handling of JSON (rare JSON needs that)
  • encodingofsource=...
    The plugin needs UTF-8 encoded data. If the API does not give UTF-8 encoded data, it has to be converted to UTF-8. The value of the encoding of the source is used for iconv to do this. E. g. is “utf-16le”

Shortcode-Parameter: Overwrite JCI Template settings

You can define a JCI Template with the needed default settings. If you need loclly other settings you can add Shortcodeparameter locally. THose overwrite the JCI Template settings.

  • url=....
    Where is the JSON?
    http://…json (use http://username:password@www…. for basic authentification).
    • If you define a relative URL (starting with “/”) here, home_url is added. This helps when switching domains (e. g. from dev- to live-server).
    • Also you can insert twig-code (e. g. {{urlparam.GETPARAM}}, ##param1## and ##param2## in the URL as placeholder. The twig-code is executed with an empty JSON and ##param1/2## is replaced by the values of the shortcode-parameters with the same name.
    • Try “dummyrequest” for having JSON with basic Page-Parameters.
    • <post.FIELD> in the URL is replaced by Value of FIELD of the Page (e. g. PageID).
  • urlgettimeout=NUMBER
    Set the time to wait for an API-anser in seconds
  • cachetime=NUMBER
    Set the time to locally cache the API-request in seconds
  • debugmode=NUMBER
    Prior to version 3.3.6 there was either debug=on or off for the whole page. By “debugmode=NUMBER” you can set the debugmode for each shortcode: NUMBER=2 shows some debug infos, NUMBER=10 all available debug infos.

Deprecated Shortcode-Paramater

The follwoing Shortcode-Parameter are still there to have backwards compatibility. But it is better to use a JCI Template, where you can program also the url, curloptions etc. by twig.

  • urlparam=...
    List separated by # of allowed GET-variable names used in the JSON-Feed-URL. E.g. “var1#var2”. Special: aaa%5Bbbb%5D / [aaa]=bbb. Some GET-variable names are “forbidden”, as WordPress uses them on their own and is filtering them (e.g., “p=…”). So we have to mask those by adding “_nowpquery”: Use “p_nowpquery” instead of “p”. The plugin will use “p=…” in the API request. If a form (e.g., with checkboxes) passes a []-Field to the Plugin, the urlparam must be set to “model%5B%5D”. Then “model[]” can be passed to the API.
    You better set the allowed POST-/GET variables in the JCI template.
  • pathparam=...
    List separated by # of allowed GET-variablenames for the path of the JSON-Feed-URL. E.g. “path1#path2#pagename”
    You better define the URL in the JCI template with twig.
  • fileext=...
    Static (not changeable via GET) extension of the JSON-Feed-URL. E.g. if “php” “.php” is added to the URL. If fileext starts with an “?”, then no “.” is added. This is useful when passing apikeys like “?apikey=007”
    You better define the URL in the JCI template with twig.
  • numberofdisplayeditems, oneofthesewordsmustbein, oneofthesewordsmustbeindepth, oneofthesewordsmustnotbein, oneofthesewordsmustnotbeindepth, requiredfieldsandvalues, requiredfieldsandvaluesdepth, requiredfieldsandvalueslogicandbetweentwofields
    Define what data you want to use by twig, please. This gives you much more powerful syntax at hand with if-then-else and regular-expression-matches
  • basenode
    twig has direct access to the JSON tree. We do not need basenode any more.
  • filterresultsin=... , filterresultsnotin=...
    This is used to filter JSON. Do this with twig-syntax, please!
  • sortfield, sortorderisup, sorttypeisnatural
    This is used to sort JSON. Do this with twig-syntax, please!
  • loopwithoutsubloop
    {% for i in_context %} will do that with twig
  • parser, method, postpayload, postbody
    Set it in the JCI template, please
  • customfieldparam=NAMES_OF_ CUSTOMFIELDS
    Define some comma-separated variables in the Shortcode-Parameter “customfieldparam” like “customfieldparam=hello1,hello2”.
    In the JSON-feed-URL you can then use this Parameter in this way: “http://wherever/path/<cf_hello1>/page.json?par=<cf_hello2>”. Then set the WordPress-Customfields hello1 and hello2 on the page you use this shortcode. When building the page, <cf_hello1> and <cf_hello2> will be replaced by the customfield-values. The resulting JSON will contain the value of the Custom Field, so that it is available in twig with {{cfp.NAMES_OF_CUSTOMFIELD}}.
    Don’t use this any more. Use twig to set up a URl. By
    wp_get_page_properties()in the twig-code you get the CPF and can use them for the URL.
  • header=..., auth...
    This is used to send info via http-header. Do this with curlooptions in the JCI template, please!
  • urlgetaddrandom=yes
    If set to “yes” the plugin adds a random-parameter to the GET-URL to bust a API-cache. Ignored if not set to “yes”.
    Do this with twig-random in the JCI template at the URL, please!
  • urlencodepostpayload=no
    Add this, if the postpayload should not be urlencoded. It depends on what the API requires. Do this with curlooptions in the JCI template, please!
  • removeampfromurl=yes
    If set to “=yes” then “&” in the URL is replaced by “&”. This is needed if 3rd party software like VisualComposer changes the text of a Shortcode. Set the URL in the JCI template and this problem does not occur.
  • curloptions=...
    When you check the access to your API-URL the best way is to do it with CURL. Then you can set many CURL-options as the way of authentication, the header etc.. Before Version 3.4.5 this was possible in some ways, but now in all ways. To do this, you can set up the shortcode-parameter “curloptions”. It is highly reccomended to set the curloptions via the plugins-template-manager!
    Example: [jsoncontentimporterpro url=… method=curlget curloptions=”CURLOPT_HTTPAUTH=CURLAUTH_BASIC;CURLOPT_TIMEOUT=30;CURLOPT_HTTPHEADER=a:b##c:d;CURLOPT_POSTFIELDS=e:f##g::h”]…[/jsoncontentimporterpro] The “CURLOPT_…” must be separated by “;”. Then “CURLOPT_…=value” sets an option. “value” there can be a number or a constant like “CURLAUTH_DIGEST”. Example: “CURLOPT_TIMEOUT=30” sets the timeout to 30 seconds. “CURLOPT_HTTPAUTH=CURLAUTH_BASIC” sets basic auth. If a “CURLOPT_…” needs an array-input you can do it like this (separate array-items by “##”): “CURLOPT_HTTPHEADER=a:b##c:d”. CURLOPT_POSTFIELDS=e:f##g::h sends an array to the API (then “multipart/form-data”). If CURLOPT_POSTFIELDS is an valid JSON-String (via template-manager), a string is sent to the API (then “application/x-www-form-urlencoded”). It depends on the API what way is ok.
    Again: It is highly reccomended to set the curloptions via the plugins-template-manager!
  • addpostdata2json=y
    If set to “y”, JSON-data is added to the API-received data: In the node “jcipageparam” the values of the WP_Post OBJECT (“get_post”, e. g. Page-ID, post_date), permalink, home_url, current-user-id are inserted. By {{jcipageparam.post.ID}} etc. twig can work with this data.
    Do not use this. Better use twig-function wp_get_page_properties()in the twig-code.
  • addcpf2json=y
    If set to “y”, JSON-data is added to the API-received data: In the object “jcipageparam” the values of the Custom Post Fields (if there are some). By {{jcipageparam.custom_fields.NAME_OF_CPF}} and similar twig code can work with this data.
    Do not use this. Better use twig-function wp_get_page_properties()in the twig code.
  • filterfieldrequired, filterfieldremove
    Removed from the Plugin. Filtering should be done with twig.
Was this article helpful?
4.5 out Of 5 Stars

1 rating

5 Stars 0%
4 Stars 100%
3 Stars 0%
2 Stars 0%
1 Stars 0%
5
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
On this page: