File includes

There's in fact three different ways to include a PHP function in an Arlima article. The easiest solution would be to use one of the article filters or an ordinary short code. But as of version 2.8 of Arlima you can include an entire PHP file within your article.

Example

Let's say that you want to create a count down script that your editors can use to display the days left until a big event is taking place. You want your editors to have full control over the date and the text that should be displayed.

1) Create the file to be included

Somewhere in your theme you create a PHP file, containing the logic of your count down. You start off with a function call to arlima_file_args to declare which arguments you can pass on when including the file (here's a full description of the different types of file arguments). These arguments will be possible to edit in the article form.

arlima-count-down.php

<?php
$args = arlima_file_args(array(
    array(
        'type' => 'date',
        'property' => 'count_down_to',
        'value' => date('Y-m-d', time()+86400),
        'width' => '30%',
        'label' => array(
            'text' => 'Count down to:'
        ),
        'settings' => array(
            'dateFormat' => 'yy-mm-dd'
        )
    ),
    array(
        'property' => 'text',
        'value' => '%s left until christmas eve 2014',
        'label' => array(
            'text' => 'Text:',
            'description' => 'Text to be displayed when count down finished'
        )
    )
));
if( !$args ) {
    // Important to return immediately if arlima_file_args() returned
    // false, this means that Arlima has included the file only to
    // get information about which arguments the file has 
    return;
}
?>
<div class="tmpl-article count-down">
    <?php printf($args['text'], human_time_diff(strtotime($args['count_down_to'])) ) ?>
</div>

2) Let Arlima know about your file

The second step is to let Arlima know about your file. You do this by hooking into the action arlima_article_includes and return an array with your files.

<?php
function my_file_includes($files) {
   $files[] = get_stylesheet_directory() . '/arlima-count-down.php';
   return $files;
}
add_filter('arlima_article_includes', 'my_file_includes');

3) Add the file to your list

Now you open the list manager in wp-admin and a new meta box will have appeared in the bottom right corner, labeled "File includes". In this meta box you will see the file name arlima-count-down.php. Drag the file over to your list and you're set to go!

File arguments

A file argument can be declared using the following attributes

array(
   'type' => 'text', // Any of the supported argument types, optional
   'property' => 'my_arg', // the name of the argument
   'value' => 'default value',
   'display' => 'block', // Either block or inline, optional 
   'width' => '100%', // The width of the field, optional
   'label' => array(
      'text' => 'Text label',
      'placeholder' => 'Can be used instead of text', // optional
      'display' => 'inline', // Either inline or block, optional
      'description' => '...' // Optional
   )
)

Here you can find the configurations for the different argument types:

Text

arlima_file_args(array(
  array(
    'property' => 'my_arg',
    'value' => 'default value',
    'rows' => 5, // If you want a textarea with 5 rows instead of an input     
    'label' => array(
      'text' => 'Text label',
    )
  )
);

Boolean

arlima_file_args(array(
  array(
    'type' => 'boolean'
    'property' => 'my_arg',
    'value' => true,
    'label' => array(
      'text' => 'Text label',
      'yes' => 'Okey' // optional text for positive value
      'no' => 'No way!' // optional text for negative value
    )
  )
);

List

arlima_file_args(array(
  array(
    'type' => 'list'
    'property' => 'my_arg',
    'options' => 'Blue, Green, Black, Pink'
    'value' => 'Black',
    'label' => array(
      'text' => 'Text label',
    )
  )
);

Date

arlima_file_args(array(
  array(
    'type' => 'date'
    'property' => 'my_arg',
    'value' => date('Y-m-d'),
    'settings' => array(
      // Any the jquery datepicker options you want
      'dateFormat' => 'yy-mm-dd'
    )
    'label' => array(
      'text' => 'Text label',
    )
  )
);

Number

Use the same attributes as for the text-argument but add 'type' => 'number'