Download the PHP package jeydotc/nev without Composer
On this page you can find all versions of the php package jeydotc/nev. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package nev
Short Description Use PHP as your templating system!
License MIT
Homepage https://github.com/JeyDotC/nev
Informations about the package nev
Welcome to NEV (No Engine Views)
Do you know why there are templating engines out there? because we're undisciplined people!
Installing
Creating a view
Rendering it
What is all this?
Nev is just the idea that, if you're disciplined enough, you can just use regular PHP classes to represent your views. All you need is a simple base class to derive from which hide most of the uggly stuff.
So, what can I do with this thing? Well, let me walk you through:
First, let's take a look at a simple view:
Ok, as you can see, create a view required you to just create a class and give it the responsibility of rendering HTML. Just a few words of wisdom, and this also applies if you just use plain PHP files:
- Use HTML as much as you can! don't do this
echo "<a href='$someVariable'>$someOtherVariable</a>"
, or this:echo "$someCrazyStringContainingHTMLYouBuiltWithcomplexOperations
. I can swear, you'll regret it. - View classes should be used only as views! don't make them call the database or deal with complex operations, do that at your business layer and give the view the info you want to render.
- These are plain classes, that means you can compose them and do all that classy stuff. Just keep in mind the item above.
Now, as we mentioned above, these are regular classes, so, you can:
Compose Views.
Even if you could create a base class and inherit from there, the general agreement is that it is better to compose things (composition over inheritance) since that leads to more flexible and maintainable code.
So, as an example, let's create a Page component which receives the page parts as parameters:
We moved all the boilerplate things to a Page class. Now let's create a specific view:
Then we can compose our page like this:
Pro Tip: Since the show
method will return a string, you can use it for a response body:
Or even further, since View implements __toString
, you could just send your view instance:
Passing data to the view
As you might have noticed from the previous examples, the data you send to the constructor (or the show method) gets mapped into your view as properties, this allows you to have auto-completion support from your IDE, this is specially useful when dealing with complex objects or collections:
And at your controller:
Boolean Values
Boolean values are a special case, of course you can set them as usual by providing a key with a value in the arguments array, but you can also set a boolean field as true
by just adding the name as a value with no key.
Let's clear this with an example:
Now that we have a boolean property in our view, we can send a value in several ways:
Note: Omitting the value will not set it to false, but set it to the default value declared in the class (usually false).
Passing extra properties to the view
You can send non-declared values to your views. They will be mapped to properties, just like the others, but, since you haven't declared them, that won't be of much use.
For that reason there is this method named extraProperties
that will give you an associative array with the non-declared values which you can use for purposes such as adding extra attributes to some elements:
Creating a Component
Something pretty useful you can do with Nev is creating components that can be used by other views.
Components have nothing special, they are just regular views with a different purpose.
Let's say we want to create a Bootstrap alert component, to do that, we just create a view:
At your view:
So far, so good, but that alert is pretty static, almost useless, so, let's add the ability to at least set the content and title:
At your view:
Ok, that's better, but, what if I wanted to add something more complex? Well, let me introduce you the draw
method:
The draw method
Sometimes your component needs to receive complex markup as a property, the draw
static method allows you to render a property by handling different scenarios:
Notice that the body and title are now rendered using the draw
method, this allows us to handle scenarios like these:
The draw
method will take care of checking the type of value for your component and do the right thing depending on the value type:
- Strings or any scalar value: The value will be returned so it can be echoed.
- callable: It will be invoked and the output will be caught and returned.
- View instance: It will be rendered by calling its
display
method.
Dealing with CSS classes
Configure CSS classes could be a bit cumbersome. Fortunately, the Html trait provides a comfortable way to add them dynamically.
Following with our example, lets first change the way we add the classes:
As you can see, all I do is to call $this->classes(...)
method and send each class as an individual string. Not much of an improvement, but bear with me, things will get better.
Now, let's add a status attribute:
Ok, now we can set the alert's status to any of the bootstrap's supported options (info, warning, danger...). But that still not sell the need for that method, so, what about adding the ability to decide if the component is dismissible:
Pay attention to the [ "alert-dismissible fade show" => $this->dismissible ]
array parameter, this is a special case supported by the ->class()
method, it basically adds the key as a class if the value evaluates to true. The array can have as many key value pairs as you like.
Now, to finish this part, let's give the component user the capability to add his own classes:
This will allow the component user to add his own classes, see sample usages:
Conditional drawing
As you can see above, the PHP template if
statement can be tiresome to write, for those cases you can optionally call the drawIf
static method instead:
The drawIf
method receives two parameters: a boolean indicating if the render will happen, and a string|callable|View that will be rendered using draw
method if the first parameter evaluates to true.
Extra properties
Sometimes you want to allow the user to add custom HTML attributes to your component. As stated in a previous section, all you need to do is getting the non-declared properties using the extraProperties
method and render them using the attr
method:
The extraProperties()
method will return all the attributes sent to the constructor that are not declared in the component class. That will allow to do things like this:
Note that we need to use the attrs
method from the Html
trait in order to display the associative array as a set of HTML attributes.
Finishing things with Style
Finally, to complete the personalization options, there is a helper method that allows you to render a key/value pair array as a CSS string.