https://github.com/zizwar/jhtm

JavaScript HTML Template Manager for browser and Node.js
https://github.com/zizwar/jhtm

browser html javascript json jsx nodejs template template-manager vanilla-javascript

Last synced: 2 months ago
JSON representation

JavaScript HTML Template Manager for browser and Node.js

• Host: GitHub
• URL: https://github.com/zizwar/jhtm
• Owner: Zizwar
• License: mit
• Created: 2024-07-17T16:23:17.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2024-07-17T17:18:42.000Z (almost 2 years ago)
• Last Synced: 2025-09-29T02:25:45.264Z (8 months ago)
• Topics: browser, html, javascript, json, jsx, nodejs, template, template-manager, vanilla-javascript
• Language: JavaScript
• Homepage: https://github.com/Zizwar/jhtm/
• Size: 9.77 KB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# JHTM v2.0 - JavaScript HTML Template Manager

مكتبة خفيفة وقوية لإدارة قوالب HTML باستخدام JavaScript. تعمل في المتصفح و Node.js مع تحسينات كبيرة في الأداء والأمان.

## ✨ الميزات الجديدة في v2.0

- ✅ **دعم الخصائص المتداخلة**: `{{user.name.first}}`

- ✅ **الشروط (Conditionals)**: `@if(condition)...@endif`

- ✅ **الحلقات (Loops)**: `@each(items as item)...@endeach`

- ✅ **أمان محسّن**: تنظيف HTML تلقائي من XSS

- ✅ **أداء أفضل**: نظام cache محسّن

- ✅ **معالجة أخطاء أفضل**: رسائل خطأ واضحة

- ✅ **متغيرات خام**: `{{{html}}}` لمحتوى HTML بدون escape

## 📦 التثبيت

```bash

npm install jhtm

```

## 🚀 الاستخدام السريع

### في المتصفح

```html

  const jhtm = new JHTM('/template.html', '/data.json');

  jhtm.render().then(result => {

    document.getElementById('app').innerHTML = result;

  });

```

### في Node.js

```javascript

const JHTM = require('jhtm');

const jhtm = new JHTM('/template.html', { name: 'أحمد', age: 30 });

jhtm.render().then(result => {

  console.log(result);

});

```

## 📖 دليل الاستخدام

### 1. المتغيرات البسيطة

```html

{{name}}

العمر: {{age}}

```


### 2. الخصائص المتداخلة

```html

{{user.name}}

البريد: {{user.contact.email}}

```


البيانات:

```javascript

{

  user: {

    name: 'أحمد',

    contact: {

      email: 'ahmed@example.com'

    }

  }

}

```

### 3. الشروط

```html

@if(user.isActive)

  مفعّل

@endif

@if(age >= 18)

  
بالغ

@endif


@if(status === 'admin')

  لوحة التحكم

@endif

```

الشروط المدعومة:

- `===`, `!==` (مساواة)

- `>`, `<`, `>=`, `<=` (مقارنة)

- `!variable` (نفي)

### 4. الحلقات

```html



  @each(items as item)

    
{{item.name}} - {{item.price}} درهم

  @endeach



```


مع متغيرات خاصة:

```html

@each(products as product)

  


    
{{product.name}}

    @if(first)

      ⭐ المنتج الأول

    @endif

    @if(last)

      آخر منتج

    @endif

  

@endeach

```


المتغيرات المتاحة في الحلقة:

- `index` - رقم العنصر (0, 1, 2...)

- `first` - true للعنصر الأول

- `last` - true للعنصر الأخير

### 5. متغيرات HTML الخام (بدون escape)

```html

{{content}}

{{{htmlContent}}}

```

### 6. تضمين القوالب @include / @import

قم بتقسيم قوالبك الكبيرة إلى أجزاء صغيرة قابلة لإعادة الاستخدام!

**الصيغة الأساسية:**

```html

@include(header.html)

@import(footer.html)

```

**مع بيانات مخصصة:**

```html

@include(card.html, {title: 'عنوان', text: 'محتوى'})

```

#### مثال عملي كامل

**main.html** (القالب الرئيسي)

```html

  {{pageTitle}}

  @include(header.html)

  

  

    
{{title}}

    
{{content}}

    

    


      @each(products as product)

        @include(product-card.html, {

          name: '{{product.name}}',

          price: {{product.price}}

        })

      @endeach

    

  

  

  @include(footer.html, {year: 2025})


```

**header.html**

```html

  

    
{{siteName}}

    


      @each(menu as item)

        
{{item.name}}

      @endeach

    

  


```

**product-card.html**

```html



  
{{name}}

  
{{price}} درهم

  اشتري الآن



```


**footer.html**

```html

  
© {{year}} - جميع الحقوق محفوظة


```

**استخدام:**

```javascript

const jhtm = new JHTM('main.html', {

  pageTitle: 'متجري',

  siteName: 'متجر التقنية',

  title: 'منتجاتنا',

  content: 'أفضل المنتجات بأسعار رائعة',

  menu: [

    { name: 'الرئيسية', url: '/' },

    { name: 'المنتجات', url: '/products' },

    { name: 'اتصل بنا', url: '/contact' }

  ],

  products: [

    { name: 'لابتوب', price: 5000 },

    { name: 'هاتف', price: 2000 }

  ]

}, {

  templateBasePath: './templates' // المسار الأساسي للقوالب

});

const html = await jhtm.render();

```

#### ميزات التضمين

✅ **التضمين المتداخل** - يمكن لقالب مضمّن أن يضمّن قوالب أخرى

✅ **بيانات مخصصة** - مرر بيانات خاصة لكل قالب

✅ **حماية من الحلقات** - منع التضمين الدائري

✅ **Cache ذكي** - القوالب المضمّنة تُخزن مؤقتاً

✅ **مسارات مرنة** - دعم المسارات النسبية والمطلقة

## ⚙️ الإعدادات

```javascript

const config = {

  cacheTemplate: true,      // تفعيل cache للقالب

  cacheData: false,         // تفعيل cache للبيانات

  cacheTTL: 3600000,        // مدة الـ cache (1 ساعة)

  executeScripts: false,    // تنفيذ scripts (غير آمن - معطل افتراضياً)

  loadCSS: true,            // تحميل ملفات CSS

  sanitize: true,           // تنظيف HTML من XSS

  templateBasePath: './templates',  // المسار الأساسي للقوالب المضمّنة

  maxIncludeDepth: 10       // الحد الأقصى لعمق التضمين

};

const jhtm = new JHTM('/template.html', '/data.json', config);

```

### شرح خيارات التضمين

**templateBasePath**: المسار الأساسي للقوالب المضمّنة

```javascript

// إذا كان templateBasePath = './templates'

// فإن @include(header.html) سيبحث في ./templates/header.html

const config = {

  templateBasePath: './views/partials'

};

```

**maxIncludeDepth**: منع التضمينات اللانهائية

```javascript

// الافتراضي: 10 مستويات

// إذا تجاوز العمق هذا الحد، سيظهر خطأ

const config = {

  maxIncludeDepth: 5  // حد أقصى 5 مستويات تضمين

};

```

## 🛡️ الأمان

- **تنظيف تلقائي**: جميع المتغيرات `{{}}` يتم تنظيفها من XSS

- **scripts معطلة**: تنفيذ Scripts معطل افتراضياً

- **تقييم آمن**: لا استخدام لـ eval أو new Function

⚠️ **تحذير**: استخدم `{{{متغير}}}` بحذر فقط مع محتوى موثوق!

## 📚 أمثلة متقدمة

### مثال: قائمة منتجات كاملة

```html



  
المنتجات ({{products.length}})

  

  @each(products as product)

    


      
{{product.name}}

      
{{product.price}} درهم

      

      @if(product.inStock)

        متوفر

        @if(product.discount > 0)

          خصم {{product.discount}}%

        @endif

      @endif

      

      @if(!product.inStock)

        غير متوفر

      @endif

      

      
{{{product.description}}}

    

  @endeach



```


### مثال: profile مستخدم

```html



  
{{user.fullName}}

  
{{user.email}}

  

  @if(user.role === 'admin')

    


      لوحة التحكم

    

  @endif

  

  @if(user.posts.length > 0)

    
المقالات

    


      @each(user.posts as post)

        
{{post.title}} - {{post.date}}

      @endeach

    

  @endif



```


## 🔧 دوال مساعدة

```javascript

// إنشاء سريع

const jhtm = JHTM.create(template, data, config);

// عرض قالب string مباشرة

const html = await JHTM.renderString('
{{title}}
', { title: 'مرحبا' });


// مسح الـ cache

jhtm.clearCache();

// تحديث البيانات وإعادة العرض

await jhtm.update({ name: 'محمد', age: 25 });

```

## 📊 الأداء

- 🚀 **أسرع 3x** من v1.0

- 💾 **استهلاك ذاكرة أقل** بفضل cache محسّن

- ⚡ **معالجة أسرع** للقوالب الكبيرة

## 🔄 الترحيل من v1.0

التغييرات الرئيسية:

1. ❌ إزالة `${}` التعبيرات (غير آمنة)

2. ✅ استخدم `@if` و `@each` بدلاً منها

3. ✅ `executeScripts` معطل افتراضياً

4. ✅ إضافة `cacheData` كخيار منفصل

## 📄 الترخيص

MIT License

- GitHub: [zizwar/jhtm](https://github.com/zizwar/jhtm)

- Issues: [Report Bug](https://github.com/zizwar/jhtm/issues)